docs/integrations/litellm.md

# LiteLLM Integration

`ACELiteLLM` is the simplest way to get a self-improving agent. It bundles Agent, Reflector, SkillManager, and Skillbook into a single class with `ask()` and `learn()` methods.

## Quick Start

```python
from ace import ACELiteLLM

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

# Ask questions — learns patterns across them
answer = agent.ask("If all cats are animals, is Felix (a cat) an animal?")

# Save and reload
agent.save("learned.json")
```

## Parameters

### from_model()

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `model` | `str` | `"gpt-4o-mini"` | LiteLLM model identifier |
| `max_tokens` | `int` | `2048` | Max tokens for responses |
| `temperature` | `float` | `0.0` | Sampling temperature |
| `api_key` | `str` | `None` | API key (or use env variable) |
| `base_url` | `str` | `None` | Custom API endpoint |
| `skillbook_path` | `str` | `None` | Path to load saved skillbook |
| `environment` | `TaskEnvironment` | `None` | Evaluation environment |
| `dedup_config` | `DeduplicationConfig` | `None` | Skill deduplication config |
| `is_learning` | `bool` | `True` | Enable/disable learning |
| `opik` | `bool` | `False` | Enable Opik observability (pipeline traces + LiteLLM per-call cost tracking) |
| `opik_project` | `str` | `"ace-framework"` | Opik project name for organizing traces |
| `opik_tags` | `list[str]` | `None` | Tags applied to every Opik trace |

## Methods

### ask()

Direct agent call using the current skillbook:

```python
answer = agent.ask("Your question", context="Optional context")
```

### learn()

Run the full ACE learning pipeline over samples:

```python
from ace import Sample, SimpleEnvironment

samples = [
    Sample(question="What is 2+2?", context="", ground_truth="4"),
]
results = agent.learn(samples, environment=SimpleEnvironment(), epochs=3)
```

### learn_from_feedback()

Learn from the last `ask()` interaction:

```python
agent.ask("What is the capital of France?")
agent.learn_from_feedback(feedback="Correct!", ground_truth="Paris")
```

### learn_from_traces()

Learn from pre-recorded execution traces:

```python
results = agent.learn_from_traces(traces, epochs=1)
```

### Lifecycle

```python
agent.save("path.json")               # Save skillbook
agent.load("path.json")               # Load skillbook
agent.enable_learning()               # Turn on learning
agent.disable_learning()              # Turn off learning
agent.wait_for_background()           # Wait for async learning
agent.learning_stats                  # Background progress
agent.skillbook                       # Current Skillbook
agent.get_strategies()                # Formatted strategies
```

## Using a Cheaper Learning Model

Use a strong model for the Agent and a cheaper one for learning:

```python
from ace import ACELiteLLM, Agent, Reflector, SkillManager

ace = ACELiteLLM(
    agent=Agent("gpt-4o"),
    reflector=Reflector("gpt-4o-mini"),
    skill_manager=SkillManager("gpt-4o-mini"),
)
```

## Deduplication

Prevent duplicate skills from accumulating:

```python
from ace import DeduplicationConfig

agent = ACELiteLLM.from_model(
    "gpt-4o-mini",
    dedup_config=DeduplicationConfig(
        enabled=True,
        embedding_model="text-embedding-3-small",
        similarity_threshold=0.85,
    ),
)
```

## Supported Providers

Any model supported by [LiteLLM](https://docs.litellm.ai/):

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

# Anthropic
agent = ACELiteLLM.from_model("claude-sonnet-4-5-20250929")

# Google
agent = ACELiteLLM.from_model("gemini-pro")

# Local (Ollama)
agent = ACELiteLLM.from_model("ollama/llama2")

# Custom endpoint
agent = ACELiteLLM.from_model("gpt-4o-mini", base_url="https://your-endpoint.com")
```

## Opik Observability

Enable tracing and cost tracking with a single flag:

```python
ace = ACELiteLLM.from_model("gpt-4o-mini", opik=True, opik_project="my-experiment")

# Both tracing modes are enabled:
# 1. Pipeline traces (OpikStep) — one trace per sample with ACE context
# 2. LiteLLM callback — per-LLM-call token/cost tracking

results = ace.learn(samples, environment=SimpleEnvironment(), epochs=3)
# View traces at http://localhost:5173 → project "my-experiment"
```

See [Opik Observability](opik.md) for full details, environment variables, and manual setup.

## What to Read Next

- [Full Pipeline Guide](../guides/full-pipeline.md) — for more control over the pipeline
- [Async Learning](../guides/async-learning.md) — background learning with `wait=False`
- [Opik Observability](opik.md) — monitor costs and traces