diff --git a/README.md b/README.md index 73fa690..29447ef 100644 --- a/README.md +++ b/README.md @@ -4,23 +4,43 @@

Python - LangGraph - CrewAI - AutoGen - Pydantic + MiniMax + KDP + Docker/k3s

## 🎯 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 +### Core Capabilities - **Multi-Framework Orchestration**: LangGraph, CrewAI, and AutoGen - **Intelligent Purpose Classification**: Automatically determines reader purpose - **100+ Content Frameworks**: From textbooks to RPG modules - **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 @@ -32,101 +52,100 @@ pip install opus-orchestrator opus generate --concept "A robot who dreams of being human" --genre sci-fi # 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 -opus generate --thread-id abc123 --resume +# Serve API +opus serve --port 8000 ``` ## πŸ“š Framework Library Opus supports **100+ frameworks** organized by content type: -### Nonfiction Categories +### Nonfiction | Category | Frameworks | Purpose | |----------|-----------|---------| -| **Tutorial/How-To** | Tutorial, Howto, Minimalist How-To, Challenge-Response | Learn to do something | -| **Explanation** | Concept Explainer, Explainer, Socratic Method | Understand a concept | -| **Transformation** | Transformation Journey, Mountain Structure, Atomic Habits | Personal change | -| **Decision** | Big Idea, Problem-Solution, Case Study | Make informed decisions | -| **Reference** | Technical Manual, Quick Reference, Encyclopedia | Look up information | -| **Inspiration** | Visionary, Narrative, Memoir | Feel motivated | +| **Tutorial/How-To** | Tutorial, Howto, Minimalist How-To | Learn to do | +| **Explanation** | Concept Explainer, Socratic Method | Understand | +| **Transformation** | Transformation Journey, Atomic Habits | Personal change | +| **Decision** | Big Idea, Case Study | Make decisions | +| **Reference** | Technical Manual, Quick Reference | Look up info | -### Educational/Academic +### Fiction | Category | Frameworks | |----------|-----------| -| **Textbooks** | Comprehensive Textbook, Textbook Chapter, Workbook | -| **Courses** | Online Course, Curriculum/Syllabus, Study Guide | -| **Academic** | Empirical Paper, Theoretical Paper, Literature Review, Thesis | -| **Research** | Position Paper, Policy Brief, Meta-Analysis | +| **Snowflake** | One-page to novel | +| **Three-Act** | Classic structure | +| **Hero's Journey** | Mythic structure | +| **Save the Cat** | Screenwriting | +| **Story Circle** | Dan Harmon's 8-part | -### Creative/Interactive +### RPG/Game Books | Category | Frameworks | |----------|-----------| -| **Branching** | Choose Your Own Adventure, Gamebook, Visual Novel | -| **Epistolary** | Epistolary Novel, Found Documents | -| **Manifesto** | Manifesto, Open Letter | -| **Experimental** | Infinite Story, Fractal Narrative, Scrapbook | -| **Performance** | Podcast Script, Screenplay, Stage Play | +| **Rulebook** | Core rules, system | +| **Adventure** | Dungeon module, campaign | +| **CYOA** | Choose Your Own Adventure | -### RPG/Tabletop Gaming +## πŸ“„ Output Formats -| Category | Frameworks | -|----------|-----------| -| **Core** | Core Rulebook, Quickstart | -| **GM Guides** | Game Master Guide, Adventure Module, Campaign Setting | -| **Supplements** | Player's Companion, Monster Manual, Sourcebook | -| **Adventure Types** | Dungeon Crawl, Hex Crawl, Sandbox | +### Scrivener Export +```python +from opus_orchestrator import export_to_scrivener -## πŸ”§ 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 OPENAI_API_KEY="your-key" # or -export MINIMAX_API_KEY="your-key" +export_to_latex(manuscript, "My Book", "out.tex", + template="kdp-trade") ``` -### 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 -agent: - model: gpt-4o - temperature: 0.7 - max_tokens: 4000 +### HTML Export +```python +from opus_orchestrator import export_to_html -output: - format: markdown - save_to_file: true +html = export_to_html(manuscript, "My Book", + template="memoir") ``` -## πŸ’» CLI Commands +## 🏭 Deployment +### Docker Compose ```bash -# Generate a book -opus generate --concept "Your book idea" [options] +# Quick start +cp .env.example .env +# Add your MINIMAX_API_KEY and GITHUB_TOKEN -# Options: -# --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 +docker-compose -f deployments/docker-compose.yml up -d +``` -# Serve API -opus serve --port 8000 +### k3s/Helm +```bash +# Install Opus API +helm install opus deployments/k3s/opus-orchestrator/ -# List frameworks -opus frameworks - -# Ingest from GitHub -opus ingest --repo https://github.com/user/repo +# Install TeX Live API (for PDF compilation) +helm install texlive deployments/k3s/texlive-api/ ``` ## πŸ”Œ REST API @@ -146,89 +165,88 @@ curl -X POST http://localhost:8000/generate/stream \ -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 ``` 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 ``` opus_orchestrator/ -β”œβ”€β”€ orchestrator.py # Main orchestration -β”œβ”€β”€ langgraph_workflow.py # LangGraph pipeline -β”œβ”€β”€ crews/ # CrewAI crews -β”œβ”€β”€ autogen_critique.py # AutoGen critique -β”œβ”€β”€ agents/ # Agent definitions -β”‚ β”œβ”€β”€ fiction/ # Fiction writers -β”‚ └── nonfiction/ # Nonfiction writers + purpose-specific -β”œβ”€β”€ frameworks.py # Fiction frameworks -β”œβ”€β”€ nonfiction/ # Nonfiction system -β”‚ β”œβ”€β”€ classifier.py # Purpose classifier -β”‚ β”œβ”€β”€ intake.py # Intake agent -β”‚ β”œβ”€β”€ expanded_frameworks.py # 35+ frameworks -β”‚ β”œβ”€β”€ textbook_frameworks.py # Educational -β”‚ β”œβ”€β”€ academic_papers.py # Academic types -β”‚ β”œβ”€β”€ creative_frameworks.py # Interactive -β”‚ └── rpg_frameworks.py # Tabletop RPG -β”œβ”€β”€ server.py # REST API -└── cli.py # CLI +β”œβ”€β”€ orchestrator.py # Main orchestration +β”œβ”€β”€ server.py # REST API +β”œβ”€β”€ cli.py # CLI +β”œβ”€β”€ langgraph_workflow.py # LangGraph pipeline +β”œβ”€β”€ nonfiction/ # Nonfiction system +β”‚ β”œβ”€β”€ classifier.py # Purpose classifier +β”‚ └── frameworks.py # 35+ frameworks +β”œβ”€β”€ frameworks.py # Fiction frameworks +β”œβ”€β”€ scrivener_export.py # Scrivener output +β”œβ”€β”€ latex_compile.py # LaTeX export +β”œβ”€β”€ html_export.py # HTML output +β”œβ”€β”€ texlive_client.py # TeX Live API +β”œβ”€β”€ templates/ +β”‚ └── latex/ # 31 templates +└── deployments/ + β”œβ”€β”€ docker-compose.yml + └── k3s/ ``` -## πŸ“„ 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 @@ -236,7 +254,6 @@ MIT Mark Havens -## πŸ”— Links +--- -- [GitHub](https://github.com/mrhavens/opus-orchestrator-ai) -- [Documentation](https://github.com/mrhavens/opus-orchestrator-ai/docs) +*Built with β™₯ using MiniMax M2.5*