Skip to main content

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

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)

Source distribution for orqest 0.8.0
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)

Table of built distributions (wheels) for orqest 0.8.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.8.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page