Metadata-Version: 2.4
Name: acumen
Version: 0.0.1.dev0
Summary: Build, Benchmark, and Optimize Agentic Skills for Python Packages.
Project-URL: Documentation, https://acumen.readthedocs.io/
Project-URL: Homepage, https://github.com/scverse/acumen
Project-URL: Source, https://github.com/scverse/acumen
Author: Pau Badia i Mompel
Maintainer-email: Pau Badia i Mompel <paubim@stanford.edu>
License: MIT License
        
        Copyright (c) 2026, Pau Badia i Mompel
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: claude-agent-sdk>=0.2.116
Requires-Dist: claude-code-log
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: psutil>=5.9
Requires-Dist: pyyaml
Requires-Dist: scipy
Requires-Dist: session-info2
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/_static/images/banner.svg" alt="acumen" width="360">
</p>

<p align="center"><b>Build, benchmark, and optimize agentic skills for your Python package.</b></p>

[![Tests][badge-tests]][tests]
[![Documentation][badge-docs]][documentation]

[badge-tests]: https://img.shields.io/github/actions/workflow/status/scverse/acumen/test.yaml?branch=main
[badge-docs]: https://app.readthedocs.org/projects/acumen/badge/

Agentic skills, tool instructions writen in plain text, allow agents to use tools more succesfuly and efficient.
However most python packages do not ship skills with them because developers have no easy way to build and benchmark skills for their tools.
Acumen closes this gap. Point it at a Python package and a few evaluation tasks, and it drafts a skill, benchmarks it and improves it across a train/test split so the gains are generalizable.


Many good tools are unusable by coding agents because their maintainers have no way to write
a skill for them — or, having written one, no way to tell whether it helps. acumen closes
that loop: point it at a Python package and a few tasks, and it drafts a skill, benchmarks it
against a no-skill baseline, and improves it across a train/test split so the gains are real
generalization, not memorized answers.

- **`acumen draft`** — write `skills/v1` from the package's own source.
- **`acumen bench`** — score a skill against a no-skill baseline, in a scrubbed sandbox where
  the skill is the only difference between arms.
- **`acumen improve`** — refine the skill from its train results, then benchmark again.
- **`acumen report`** — aggregate every run into one self-contained `report.html`: success
  rate per version, train vs. test. Bars are coloured by model, with a grey bar pooling all
  of them; pass `--palette claude-opus-5=#3b7ea1` (repeatable) to recolour any of them.

You decide when to stop. Every version is benchmarked on both splits, and only train results
reach the improver — so a widening train/test gap is a visible sign a skill is overfitting
rather than genuinely helping.

## Quickstart

```bash
# 1. Scaffold a starter config.yaml and tasks.yaml
acumen init

# 2. Fill in config.yaml (repo). Write tasks.yaml by hand, or generate it:
acumen tasks                     # mine the package for real analyses -> tasks.yaml

# 3. Then run the loop:
acumen bench --no-skill          # the baseline arm
acumen draft                     # generate skills/v1 from the package source, or write by hand
acumen bench --skill v1          # benchmark the skill against the baseline
acumen improve                   # generate skills/v2 from v1's train results, or write by hand
acumen bench --skill v2
acumen report                    # aggregate every run into report.html

# 4. Once a version proves out, ship it into the package itself:
acumen ship --skill v2           # add a <dist>-install-skills console script (PR, or local edit)
```

`acumen ship` packages the chosen skill version into the target: the package gains a
`<dist>-install-skills` command that installs the skill into the skills directory of whichever
agent the user names — `--agent {claude,codex,agents,claude-science}`, or an explicit `--dest` —
so the package's own users get the guidance with one command, wherever they run their agent. The
same bundle installs verbatim into every framework.

`acumen tasks`, `acumen draft`, and `acumen improve` each accept `--feedback "…"` to steer the
agent with context it can't infer — which functionality to skip when generating tasks, what a
skill should emphasise or fix. The guidance is added to the prompt without overriding the
train/test isolation, and for `draft`/`improve` it is recorded in the version's `meta.json` and
shown in the report. (Don't paste held-out test answers into `improve` feedback — that would
defeat the split.)

`draft`, `improve`, `tasks`, and `ship` each drive a long autonomous agent. Every run writes a
live `logs/acumen-<command>-<datetime>.jsonl` (one event per step, flushed as it goes — so you
can watch progress by reading the file) and a rendered `.html` transcript. Add `--stream` to
mirror the conversation to the terminal, or `--log-dir` to change where the logs land.

## Getting started

Please refer to the [documentation][],
in particular, the [API documentation][].

## Installation

You need to have Python 3.12 or newer installed on your system.
If you don't have Python installed, we recommend installing [uv][].

<!--
1) Install the latest release of `acumen` from [PyPI][]:

```bash
pip install acumen
```
-->

And to install the acumen skill that ships with the package into your agent's skills directory,
run `acumen-install-skills --agent {claude,codex,agents,claude-science}` (or `--dest <dir>` to
choose the directory yourself):

```bash
acumen-install-skills --agent claude
```

## Release notes

See the [changelog][].

## Contact

For questions and help requests, you can reach out in the [scverse discourse][].
If you found a bug, please use the [issue tracker][].

## Citation

> t.b.a

[uv]: https://github.com/astral-sh/uv
[scverse discourse]: https://discourse.scverse.org/
[issue tracker]: https://github.com/scverse/acumen/issues
[tests]: https://github.com/scverse/acumen/actions/workflows/test.yaml
[documentation]: https://acumen.readthedocs.io
[changelog]: https://acumen.readthedocs.io/page/changelog.html
[api documentation]: https://acumen.readthedocs.io/page/api.html
[pypi]: https://pypi.org/project/acumen
