Metadata-Version: 2.4
Name: attune-harness
Version: 0.2.0
Summary: Portable execution contracts for multi-model agent work
Author-email: Patrick Roebuck <admin@smartaimemory.com>
Maintainer-email: Smart-AI-Memory <admin@smartaimemory.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Smart-AI-Memory/attune-harness
Project-URL: Repository, https://github.com/Smart-AI-Memory/attune-harness
Project-URL: Issues, https://github.com/Smart-AI-Memory/attune-harness/issues
Keywords: ai-agent,multi-agent,agent-harness,llm,mcp,developer-tools,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tokens
Requires-Dist: tiktoken==0.12.0; extra == "tokens"
Provides-Extra: verify
Requires-Dist: attune-verify==0.6.0; extra == "verify"
Provides-Extra: rag
Requires-Dist: attune-rag==1.2.0; extra == "rag"
Provides-Extra: voyage
Requires-Dist: voyageai==0.5.0; extra == "voyage"
Requires-Dist: lancedb==0.38.0; extra == "voyage"
Requires-Dist: pyarrow==25.0.1; extra == "voyage"
Requires-Dist: jsonschema==4.26.0; extra == "voyage"
Provides-Extra: review
Requires-Dist: attune-forms==0.17.0; extra == "review"
Requires-Dist: attune-verify==0.6.0; extra == "review"
Requires-Dist: attune-rag==1.2.0; extra == "review"
Provides-Extra: mcp
Requires-Dist: mcp==2.2.0; extra == "mcp"
Requires-Dist: attune-forms==0.17.0; extra == "mcp"
Requires-Dist: attune-verify==0.6.0; extra == "mcp"
Requires-Dist: attune-rag==1.2.0; extra == "mcp"
Provides-Extra: memory-native
Requires-Dist: anthropic==1.6.0; extra == "memory-native"
Requires-Dist: httpx2==2.13.0; extra == "memory-native"
Dynamic: license-file

# Attune Harness

**Run an agent's work, check it independently, and keep a receipt of which happened.**

