Add comprehensive CLI, OpenAPI server, and documentation

CLI Commands: - generate: Full manuscript generation with full GitHub content - serve: Start FastAPI server with OpenAPI docs - ingest: Standalone GitHub ingestion - frameworks: List all story frameworks - config: Show configuration - docs: Show comprehensive docs (terminal/markdown/html) - api: Export OpenAPI spec Server: - FastAPI with /docs, /redoc interactive docs - /generate, /ingest, /frameworks, /health endpoints - OpenAPI 3.0 specification Documentation: - Terminal, markdown, and HTML formats - Full API reference - Framework documentation - Environment variables guide - Project structure Fix: Use full GitHub content as seed (not just 5000 chars)
2026-03-13 03:10:01 +00:00
parent 6d23707ae4
commit 64bea5cae6
4 changed files with 938 additions and 61 deletions
@@ -0,0 +1,317 @@
+"""Documentation generator for Opus Orchestrator."""
+
+from opus_orchestrator.frameworks import FRAMEWORKS
+
+
+def generate_docs(format: str = "terminal") -> str:
+    """Generate comprehensive documentation.
+    
+    Args:
+        format: Output format (terminal, markdown, html)
+    
+    Returns:
+        Formatted documentation string
+    """
+    if format == "markdown":
+        return generate_markdown()
+    elif format == "html":
+        return generate_html()
+    else:
+        return generate_terminal()
+
+
+def generate_terminal() -> str:
+    """Generate terminal-formatted documentation."""
+    return f"""
+╔══════════════════════════════════════════════════════════════════════╗
+║                    OPUS ORCHESTRATOR AI                              ║
+║              Full-Flow AI Book Generation System                     ║
+╚══════════════════════════════════════════════════════════════════════╝
+
+VERSION: 0.2.0
+
+───────────────────────────────────────────────────────────────────────
+📖 OVERVIEW
+───────────────────────────────────────────────────────────────────────
+
+Opus Orchestrator is a comprehensive AI book generation system that 
+transforms raw content into publication-ready manuscripts.
+
+TECHNOLOGY STACK:
+  • LangGraph     - Workflow orchestration & state management
+  • CrewAI        - Role-based agent crews  
+  • AutoGen       - Multi-agent critique & debate
+  • PydanticAI    - Structured output validation
+
+───────────────────────────────────────────────────────────────────────
+🚀 QUICK START
+───────────────────────────────────────────────────────────────────────
+
+# Install
+pip install opus-orchestrator-ai
+
+# Set environment variables
+export OPENAI_API_KEY="sk-..."
+export GITHUB_TOKEN="ghp_..."
+
+# Generate a manuscript
+opus generate --concept "A robot dreams of love" --words 5000
+
+# Or from GitHub repo
+opus generate --repo mrhavens/my-book-ideas --framework hero-journey
+
+# Start API server
+opus serve --port 8000
+
+───────────────────────────────────────────────────────────────────────
+📋 COMMANDS
+───────────────────────────────────────────────────────────────────────
+
+opus generate [OPTIONS]
+  Generate a manuscript
+  
+  --concept, -c        Seed concept or story idea
+  --repo, -r           GitHub repo to ingest
+  --framework, -f     Framework (snowflake, hero-journey, etc.)
+  --genre, -g          Genre (fiction, sci-fi, fantasy, etc.)
+  --type, -t           Book type (fiction, nonfiction)
+  --words, -w          Target word count (default: 5000)
+  --chapters, -n       Number of chapters (default: 3)
+  --tone               Writing tone (default: literary)
+  --use-crewai         Use CrewAI instead of LangGraph
+  --no-autogen         Disable AutoGen critique
+
+opus serve [OPTIONS]
+  Start OpenAPI REST server
+  
+  --host               Host to bind (default: 0.0.0.0)
+  --port, -p           Port to bind (default: 8000)
+  --reload             Enable auto-reload
+
+opus ingest --repo OWNER/REPO
+  Ingest content from GitHub
+
+opus frameworks
+  List available story frameworks
+
+opus config [--env]
+  Show configuration
+
+opus docs
+  Show this documentation
+
+opus api [--format json|yaml]
+  Show OpenAPI specification
+
+───────────────────────────────────────────────────────────────────────
+📚 STORY FRAMEWORKS
+───────────────────────────────────────────────────────────────────────
+{_format_frameworks()}
+───────────────────────────────────────────────────────────────────────
+🌐 API REFERENCE
+───────────────────────────────────────────────────────────────────────
+
+Base URL: http://localhost:8000
+
+Endpoints:
+  GET  /              → Redirect to /docs
+  GET  /health        → Health check
+  GET  /frameworks    → List frameworks
+  POST /generate      → Generate manuscript
+  POST /ingest        → Ingest from GitHub
+  
+Interactive Docs: http://localhost:8000/docs
+
+───────────────────────────────────────────────────────────────────────
+🔧 ENVIRONMENT VARIABLES
+───────────────────────────────────────────────────────────────────────
+
+OPENAI_API_KEY      Required for LLM calls (or MINIMAX_API_KEY)
+GITHUB_TOKEN        For accessing private repositories
+ANTHROPIC_API_KEY   Optional - alternative LLM provider
+
+───────────────────────────────────────────────────────────────────────
+📁 PROJECT STRUCTURE
+───────────────────────────────────────────────────────────────────────
+
+opus_orchestrator/
+├── __init__.py           # Main exports
+├── cli.py                # CLI entry point
+├── server.py             # FastAPI server
+├── orchestrator.py       # Main orchestrator
+├── langgraph_workflow.py # LangGraph pipeline
+├── autogen_critique.py   # AutoGen critique
+├── pydanticai_agent.py   # PydanticAI agents
+├── config.py             # Configuration
+├── frameworks.py         # Story frameworks
+├── agents/               # Agent implementations
+│   ├── fiction/          # Fiction agents
+│   └── nonfiction/      # Nonfiction agents
+├── crews/               # CrewAI crews
+│   ├── fiction_crew.py
+│   └── nonfiction_crew.py
+├── schemas/              # Pydantic schemas
+└── utils/                # Utilities
+    ├── github_ingest.py
+    ├── llm.py
+    └── docs.py
+
+───────────────────────────────────────────────────────────────────────
+💡 EXAMPLES
+───────────────────────────────────────────────────────────────────────
+
+# Generate a sci-fi novel
+opus generate \\
+  --concept "In 2150, humanity's last robot dreams of love" \\
+  --framework hero-journey \\
+  --genre science-fiction \\
+  --words 80000
+
+# Generate from your notes
+opus generate --repo mrhavens/my-novel-ideas \\
+  --framework snowflake \\
+  --chapters 12
+
+# Use CrewAI for faster generation
+opus generate --concept "Your idea" --use-crewai
+
+# API usage
+curl -X POST "http://localhost:8000/generate" \\
+  -H "Content-Type: application/json" \\
+  -d '{{"concept": "A love story", "target_word_count": 1000}}'
+
+───────────────────────────────────────────────────────────────────────
+📄 LICENSE
+───────────────────────────────────────────────────────────────────────
+
+MIT License
+
+Built with the WE Architecture — witness and co-creation in code.
+
+╚══════════════════════════════════════════════════════════════════════╝
+"""
+
+
+def generate_markdown() -> str:
+    """Generate Markdown documentation."""
+    return f"""# Opus Orchestrator AI
+
+> Full-flow AI book generation using LangGraph, CrewAI, AutoGen, and PydanticAI
+
+## Overview
+
+Opus Orchestrator transforms raw content into publication-ready manuscripts using a multi-agent system.
+
+## Installation
+
+```bash
+pip install opus-orchestrator-ai
+```
+
+## Quick Start
+
+```python
+from opus_orchestrator import run_opus
+
+result = await run_opus(
+    seed_concept="A robot dreams of love",
+    framework="snowflake",
+    genre="science-fiction",
+    target_word_count=5000,
+)
+```
+
+## CLI Usage
+
+```bash
+# Generate manuscript
+opus generate --concept "Your story" --words 5000
+
+# From GitHub
+opus generate --repo owner/repo --framework hero-journey
+
+# Start API
+opus serve --port 8000
+```
+
+## Story Frameworks
+
+{_format_frameworks_markdown()}
+
+## API
+
+See http://localhost:8000/docs for interactive API documentation.
+
+## Configuration
+
+Set these environment variables:
+
+- `OPENAI_API_KEY` - Required for LLM
+- `GITHUB_TOKEN` - For private repos
+- `MINIMAX_API_KEY` - Alternative LLM
+
+## License
+
+MIT
+"""
+
+
+def generate_html() -> str:
+    """Generate HTML documentation."""
+    terminal = generate_terminal()
+    # Simple HTML wrapper
+    return f"""<!DOCTYPE html>
+<html>
+<head>
+    <title>Opus Orchestrator AI</title>
+    <style>
+        body {{ font-family: monospace; background: #1e1e1e; color: #d4d4d4; padding: 20px; }}
+        pre {{ white-space: pre-wrap; }}
+    </style>
+</head>
+<body>
+    <pre>{terminal}</pre>
+</body>
+</html>"""
+
+
+def _format_frameworks() -> str:
+    """Format frameworks for terminal output."""
+    lines = []
+    for framework, info in FRAMEWORKS.items():
+        name = info.get("name", str(framework))
+        desc = info.get("description", "")
+        stages = info.get("stages", [])
+        beats = info.get("beats", [])
+        
+        lines.append(f"\n  {name}")
+        lines.append(f"    {desc}")
+        
+        if stages:
+            lines.append(f"    Stages: {len(stages)}")
+            for i, stage in enumerate(stages[:3], 1):
+                lines.append(f"      {i}. {stage}")
+            if len(stages) > 3:
+                lines.append(f"      ... and {len(stages) - 3} more")
+        
+        if beats:
+            lines.append(f"    Beats: {len(beats)}")
+            for beat in beats[:3]:
+                beat_name = beat[0] if isinstance(beat, tuple) else beat
+                lines.append(f"      • {beat_name}")
+            if len(beats) > 3:
+                lines.append(f"      ... and {len(beats) - 3} more")
+    
+    return "\n".join(lines)
+
+
+def _format_frameworks_markdown() -> str:
+    """Format frameworks for markdown."""
+    lines = []
+    for framework, info in FRAMEWORKS.items():
+        name = info.get("name", str(framework))
+        desc = info.get("description", "")
+        
+        lines.append(f"### {name}\n{desc}\n")
+    
+    return "\n".join(lines)