Metadata-Version: 2.4
Name: nasfai
Version: 0.20.1
Summary: Natural Selection for AI — a generalized agent-optimization framework that evolves LLM agents against explicit fitness functions.
Project-URL: Homepage, https://github.com/david-der/nasfai
Project-URL: Repository, https://github.com/david-der/nasfai
Author: David Der
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,evolutionary,genetic,llm,opentelemetry,optimization,prompt-optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: jinja2>=3.1
Requires-Dist: opentelemetry-api>=1.27
Requires-Dist: opentelemetry-sdk>=1.27
Requires-Dist: opentelemetry-semantic-conventions>=0.48b0
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'all'
Requires-Dist: datasets>=2.19; extra == 'all'
Requires-Dist: openai>=1.40; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'claude'
Provides-Extra: data
Requires-Dist: datasets>=2.19; extra == 'data'
Provides-Extra: dspy
Requires-Dist: dspy-ai>=2.5; extra == 'dspy'
Provides-Extra: mlflow
Requires-Dist: mlflow>=2.14; extra == 'mlflow'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Provides-Extra: otlp
Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'otlp'
Description-Content-Type: text/markdown

# nasfai — Natural Selection for AI

**Optimize AI agents by natural selection.** Give nasfai a declarative agent **blueprint**, an
explicit **fitness function**, and an eval dataset; it generates a **population** of agent
variants, measures each against the objective, selects and recombines the best, and returns a
**champion** agent — plus a fully reproducible record of how it got there.

The optimization machinery is the product; the agents it produces are the output.

```
blueprint ─▶ seed population ─▶ ┌─ evaluate fitness ─▶ select ─▶ vary ─┐ ─▶ champion + lineage
                                └──────────────── repeat ──────────────┘
```

- **Explicit objectives.** The fitness function is a first-class, swappable plugin, logged
  verbatim in every run — never implicit. Cost (tokens/$) is always a component. Score on
  classification metrics, sandboxed `pass@1`, or a user-defined multi-criteria LLM judge.
- **A real search, not a random walk.** Fitness-aware LLM prompt mutation, multi-objective
  Pareto selection, tournament/rank/roulette strategies, variance-aware (repeat + LCB)
  scoring, adaptive operator rates, successive-halving early elimination, and cross-run
  warm-start — all opt-in and determinism-preserving.
- **Reproducible & auditable.** Every genome is content-addressed; every run pins its inputs
  in a manifest; every champion traces through a lineage DAG back to the seed.
- **Observable by default.** Instrumented with OpenTelemetry GenAI semantic conventions;
  swap the exporter (console → jsonl → OTLP) with one config field.
- **Provider-neutral.** A deterministic mock provider runs the whole loop — and CI — with
  zero API spend. Real runs go through the Claude Agent SDK or the Anthropic API.

## Install

```bash
uv sync                      # dev: creates the venv, installs everything
# or, as a dependency:
pip install nasfai           # core; add extras: nasfai[claude,data,otlp]
```

## Quickstart

Evolve and optimize a Claude Agent SDK coding agent on the deterministic mock provider —
no API key, no network, fully reproducible:

```bash
uv run nasfai evolve --run examples/claude_sdk_coding_agent/run.mock.yaml
```

You'll watch `pass@1` climb across generations and get a champion plus a report at
`.nasfai/runs/<id>/report.md`. Then inspect what happened:

```bash
uv run nasfai report  <run-id>
uv run nasfai lineage --genome <champion-id> --run <run-id>
uv run nasfai blueprint list
```

To run it for real (opt-in, needs credentials + budget), see
[`examples/claude_sdk_coding_agent/`](examples/claude_sdk_coding_agent/README.md).

## Dashboard

A dependency-free local dashboard to browse, trace, and compare runs — fitness curves,
champion + lineage, per-task cost and wall-clock, the OpenTelemetry span timeline, and
side-by-side run comparison:

```bash
uv run nasfai serve              # → http://127.0.0.1:8000
```

Light, dense, and built on the same run store the CLI writes — point it at any
`.nasfai/runs` directory.

## Library API

```python
from nasfai import evolve
from nasfai.config import load_run_config

config = load_run_config("examples/claude_sdk_coding_agent/run.mock.yaml")
run = evolve("claude-sdk-coder", config)
champion = run.champion
print(champion.genome.id, champion.fitness.score, champion.fitness.components)
```

## Use it from another project — the Agent Skill

nasfai ships as a portable [Agent Skill](https://agentskills.io) in [`skills/nasfai/`](skills/nasfai/),
so an AI coding agent (Claude Code, etc.) can optimize *your* agents without you copying any
framework code. Drop it in and ask your agent to "optimize my agent against `<metric>` on
`<data>`":

```bash
mkdir -p ~/.claude/skills && cp -r skills/nasfai ~/.claude/skills/nasfai
```

It bundles the workflow, the exact blueprint/fitness/run‑config schemas, and a scaffolder that
generates a ready‑to‑run experiment. See [`skills/nasfai/README.md`](skills/nasfai/README.md).

## The vocabulary

A small evolutionary vocabulary runs through the whole system: **genome** (a serializable
agent), **phenotype** (its behavior when run), **population**, **generation**, **fitness**,
**selection**, **variation** (mutation + recombination, bounded by the blueprint's
**search space**), **lineage**, and **run**. Full definitions in
[`docs/03-concepts.md`](docs/03-concepts.md).

## Development

```bash
just            # lint + test
just test-cov   # tests with coverage gate
just lint       # ruff + ruff format --check + mypy
just fix        # auto-fix lint + format
```

## Documentation

Full design docs, architecture, and ADRs are in [`docs/`](docs/README.md). The build plan and
milestones are in [`docs/13-implementation-plan.md`](docs/13-implementation-plan.md); the
backlog is in [`stories/`](stories/backlog.md).

## License

Apache-2.0.
