Metadata-Version: 2.5
Name: bandr
Version: 0.3.0
Summary: Turn agent traces into runnable Harbor tasks with verifiers.
Project-URL: Homepage, https://github.com/bandr-ai/bandits
Project-URL: Source, https://github.com/bandr-ai/bandits
Project-URL: Issues, https://github.com/bandr-ai/bandits/issues
Project-URL: Changelog, https://github.com/bandr-ai/bandits/blob/main/CHANGELOG.md
Author: Bandr
Keywords: agents,ingest,llm,opentelemetry,traces
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# bandr

### Agent logs in. Harbor tasks out.

Rebuild the jobs in your traces as runnable tasks for evaluation and training.

[![CI](https://github.com/bandr-ai/bandits/actions/workflows/quality.yml/badge.svg)](https://github.com/bandr-ai/bandits/actions/workflows/quality.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-59636e)](https://github.com/bandr-ai/bandits/blob/main/pyproject.toml)

[**Get started**](#quickstart) &nbsp;·&nbsp; [How it works](#how-it-works) &nbsp;·&nbsp; [Try the example](#try-it-on-three-traces) &nbsp;·&nbsp; [Guides](#documentation)

</div>

<picture>
  <source media="(prefers-reduced-motion: reduce) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bandr-ai/bandits/main/docs/assets/readme/mint-workflow-dark.png">
  <source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/bandr-ai/bandits/main/docs/assets/readme/mint-workflow-light.png">
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bandr-ai/bandits/main/docs/assets/readme/mint-workflow-dark.gif">
  <img src="https://raw.githubusercontent.com/bandr-ai/bandits/main/docs/assets/readme/mint-workflow-light.gif" alt="bandr converts traces into a Harbor task. A model attempts the task in its environment, the task verifier grades the output, and the new trajectory and result can feed the next conversion." width="100%">
</picture>

<p align="center"><sub><a href="https://raw.githubusercontent.com/bandr-ai/bandits/main/docs/assets/readme/mint-workflow-light.gif">Open GIF</a> &nbsp;·&nbsp; <a href="https://github.com/bandr-ai/bandits/blob/main/examples/mint/net-revenue">Run the example</a> &nbsp;·&nbsp; <a href="https://raw.githubusercontent.com/bandr-ai/bandits/main/docs/assets/readme/mint-workflow-light.png">Still image</a></sub></p>

bandr helps your coding agent turn the jobs captured in your logs into
**runnable [Harbor task packages](https://github.com/harbor-framework/harbor)**:
the original instruction, starting environment, outcome verifier, and an oracle
when one is available.

Bring logs and any existing harness or starting-state files. The coding agent
writes source-specific parsers and generators; Mint runs them over the corpus,
writes the packages, checks them, and records their provenance and gaps.
Successful, failed, and partial runs can all contribute. Repeat attempts at the
same instance become one task with their evidence kept together.

**Traces → Harbor task → model attempt → verifier grade → new traces.**
Harbor can run an agent on the packaged task and grade its output using the task's
verifier. The resulting trajectory and result can become input for another
conversion. Use the tasks for evaluation or as environments in a training
workflow.

## Quickstart

**Install bandr, then give your coding agent the bundled skill.**

The package is `bandr`; its command is `mint`.

```bash
pip install bandr
mint skill install
```

<sub>First release pending: until Bandr is published on PyPI, install this checkout with <code>pip install .</code>. Python 3.11+.</sub>

Start a new Claude Code session and ask:

```text
Use Mint to turn ./logs into Harbor tasks in ./mint-workspace.
Inspect the source first, build a few tasks, then validate and report.
```

The skill goes into `~/.claude/skills/mint/`. Use `mint skill install --project`
for the current project's `.claude/skills/mint/`. Other coding agents can read
[SKILL.md](https://github.com/bandr-ai/bandits/blob/main/mint/SKILL.md) directly.

<details>
<summary>Other install options and updating the skill</summary>

For an isolated CLI installation, use `uv tool install bandr` or
`pipx install bandr`. For local development, run `uv sync --extra dev` and use
`uv run mint ...` to run this checkout.

After upgrading, re-run `mint skill install`. If the installed skill differs,
review it and use `--force` to replace `SKILL.md`; other files are preserved.

</details>

## When to use Mint

| You have | You want | Mint helps you build |
| :--- | :--- | :--- |
| Failed or successful agent traces | Repeatable tests of the same work | Whole-job tasks with starting files and outcome checks |
| Several attempts at one job | One task with all attempts as evidence | Grouped instances with source references |
| Traces plus an existing harness | Tasks for evaluation or training rollouts | Harbor packages that reuse the supplied environment |

Bring the starting-state files or harness when you have them. Missing evidence
becomes a recorded gap or a candidate to finish, rather than an invented environment.

## How it works

**The coding agent writes source-specific code. Mint runs it over the corpus and
records the evidence.**

| Step | What happens |
| :--- | :--- |
| **Read** | Sample the logs, write a parser, and identify the whole jobs the agent was given. |
| **Rebuild** | Group repeated attempts and construct each job's instruction, starting environment, verifier, and oracle when available. |
| **Challenge** | Check structure, answer leaks, and credentials. Exercise the verifier with the oracle, no-op, wrong outcomes, and valid alternatives. |
| **Report** | Inspect task provenance, gate results, exclusion reasons, and gaps. Resume from `mint status`. |

The output is a task package you can inspect:

```text
out/tasks/<type>/<task>/
├── instruction.md          # the original job
├── environment/            # the world before the agent acted
├── tests/test.sh           # check the requested outcome
├── solution/solve.sh       # optional oracle
└── task.toml               # runtime configuration and provenance
```

The verifier checks the outcome; it does not require a new agent to replay the
logged steps. Mint can also build dialogue tasks with a runtime user simulator,
or use a model judge when deterministic grading is unsuitable.

## Try it on three traces

The [bundled example](https://github.com/bandr-ai/bandits/blob/main/examples/mint) contains three synthetic attempts at two
jobs. Two recorded answers are wrong. Its generator recomputes the expected
answers from the starting files and builds two tasks.

**Run it yourself:** [logs → parser → task generator → validation → report](https://github.com/bandr-ai/bandits/blob/main/examples/mint/README.md).
No model calls or production logs are needed.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bandr-ai/bandits/main/docs/assets/readme/mint-checks-dark.png">
  <img src="https://raw.githubusercontent.com/bandr-ai/bandits/main/docs/assets/readme/mint-checks-light.png" alt="Captured output from the bundled example: local runner; level 1 checks two tasks with zero failures; level 2 passes both sampled tasks with no infrastructure errors. Tasks remain generated." width="100%">
</picture>

Local checks leave tasks **`generated`**. Install Harbor and start Docker, then
run `mint validate --runner harbor` for container execution. Only passing Harbor
execution gates can produce **`validated`**. The example's answer oracle proves
verifier wiring; inspect that the expected answer follows from the inputs.

<details>
<summary>Validation statuses, sensitive data, and what passing gates prove</summary>

| Status | Meaning |
| :--- | :--- |
| `generated` | Structure and content gates passed; execution may be local-only, untested, or missing an oracle. |
| `validated` | Required Harbor execution gates passed, including an accepted oracle and rejected no-op/wrong outcomes. |
| `judged` | A model grades the task. Inspect calibration and execution evidence; it is never called validated. |
| `blocked` | A content scan found an answer leak or credential. Credential-blocked packages are removed from `out/tasks`; fix and regenerate. |
| `exec_failed` | Structure, execution gates, or a type audit failed. Inspect the reason. |

Passing gates are evidence about the verifier, not proof that the expected answer
is correct or the reconstructed task is faithful. Review the source references,
grading trust, oracle provenance, and gaps in `report.md`.

The secret scan is best-effort text scanning. Binary and explicitly allowed files
are outside it; raw logs, parsed trajectories, and internal metadata can remain
sensitive. See the [validation guide](https://github.com/bandr-ai/bandits/blob/main/mint/guides/validation.md).

</details>

## Documentation

| Start here | For |
| :--- | :--- |
| [Mint skill](https://github.com/bandr-ai/bandits/blob/main/mint/SKILL.md) | The full agent-assisted workflow |
| [Parsing](https://github.com/bandr-ai/bandits/blob/main/mint/guides/parsing.md) · [Checks](https://github.com/bandr-ai/bandits/blob/main/mint/guides/checks.md) | Reading your source format and optional findings |
| [Task types](https://github.com/bandr-ai/bandits/blob/main/mint/guides/tasktypes.md) | Building whole jobs, environments, and verifiers |
| [Validation](https://github.com/bandr-ai/bandits/blob/main/mint/guides/validation.md) · [Harbor](https://github.com/bandr-ai/bandits/blob/main/mint/guides/harbor.md) | Execution gates and runtime integration |

Run `mint --help`, `mint schema`, and `mint docs` for the installed version's
commands and contracts. [Open an issue](https://github.com/bandr-ai/bandits/issues)
for a bug or a conversion case you cannot represent.

<details>
<summary>Development, releases, and older recipes</summary>

```bash
uv sync --extra dev
uv run ruff check bandits mint tests
uv run ruff format --check bandits mint tests
uv run pytest tests
```

The distribution is `bandr`; Python imports remain `mint` and `bandits`.
`bandits` provides the ingestion library. See [releasing](https://github.com/bandr-ai/bandits/blob/main/docs/releasing.md) and
[the changelog](https://github.com/bandr-ai/bandits/blob/main/CHANGELOG.md). Older [SFT](https://github.com/bandr-ai/bandits/blob/main/recipes/data/sft) and [JEV](https://github.com/bandr-ai/bandits/blob/main/recipes/jev)
recipes are retained for reference.

[Visual source and build instructions](https://github.com/bandr-ai/bandits/blob/main/docs/assets/readme/README.md).

</details>

<sub>Anonymous command usage is enabled by default. No log contents or paths are sent. Disable it with <code>mint telemetry off</code> or <code>MINT_TELEMETRY_DISABLED=1</code>. <a href="https://github.com/bandr-ai/bandits/blob/main/docs/telemetry.md">Captured fields and limits</a>.</sub>
