orqest 0.8.0

Typed agent primitives and orchestration on top of pydantic-ai — memory, autonomy, healing, metacognition, generative UI, MCP, optimization.

Orqest

A Python library for building agentic harnesses on top of pydantic-ai. Not an agent framework with a runtime, server, or UI of its own — Orqest ships the plumbing you import to build those: typed agents, composition primitives, lifecycle hooks, memory typology, runtime agent design, metacognition, self-healing, and generative UI. All opt-in.

Status: v0.8.0. The five novel cognitive-substrate features shipped in [0.2.0] (2026-04-25): runtime agent design, cognitive memory typology, metacognition primitives, self-healing primitives, generative UI. [0.3.0]–[0.4.0] were the reconcile + advance passes that brought preview-tier capabilities into Tier 1. [0.8.0] adds the orqest.optimization battery (GEPA-powered prompt + topology evolution), the Tier-2 Docker sandbox with per-user persisted MCP tool library, runtime topology design, dynamic tool spawning, and a provider-agnostic reasoning knob. Test count: 1117.

Install

Requires Python 3.12+.

pip install orqest
# or
uv pip install orqest

Create a .env file (or set the equivalent env vars):

LLM_API_KEY=your_key_here
LLM_MODEL=openai:gpt-4.1

Quickstart

The smallest working agent — 10 lines of useful code:

import asyncio
from pydantic import BaseModel
from orqest import load_config
from orqest.agents import BaseAgent, GlobalState


class Answer(BaseModel):
    text: str


class QAAgent(BaseAgent[GlobalState, Answer]):
    async def _run_implementation(self, state, **kwargs) -> Answer:
        result = await self.call_model(state.get_latest_message("user"), state)
        return result.output


async def main():
    config = load_config()
    agent = QAAgent(
        agent_name="qa",
        system_prompt="Answer concisely.",
        output_type=Answer,
        model=config.llm_model,
        api_key=config.llm_api_key,
    )
    state = GlobalState()
    state.add_message("user", "What is the capital of France?")
    print((await agent.run(state)).text)


asyncio.run(main())

What Orqest gives you

Eight composable batteries — opt-in, picked à-la-carte per application:

• Composition — Pipeline, Parallel, Router, RefinementLoop. Sequence agents, fan out + merge, route by classifier, iterate until "good enough."
• Memory — LocalMemoryStore (SQLite + FTS5, or embedding-cosine recall via a pluggable embedder) with typed semantic / episodic / procedural retrieval. Per-kind policy: reliability decay, TTL retention, skill versioning. Pluggable MemoryStore Protocol for production backends.
• Autonomy — AgentSpec + AgentFactory + ToolRegistry + MetaOrchestrator. Agents that decompose goals and spawn specialists at runtime.
• Metacognition — EnrichedOutput[OutputT] carrying confidence, uncertainty_targets, capability_boundary. Three pluggable ConfidenceProtocol strategies (free / +1 call / +k calls). Agents that know what they don't know.
• Self-healing — Watchdog Protocol + StallDetector / LoopDetector / RegressionDetector. RecoveryAction discriminated union → HookDecision flow. FallbackModel for transparent provider failover.
• Generative UI — UIComponentSpec[T] typed components — 17 across 3 layers: compositional primitives (Plan, Chart, Table, Form, TakeoverDialog, Layout, Text, Markdown, Image, Badge, Button, Input), declarative grammars (Vega, Mermaid, Latex, JsonViewer), and a sandboxed HTML escape hatch. Agents emit; frontend resolves.
• Observability — EventBus, JSONTracer, sse_sidecar (with replay + heartbeat + ring buffer). Wire once, every tool emits.
• MCP — client (MCPServerManager) + server (create_orqest_server) + auto-discovery (get_or_discover + DiscoveryHook + PermissionGate).

Building an application

Read SKILLS.md first. It's the playbook for integrating Orqest into an existing codebase: discovery questions to ask the developer, codebase-walk patterns to identify the existing stack, minimal-surface selection rules, eight pattern recipes, and an end-to-end FastAPI walkthrough. Designed for LLM coding assistants (Claude Code, Cursor) and human developers alike.

The flagship reference consumer is demo/polymath/ — every Orqest battery lit up end-to-end (chat + dockview workspace + sub-agent roster + memory typology + cognitive gutter + healing toasts + generative UI tabs).

Supported model providers

provider:model_id format routes to the right SDK. The full pydantic-ai dependency bundles every provider SDK; the lazy import is defensive.

Provider	Format	Example
OpenAI	openai:model_id	openai:gpt-4.1
Anthropic	anthropic:model_id	anthropic:claude-sonnet-4-6
Google	google:model_id	google:gemini-2.5-pro
OpenRouter	openrouter:model_id	openrouter:anthropic/claude-3.5-sonnet

Documentation

• SKILLS.md — how to build with Orqest (discovery → codebase walk → minimal surface → recipes)
• Notebooks — start here if you're evaluating Orqest: a 12-notebook tour from the cognitive substrate → meta-orchestrator → generative UI → orchestrated workflow → reasoning → optimization (basic + compound) → topology search (basic + GEPA) → runtime topology → dynamic tools → autonomous-coder combo
• Benchmarks — reproducible head-to-heads measuring what each battery delivers over a baseline. Current: coding/ — test-driven refinement loop beats single-shot by +17pp pass@1 (3-trial average)
• Concepts — agents, state, composition, memory, metacognition, healing, generative UI
• API Reference — auto-generated from source
• Examples — runnable per-primitive references (basic agent → streaming → pipeline → refinement → memory → observability)
• CLAUDE.md — agent-instructions ground truth
• Changelog

Contributing

Contributions welcome. Open an issue or PR; new subsystems land as tracer-bullet tests-first slices.

License

MIT