docs/api/index.md

# API Reference

Quick reference for the most-used classes and functions in `ace`.

## Runners

### ACELiteLLM

Simple self-improving conversational agent.

```python
from ace import ACELiteLLM

agent = ACELiteLLM.from_model("gpt-4o-mini")
```

| Method | Description |
|--------|-------------|
| `ask(question, context="")` | Generate an answer using the current skillbook |
| `learn(samples, environment, epochs=1, *, wait=True)` | Run the full ACE learning pipeline |
| `learn_from_feedback(feedback, ground_truth=None)` | Learn from the last `ask()` interaction |
| `learn_from_traces(traces, epochs=1, *, wait=True)` | Learn from pre-recorded execution traces |
| `save(path)` | Save skillbook to JSON |
| `load(path)` | Load skillbook from JSON |
| `enable_learning()` / `disable_learning()` | Toggle learning on/off |
| `wait_for_background(timeout=None)` | Wait for async learning to finish |
| `learning_stats` | Dict with background learning progress |
| `get_strategies()` | Formatted string of current strategies |

See [LiteLLM Integration](../integrations/litellm.md) for full details.

### ACE

Full adaptive pipeline (Agent + Reflector + SkillManager + Environment).

```python
from ace import ACE, Agent, Reflector, SkillManager, Skillbook, SimpleEnvironment

runner = ACE.from_roles(
    agent=Agent("gpt-4o-mini"),
    reflector=Reflector("gpt-4o-mini"),
    skill_manager=SkillManager("gpt-4o-mini"),
    environment=SimpleEnvironment(),
    skillbook=Skillbook(),
)

results = runner.run(samples, epochs=3)
```

| Method | Description |
|--------|-------------|
| `run(samples, epochs=1, wait=True)` | Run adaptation loop, return `list[SampleResult]` |
| `save(path)` | Save skillbook |
| `wait_for_background(timeout=None)` | Wait for async learning |
| `learning_stats` | Background learning progress |

See [Full Pipeline Guide](../guides/full-pipeline.md).

### BrowserUse

Browser automation with learning.

```python
from ace import BrowserUse

runner = BrowserUse.from_model(browser_llm=my_llm, ace_model="gpt-4o-mini")
results = runner.run("Find the top post on Hacker News")
```

See [Browser-Use Integration](../integrations/browser-use.md).

### LangChain

Wrap LangChain Runnables with learning.

```python
from ace import LangChain

runner = LangChain.from_model(my_chain, ace_model="gpt-4o-mini")
results = runner.run([{"input": "Summarize this document"}])
```

See [LangChain Integration](../integrations/langchain.md).

### ClaudeCode

Claude Code CLI with learning.

```python
from ace import ClaudeCode

runner = ClaudeCode.from_model(working_dir="./project", ace_model="gpt-4o-mini")
results = runner.run("Add unit tests for utils.py")
```

See [Claude Code Integration](../integrations/claude-code.md).

### ClaudeSDKExecuteStep / ClaudeSDKToTrace

Direct Anthropic Messages API steps for custom pipelines.

```python
from ace import Pipeline, Reflector, SkillManager, Skillbook, learning_tail
from ace.integrations import ClaudeSDKExecuteStep, ClaudeSDKToTrace

skillbook = Skillbook()
pipe = Pipeline([
    ClaudeSDKExecuteStep(model="claude-sonnet-4-20250514"),
    ClaudeSDKToTrace(),
    *learning_tail(Reflector("gpt-4o-mini"), SkillManager("gpt-4o-mini"), skillbook),
])
```

`ClaudeSDKResult` and `ToolCall` are Pydantic models, so token counts, latency,
tool calls, and serialization are validated before the learning tail consumes
the trace.

See [Claude SDK Integration](../integrations/claude-sdk.md).

---

## Roles

### Agent

Produces answers using the current skillbook.

```python
from ace import Agent

agent = Agent("gpt-4o-mini")
output = agent.generate(
    question="What is 2+2?",
    context="",
    skillbook=skillbook,
    reflection=None,  # optional
)
```

**AgentOutput fields:**

