🎯 OrchestrAI

Autonomous Goal-Driven AI Orchestration Platform

Define goals. Orchestrate AI agents. Guarantee quality outcomes.

What is OrchestrAI?

OrchestrAI is an autonomous AI orchestration framework that transforms high-level objectives into executable tasks, coordinates multiple AI providers, and ensures outputs meet your quality standards.

Core Philosophy

Unlike simple chat wrappers, OrchestrAI implements a goal-centric execution model:

Goal → Requirements → Success Criteria → Task Decomposition → AI Execution → Validation

Key Capabilities

Capability	Description
Goal Definition	Structured goals with requirements and measurable success criteria
Multi-Provider Orchestration	7 AI providers, 20+ models, unified API interface
Task Decomposition	Break complex goals into executable AI tasks
Quality Validation	Verify AI outputs against defined success criteria
Execution Monitoring	Track progress and ensure goal alignment

Supported Providers

Provider	Models	Best For
OpenAI	GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo	General purpose, coding, multimodal
Anthropic	Claude Sonnet 4, Haiku 4, Opus 4	Reasoning, safety, long context
Google	Gemini 2.0 Flash, 1.5 Pro/Flash	Speed, 2M context window
DeepSeek	DeepSeek V3, R1	Cost-effective reasoning
xAI	Grok-2, Grok-2 Vision	Real-time knowledge
Cohere	Command R+, Command R	Enterprise RAG, tool use
Mistral	Mistral Large 3, Codestral	Multilingual, specialized coding

Quick Start

1. Clone and Install

git clone https://github.com/ChrisXHL/OrchestrAI.git
cd OrchestrAI
pip install -r requirements.txt

2. Configure API Keys

cp .env.local.example .env.local
# Edit .env.local with your API keys

# Example .env.local
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-api03-...
GOOGLE_API_KEY=AIza...
DEEPSEEK_API_KEY=sk-...
XAI_API_KEY=xai-...
COHERE_API_KEY=cov-...
MISTRAL_API_KEY=...

3. Run the Server

cd src
python main.py

Visit http://localhost:3000 for the web interface.

Or use uvicorn directly:

uvicorn src.main:app --reload --port 3000

Architecture

OrchestrAI/
├── src/
│   ├── main.py              # FastAPI application entry point
│   ├── models/              # Data models (Goal, Task, Project, ProviderConfig)
│   ├── providers/           # AI provider integrations (OpenAI, Anthropic, etc.)
│   └── web/
│       ├── templates/       # Jinja2 HTML templates
│       └── static/          # Static assets (CSS, JS, images)
├── config/
│   ├── models.yaml          # Model configurations and pricing
│   └── providers.yaml       # Provider settings
├── docs/                    # MkDocs documentation
│   ├── guides/              # User guides
│   ├── api/                 # API reference
│   └── deployment/          # Deployment guides
├── tests/                   # Test suite
└── site/                    # Built documentation (GitHub Pages)

API Overview

Base URL

http://localhost:3000

Key Endpoints

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/providers	List configured providers
POST	/api/chat	Send chat request to AI
POST	/api/projects	Create a new project
POST	/api/projects/{id}/goals	Create goal in project
POST	/api/goals/{id}/tasks	Create task for goal

Example: Create a Goal

curl -X POST http://localhost:3000/api/projects/{project_id}/goals \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Build a REST API",
    "description": "Create a production-ready REST API with FastAPI",
    "requirements": ["Authentication", "CRUD operations", "Tests"],
    "success_criteria": ["Passes linting", "80% test coverage", "Dockerized"],
    "provider": "openai",
    "model": "gpt-4o"
  }'

Documentation

• Quick Start
• Configuration Guide
• API Reference
• Deployment

Build and preview docs locally:

mkdocs serve
# Visit http://localhost:8000

Use Cases

Autonomous Code Generation

goal = Goal(
    title="Build e-commerce API",
    requirements=["User auth", "Product CRUD", "Order management"],
    success_criteria=["Passes tests", "Dockerized", "API docs generated"]
)
# OrchestrAI decomposes into tasks and coordinates AI execution

Research & Analysis

goal = Goal(
    title="Analyze market trends",
    requirements=["Data sources", "Visualizations", "Summary"],
    success_criteria=["5+ sources", "3 charts", "Executive summary"]
)
# Tasks delegated to best-suited models for each subtask

Document Generation

goal = Goal(
    title="Generate technical documentation",
    requirements=["API reference", "Examples", "Architecture diagram"],
    success_criteria=["Complete coverage", "Code examples pass", "Diagrams render"]
)
# Quality validated against success criteria

Why OrchestrAI?

Technical Dimension	OrchestrAI	Standard Chatbots
Execution Model	Dynamic task decomposition with dependency graph management	Static prompt engineering with no task structure
Multi-Model Routing	Automatic routing with fallback chains, cost-aware model selection	Single model per conversation, no fallback
Quality Gates	Criteria-based validation gates (pass/fail on success criteria)	Post-hoc quality assessment via prompting
State Management	Stateful goal tracking with progress persistence across sessions	Stateless conversations, context lost on reload
API Abstraction	Provider-agnostic unified interface (swap providers without code changes)	Provider-locked implementations
Error Handling	Automatic retry with exponential backoff, circuit breaker patterns	Manual error handling per call
Execution Control	Parallel task execution, conditional task dependencies	Sequential single-turn interactions
Context Optimization	Intelligent context window management, summary-based truncation	No context optimization, context limit errors

