{"id":48133912,"url":"https://github.com/cheesejaguar/sopher.ai","last_synced_at":"2026-04-04T16:42:49.579Z","repository":{"id":309887614,"uuid":"1037877907","full_name":"cheesejaguar/sopher.ai","owner":"cheesejaguar","description":"📚 AI book-writing platform that transforms author briefs into complete manuscripts using multi-agent CrewAI system. Built with FastAPI backend, Next.js frontend, real-time SSE streaming, PostgreSQL/Redis storage, and comprehensive cost   tracking. Production-ready with Kubernetes deployment. ✨🤖","archived":false,"fork":false,"pushed_at":"2026-02-17T00:29:06.000Z","size":2530,"stargazers_count":5,"open_issues_count":21,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-17T00:30:17.062Z","etag":null,"topics":["agentic-ai","crewai","docker","fastapi","generative-ai","langchain","litellm","llm","nextjs14","tailwindcss"],"latest_commit_sha":null,"homepage":"https://sopher.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cheesejaguar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_AUDIT.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-14T09:03:38.000Z","updated_at":"2026-02-17T00:29:09.000Z","dependencies_parsed_at":"2025-08-14T11:45:27.341Z","dependency_job_id":null,"html_url":"https://github.com/cheesejaguar/sopher.ai","commit_stats":null,"previous_names":["cheesejaguar/sopher.ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cheesejaguar/sopher.ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesejaguar%2Fsopher.ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesejaguar%2Fsopher.ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesejaguar%2Fsopher.ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesejaguar%2Fsopher.ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cheesejaguar","download_url":"https://codeload.github.com/cheesejaguar/sopher.ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesejaguar%2Fsopher.ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","crewai","docker","fastapi","generative-ai","langchain","litellm","llm","nextjs14","tailwindcss"],"created_at":"2026-04-04T16:42:49.047Z","updated_at":"2026-04-04T16:42:49.561Z","avatar_url":"https://github.com/cheesejaguar.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sopher.ai\n\n[![CI/CD Pipeline](https://github.com/cheesejaguar/sopher.ai/actions/workflows/ci.yml/badge.svg)](https://github.com/cheesejaguar/sopher.ai/actions/workflows/ci.yml)\n[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAn AI-powered book writing system that transforms author briefs into complete manuscripts using a multi-agent pipeline with real-time streaming and cost controls.\n\n## Overview\n\nsopher.ai orchestrates five specialized AI agents to generate novels from a simple brief:\n\n1. **Concept Generator** - Expands briefs into rich story concepts with themes, settings, and conflicts\n2. **Outliner** - Creates detailed chapter-by-chapter structure with plot threads and character arcs\n3. **Writer** - Generates prose following style guides and maintaining voice consistency\n4. **Editor** - Performs structural editing, pacing adjustments, and prose polish\n5. **Continuity Checker** - Validates consistency across characters, timeline, and plot details\n\nThe system uses a thin orchestration layer built on [LiteLLM](https://github.com/BerriAI/litellm) for model routing, providing full control over prompts and generation flow without heavy framework dependencies.\n\n## Features\n\n- **Real-time Streaming** - Server-Sent Events with sub-300ms latency for live generation feedback\n- **Multi-Model Support** - Route between GPT-4, Claude, Gemini with automatic fallbacks\n- **Structured Outputs** - Pydantic models ensure type-safe, validated responses from LLMs\n- **Cost Management** - Per-agent budget allocation with real-time tracking and limits\n- **Parallel Generation** - Write multiple chapters concurrently with shared context\n- **Genre Templates** - Specialized prompts for mystery, romance, fantasy, thriller, and more\n- **Style Learning** - Analyze and replicate author voice from sample text\n- **Export Formats** - Generate manuscripts in Markdown, plain text, or structured JSON\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| **Backend** | FastAPI, SQLAlchemy (async), PostgreSQL, Redis |\n| **AI Orchestration** | LiteLLM, Pydantic, custom Agent framework |\n| **Frontend** | Next.js 14 (App Router), TypeScript, Tailwind CSS, Zustand |\n| **Infrastructure** | Docker, Kubernetes (GKE), Prometheus, Grafana |\n| **CI/CD** | GitHub Actions, CodeQL, Semgrep |\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.12+\n- Node.js 20+\n- Docker \u0026 Docker Compose\n- API keys for at least one LLM provider (OpenAI, Anthropic, or Google)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/cheesejaguar/sopher.ai.git\ncd sopher.ai\n\n# Copy environment template\ncp .env.example .env\n\n# Add your API keys to .env (at minimum, one of these):\n# OPENAI_API_KEY=sk-...\n# ANTHROPIC_API_KEY=sk-ant-...\n# GOOGLE_API_KEY=AI...\n```\n\n### Run with Docker (Recommended)\n\n```bash\ncd infra\ndocker-compose -f docker-compose.dev.yml up\n```\n\nAccess the application:\n- **Frontend**: http://localhost:3000\n- **API Docs**: http://localhost:8000/docs\n- **Prometheus**: http://localhost:9090\n\n### Run Locally\n\n```bash\n# Terminal 1: Backend\ncd backend\npip install -e .[dev]\nuvicorn app.main:app --reload\n\n# Terminal 2: Frontend\ncd frontend\nnpm install\nnpm run dev\n```\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                         Next.js Frontend                          │\n│                    (SSE streaming, Zustand state)                 │\n└─────────────────────────────┬────────────────────────────────────┘\n                              │ HTTP/SSE\n┌─────────────────────────────▼────────────────────────────────────┐\n│                         FastAPI Backend                           │\n│                                                                   │\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │\n│  │   Routers   │  │  Services   │  │   Agents    │              │\n│  │  (outline,  │──│  (chapter,  │──│  (concept,  │              │\n│  │  chapters,  │  │  continuity,│  │  outline,   │              │\n│  │  export)    │  │  export)    │  │  writer,    │              │\n│  └─────────────┘  └─────────────┘  │  editor,    │              │\n│                                     │  continuity)│              │\n│                                     └──────┬──────┘              │\n└────────────────────────────────────────────┼─────────────────────┘\n                                             │\n┌────────────────────────────────────────────▼─────────────────────┐\n│                          LiteLLM Router                           │\n│                                                                   │\n│     ┌─────────┐      ┌─────────┐      ┌─────────┐               │\n│     │ GPT-4/5 │      │ Claude  │      │ Gemini  │               │\n│     │(primary)│ ───▶ │(fallback│ ───▶ │(overflow│               │\n│     └─────────┘      └─────────┘      └─────────┘               │\n└───────────────────────────────────────────────────────────────────┘\n                              │\n        ┌─────────────────────┼─────────────────────┐\n        ▼                     ▼                     ▼\n┌───────────────┐    ┌───────────────┐    ┌───────────────┐\n│  PostgreSQL   │    │     Redis     │    │  Prometheus   │\n│  (projects,   │    │   (cache,     │    │   (metrics,   │\n│   artifacts)  │    │  rate limits) │    │   monitoring) │\n└───────────────┘    └───────────────┘    └───────────────┘\n```\n\n## API Reference\n\n### Core Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v1/projects` | POST | Create a new book project |\n| `/api/v1/projects/{id}/outline/stream` | GET | Stream outline generation |\n| `/api/v1/projects/{id}/chapters/{n}/generate/stream` | POST | Stream chapter generation |\n| `/api/v1/projects/{id}/chapters/{n}/edit/stream` | POST | Stream editorial pass |\n| `/api/v1/projects/{id}/continuity/check` | POST | Run continuity validation |\n| `/api/v1/projects/{id}/export` | GET | Export manuscript |\n\n### SSE Event Format\n\n```typescript\n// Token stream\n{ \"event\": \"token\", \"data\": \"The story begins...\" }\n\n// Progress checkpoint\n{ \"event\": \"checkpoint\", \"data\": {\"stage\": \"writing\", \"progress\": 0.45} }\n\n// Completion\n{ \"event\": \"complete\", \"data\": {\"tokens\": 3500, \"duration\": 12.3} }\n```\n\n## Agent System\n\nThe agent system uses a thin abstraction over LiteLLM:\n\n```python\nfrom app.agents import BookPipeline\n\npipeline = BookPipeline(model=\"gpt-4\")\n\n# Generate a complete book\nasync for item in pipeline.generate_book(\n    brief=\"A detective novel set in 1920s Chicago\",\n    num_chapters=12\n):\n    if isinstance(item, GenerationProgress):\n        print(f\"Stage: {item.stage}, Progress: {item.progress}\")\n    elif isinstance(item, Chapter):\n        print(f\"Chapter {item.number}: {item.title}\")\n```\n\n### Custom Agents\n\nCreate specialized agents with structured outputs:\n\n```python\nfrom app.agents import Agent, AgentConfig\nfrom pydantic import BaseModel\n\nclass CharacterProfile(BaseModel):\n    name: str\n    background: str\n    motivations: list[str]\n\nconfig = AgentConfig(\n    role=\"character_designer\",\n    system_prompt=\"You create detailed character profiles...\",\n    model=\"gpt-4\",\n    temperature=0.8\n)\n\nagent = Agent(config, response_model=CharacterProfile)\nprofile = await agent.run(\"Create a villain for a noir mystery\")\n```\n\n## Development\n\n### Running Tests\n\n```bash\ncd backend\n\n# Run all tests with coverage\npytest tests/ -v --cov=app\n\n# Run specific test file\npytest tests/test_agents/test_orchestrator.py -v\n\n# Run with parallel execution\npytest tests/ -n auto\n```\n\nCurrent test coverage: **86%** with **2280+ tests**\n\n### Code Quality\n\n```bash\ncd backend\n\n# Format code\nblack app tests\n\n# Lint\nruff check app tests\n\n# Type check\nmypy app\n\n# Run all checks\nblack app tests \u0026\u0026 ruff check app tests \u0026\u0026 mypy app \u0026\u0026 pytest tests/\n```\n\n### Frontend Development\n\n```bash\ncd frontend\n\nnpm run dev          # Start dev server\nnpm run build        # Production build\nnpm run lint         # ESLint\nnpm run type-check   # TypeScript validation\nnpm run test         # Run tests\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `OPENAI_API_KEY` | OpenAI API key | - |\n| `ANTHROPIC_API_KEY` | Anthropic API key | - |\n| `GOOGLE_API_KEY` | Google AI API key | - |\n| `DATABASE_URL` | PostgreSQL connection | `postgresql+asyncpg://postgres:postgres@localhost:5432/sopherai` |\n| `REDIS_URL` | Redis connection | `redis://localhost:6379/0` |\n| `JWT_SECRET` | JWT signing secret (min 32 chars) | - |\n| `MONTHLY_BUDGET_USD` | Cost limit per user | `100` |\n| `PRIMARY_MODEL` | Default LLM model | `gpt-4` |\n| `LOG_LEVEL` | Logging verbosity | `INFO` |\n\n### Model Configuration\n\nConfigure model routing in code or via environment:\n\n```python\npipeline = BookPipeline(\n    model=\"gpt-4\",\n    fallback_models=[\"claude-3-opus\", \"gemini-pro\"],\n    temperature=0.7,\n    max_tokens=4000\n)\n```\n\n## Deployment\n\n### Kubernetes (GKE)\n\n```bash\n# Build images\ndocker build -t ghcr.io/your-org/sopher-api:latest backend/\ndocker build -t ghcr.io/your-org/sopher-web:latest frontend/\n\n# Push to registry\ndocker push ghcr.io/your-org/sopher-api:latest\ndocker push ghcr.io/your-org/sopher-web:latest\n\n# Deploy\nkubectl apply -f infra/k8s/\n\n# Create secrets\nkubectl create secret generic sopher-secrets \\\n  --from-literal=OPENAI_API_KEY=$OPENAI_API_KEY \\\n  --from-literal=JWT_SECRET=$(openssl rand -hex 32)\n```\n\n### Health Checks\n\n| Endpoint | Purpose |\n|----------|---------|\n| `/healthz` | Basic health check |\n| `/readyz` | Readiness probe (DB + Redis) |\n| `/livez` | Liveness probe |\n\n## Monitoring\n\nPrometheus metrics available at `/api/metrics`:\n\n- `llm_inference_seconds` - LLM response latency histogram\n- `llm_tokens_total` - Token usage by model and agent\n- `llm_cost_usd_total` - Cost tracking\n- `active_sessions` - Concurrent generation sessions\n- `cache_hits_total` / `cache_misses_total` - Cache efficiency\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Run tests and linting (`pytest \u0026\u0026 ruff check \u0026\u0026 mypy app`)\n4. Commit changes (`git commit -m 'Add amazing feature'`)\n5. Push to branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\nThe CI pipeline runs automatically on PRs - all checks must pass before merging.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheesejaguar%2Fsopher.ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheesejaguar%2Fsopher.ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheesejaguar%2Fsopher.ai/lists"}