| Field | Type | Description |
|-------|------|-------------|
| `final_answer` | `str` | The generated answer |
| `reasoning` | `str` | Step-by-step reasoning |
| `skill_ids` | `list[str]` | Skillbook strategies cited |
| `raw` | `dict` | Raw LLM response |

### Reflector

Analyzes what worked and what failed.

```python
from ace import Reflector

reflector = Reflector("gpt-4o-mini")
reflection = reflector.reflect(
    question="What is 2+2?",
    agent_output=output,
    skillbook=skillbook,
    ground_truth="4",
    feedback="Correct!",
)
```

**ReflectorOutput fields:**

| Field | Type | Description |
|-------|------|-------------|
| `reasoning` | `str` | Analysis of the outcome |
| `error_identification` | `str` | What went wrong |
| `root_cause_analysis` | `str` | Why it went wrong |
| `correct_approach` | `str` | What should have been done |
| `key_insight` | `str` | Main lesson learned |
| `skill_tags` | `list[SkillTag]` | `(skill_id, tag)` pairs — populated in online mode when agent cited skills |
| `raw` | `dict` | Raw LLM response |

### SkillManager

Transforms reflections into skillbook updates.

```python
from ace import SkillManager

skill_manager = SkillManager("gpt-4o-mini")
sm_output = skill_manager.update_skills(
    reflections=(reflection,),
    skillbook=skillbook,
    question_context="Math problems",
    progress="3/5 correct",
    source=source,
)
# skillbook has already been mutated in place
```

Returns a `SkillManagerOutput` with an `.update` field (`UpdateBatch`) and `.raw` field.

See [Roles](../concepts/roles.md) for full details.

---

## Skillbook

```python
from ace import Skillbook

skillbook = Skillbook()
```

| Method / Property | Description |
|-------------------|-------------|
| `add_skill(section, issue=None, keywords=None, insight=None, content=None)` | Add a skill |
| `apply_update(update_batch)` | Apply update operations |
| `as_prompt()` | Markdown format for LLM consumption |
| `save_to_file(path)` | Save JSON plus embeddings sidecar |
| `Skillbook.load_from_file(path)` | Load JSON plus embeddings sidecar if present |
| `stats()` | Section count, skill count, active skill totals |
| `skills()` | List of all skills |

See [The Skillbook](../concepts/skillbook.md).

---

## Data Types

### Sample

```python
from ace import Sample

sample = Sample(
    question="What is 2+2?",
    context="Show your work",
    ground_truth="4",
)
```

### EnvironmentResult

```python
from ace import EnvironmentResult

result = EnvironmentResult(
    feedback="Correct!",
    ground_truth="4",
    metrics={"accuracy": 1.0},
)
```

### UpdateOperation

```python
from ace import UpdateOperation

op = UpdateOperation(
    type="ADD",
    section="context",
    keywords=["math", "decomposition"],
    issue="Complex arithmetic questions are easier to solve when the work is decomposed into smaller verified steps.",
    insight="Break problems into smaller steps before computing.",
    reflection_index=0,
    reflection_indices=[0, 1],
    skill_id="math-00001",
)
```

Operations: `ADD`, `UPDATE`, `TAG`, `REMOVE`. See [Update Operations](../concepts/updates.md).

### DeduplicationConfig

**Requires:** `uv add ace-framework[deduplication]`

```python
from ace import DeduplicationConfig

config = DeduplicationConfig(
    enabled=True,
    embedding_model="text-embedding-3-small",
    similarity_threshold=0.85,
)
```

---

## Environments

Extend `TaskEnvironment` to provide evaluation feedback:

```python
from ace import TaskEnvironment, EnvironmentResult

class MyEnvironment(TaskEnvironment):
    def evaluate(self, sample, agent_output):
        correct = sample.ground_truth.lower() in agent_output.final_answer.lower()
        return EnvironmentResult(
            feedback="Correct!" if correct else "Incorrect",
            ground_truth=sample.ground_truth,
        )
```

A built-in `SimpleEnvironment` uses substring matching and is included for quick testing.

---

## Providers

### resolve_model

Resolve a model string to a PydanticAI model instance:

```python
from ace.providers import resolve_model

model = resolve_model("gpt-4o-mini")
```

