opus-orchestrator-ai/README.md

Opus Orchestrator AI

A comprehensive AI-powered book generation system with LangGraph, CrewAI, and AutoGen.

🎯 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.

✨ Features

• 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

🚀 Quick Start

# Install
pip install opus-orchestrator

# Generate a book (fiction)
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"

# Resume from checkpoint
opus generate --thread-id abc123 --resume

📚 Framework Library

Opus supports 100+ frameworks organized by content type:

Nonfiction Categories

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

Educational/Academic

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

Creative/Interactive

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

RPG/Tabletop Gaming

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

🔧 Configuration

Environment Variables

export OPENAI_API_KEY="your-key"  # or
export MINIMAX_API_KEY="your-key"

Config File (opus.yaml)

agent:
  model: gpt-4o
  temperature: 0.7
  max_tokens: 4000

output:
  format: markdown
  save_to_file: true

💻 CLI Commands

# Generate a book
opus generate --concept "Your book idea" [options]

# 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

# Serve API
opus serve --port 8000

# List frameworks
opus frameworks

# Ingest from GitHub
opus ingest --repo https://github.com/user/repo

🔌 REST API

# Start server
opus serve

# Generate (blocking)
curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"concept": "Your book idea", "book_type": "fiction"}'

# Generate (streaming)
curl -X POST http://localhost:8000/generate/stream \
  -H "Content-Type: application/json" \
  -d '{"concept": "Your book idea"}'

🧠 Architecture

User Input → Intent Classification → Framework Selection
    ↓
Purpose Detection (learn/understand/transform/decide/reference/inspire)
    ↓
Framework匹配 (100+ frameworks by category)
    ↓
Agent Selection (purpose-specific writer + critique)
    ↓
Generation Pipeline (LangGraph/CrewAI/AutoGen)
    ↓
Manuscript Output

📦 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:

# 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

📄 License

MIT

👤 Author

Mark Havens

🔗 Links

• GitHub
• Documentation