Semantic Orchestration Framework

A cloud-agnostic, configuration-driven framework for building hierarchical multi-agent systems with LangGraph and PydanticAI.

What is this?

Semantic Orchestration is a declarative framework for orchestrating complex agentic workflows. Instead of hard-coding agent interactions, you define:

• Roles (agent templates with capabilities)
• Agents (instances of roles with specific context)
• Workflows (how agents collaborate to solve tasks)
• MCP Servers (external tools provided via Model Context Protocol)

All through YAML configuration. The framework handles the orchestration, LLM provider abstraction, and execution.

Key Features

✨ Declarative Configuration: Define agents and workflows in YAML, not code
🔌 Provider Agnostic: Works with any LiteLLM-compatible provider (OpenAI, Anthropic, DeepSeek, Qwen, etc.)
🏗️ Hierarchical Orchestration: Delegate complex tasks to sub-orchestration networks
🔧 MCP Integration: First-class support for Model Context Protocol tools via JSON/YAML configs
📦 Container-Ready: Develop in devcontainers, deploy anywhere (Docker, K8s)
🎯 Registry-Factory Pattern: Add capabilities without modifying core engine

Quick Start

Prerequisites

• Python 3.13+
• Docker (for devcontainer)
• uv package manager

Installation

# Clone repository
git clone https://github.com/your-org/semantic-orchestration.git
cd semantic-orchestration

# Install dependencies
uv sync

# Set up environment
cp .env.example .env  # Add your API keys

# Run example
uv run python examples/basic_agent.py

Devcontainer Setup (Recommended)

# Open in neovim with devcontainer extension
nvim .

# Container auto-builds and attaches
# All dependencies pre-installed

Configuration

The framework follows a Component-Entity-System (CES) pattern:

config/
├── roles/       # Templates: "What can an agent do?"
├── agents/      # Instances: "A specific agent with context"
├── workflows/   # Topology: "How do agents work together?"
└── mcp/         # Tools: "External tool providers (MCP)"

Example: Code Review Workflow

1. Define a Role (config/roles/code_reviewer.yaml)

role_id: code_reviewer
llm_config:
  model: deepseek-chat
  temperature: 0.1
system_prompt: |
  You are an expert code reviewer. Analyze code for:
  - Bugs and potential issues
  - Best practices adherence
  - Performance concerns
tools:
  - read_file
  - analyze_ast

2. Create an Agent (config/agents/python_reviewer.yaml)

agent_id: python_reviewer
role: code_reviewer
system_prompt_variables:
  language: Python
  style_guide: PEP 8
llm_overrides:
  temperature: 0.05  # More deterministic

3. Define a Workflow (config/workflows/code_review.yaml)

workflow_id: code_review_workflow
supervisor: review_coordinator
workers:
  - python_reviewer
  - security_analyzer
  - performance_checker
execution: parallel

4. Run It

from src.core.orchestrator import Orchestrator

orch = Orchestrator.from_config("config/")
result = orch.run_workflow(
    workflow_id="code_review_workflow",
    input={"file_path": "src/main.py"}
)

Why Configuration-Driven?

Before (traditional code):

# Hard-coded agents and logic
reviewer = CodeReviewer(model="gpt-4")
security = SecurityAnalyzer(model="claude-3")
result = await run_parallel([reviewer, security])

After (semantic orchestration):

# Declarative YAML
workflow:
  workers: [code_reviewer, security_analyzer]
  execution: parallel

Benefits:

• ✅ No code changes to add/remove agents
• ✅ A/B test different models via config
• ✅ Non-engineers can modify workflows
• ✅ Version control agent behaviours

Use Cases

Hierarchical Task Delegation

• Complex research with specialized sub-agents
• Multi-stage pipelines (data → analysis → report)

Dense Knowledge Integration

• Multiple MCP servers (docs, databases, APIs)
• Declarative tool access via config

Multi-Provider Orchestration

• Brain agent (DeepSeek) plans, workers (Qwen) execute
• Automatic failover between providers

Development

This project uses:

• beads (bd) for issue tracking
• uv for Python package management
• neovim + devcontainer for development
• jujutsu/git for version control

Quick Dev Commands

# Find work
bd ready

# Run tests
uv run pytest

# Type check
uv run mypy src/

# Run example
uv run python examples/basic_agent.py

See DEVELOPMENT.md for detailed setup and workflow.

Documentation

• ARCHITECTURE.MD - Technical patterns and design principles
• DEVELOPMENT.md - Setup, workflow, and troubleshooting
• AGENTS.md - Quick reference for AI agents and developers

Roadmap

Active development tracked in beads:

bd list --status=open  # See planned work
bd stats               # Project health

License

MIT License - see LICENSE for details.

---

Built with ❤️ using LangGraph, PydanticAI, and modern Python tooling.

Quick Start

1. Set up environment:

   cp .env.example .env
   # Add your OPENROUTER_API_KEY to .env

2. Run locally:

   uv run uvicorn src.api.server:app --reload

3. Or run in Docker:

   docker compose -f docker/docker-compose.dev.yml up

4. Invoke the agent:

   curl -X POST http://localhost:8000/invoke \
     -H "Content-Type: application/json" \
     -d '{"agent_id": "researcher", "input": "What is quantum computing?"}'

The agent will respond using the configured LLM via OpenRouter.