Skip to content

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

from ace_next 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:

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

learn()

Run the full ACE learning pipeline over samples:

from ace_next 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:

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:

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

Lifecycle

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:

from ace_next import ACELiteLLM, Agent, Reflector, SkillManager, LiteLLMClient

agent_llm = LiteLLMClient(model="gpt-4o")
learning_llm = LiteLLMClient(model="gpt-4o-mini")

ace = ACELiteLLM(
    llm=agent_llm,
    agent=Agent(agent_llm),
    reflector=Reflector(learning_llm),
    skill_manager=SkillManager(learning_llm),
)

Deduplication

Prevent duplicate skills from accumulating:

from ace_next 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:

# 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:

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 for full details, environment variables, and manual setup.