orqest 0.8.0__tar.gz

orqest-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kareemlsd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orqest-0.8.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: orqest
+Version: 0.8.0
+Summary: Typed agent primitives and orchestration on top of pydantic-ai — memory, autonomy, healing, metacognition, generative UI, MCP, optimization.
+Author-email: Kareem El Sayed <k.elsayed@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Kareemlsd/orqest
+Project-URL: Documentation, https://kareemlsd.github.io/orqest/
+Project-URL: Repository, https://github.com/Kareemlsd/orqest
+Project-URL: Changelog, https://github.com/Kareemlsd/orqest/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Kareemlsd/orqest/issues
+Keywords: agents,agentic,pydantic-ai,llm,orchestration,mcp,memory,metacognition,self-healing,generative-ui
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic
+Classifier: Framework :: Pydantic :: 2
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-ai>=1.37.0
+Requires-Dist: pytest-asyncio>=1.0.0
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: uvicorn>=0.35.0
+Dynamic: license-file
+
+# Orqest
+
+A Python library for building **agentic harnesses** on top of [pydantic-ai](https://ai.pydantic.dev). 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+**.
+
+```bash
+pip install orqest
+# or
+uv pip install orqest
+```
+
+Create a `.env` file (or set the equivalent env vars):
+
+```bash
+LLM_API_KEY=your_key_here
+LLM_MODEL=openai:gpt-4.1
+```
+
+## Quickstart
+
+The smallest working agent — 10 lines of useful code:
+
+```python
+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`](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/`](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](SKILLS.md)** — how to build with Orqest (discovery → codebase walk → minimal surface → recipes)
+- **[Notebooks](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](benchmarks/)** — reproducible head-to-heads measuring what each battery delivers over a baseline. Current: [`coding/`](benchmarks/coding/) — test-driven refinement loop beats single-shot by +17pp pass@1 (3-trial average)
+- **[Concepts](https://kareemlsd.github.io/orqest/concepts/agents/)** — agents, state, composition, memory, metacognition, healing, generative UI
+- **[API Reference](https://kareemlsd.github.io/orqest/api/agents/)** — auto-generated from source
+- **[Examples](examples/)** — runnable per-primitive references (basic agent → streaming → pipeline → refinement → memory → observability)
+- **[CLAUDE.md](CLAUDE.md)** — agent-instructions ground truth
+- **[Changelog](CHANGELOG.md)**
+
+## Contributing
+
+Contributions welcome. Open an issue or PR; new subsystems land as tracer-bullet tests-first slices.
+
+## License
+
+[MIT](LICENSE)

orqest-0.8.0/README.md

@@ -0,0 +1,109 @@
+# Orqest
+
+A Python library for building **agentic harnesses** on top of [pydantic-ai](https://ai.pydantic.dev). 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+**.
+
+```bash
+pip install orqest
+# or
+uv pip install orqest
+```
+
+Create a `.env` file (or set the equivalent env vars):
+
+```bash
+LLM_API_KEY=your_key_here
+LLM_MODEL=openai:gpt-4.1
+```
+
+## Quickstart
+
+The smallest working agent — 10 lines of useful code:
+
+```python
+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`](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/`](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](SKILLS.md)** — how to build with Orqest (discovery → codebase walk → minimal surface → recipes)
+- **[Notebooks](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](benchmarks/)** — reproducible head-to-heads measuring what each battery delivers over a baseline. Current: [`coding/`](benchmarks/coding/) — test-driven refinement loop beats single-shot by +17pp pass@1 (3-trial average)
+- **[Concepts](https://kareemlsd.github.io/orqest/concepts/agents/)** — agents, state, composition, memory, metacognition, healing, generative UI
+- **[API Reference](https://kareemlsd.github.io/orqest/api/agents/)** — auto-generated from source
+- **[Examples](examples/)** — runnable per-primitive references (basic agent → streaming → pipeline → refinement → memory → observability)
+- **[CLAUDE.md](CLAUDE.md)** — agent-instructions ground truth
+- **[Changelog](CHANGELOG.md)**
+
+## Contributing
+
+Contributions welcome. Open an issue or PR; new subsystems land as tracer-bullet tests-first slices.
+
+## License
+
+[MIT](LICENSE)

orqest-0.8.0/orqest/__init__.py

@@ -0,0 +1,50 @@
+from .config import OrqestConfig, get_default_config, load_config
+from .healing import HealingConfig
+from .hooks import (
+    Abort,
+    Continue,
+    HookAbortError,
+    HookDecision,
+    HookRunner,
+    Redirect,
+    Skip,
+    ToolHook,
+)
+from .metacognition import EnrichedOutput, MetacognitionConfig
+from .optimization import MetaAgentConfig, OptimizationConfig
+from .orchestration import (
+    Parallel,
+    Pipeline,
+    RefinementLoop,
+    Router,
+)
+from .plan import ExecutionPlan, PlanStatus, PlanSubtask, PlanTask
+from .workbench import Workbench
+
+__all__ = [
+    "Abort",
+    "Continue",
+    "EnrichedOutput",
+    "ExecutionPlan",
+    "HealingConfig",
+    "HookAbortError",
+    "HookDecision",
+    "HookRunner",
+    "MetaAgentConfig",
+    "MetacognitionConfig",
+    "OptimizationConfig",
+    "OrqestConfig",
+    "Parallel",
+    "Pipeline",
+    "PlanStatus",
+    "PlanSubtask",
+    "PlanTask",
+    "Redirect",
+    "RefinementLoop",
+    "Router",
+    "Skip",
+    "ToolHook",
+    "Workbench",
+    "get_default_config",
+    "load_config",
+]

orqest-0.8.0/orqest/agents/__init__.py

@@ -0,0 +1,27 @@
+from ..utils.reasoning import ReasoningEffort
+from .base_agent import (
+    BaseAgent,
+    Prompt,
+    budget_tool_results,
+    keep_recent_messages,
+)
+from .compound_tool import CompoundTool
+from .context_manager import ContextManager
+from .retry import run_with_retry
+from .session_state import BaseSessionState
+from .state import GlobalState
+from .tool_wrapper import as_tool
+
+__all__ = [
+    "BaseAgent",
+    "BaseSessionState",
+    "CompoundTool",
+    "ContextManager",
+    "GlobalState",
+    "Prompt",
+    "ReasoningEffort",
+    "as_tool",
+    "budget_tool_results",
+    "keep_recent_messages",
+    "run_with_retry",
+]