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 theorqest.optimizationbattery (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-agnosticreasoningknob. 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 typedsemantic/episodic/proceduralretrieval. Per-kind policy: reliability decay, TTL retention, skill versioning. PluggableMemoryStoreProtocol for production backends. - Autonomy —
AgentSpec+AgentFactory+ToolRegistry+MetaOrchestrator. Agents that decompose goals and spawn specialists at runtime. - Metacognition —
EnrichedOutput[OutputT]carryingconfidence,uncertainty_targets,capability_boundary. Three pluggableConfidenceProtocolstrategies (free / +1 call / +k calls). Agents that know what they don't know. - Self-healing —
WatchdogProtocol +StallDetector/LoopDetector/RegressionDetector.RecoveryActiondiscriminated union →HookDecisionflow.FallbackModelfor 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: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
Metadata
Release files for orqest 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| orqest-0.8.0.tar.gz | 259.7 kB | With provenance | Details for orqest-0.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| orqest-0.8.0-py3-none-any.whl | Python 3 | none | any | Details for orqest-0.8.0-py3-none-any.whl |
Total release size: 585.4 kB
Release files / orqest-0.8.0.tar.gz
| Download URL | orqest-0.8.0.tar.gz |
|---|---|
| Size | 259.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e50607739c6a61dec993d8c6ee30414412a2cb5f3e0644dc6e128d33974ac7ce
|
|
BLAKE2b-256 checksum How to use checksums |
f208cc67fe2f6b9cc0d8be3860d2862e5fee065ea9c1187d749892f1dda1ca2f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 23, 2026.
Transparency logRelease files / orqest-0.8.0-py3-none-any.whl
| Download URL | orqest-0.8.0-py3-none-any.whl |
|---|---|
| Size | 325.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ffbf2a427fad9a8d94241360dc9063280d2d44082f8d48f6b93486e50a43dcd7
|
|
BLAKE2b-256 checksum How to use checksums |
1b312bc840484f5179615f9b0bca2f9722311dea10ba130095fa54803cb5259e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 23, 2026.
Transparency logSecurity for orqest 0.8.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for orqest-0.8.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.