Metadata-Version: 2.4
Name: agent-utilities
Version: 3.0.0
Summary: In-run agent harness: the agent run loop, edit application, tool contracts, constraints, pre-emit gates, the developer workspace and the host ports graph-os fills
Author-email: Repository Maintainers <maintainers@knuckles.team>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<2.15.0.dev0,>=2.14.1
Requires-Dist: platformdirs>=4.13.3
Requires-Dist: pydantic-ai-slim==2.57.0
Requires-Dist: pydantic-graph==2.57.0
Requires-Dist: pydantic-ai-harness<0.58.0,>=0.57.0
Provides-Extra: openai
Requires-Dist: pydantic-ai-slim[openai]==2.57.0; extra == "openai"
Dynamic: license-file

# Agent Utilities

**The in-run agent harness.** agent-utilities holds only the mechanism inside one
agent run. It applies the decisions it is given; it does not store, decide,
serve or connect on its own.

[![PyPI - Version](https://img.shields.io/pypi/v/agent-utilities)](https://pypi.org/project/agent-utilities/)
[![Build](https://github.com/Knuckles-Team/agent-utilities/actions/workflows/release.yml/badge.svg)](https://github.com/Knuckles-Team/agent-utilities/actions/workflows/release.yml)

*Version: 3.0.0*

## What it contains

| Module | What it does inside one run |
|---|---|
| `agent_utilities.harness.edit_engine` | Parses model-proposed edits (search/replace blocks, unified diffs), applies them with graduated matching, and re-prompts on malformed or unmatched edits. |
| `agent_utilities.harness.contract_validator` | Checks a tool call's pre-conditions and its output's schema and verifier. |
| `agent_utilities.harness.constraint_engine` | Enforces hierarchical constraints on tool calls (prompt, tool description, middleware, implementation) and escalates repeated violations. |
| `agent_utilities.harness.quality_gates` | The pre-emit gate: antipattern detection, a preflight checklist and a multi-dimensional critique, in warn or block mode. |
| `agent_utilities.runtime` | The developer workspace: typed actions and observations, a stateful shell, local and container backends, a policy gate it is given, and the browser and computer-use tier ports. |
| `agent_utilities.host_ports` | The protocols the host fills: native and remote toolsets, tool clients, outbound credentials, delegated identity, the fleet catalog and the session keepalive. Without a host every binding port fails closed. |
| `agent_utilities.core.paths` | Resolves the platform config, data, cache and log directories (`GRAPH_OS_CONFIG_DIR`, XDG). |

## Where everything else lives

- **[epistemic-graph](https://github.com/Knuckles-Team/epistemic-graph)**: facts, records,
  vocabulary, storage and queries, ingest, retrieval, reasoning, memory, decisions, and
  learning (evaluation, harness evolution, reward and trace records).
- **[graph-os](https://github.com/Knuckles-Team/graph-os)**: admission, auth, served
  operations (MCP, REST, A2A), messaging front-ends, the registry and the multiplexer.
  graph-os hosts this harness and registers the `host_ports` providers.
- **[agent-connector-sdk](https://github.com/Knuckles-Team/agent-connector-sdk)**:
  connector contracts, transports, the A2A protocol library and connector helpers.

## Install and use

```bash
pip install agent-utilities
```

```python
from agent_utilities.runtime import create_workspace
from agent_utilities.runtime.events import CmdRunAction, TestRunAction

async with create_workspace(run_id="r1", prefer_docker=False) as ws:
    await ws.act(CmdRunAction(command="git status"))
    result = await ws.act(TestRunAction(selector="tests"))
```

## Develop

```bash
uv sync --group dev
uv run ruff check . && uv run ruff format --check .
uv run mypy agent_utilities
uv run pytest -q
```

## License

MIT, see [LICENSE](LICENSE).
