Metadata-Version: 2.4
Name: bound-policy
Version: 0.5.0
Summary: A deterministic, configurable control policy for agent workflows.
Project-URL: Homepage, https://github.com/Danny-de-bree/bound
Project-URL: Repository, https://github.com/Danny-de-bree/bound
Project-URL: Documentation, https://github.com/Danny-de-bree/bound#readme
Project-URL: Issues, https://github.com/Danny-de-bree/bound/issues
Project-URL: Changelog, https://github.com/Danny-de-bree/bound/blob/main/CHANGELOG.md
Author-email: Danny de Bree <ddebree1990@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent-loop,agentic-ai,agents,bounded-utility,decision-making,llm,policy,satisficing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

<p align="center">
  <strong>Agents that know when good enough is enough.</strong>
</p>

<p align="center">
  <a href="https://github.com/Danny-de-bree/bound/actions/workflows/ci.yml"><img src="https://github.com/Danny-de-bree/bound/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/bound-policy/"><img src="https://img.shields.io/pypi/v/bound-policy.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/bound-policy/"><img src="https://img.shields.io/pypi/pyversions/bound-policy.svg" alt="Python versions"></a>
  <a href="https://github.com/Danny-de-bree/bound/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Danny-de-bree/bound.svg" alt="License"></a>
</p>

# BOUND

**The deterministic control harness for AI agents.**

Coding agents are good at continuing. They are less good at knowing when to stop.

BOUND sits between execution and the agent's next decision, turning observable evidence into a deterministic control signal:

**ACCEPT · RETRY · REPLAN · ROLLBACK**

<p align="center">
  <img src="assets/bound-agent-workflow.png" alt="BOUND deterministic control harness for AI agent workflows" width="100%">
</p>

## Put BOUND in your agent

Choose your agent, open its integration prompt, and paste it into a new session:

- [Cline](integrations/cline/INSTALL_BOUND.md)
- [Claude Code](integrations/claude-code/INSTALL_BOUND.md)
- [Kilo Code](integrations/kilo-code/INSTALL_BOUND.md)
- [Hermes Agent](integrations/hermes-agent/INSTALL_BOUND.md)
- [Any other agent](integrations/generic/INSTALL_BOUND.md)

**That's it.**

The prompt tells the agent to install BOUND, inspect its workflow, identify meaningful evaluation boundaries, and wire the harness into its control loop.

For the initial setup, use your agent's strongest **architecture or planning mode** — or a stronger model if available. This first pass should focus on defining the plan, meaningful step boundaries, acceptance criteria, risks, budgets, and observable evidence.

```text
Paste integration prompt into agent
              ↓
Agent installs BOUND
              ↓
Agent inspects project + workflow
              ↓
Agent defines goals, contracts, and evidence
              ↓
You review the integration plan
              ↓
Agent wires BOUND into the workflow
              ↓
Run your agent with BOUND
```

Once configured, the normal execution loop can use BOUND deterministically. No LLM judge is required for observable criteria.

## The control loop

BOUND belongs after a meaningful execution step and before the agent decides whether to keep optimizing the same objective.

```text
Agent executes
      ↓
Observable evidence
      ↓
BOUND evaluates
      ↓
ACCEPT / RETRY / REPLAN / ROLLBACK
      ↓
Agent changes its next action
```

Conceptually:

```python
result = workflow.evaluate_step(
    contract=contract,
    evidence=evidence,
    criteria=criteria,
)

match result.decision:
    case "ACCEPT":
        continue_to_next_step()
    case "RETRY":
        retry_current_approach()
    case "REPLAN":
        choose_new_strategy()
    case "ROLLBACK":
        rollback()
```

The agent still owns planning, reasoning, tool use, code changes, and execution.

**BOUND decides whether the current result is good enough to move on.**

## Four decisions

| Decision | Meaning |
| --- | --- |
| **ACCEPT** | Good enough. Stop optimizing this step and continue. |
| **RETRY** | Keep the current approach and make one focused correction. |
| **REPLAN** | Stop iterating on the current strategy and choose another approach. |
| **ROLLBACK** | A hard risk boundary was exceeded. Return to a safe state. |

BOUND can use observable evidence such as tests, lint and type checks, acceptance checks, expected changes, retries, tool calls, token usage, runtime, and rollback availability.

> **Good enough is enough. Keep progressing.**

## Why BOUND?

Without an explicit stopping policy, an agent can continue working after the task is already satisfactory:

```text
task solved
    ↓
tests pass
    ↓
more refinement
    ↓
more calls and changes
    ↓
possible regression
```

BOUND adds an explicit control point:

```text
task solved
    ↓
evidence collected
    ↓
BOUND evaluates
    ↓
ACCEPT
    ↓
continue to the next goal
```

BOUND does not replace the agent. It is a thin control harness around the agent's execution loop.

## How it works

BOUND is the **control harness**.

Under the hood:

```text
Contracts + evidence  → evaluation layer
BoundPolicy           → deterministic decision engine
BOUND                 → control harness
Integration prompts   → adoption layer
```

The scoring model, evidence mapping, thresholds, weights, calculations, and exact decision rules live in the technical documentation:

**[Read the architecture and scoring model →](architecture/README.md)**

## Manual installation

If you want to integrate BOUND directly:

```bash
pip install bound-policy
```

Or:

```bash
uv add bound-policy
```

The PyPI distribution is `bound-policy`; the Python import and CLI are `bound`.

## Current status

BOUND is experimental.

The scoring heuristics, weights, thresholds, and integration patterns still need broader validation on real agent workloads.

The next milestone is dogfooding BOUND inside real coding agents and measuring whether it reduces unnecessary post-solution work, calls, tokens, retries, and regressions without reducing task success.

## Development

```bash
git clone https://github.com/Danny-de-bree/bound.git
cd bound

uv sync
uv run pytest
uv run ruff check .
```

## License

MIT © Danny de Bree