acumen

Build, benchmark, and optimize agentic skills for Python packages.

acumen is a python package to build, benchmark and optimize agentic skills for any Python package.
An agentic skill is a short set of plain-text instructions that helps a coding agent use a package correctly.
Given a package and a few tasks, acumen trains a skill in the same way one would train a model.
In every epoch, coding agents attempt the training tasks, and acumen learns from the errors they make to rewrite the skill.
Each new version is scored on held-out validation tasks, training stops once validation no longer improves, and the best version is evaluated one last time on an untouched test set.
With the final skill, coding agents are more successful at solving tasks that require using the Python package than they are without the skill.

acumen is part of the scverse® project (website, governance) and is fiscally sponsored by NumFOCUS.
If you like scverse® and want to support our mission, please consider making a tax-deductible donation to help the project pay for developer time, professional services, travel, workshops, and a variety of other needs.

Getting started

Please refer to the documentation,
in particular, the Getting started tutorial and 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.

acumen runs its agents with Claude, Codex, or both, and you only need to install the backend you use.
There are several alternative options to install acumen:

1. Install the latest stable release from PyPI to run Claude models (requires an Anthropic API key or a claude login):

pip install acumen[claude]

1. Install the latest stable release from PyPI to run Codex models (requires the codex CLI on your PATH and a Codex login or API key):

pip install acumen

1. Install the latest stable release from PyPI to run both:

pip install acumen[all]

1. Install the latest development version:

pip install "acumen[all] @ git+https://github.com/scverse/acumen.git@main"

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