Metadata-Version: 2.4
Name: agent-platform
Version: 1.1.1
Summary: Hierarchical, safety-by-construction distributed AI agent framework (Python port)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"

# AgentPlatform — Python

A faithful Python port of the C# **AgentPlatform** framework: a hierarchical,
safety-by-construction, distributed AI-agent runtime. The model only ever emits a
typed `AgentDecision`; every side effect is funneled through a deterministic
action gateway (risk → policy → approval → capability → firewall → execute →
verify → commit/rollback → audit). The control plane is plain code the model
cannot negotiate with.

## Install & test

```bash
cd python
pip install -e ".[test]"
pytest -q                 # 560 tests (1 skips without a Docker daemon)
python -m examples.coding_agent
```

Requires Python 3.11+. The core is **stdlib-only** — no third-party runtime
dependencies. `pytest`/`pytest-asyncio` are only needed for the test suite.

## Layout

| Module | Mirrors (C#) | Contents |
|---|---|---|
| `agent_platform/abstractions.py` | `AgentPlatform.Abstractions` | every core record, enum, and Protocol interface |
| `agent_platform/platform_json.py` | `PlatformJson` | camelCase reflective (de)serialization, strict enum handling |
| `agent_platform/clock.py` | `TimeProvider`/`FakeTimeProvider` | injectable time for deterministic runs |
| `agent_platform/domain/` | `AgentPlatform.Domain` | budget, risk engine, decision validator, escalation, glob, loop/stagnation detection, salience, structural plan critic |
| `agent_platform/application/` | `AgentPlatform.Application` | the agent loop, action gateway, context router, verifiers, plan critics, escalation service, evaluation harness, replay clients |
| `agent_platform/tools/` | `AgentPlatform.Tools` | firewall (SSRF/SQL/path-traversal), injection classifier, tool registry, sandbox executor |
| `agent_platform/modelruntime/` | `AgentPlatform.ModelRuntime` | scripted, Ollama, OpenAI-compatible, native Anthropic, and routing/fallback clients (providers, bias & castes); model catalog |
| `agent_platform/memory/` | `AgentPlatform.Memory` | memory store, semantic index, workspace, ingestion pipeline, hashing embedder |
| `agent_platform/policy/` | `AgentPlatform.Policy` | capability token service, reference policy engine |
| `agent_platform/skills/` | skill system | programmatic procedural memory: store, router, runtime, interpreters, critic, inducer, developer skills |
| `agent_platform/orchestration/` | `AgentPlatform.Orchestration` | durable task orchestrator with circuit breaker + backoff |
| `agent_platform/infra/` | `AgentPlatform.Infrastructure` | in-memory stores (charter, checkpoint, transitions, trajectory, audit, approvals, competence, …), trajectory replayer, benchmark harness |
| `agent_platform/di.py` | `AgentPlatformBuilder` | `build_in_memory_platform(...)` composition root |

## Quick start

```python
import asyncio
from agent_platform.di import build_in_memory_platform
from agent_platform.modelruntime.scripted import ScriptedModelClient
from agent_platform.modelruntime.ollama import OllamaModelClient, OllamaOptions

# Deterministic (tests/replays):
model = ScriptedModelClient()          # .enqueue(AgentDecision(...))
# Or a real local model:
# model = OllamaModelClient(OllamaOptions(model="qwen3:4b-instruct-2507"))

platform = build_in_memory_platform(model, tools=[...], policy_options=...)
await platform.charter_store.put(charter)
result = await platform.runtime.run(task)
```

## Connecting a model

Pick the local and central models from a `model-config.json` (Anthropic, OpenAI, Gemini, xAI Grok,
DeepSeek, Mistral, OpenRouter, Ollama, or a model you self-host):

```python
from agent_platform.modelruntime.providers import load_model_config, build_model_runtime
model = build_model_runtime(load_model_config("config/model-config.json"))
platform = build_in_memory_platform(model, tools=[...])
```

Full provider table, the native Anthropic client, the custom/self-hosted connector, and env-var keys
are documented in **[docs/model-providers.md](docs/model-providers.md)** (example config:
[`config/model-config.example.json`](config/model-config.example.json)).

## Documentation

- Port-specific: [docs/getting-started.md](docs/getting-started.md) — setup, integrating into
  your project, and usage; [docs/model-providers.md](docs/model-providers.md) — connecting LLMs.
- Language-agnostic concepts (shared with the C# reference): [`../docs/`](../docs/) —
  [architecture](../docs/architecture.md), [security model](../docs/security-model.md),
  [threat model](../docs/threat-model.md), [agent lifecycle](../docs/agent-lifecycle.md),
  [memory model](../docs/memory-model.md), [skill system](../docs/skill-system.md),
  [overview](../docs/overview.md). Class names map C# → Python per the table above.

## Fidelity notes

The port reproduces the framework core and all its safety machinery. Distributed
adapters that are stack-specific in C# (EF Core/Postgres, OPA HTTP, ASP.NET
endpoints, OpenTelemetry) are represented by their in-memory/idiomatic equivalents
behind the same interfaces; wire a real backend by implementing the corresponding
Protocol. Behavior verified against the C# unit, security, and regression suites.
