mrhavens/opus-orchestrator-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README with all features: Scrivener, LaTeX, templates, deployment

Browse Source
This commit is contained in:
Solaria
2026-03-14 23:45:27 +00:00
parent e821c0fe55
commit 5d45451121
1 changed files with 153 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+153 -136
View File
@@ -4,23 +4,43 @@
<p align="center"> <p align="center">
<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python"> <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python">
<img src="https://img.shields.io/badge/LangGraph-✅-green.svg" alt="LangGraph"> <img src="https://img.shields.io/badge/LLM-MiniMax_M2.5-green.svg" alt="MiniMax">
<img src="https://img.shields.io/badge/CrewAI-✅-green.svg" alt="CrewAI"> <img src="https://img.shields.io/badge/KDP-Ready-orange.svg" alt="KDP">
<img src="https://img.shields.io/badge/AutoGen-✅-green.svg" alt="AutoGen"> <img src="https://img.shields.io/badge/Docker-k3s-blue.svg" alt="Docker/k3s">
<img src="https://img.shields.io/badge/Pydantic-✅-green.svg" alt="Pydantic">
</p> </p>
## 🎯 What is Opus? ## 🎯 What is Opus?
Opus is an AI-powered book generation system that creates professional manuscripts using multiple AI agent frameworks. It supports **fiction** and **nonfiction** with intelligent purpose classification. Opus is an AI-powered book generation system that creates professional manuscripts. It supports **fiction** and **nonfiction** with intelligent purpose classification, multiple export formats, and professional publishing workflows.
## ✨ Features ## ✨ Features
### Core Capabilities
- **Multi-Framework Orchestration**: LangGraph, CrewAI, and AutoGen - **Multi-Framework Orchestration**: LangGraph, CrewAI, and AutoGen
- **Intelligent Purpose Classification**: Automatically determines reader purpose - **Intelligent Purpose Classification**: Automatically determines reader purpose
- **100+ Content Frameworks**: From textbooks to RPG modules - **100+ Content Frameworks**: From textbooks to RPG modules
- **Checkpoint/Resume**: Long generations can resume from failure - **Checkpoint/Resume**: Long generations can resume from failure
- **REST API + CLI**: Programmatic or command-line usage
### Input Sources
- **GitHub Repository**: Ingest from any public/private repo
- **S3/Backblaze**: Cloud storage ingestion
- **Local Files**: Direct file input
### Output Formats
- **Scrivener Export**: Chapter-by-chapter with `binder.json`
- **LaTeX**: 31 professional templates
- **HTML**: Styled web output
- **PDF**: Via LaTeX compilation
### Publishing
- **KDP Templates**: 5 trim sizes (5x8, 5.5x8.5, 6x9, 8x8, 8.5x11)
- **31 LaTeX Templates**: Novel, memoir, academic, RPG, cookbook, etc.
- **ISBN/Metadata**: Full publishing metadata support
### Deployment
- **Docker Compose**: Full local stack
- **k3s/Helm**: Production Kubernetes
- **REST API**: Programmatic access
## 🚀 Quick Start ## 🚀 Quick Start
@@ -32,101 +52,100 @@ pip install opus-orchestrator
opus generate --concept "A robot who dreams of being human" --genre sci-fi opus generate --concept "A robot who dreams of being human" --genre sci-fi
# Generate a book (nonfiction) # Generate a book (nonfiction)
opus generate --book-type nonfiction --purpose learn --category technology "How to build an AI app" opus generate --book-type nonfiction --purpose learn "How to build an AI app"
# Resume from checkpoint # Serve API
opus generate --thread-id abc123 --resume opus serve --port 8000
``` ```
## 📚 Framework Library ## 📚 Framework Library
Opus supports **100+ frameworks** organized by content type: Opus supports **100+ frameworks** organized by content type:
### Nonfiction Categories ### Nonfiction
| Category | Frameworks | Purpose | | Category | Frameworks | Purpose |
|----------|-----------|---------| |----------|-----------|---------|
| **Tutorial/How-To** | Tutorial, Howto, Minimalist How-To, Challenge-Response | Learn to do something | | **Tutorial/How-To** | Tutorial, Howto, Minimalist How-To | Learn to do |
| **Explanation** | Concept Explainer, Explainer, Socratic Method | Understand a concept | | **Explanation** | Concept Explainer, Socratic Method | Understand |
| **Transformation** | Transformation Journey, Mountain Structure, Atomic Habits | Personal change | | **Transformation** | Transformation Journey, Atomic Habits | Personal change |
| **Decision** | Big Idea, Problem-Solution, Case Study | Make informed decisions | | **Decision** | Big Idea, Case Study | Make decisions |
| **Reference** | Technical Manual, Quick Reference, Encyclopedia | Look up information | | **Reference** | Technical Manual, Quick Reference | Look up info |
| **Inspiration** | Visionary, Narrative, Memoir | Feel motivated |
### Educational/Academic ### Fiction
| Category | Frameworks | | Category | Frameworks |
|----------|-----------| |----------|-----------|
| **Textbooks** | Comprehensive Textbook, Textbook Chapter, Workbook | | **Snowflake** | One-page to novel |
| **Courses** | Online Course, Curriculum/Syllabus, Study Guide | | **Three-Act** | Classic structure |
| **Academic** | Empirical Paper, Theoretical Paper, Literature Review, Thesis | | **Hero's Journey** | Mythic structure |
| **Research** | Position Paper, Policy Brief, Meta-Analysis | | **Save the Cat** | Screenwriting |
| **Story Circle** | Dan Harmon's 8-part |
### Creative/Interactive ### RPG/Game Books
| Category | Frameworks | | Category | Frameworks |
|----------|-----------| |----------|-----------|
| **Branching** | Choose Your Own Adventure, Gamebook, Visual Novel | | **Rulebook** | Core rules, system |
| **Epistolary** | Epistolary Novel, Found Documents | | **Adventure** | Dungeon module, campaign |
| **Manifesto** | Manifesto, Open Letter | | **CYOA** | Choose Your Own Adventure |
| **Experimental** | Infinite Story, Fractal Narrative, Scrapbook |
| **Performance** | Podcast Script, Screenplay, Stage Play |
### RPG/Tabletop Gaming ## 📄 Output Formats
| Category | Frameworks | ### Scrivener Export
|----------|-----------| ```python
| **Core** | Core Rulebook, Quickstart | from opus_orchestrator import export_to_scrivener
| **GM Guides** | Game Master Guide, Adventure Module, Campaign Setting |
| **Supplements** | Player's Companion, Monster Manual, Sourcebook |
| **Adventure Types** | Dungeon Crawl, Hex Crawl, Sandbox |
## 🔧 Configuration result = export_to_scrivener(
manuscript,
"My Book",
split_chapters=True,
branch="draft/chapter-1",
push_to_remote=True,
)
```
Output: Individual `.md` files + `binder.json`
### Environment Variables ### LaTeX Templates (31)
```python
from opus_orchestrator import export_to_latex
```bash export_to_latex(manuscript, "My Book", "out.tex",
export OPENAI_API_KEY="your-key" # or template="kdp-trade")
export MINIMAX_API_KEY="your-key"
``` ```
### Config File (`opus.yaml`) **Templates:**
- **KDP**: pocket, trade, 6x9, square, large
- **Genre**: novel, memoir, romance, thriller, sci-fi
- **Academic**: textbook, academic, cleanthesis, classicthesis
- **Specialty**: poetry, cookbook, screenplay, RPG
```yaml ### HTML Export
agent: ```python
model: gpt-4o from opus_orchestrator import export_to_html
temperature: 0.7
max_tokens: 4000
output: html = export_to_html(manuscript, "My Book",
format: markdown template="memoir")
save_to_file: true
``` ```
## 💻 CLI Commands ## 🏭 Deployment
### Docker Compose
```bash ```bash
# Generate a book # Quick start
opus generate --concept "Your book idea" [options] cp .env.example .env
# Add your MINIMAX_API_KEY and GITHUB_TOKEN
# Options: docker-compose -f deployments/docker-compose.yml up -d
# --book-type {fiction,nonfiction} Book type ```
# --framework {snowflake,save-the-cat,...} Story framework
# --genre {sci-fi,fantasy,romance,...} Genre
# --purpose {learn,understand,transform,decide,reference,inspire} Reader purpose
# --category {business,leadership,memoir,...} Nonfiction category
# --words TARGET_WORD_COUNT Target word count
# --thread-id THREAD_ID Checkpoint ID for resume
# --resume Resume from checkpoint
# Serve API ### k3s/Helm
opus serve --port 8000 ```bash
# Install Opus API
helm install opus deployments/k3s/opus-orchestrator/
# List frameworks # Install TeX Live API (for PDF compilation)
opus frameworks helm install texlive deployments/k3s/texlive-api/
# Ingest from GitHub
opus ingest --repo https://github.com/user/repo
``` ```
## 🔌 REST API ## 🔌 REST API
@@ -146,89 +165,88 @@ curl -X POST http://localhost:8000/generate/stream \
-d '{"concept": "Your book idea"}' -d '{"concept": "Your book idea"}'
``` ```
## ⚙️ Configuration
### Environment Variables
```bash
export MINIMAX_API_KEY="your-key" # Primary
export GITHUB_TOKEN="your-token"
```
### Config File
```yaml
agent:
provider: minimax
model: MiniMax/MiniMax-M2.5
temperature: 0.7
output:
format: markdown
save_to_file: true
split_chapters: true
```
## 🧠 Architecture ## 🧠 Architecture
``` ```
User Input → Intent Classification → Framework Selection User Input → Intent Classification → Framework Selection
↓ ↓
Purpose Detection (learn/understand/transform/decide/reference/inspire) Purpose Detection (learn/understand/transform/decide)
↓ ↓
Framework匹配 (100+ frameworks by category) Framework匹配 (100+ frameworks)
↓ ↓
Agent Selection (purpose-specific writer + critique) Agent Selection (purpose-specific)
↓ ↓
Generation Pipeline (LangGraph/CrewAI/AutoGen) Generation (LangGraph/CrewAI/AutoGen)
↓ ↓
Manuscript Output Output (Scrivener/LaTeX/HTML/PDF)
``` ```
## 📦 Nonfiction Purpose System
The nonfiction pipeline uses **Purpose × Structure** classification:
### Reader Purposes
1. **LEARN_HANDS_ON** — Reader wants to DO something (tutorials, how-to)
2. **UNDERSTAND** — Reader wants to GRASP a concept (explanations)
3. **TRANSFORM** — Reader wants to CHANGE themselves (self-help, memoir)
4. **DECIDE** — Reader wants to MAKE A DECISION (business, analysis)
5. **REFERENCE** — Reader wants to LOOK UP info (manuals, documentation)
6. **BE_INSPIRED** — Reader wants to FEEL motivated (stories, manifestos)
### Framework Selection
The system automatically selects the best framework based on:
- Explicit flags (`--purpose`, `--category`)
- Keyword classification from concept
- Content analysis (for existing blogs/articles)
- Conversational Q&A (when ambiguous)
## 🔄 Checkpointing/Resume
Long generations can fail. Use checkpointing to resume:
```bash
# First run - saves checkpoint
opus generate --concept "My book" --thread-id my-book-001
# If it fails...
# Resume from checkpoint
opus generate --concept "My book" --thread-id my-book-001 --resume
```
## 🤖 Multi-Agent Systems
Opus supports three orchestration backends:
1. **LangGraph** — State machine with checkpointing
2. **CrewAI** — Sequential agent crews
3. **AutoGen** — Multi-agent debate/critique
## 📁 Project Structure ## 📁 Project Structure
``` ```
opus_orchestrator/ opus_orchestrator/
├── orchestrator.py # Main orchestration ├── orchestrator.py # Main orchestration
├── langgraph_workflow.py # LangGraph pipeline ├── server.py # REST API
├── crews/ # CrewAI crews ├── cli.py # CLI
├── autogen_critique.py # AutoGen critique ├── langgraph_workflow.py # LangGraph pipeline
├── agents/ # Agent definitions ├── nonfiction/ # Nonfiction system
│ ├── fiction/ # Fiction writers │ ├── classifier.py # Purpose classifier
│ └── nonfiction/ # Nonfiction writers + purpose-specific │ └── frameworks.py # 35+ frameworks
├── frameworks.py # Fiction frameworks ├── frameworks.py # Fiction frameworks
├── nonfiction/ # Nonfiction system ├── scrivener_export.py # Scrivener output
│ ├── classifier.py # Purpose classifier ├── latex_compile.py # LaTeX export
│ ├── intake.py # Intake agent ├── html_export.py # HTML output
│ ├── expanded_frameworks.py # 35+ frameworks ├── texlive_client.py # TeX Live API
│ ├── textbook_frameworks.py # Educational ├── templates/
│ ├── academic_papers.py # Academic types │ └── latex/ # 31 templates
│ ├── creative_frameworks.py # Interactive └── deployments/
│ └── rpg_frameworks.py # Tabletop RPG ├── docker-compose.yml
├── server.py # REST API └── k3s/
└── cli.py # CLI
``` ```
## 📄 License ## 📦 Test Suite
```bash
# Run tests
pytest tests/ -v
# Test categories
tests/
├── test_github_ingest.py # GitHub ingestion
├── test_s3_ingest.py # S3/Backblaze
├── test_generation.py # Document generation
├── test_output_push.py # Output push
└── test_e2e.py # End-to-end
```
## 🔗 Links
- [GitHub](https://github.com/mrhavens/opus-orchestrator-ai)
- [Issues](https://github.com/mrhavens/opus-orchestrator-ai/issues)
- [BECOMINGONE](https://github.com/mrhavens/becomingone)
## 📜 License
MIT MIT
@@ -236,7 +254,6 @@ MIT
Mark Havens Mark Havens
## 🔗 Links ---
- [GitHub](https://github.com/mrhavens/opus-orchestrator-ai) *Built with ♥ using MiniMax M2.5*
- [Documentation](https://github.com/mrhavens/opus-orchestrator-ai/docs)