> **Status: 0.2.0, alpha.** Interfaces, configuration formats and CLI commands may
> change before 1.0. What is and is not qualified is
> [listed below](#what-is-qualified-and-what-is-not), not implied.

On September 18, 2026 I ran twelve model-written implementations of a small JSONL
exporter through Harness. Nine behaved correctly under the full check. The other three passed when their serializer
was tested directly, and failed when run through the real command line, which is the
only way anyone would ever use them
([results](https://github.com/Smart-AI-Memory/attune-harness/blob/v0.2.0/docs/plan-build-native-results.md)).

That gap is what Harness is for. A participant produces output: a model, a command,
or your own code. A check you supply, separate from the participant, decides whether
the output counts. You get back a receipt that says which. The participant's account
of its own work is recorded. It is never the evidence.

## A wrong answer comes back rejected

```sh
pip install attune-harness
```

The core has no dependencies and needs Python 3.10 or later. No provider SDK, no
API key, and no attune-ai installation.

```python
from attune_harness import Check, Output, Task, run

class Worker:
    def run(self, task: Task) -> Output:
        return Output("4")

receipt = run(
    Task("addition", "Compute 2 + 2", ("Return the integer result",)),
    "example-worker",
    Worker(),
    lambda task, output: Check(output.text == "4", "Compared with independent arithmetic"),
)
print(receipt.status.value)  # verified
```

Change the worker to return `"5"` and the same call returns `rejected`, with the
output and the check's evidence still attached. If the participant or the check
raises, the status is `failed` and the receipt names the stage and the error. `run`
executes once. It never retries on its own.

`python -m attune_harness` runs the installed demonstration and prints a JSON receipt.

## The CLI applies the same contract to larger work

```text
attune-harness --help

Task execution
  plan         Define intent and accept its scope
  build        Execute accepted tasks and protected checks
  review       Assess a document against project evidence
  fix          Repair scoped files and check the result
  test         Test a captured change and retain the evidence

Task controls
  status       Inspect a saved task
  resume       Continue a saved task

AI tools and integration
  --help-all   Browse operational tools and compatibility commands
```

Every verb follows one pattern. You accept a scope before anything runs, the host
applies the effects, and checks fixed in advance decide the outcome. `fix` is the
clearest example: it freezes an acceptance probe before the worker starts, applies
the worker's proposed replacement itself, and keeps the failed-before and
passed-after probe evidence. A saved task can be inspected with `status` and
continued with `resume`; completed operations replay from saved evidence instead of
running again.

Reaching outside the process takes explicit permission. External command
participants need `--allow-external`, and native model participants also need
`--allow-native`. **Approving a plan does not authorize paid calls.**

Many of these commands are there for the agent and its integrations to call.
Learning their syntax is not the price of entry, and `attune-harness COMMAND --help`
covers direct use. Full usage, exit codes and recovery controls are in the
[CLI guide](https://github.com/Smart-AI-Memory/attune-harness/blob/v0.2.0/docs/cli-guide.md).

## Install only what you use

| You want | Install |
| --- | --- |
| The core contracts and CLI, with no dependencies | `pip install attune-harness` |
| Document claim verification (`attune-verify` 0.6.0) | `pip install 'attune-harness[verify]'` |
| Local Markdown retrieval with source hashes, no model calls (`attune-rag` 1.2.0) | `pip install 'attune-harness[rag]'` |
| The evidence-review and test journeys: forms, retrieval and verification together | `pip install 'attune-harness[review]'` |
| Accepted retrieval grants served over MCP stdio (`mcp` 2.2.0) | `pip install 'attune-harness[mcp]'` |
| Repository-first retrieval on Voyage embeddings | `pip install 'attune-harness[voyage]'` |
| Token counting (`tiktoken` 0.12.0) | `pip install 'attune-harness[tokens]'` |
| Experimental: memory proposals from a Claude model over a pinned, data-only Anthropic API transport (`anthropic` 1.6.0, `httpx2` 2.13.0). POSIX only, needs `ANTHROPIC_API_KEY`, makes paid calls | `pip install 'attune-harness[memory-native]'` |

Extras pin exact versions as of 0.2.0. Keep the quotes: zsh and bash treat square
brackets as glob characters. When an extra is missing, the command that needs it
returns an actionable unavailable report instead of a traceback.

## What is qualified and what is not

I would rather you find the limits here than in your own checkout. Green software
tests and model quality are different claims, and this project keeps them apart.

| Area | Qualified | Not qualified |
| --- | --- | --- |
| Platforms | CI builds and installs the wheel on macOS, Ubuntu and Windows with Python 3.10 and 3.12, and exercises timeouts, cancellation, bounded output, crash-released locks and recovery ([guide](https://github.com/Smart-AI-Memory/attune-harness/blob/v0.2.0/docs/qualification.md)) | Other Python versions are outside the matrix. On Windows, a process that holds a run's `record.json` open for more than about two seconds still fails that run closed |
| Models | CI calls no model provider. Native Claude and Codex adapters have recorded comparisons | Native planning and building are experimental. In the September 18, 2026 comparison the original reply contract accepted 1 of 24 replies; after the contract was corrected it accepted 12 of 12. Two repetitions per role do not establish a reliability rate |
| `fix` and `test` | Local POSIX Git checkouts, regular files, default pytest discovery | File creation, deletion and renames, linked worktrees, custom pytest collectors, committed revision ranges |
| `fix` on Windows | Nothing yet. New in 0.2.0 and experimental: `fix` runs on a fixed local NTFS volume instead of refusing, and its native tests pass in CI on windows-2022 and windows-2025 ([design note](https://github.com/Smart-AI-Memory/attune-harness/blob/v0.2.0/docs/design-windows-effect-backend.md)) | Everything beyond those tests: deletion and renames, files with their own ACL or nonstandard attributes, files over 64 KiB, crash recovery, concurrent writers, power-loss durability, and any run against a real project. `test` on Windows is unchanged and unqualified |
| Isolation | Commands and probes run as supervised processes with deadlines and bounded output | **This is not a security sandbox.** Use a dedicated checkout and commands you trust |
| Receipts | Receipts retain the task, output and check evidence locally | They are local values, not signed attestations. Constructing a `Receipt` directly certifies nothing |
| Plan acceptance | Core imports, help and the library run standalone | `plan --accept` needs the optional Attune AI Spec runtime in the same environment |
| Protocols | MCP (2025-11-25 and 2026-07-28 profiles) and A2A 1.0 have local independent-client receipts | Remote authentication, arbitrary executable plugins and automatic host installation |
| Memory | A read-only integration plan is accepted and qualified in a temporary install | The memory modules and the `memory-native` extra ship in the wheel but are experimental and not activated for live memories. The native transport is POSIX only, accepts two exact model IDs, refuses any other SDK version, and is never exercised in CI |
| Roadmap | | `ship` and `reflect` are planned routes and do not exist yet |

## Harness and attune-ai

Harness is the successor I am building to
[attune-ai](https://pypi.org/project/attune-ai/). It starts from a constraint
attune-ai never had: the core must run with no provider SDK and nothing else from
the Attune family installed. The Attune libraries come in as extras, where you can
see exactly what each one adds.

attune-ai is still where cross-session memory, the Claude Code plugin and the
multi-agent workflows live. Harness does not replace those today. If that is what
you need, install attune-ai.

## Links

- [Qualification guide](https://github.com/Smart-AI-Memory/attune-harness/blob/v0.2.0/docs/qualification.md)
- [CLI guide](https://github.com/Smart-AI-Memory/attune-harness/blob/v0.2.0/docs/cli-guide.md)
- [Portable contract](https://github.com/Smart-AI-Memory/attune-harness/blob/v0.2.0/docs/portable-contract.md)
- [Repository](https://github.com/Smart-AI-Memory/attune-harness) and
  [issues](https://github.com/Smart-AI-Memory/attune-harness/issues)

**Apache License 2.0.**

Built by Patrick Roebuck, working with Codex and Claude.