Supports any [LiteLLM model](https://docs.litellm.ai/) or PydanticAI-native identifier.

### ACEModelConfig

Configuration for model selection per role:

```python
from ace.providers import ACEModelConfig

config = ACEModelConfig.from_toml("ace.toml")
agent_model = config.for_role("agent")
```

---

## Observability

### OpikStep

Append to any pipeline for automatic tracing and cost tracking:

```python
from ace import OpikStep

OpikStep(project_name="my-experiment", tags=["training"])
```

### register_opik_litellm_callback

Standalone LLM cost tracking without pipeline traces:

```python
from ace import register_opik_litellm_callback

register_opik_litellm_callback(project_name="my-experiment")
```

See [Opik Observability](../integrations/opik.md).

---

## Recursive Reflector (RR)

PydanticAI agent-based trace analyser with tools for code execution and sub-agent analysis.

### RRStep

Drop-in replacement for `Reflector` — satisfies both `StepProtocol` and `ReflectorLike`.

```python
from ace.rr import RRStep, RRConfig

rr = RRStep(
    "gpt-4o-mini",                          # Model string
    config=RRConfig(max_requests=20),       # Configuration
)

# As drop-in reflector
ace = ACELiteLLM.from_model("gpt-4o-mini", reflector=rr)

# As pipeline step
pipe = Pipeline([..., rr, ...])
```

### RRConfig

| Parameter | Default | Description |
|-----------|---------|-------------|
| `timeout` | `30.0` | Per-execution timeout in seconds (Unix only) |
| `max_tokens` | `500_000` | Total token budget (input + output) per agent run |
| `max_requests` | `50` | Safety cap on LLM requests per agent run |
| `context_window` | `128_000` | Model context window; compaction triggers at 85% |
| `max_output_chars` | `20_000` | Per-execution output truncation limit |
| `max_depth` | `2` | Maximum recursion depth (0=root, max_depth=leaf) |
| `child_budget_fraction` | `0.5` | Fraction of remaining token budget for child sessions |
| `max_compactions` | `3` | Safety cap on full summarization rounds |
| `microcompact_keep_recent` | `3` | Recent tool results to preserve during microcompaction |

### Sandbox Functions

Available inside `execute_code` tool calls:

| Function | Description |
|----------|-------------|
| `FINAL(value)` | Submit final result dict (terminates the loop) |
| `FINAL_VAR(name)` | Submit a named variable as the result |
| `SHOW_VARS()` | Print available variables (debugging) |
| `register_helper(name, source, desc)` | Register a reusable helper function |
| `list_helpers()` | List registered helper names/descriptions |
| `run_helper(name, *args, **kwargs)` | Invoke a registered helper |
| `get_item_messages(item)` | Return message list for a batch item |
| `get_item_question(item)` | Return question string for a batch item |
| `get_message_text(msg)` | Safely render message content as text |

### TraceContext

Structured trace wrapper with factory methods:

| Factory | Input |
|---------|-------|
| `TraceContext.from_agent_output(output)` | `AgentOutput` |
| `TraceContext.from_conversation_history(msgs)` | `list[dict]` |
| `TraceContext.from_tau_simulation(msgs, system_prompt)` | TAU-bench messages |
| `TraceContext.from_browser_use(history)` | browser-use `AgentHistory` |
| `TraceContext.from_langchain(steps)` | LangChain intermediate steps |
| `TraceContext.from_reasoning_string(text)` | Raw reasoning string |
| `TraceContext.combine(traces)` | Merge multiple traces |

See [RR_DESIGN.md](../RR_DESIGN.md) for the full architecture reference.

---

## Prompts

The default prompts are v2.1 (built into `ace`). Pass a custom template via `prompt_template`:

```python
agent = Agent("gpt-4o-mini", prompt_template="Custom prompt with {skillbook}, {question}, {context}")
reflector = Reflector("gpt-4o-mini", prompt_template="Custom reflector prompt ...")
skill_manager = SkillManager("gpt-4o-mini", prompt_template="Custom skill manager prompt ...")
```

See [Prompt Engineering](../guides/prompts.md).