Technical Architecture Advantages

1. Dynamic Task Decomposition

OrchestrAI transforms high-level goals into executable task graphs with dependency management:

graph TD
    A[Goal: Build E-commerce API] --> B[Analyze Requirements]
    B --> C{Dependency Analysis}
    C --> D[Database Schema Design]
    C --> E[User Auth Implementation]
    C --> F[Product API]
    D --> E
    D --> F
    E --> G[Shopping Cart]
    F --> G
    G --> H[Order Pipeline]
    H --> I[OpenAPI Docs]
    H --> J[Unit Tests]
    I & J --> K[Quality Validation]
    K --> L{All Pass?}
    L -->|Yes| M[Goal Complete]
    L -->|No| N[Revise & Retry]
    N --> B

Loading

Key features:

• Automatic dependency detection between tasks
• Parallel execution of independent tasks
• Conditional task execution based on upstream results

📂 Full example: examples/task_decomposition.py

2. Provider-Agnostic Abstraction Layer

Unified interface for 7 AI providers - swap providers without code changes:

from src.providers import create_provider
from src.models import ProviderConfig

# Configure providers
config = ProviderConfig(
    provider_id="openai",
    api_key="sk-...",
    default_model="gpt-4o"
)

# SAME code works with ANY provider
provider = create_provider("openai", config)
# ^ Swap "anthropic", "google", "deepseek", etc.

response = provider.complete(
    prompt="Explain quantum computing",
    model=config.default_model,
    temperature=0.7
)

Supported providers:

• OpenAI (GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo)
• Anthropic (Claude Sonnet 4, Haiku 4, Opus 4)
• Google (Gemini 2.0 Flash, 1.5 Pro/Flash)
• DeepSeek (DeepSeek V3, DeepSeek R1)
• xAI (Grok-2, Grok-2 Vision)
• Cohere (Command R+, Command R)
• Mistral (Mistral Large 3, Codestral)

📂 Full example: examples/provider_abstraction.py

3. Automatic Fallback & Retry with Circuit Breaker

Resilient routing with automatic failover and circuit breaker patterns:

from src.routing import SmartRouter

router = SmartRouter()

# Automatic fallback chain with circuit breaker
result = await router.route_with_fallback(
    prompt="Write a Python function",
    primary_provider="openai",
    primary_model="gpt-4o",
    max_retries=3
)

# Flow:
# 1. Try primary (gpt-4o)
# 2. If fails → try claude-sonnet-4
# 3. If fails → try gemini-1.5-pro
# 4. Apply circuit breaker (skip unhealthy providers)
# 5. Track costs and latency per provider

Circuit breaker states:

• 🟢 HEALTHY: Provider accepting requests
• 🟡 DEGRADED: Provider responding slowly
• 🔴 CIRCUIT_OPEN: Provider blocked (failure threshold reached)

📂 Full example: examples/fallback_routing.py

4. Quality Validation Pipeline

Criteria-based gates that validate every output against defined success criteria:

from src.models import Goal
from src.validation import QualityGate

# Define goal with measurable success criteria
goal = Goal(
    title="Build E-commerce API",
    success_criteria=[
        "Tests pass",
        "Type errors: 0",
        "Coverage > 80%",
        "Passes linting",
        "API docs generated",
        "No security vulnerabilities"
    ]
)

# Quality gate validates each output
gate = QualityGate(goal_id=goal.id, success_criteria=goal.success_criteria)
results = gate.validate(output_code, metadata)

# Results:
# ✅ Tests pass - All 15 tests passed
# ✅ Type errors: 0 - No type errors found
# ✅ Coverage > 80% - Coverage at 92%
# ✅ Passes linting - No linting issues
# ✅ API docs generated - OpenAPI spec valid
# ✅ No security vulnerabilities - Scan clean

📂 Full example: examples/quality_validation.py

Running the Examples

# Clone and install
git clone https://github.com/ChrisXHL/OrchestrAI.git
cd OrchestrAI
pip install -r requirements.txt

# Run any example
python examples/task_decomposition.py
python examples/provider_abstraction.py
python examples/fallback_routing.py
python examples/quality_validation.py

All examples include:

• ✅ Working Python code you can run immediately
• ✅ Console output showing expected behavior
• ✅ Integration with OrchestrAI's core modules

When to Use OrchestrAI

Use Case	Recommendation
Quick one-off questions	Standard chatbot
Complex multi-step objectives	OrchestrAI
Production AI integration	OrchestrAI
Cost-optimized AI operations	OrchestrAI
Cross-provider model evaluation	OrchestrAI

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

---

Autonomous Goal-Driven AI Orchestration

GitHub · Docs