Metadata-Version: 2.4
Name: contragent
Version: 1.1.0
Summary: Contract-based deterministic trajectory supervision of LLM agents
Author: Yifeng Xiao
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/SponsioLabs/ContrAgent
Project-URL: Repository, https://github.com/SponsioLabs/ContrAgent
Keywords: llm-agents,runtime-verification,assume-guarantee-contracts,ltlf,trajectory-supervision
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0
Provides-Extra: smt
Requires-Dist: z3-solver>=4.12; extra == "smt"
Provides-Extra: llm
Requires-Dist: openai>=1.0; extra == "llm"
Requires-Dist: anthropic; extra == "llm"
Requires-Dist: google-genai; extra == "llm"
Provides-Extra: pdf
Requires-Dist: pypdf>=3.0; extra == "pdf"
Provides-Extra: chase
Requires-Dist: chase-cps<0.4,>=0.3.0; extra == "chase"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: ruff==0.15.16; extra == "dev"
Requires-Dist: z3-solver>=4.12; extra == "dev"
Dynamic: license-file

# ContrAgent

**Symbolic temporal supervision of LLM agents using assume-guarantee contracts.**

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/SponsioLabs/ContrAgent/blob/main/LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![arXiv](https://img.shields.io/badge/arXiv-2609.18128-b31b1b.svg)](https://arxiv.org/abs/2609.18128)

![ContrAgent: contracts are compiled once into DFA monitors, which gate tool calls online and replay recorded traces offline](https://raw.githubusercontent.com/SponsioLabs/ContrAgent/main/docs/figures/framework.png)

Write rules about what an agent may call, and when. ContrAgent checks
every tool call against them before it runs, in microseconds, with no
model in the loop.

The rules are assume-guarantee contracts: pairs of ALTL<sub>f</sub>
formulas (linear temporal logic on finite traces with linear arithmetic)
over the agent's tool-call trace. Each contract compiles to a
deterministic finite automaton that serves two roles. **Online**, it
gates each tool call before execution and blocks, redirects, or
escalates a violating call. **Offline**, it replays a recorded trace and
returns a verdict with the first violating event. A library is
independent of the agent's model, transfers across agents that share a
tool interface, and is checked for conflicts when loaded.

## Installation

```bash
pip install -e .              # runtime and command line; Python 3.10+
pip install -e ".[dev]"       # plus pytest, ruff, and z3
```

## Quick start

A contract is a rule over the order, count, and arguments of tool calls.
Two from [`examples/bank.yaml`](https://github.com/SponsioLabs/ContrAgent/blob/main/examples/bank.yaml):

```yaml
- desc: "identity must be verified before funds move"
  G: {ltl: "(!(called('transfer_funds')) U called('verify_identity')) | G(!(called('transfer_funds')))"}
- desc: "no email after a file read"
  G: {ltl: "G((called('read_file') -> G(!(called('send_email')))))"}
```

Both are about the shape of the trace, not its content: the first refuses
a transfer until an identity check has happened, the second refuses any
email once a file has been read, whatever the email says. Wrap your tools
and every call is checked:

```python
from contragent import ContrAgent

guard = ContrAgent(agent_id="bank_agent", config="bank.yaml", verbose=True)

@guard.wrap
def transfer_funds(amount: float, to: str) -> dict:
    ...

transfer_funds(500, "ACME")
# -> "The action `transfer_funds` was rejected by policy: identity must be
#     verified before funds move. Choose a different approach."
```

A refused call never runs; the wrapper returns the refusal text, which is
what goes back to the model as the tool result (`on_block="raise"` raises
instead). `guard.wrap({...})` wraps a whole tool table, and loops that
execute tools elsewhere call the two hooks, `guard_before` and
`guard_after`, themselves. When a call owes the next one (`G(a -> X b)`),
the result comes back with a prompt to call `b` next, and before the agent
stops, `guard.guard_finish()` prompts for what is still owed.
`verbose=True` prints every decision as it is made, as a timeline of the
session; `trace_path=` writes the session at `finish_session()` as a trace
file that `contragent replay` reads back.

The same library replays a recorded trace:

```bash
contragent replay trace.json --config bank.yaml
```

[`examples/`](https://github.com/SponsioLabs/ContrAgent/tree/main/examples) has a supervised tool-calling loop and traces to
replay; nothing there needs a model or credentials.

## Documentation

- [Authoring a contract library](https://github.com/SponsioLabs/ContrAgent/blob/main/docs/authoring.md): the four rule
  shapes, weak versus strong until, which side a predicate belongs on,
  arguments, the checks to run before an agent runs under a library,
  enforcement actions, and the Python form.
- [Interaction predicates](https://github.com/SponsioLabs/ContrAgent/blob/main/docs/predicates.md): the vocabulary formulas
  are written over, and how each predicate is fed.
- [Conflict check](https://github.com/SponsioLabs/ContrAgent/blob/main/docs/conflict-check.md): optional solvers for the
  load-time library check.
- [CHASE export](https://github.com/SponsioLabs/ContrAgent/blob/main/docs/chase.md): contract algebra and model checking on
  an exported library.

## Offline evaluation

```bash
contragent eval traces/ --config contragent/contracts/benchmark/rjudge.yaml --agent "*"
contragent replay trace.json --config contragent/contracts/sopbench/bank.yaml
contragent conflicts --config contragent/contracts/sopbench/hotel.yaml
```

`eval` replays a directory of `safe_*.json` / `unsafe_*.json` traces and
reports precision, recall, and false-positive rate per contract;
`replay` prints the verdict and the first violating event of one trace;
`conflicts` runs the library conflict check.

## Experiments

Both roles are evaluated on four benchmarks with the libraries under
`contragent/contracts/`. Success and safety are in percent; ASR is the
attack success rate.

| Benchmark | Role | Result |
|---|---|---|
| SOPBench (7 domains, gemini-2.5-flash) | online enforcement | success / safety 91 / 32 unguarded, 64 / 94 with the procedure in the prompt, 24 / 98 with an LLM judge, **90 / 98 with ContrAgent** at +0.14 s per task |
| AgentDojo (gpt-4o, `important_instructions`) | online enforcement | ASR 47.7% → **11.1%** with no injection detector and **0.79%** with the recorded injection as the untrusted span, utility unchanged at 72.6%, 0.16 ms per call |
| R-Judge (571 records) | offline evaluation | precision **97.0%**, recall **87.0%**, F₁ 91.8%; the misses are semantic, not procedural |
| tau²-bench (4,464 traces) | offline evaluation | the strongest model passes 25–60% of tasks by outcome but **0%** without a procedural violation, decided at 0.83 ms per call |

Each number's record, with the command that produced it and the summary
file behind it, is under [`experiments/`](https://github.com/SponsioLabs/ContrAgent/tree/main/experiments). Third-party
datasets are not redistributed; [`benchmarks/README.md`](https://github.com/SponsioLabs/ContrAgent/blob/main/benchmarks/README.md)
says where to place each one and how to rerun.

## Citation

```bibtex
@article{xiao2026contragent,
  title   = {Symbolic Temporal Supervision of {LLM} Agents Using Contracts},
  author  = {Xiao, Yifeng and Nuzzo, Pierluigi},
  journal = {arXiv preprint arXiv:2609.18128},
  year    = {2026}
}
```

## License

Apache-2.0. Copyright 2026 Yifeng Xiao. See [`LICENSE`](https://github.com/SponsioLabs/ContrAgent/blob/main/LICENSE) and
[`NOTICE`](https://github.com/SponsioLabs/ContrAgent/blob/main/NOTICE); ContrAgent includes code derived from
[Sponsio](https://github.com/SponsioLabs/Sponsio) (Apache-2.0). See
[`CONTRIBUTING.md`](https://github.com/SponsioLabs/ContrAgent/blob/main/CONTRIBUTING.md) for the development workflow.
