### Contributor Setup with UV Sync

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/installation.md

Clone the repository and use uv sync to install all dependencies for development. This is the recommended and fastest method.

```bash
git clone https://github.com/kayba-ai/agentic-context-engine
cd agentic-context-engine
uv sync  # Installs everything (10-100x faster than pip)
```

--------------------------------

### Verify Installation using ACELiteLLM from Setup

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/installation.md

Instantiate ACELiteLLM using the configuration saved by 'ace setup' and test it by asking a question.

```python
from ace import ACELiteLLM

# Uses ace.toml + .env from `ace setup`
agent = ACELiteLLM.from_setup()
print(agent.ask("Hello!"))
```

--------------------------------

### Agent Setup

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/hosted-api.md

Prints CLI instructions and installs pipeline skills. Use --append-to to save instructions to a file, --no-skills to skip skill installation, or --project-dir to specify a different project.

```bash
kayba setup
```

```bash
kayba setup --append-to AGENTS.md
```

```bash
kayba setup --no-skills
```

```bash
kayba setup --project-dir /path/to/project
```

--------------------------------

### Development Setup and Commands

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/CONTRIBUTING.md

This section details the initial setup for development, including cloning the repository, installing dependencies using 'uv sync', running tests with 'uv run pytest', and executing linting/formatting checks with 'uv run black' and 'uv run mypy'. It also shows how to run specific test files or test categories.

```bash
# Clone your fork
git clone https://github.com/your-username/agentic-context-engine.git
cd agentic-context-engine

# Install all dependencies (uses UV - 10-100x faster than pip)
uv sync

# Run tests
uv run pytest

# Run linting and formatting
uv run black ace/ tests/ examples/
uv run mypy ace/

# Run specific test files
uv run pytest tests/test_skillbook.py
uv run pytest -m unit  # Only unit tests
uv run pytest -m integration  # Only integration tests
```

--------------------------------

### Set Up Kayba Pipeline Skill

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/installation.md

Run 'kayba setup' to install the evaluation pipeline skill for Claude Code integration. This command installs the skill to .claude/skills/ and provides CLI instructions.

```bash
kayba setup
```

--------------------------------

### Install from Source

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/hosted-api.md

Install dependencies from source using uv sync.

```bash
uv sync
```

--------------------------------

### Install Kayba Tracing SDK

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/agent-guides/tracing-sdk.md

Install the tracing SDK with the optional 'tracing' extra. This will also install MLflow as the tracing backend.

```bash
pip install ace-framework[tracing]
```

--------------------------------

### Contributor Setup with UV Add -e

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/installation.md

Clone the repository and use uv add -e . to install the project in editable mode for development.

```bash
git clone https://github.com/kayba-ai/agentic-context-engine
cd agentic-context-engine
uv add -e .
```

--------------------------------

### Install Cloud Extra for Coding Agent Skills

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/installation.md

Install the 'cloud' extra for the ace-framework using uv to enable hosted CLI and setup functionalities.

```bash
uv add 'ace-framework[cloud]'
```

--------------------------------

### Interactive ACE Setup

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/README.md

Run the ace setup command to be guided through model selection, API keys, and connection validation.

```bash
ace setup
```

--------------------------------

### Quick Start LangChain Runner

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/langchain.md

Initialize and run a LangChain runnable with ACE. This example shows how to wrap a chain and execute multiple inputs, then save the learned skillbook.

```python
from ace import LangChain

runner = LangChain.from_model(your_chain, ace_model="gpt-4o-mini")

results = runner.run([
    {"input": "Summarize this document"},
    {"input": "Extract key entities"},
])

runner.save("chain_expert.json")
```

--------------------------------

### Verify Installation using ACELiteLLM by Model Name

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/installation.md

Instantiate ACELiteLLM directly with a model name if you have not used 'ace setup', and test it by asking a question.

```python
agent = ACELiteLLM.from_model("gpt-4o-mini")
print(agent.ask("Hello!"))
```

--------------------------------

### Install Cloud Extra

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/hosted-api.md

Install the 'cloud' extra for the ace-framework using uv.

```bash
uv tool install 'ace-framework[cloud]' --python 3.12
```

--------------------------------

### Initialize ACELiteLLM after Setup

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/setup.md

After completing the guided setup, initialize the `ACELiteLLM` in your Python code using `from_setup()` to leverage the configured models and credentials.

```python
from ace import ACELiteLLM

ace = ACELiteLLM.from_setup()
answer = ace.ask("What is 2+2?")
```

--------------------------------

### Install OpenClaw Tracing Plugin

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/sdk/openclaw/README.md

Install the plugin using the OpenClaw CLI. Ensure you have the necessary permissions and environment setup.

```bash
openclaw plugins install @kayba_ai/openclaw-tracing
```

--------------------------------

### Quick Start with ACELiteLLM

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/litellm.md

Initialize an agent with a LiteLLM model and start asking questions. The agent learns from interactions and can be saved.

```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")
```

--------------------------------

### Quick Start: Configure and Trace an Agent

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/tracing.md

Configure Kayba tracing with your API key and use the `@trace` decorator to automatically capture function inputs, outputs, and duration. This example shows basic configuration and tracing of a single agent function.

```python
from ace.tracing import configure, trace, start_span

configure(api_key="kb-...")

@trace
def my_agent(query: str) -> str:
    with start_span("retrieval") as span:
        span.set_inputs({"query": query})
        results = search(query)
        span.set_outputs(results)
    return synthesize(results)

my_agent("What is the capital of France?")
```

--------------------------------

### ACELiteLLM Full Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/opik.md

This example demonstrates how to initialize ACELiteLLM with Opik integration for training and learning from samples. Traces can be viewed in the Opik UI.

```python
from ace import ACELiteLLM, Sample, SimpleEnvironment

ace = ACELiteLLM.from_model("gpt-4o-mini", opik=True, opik_project="ace-training")

samples = [
    Sample(question="What is 2+2?", context="", ground_truth="4"),
    Sample(question="Capital of France?", context="", ground_truth="Paris"),
]

results = ace.learn(samples, environment=SimpleEnvironment(), epochs=3)
ace.save("trained.json")

# View traces at http://localhost:5173 → project "ace-training"
```

--------------------------------

### Install ACE with Observability

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/opik.md

Install the ACE framework with the observability extra to include Opik integration.

```bash
uv add ace-framework[observability]
```

--------------------------------

### Initialize and Use ACELiteLLM Agent

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/index.md

Demonstrates how to initialize an agent using ACELiteLLM, ask it a question, and save its learned knowledge. This is a quick way to get started with a self-improving agent.

```python
from ace import ACELiteLLM

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

answer = agent.ask("If all cats are animals, is Felix (a cat) an animal?")

agent.save("learned.json")
```

--------------------------------

### Project Setup and Imports

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/examples/ace/ace_demo.ipynb

Sets up the project root and imports necessary libraries for ACE.

```python
from pathlib import Path
import sys

_here = Path(__file__).resolve().parent if "__file__" in dir() else Path.cwd()
_root = _here
for _p in [_here] + list(_here.parents):
    if (_p / "pipeline" / "__init__.py").exists():
        _root = _p
        break
sys.path.insert(0, str(_root))

from dotenv import load_dotenv

load_dotenv(_root / ".env")

print(f"Project root: {_root}")
print("Setup OK")
```

--------------------------------

### Complete ACE Pipeline Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/guides/full-pipeline.md

A comprehensive example demonstrating the creation of roles, pipeline runner, samples, training, and saving the skillbook.

```python
from ace import (
    ACE, Agent, Reflector, SkillManager,
    Sample, SimpleEnvironment,
)

# Roles (each takes a model string directly)
agent = Agent("gpt-4o-mini")
reflector = Reflector("gpt-4o-mini")
skill_manager = SkillManager("gpt-4o-mini")

# Pipeline
runner = ACE.from_roles(
    agent=agent,
    reflector=reflector,
    skill_manager=skill_manager,
    environment=SimpleEnvironment(),
)

# Training data
samples = [
    Sample(question="What is 2+2?", context="", ground_truth="4"),
    Sample(question="Capital of France?", context="", ground_truth="Paris"),
]

# Train and save
results = runner.run(samples, epochs=3)
runner.save("trained.json")
```

--------------------------------

### Install Agentic Context Engine

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/specs/001-openclaw-integration/quickstart.md

Clone the repository and install dependencies using uv.

```bash
git clone https://github.com/kayba-ai/agentic-context-engine.git
cd agentic-context-engine
uv sync
```

--------------------------------

### Install ACE Framework

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/examples/agentic-system-prompting/README.md

Install the ACE framework using pip. For development, clone the repository and install in editable mode.

```bash
pip install ace-framework
```

```bash
git clone https://github.com/kayba-ai/agentic-context-engine
cd agentic-context-engine
uv sync
uv pip install -e .  # Required to run examples
```

--------------------------------

### Install and Run ACE Framework

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/examples/README.md

Basic installation and execution commands for the ACE Framework. Ensure your OpenAI API key is set as an environment variable.

```bash
# 1. Install
pip install ace-framework

# 2. Set API key
export OPENAI_API_KEY="your-api-key"

# 3. Run example
python examples/simple_ace_example.py

# Browser examples (contributors: uv sync --group demos)
uv run python examples/browser-use/simple_ace_agent.py
```

--------------------------------

### Quick Start BrowserUse Runner

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/browser-use.md

Initialize a BrowserUse runner with specified LLMs for browser tasks and ACE learning. This example demonstrates running a single task and saving the learned skillbook.

```python
from ace import BrowserUse
from langchain_openai import ChatOpenAI

runner = BrowserUse.from_model(
    browser_llm=ChatOpenAI(model="gpt-4o"),
    ace_model="gpt-4o-mini",
)

results = runner.run("Find the top post on Hacker News")
runner.save("browser_expert.json")
```

--------------------------------

### Tool Use Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/claude-sdk.md

Example demonstrating how to define and use tools with `ClaudeSDKExecuteStep` for function calling.

```APIDOC
## Tool Use Example

### Description
If Claude returns tool use blocks, they are captured on `ClaudeSDKResult.tool_calls` as validated `ToolCall` models.

### Code Example
```python
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    }
]

execute = ClaudeSDKExecuteStep(
    model="claude-sonnet-4-20250514",
    tools=tools,
)
```
```

--------------------------------

### Install ACE Framework

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/README.md

Use uv to add the ace-framework to your project. Additional dependencies can be installed with optional extras.

```bash
uv add ace-framework
```

```bash
uv add 'ace-framework[browser-use]'
```

```bash
uv add 'ace-framework[langchain]'
```

```bash
uv add 'ace-framework[logfire]'
```

```bash
uv add 'ace-framework[mcp]'
```

```bash
uv add 'ace-framework[deduplication]'
```

--------------------------------

### Install BrowserUse Integration

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/browser-use.md

Install the ACE framework with browser-use capabilities using pip.

```bash
uv add ace-framework[browser-use]
```

--------------------------------

### Browser-Use Runner Quick Setup with `from_model()`

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/guides/integration.md

Use `from_model()` for a quick setup of the BrowserUse runner. It automatically builds ACE roles from a model string and can optionally resume from a saved skillbook.

```python
runner = BrowserUse.from_model(
    browser_llm=ChatOpenAI(model="gpt-4o"),
    ace_model="gpt-4o-mini",       # Model for Reflector + SkillManager
    skillbook_path="saved.json",   # Optional: resume from saved skillbook
)
```

--------------------------------

### ACE Runner Full Example with Opik Integration

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/opik.md

This example shows how to set up and run the ACE runner with Opik integration, including custom steps and optional LLM callback for cost tracking. It's suitable for more manual pipeline configurations.

```python
from ace import (
    ACE, Agent, Reflector, SkillManager, Skillbook,
    SimpleEnvironment, Sample, OpikStep,
    register_opik_litellm_callback,
)

runner = ACE.from_roles(
    agent=Agent("gpt-4o-mini"),
    reflector=Reflector("gpt-4o-mini"),
    skill_manager=SkillManager("gpt-4o-mini"),
    environment=SimpleEnvironment(),
    extra_steps=[OpikStep(project_name="ace-training")],
)

# Optionally add LLM-level cost tracking
register_opik_litellm_callback(project_name="ace-training")

samples = [
    Sample(question="What is 2+2?", context="", ground_truth="4"),
    Sample(question="Capital of France?", context="", ground_truth="Paris"),
]

results = runner.run(samples, epochs=3)
runner.save("trained.json")
```

--------------------------------

### Setup script for OpenClaw integration

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/examples/openclaw/kayba-ace/SKILL.md

Command to run the setup script for integrating the ACE skill into an OpenClaw workspace.

```bash
python examples/openclaw/setup.py
```

--------------------------------

### Example CLI Output

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/specs/001-openclaw-integration/contracts/cli.md

This is an example of the console output produced by the `learn_from_traces.py` script. It shows the discovery of sessions, parsing, loading of the skillbook, learning from traces, saving process, and syncing to OpenClaw.

```text
============================================================
  Discovering sessions
============================================================
  Sessions dir:  ~/.openclaw/agents/main/sessions
  Total sessions: 12
  Already processed: 10
  New to process: 2

============================================================
  Parsing sessions
============================================================
  + b3db607f-....jsonl: Hello world
  Parsed: 2, Skipped (empty): 0

============================================================
  Loading skillbook
============================================================
  Loaded 5 existing strategies from ~/.openclaw/ace_skillbook.json

============================================================
  Learning from 2 traces
============================================================
  Processed: 2/2
  New strategies: 1 (total: 6)

  Latest strategies:
    [session_mgmt-00006] Use greeting to establish session context...

============================================================
  Saving
============================================================
  Skillbook: ~/.openclaw/ace_skillbook.json
  Processed log: ~/.openclaw/ace_processed.txt

============================================================
  Syncing to OpenClaw
============================================================
  Synced 6 strategies to ~/.openclaw/workspace/AGENTS.md

============================================================
  Done
============================================================

```

--------------------------------

### Programmatic Workflow: Install Prompt

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/hosted-api.md

Installs the generated prompt into the specified agent target.

```bash
kayba prompts install --target codex
```

--------------------------------

### Interactive Workflow: Generate and Install Prompt

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/hosted-api.md

Generates a prompt to a file and then installs it into the specified agent target.

```bash
kayba prompts generate -o prompt.md
```

```bash
kayba prompts install --target claude-code
```

--------------------------------

### Minimal Configuration with Environment Variable

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/tracing.md

If the KAYBA_API_KEY environment variable is set, tracing can be configured with a single line of code, simplifying setup.

```python
from ace.tracing import configure
configure()
```

--------------------------------

### Install ACE LangChain Integration

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/langchain.md

Install the ACE framework with LangChain support using pip or uv.

```bash
uv add ace-framework[langchain]
```

--------------------------------

### Install OpenClaw from source

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/openclaw.md

Clone the OpenClaw repository and install dependencies using pnpm. This method is for building from source.

```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm openclaw onboard --install-daemon
```

--------------------------------

### Install Prompts

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/hosted-api.md

Installs generated prompts into agent configuration files. Use --target to specify the agent type or --input for a local file.

```bash
# Install the latest prompt from Kayba into Claude Code
kayba prompts install --target claude-code

# Install the latest prompt into a universal agent file
kayba prompts install --target universal

# Install a local export into Cursor
kayba prompts install --input prompt.md --target cursor
```

--------------------------------

### Install Ace Framework with UV

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/installation.md

Use uv to add the ace-framework package to your project.

```bash
uv add ace-framework
```

--------------------------------

### Start Opik Server with Docker

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/opik.md

Run the Opik server locally using Docker for development and testing.

```bash
docker run -d -p 5173:5173 --name opik ghcr.io/comet-ml/opik:latest

# View traces at http://localhost:5173
```

--------------------------------

### ACE TOML Configuration Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/ACE_REFERENCE.md

Example TOML file demonstrating how to configure ACE models for default, agent, and reflector roles.

```toml
[default]
model = "gpt-4o-mini"

[agent]
model = "claude-sonnet-4-20250514"
max_tokens = 4096

[reflector]
model = "gpt-4o-mini"

```

--------------------------------

### Setup Coding Agent (Persistent)

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/hosted-api.md

Appends setup instructions to agent configuration files for persistent access across all future sessions. Use AGENTS.md for universal compatibility.

```bash
kayba setup --append-to AGENTS.md      # universal (Claude Code, Cursor, Copilot, Windsurf, etc.)
kayba setup --append-to CLAUDE.md      # Claude Code only
kayba setup --append-to .cursorrules   # Cursor only
```

--------------------------------

### Install OpenClaw using npm

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/openclaw.md

Use npm to install OpenClaw globally and run the onboard wizard to set up model providers and API keys.

```bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
```

--------------------------------

### Install Ace Framework with Optional Extras

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/installation.md

Install the ace-framework with specific optional features using uv. Choose extras like 'all', 'instructor', 'langchain', 'browser-use', 'claude-code', 'claude-sdk', 'observability', 'deduplication', or 'transformers' based on your needs.

```bash
uv add 'ace-framework[all]'
```

```bash
uv add 'ace-framework[instructor]'
```

```bash
uv add 'ace-framework[langchain]'
```

```bash
uv add 'ace-framework[browser-use]'
```

```bash
uv add 'ace-framework[claude-code]'
```

```bash
uv add 'ace-framework[claude-sdk]'
```

```bash
uv add 'ace-framework[observability]'
```

```bash
uv add 'ace-framework[deduplication]'
```

```bash
uv add 'ace-framework[transformers]'
```

--------------------------------

### Install ACE with MCP Extra

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/mcp-client-setup.md

Install the ACE framework with the MCP extra using pip or uv. This is a prerequisite for using the MCP client.

```bash
pip install "ace-framework[mcp]"
```

```bash
uv add "ace-framework[mcp]"
```

--------------------------------

### Full ACE Pipeline Setup

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/concepts/overview.md

Initialize the full ACE pipeline with specified roles and an environment. This setup is suitable for building new agents from scratch. The `epochs` parameter controls the number of learning cycles.

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

runner = ACE.from_roles(
    agent=Agent("gpt-4o-mini"),
    reflector=Reflector("gpt-4o-mini"),
    skill_manager=SkillManager("gpt-4o-mini"),
    environment=SimpleEnvironment(),
)
results = runner.run(samples, epochs=3)
```

--------------------------------

### Load ACE Agent from Setup

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/quick-start.md

Loads an ACE agent using the configuration from `ace setup`. This agent learns patterns across questions asked.

```python
from ace import ACELiteLLM

agent = ACELiteLLM.from_setup()

# Ask related questions — the agent learns patterns across them
answer1 = agent.ask("If all cats are animals, is Felix (a cat) an animal?")
answer2 = agent.ask("If all birds fly, can penguins (birds) fly?")

print(f"Learned {len(agent.skillbook.skills())} strategies")

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

--------------------------------

### Install OpenClaw using Docker

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/openclaw.md

Clone the OpenClaw repository and use the provided script to build the Docker image and set up the gateway.

```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh
```

--------------------------------

### Install and Run ACE on Host Machine

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/examples/openclaw/README.md

Instructions for installing and running ACE directly on the host machine, bypassing Docker customization. Requires setting an LLM API key.

```bash
# 1. Install
git clone https://github.com/Kayba-ai/agentic-context-engine.git
cd agentic-context-engine
uv sync

# 2. Set your LLM API key
export ANTHROPIC_API_KEY="your-key"

# 3. Dry run (no LLM calls, just parse sessions)
uv run python examples/openclaw/kayba-ace/learn_from_traces.py --dry-run

# 4. Learn from all new sessions
uv run python examples/openclaw/kayba-ace/learn_from_traces.py
```

--------------------------------

### TOML Configuration Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/CLI_DESIGN.md

Illustrates the structure of the `ace.toml` file for defining model configurations for different roles.

```toml
[default]
model = "gpt-4o-mini"

[agent]
model = "claude-sonnet-4-20250514"
max_tokens = 4096

[reflector]
model = "gpt-4o-mini"
temperature = 0.2
```

--------------------------------

### TraceAnalyser Usage Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/ACE_REFERENCE.md

Demonstrates how to use TraceAnalyser to learn from browser usage history. Requires `Reflector` and `SkillManager` to be initialized.

```python
from ace import TraceAnalyser, Reflector, SkillManager

traces = [
    {
        "task": "Find the cheapest flight to Tokyo",
        "output": "$450 on ANA, departing March 15",
        "feedback": "Correct price found in 8 steps",
        "reasoning": "Step 1: Navigate to Google Flights...",
    },
    {
        "task": "Book a hotel in Shibuya",
        "output": "Failed: could not find checkout button",
        "feedback": "Task failed after 15 steps — checkout button was behind a cookie modal",
        "reasoning": "Step 1: Navigate to Booking.com...",
    },
]

analyser = TraceAnalyser.from_roles(reflector=Reflector("gpt-4o-mini"), skill_manager=SkillManager("gpt-4o-mini"))
results = analyser.run(traces, epochs=2)
analyser.save("travel_agent.json")

```

--------------------------------

### Agent Usage Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/ACE_REFERENCE.md

Demonstrates how to instantiate and use the Agent class to generate answers based on a question, context, and skillbook.

```python
agent = Agent("gpt-4o-mini")
output = agent.generate(
    question="What is the capital of France?",
    context="Answer concisely",
    skillbook=skillbook,
)
# output.final_answer == "Paris"
# output.skill_ids == ["geography-00001"]
```

--------------------------------

### Browser-Use Runner Setup

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/guides/integration.md

Quickly set up the BrowserUse runner using `from_model()`. Specify models for the browser LLM and ACE, then run tasks and save the skillbook.

```python
from ace import BrowserUse
from langchain_openai import ChatOpenAI

runner = BrowserUse.from_model(
    browser_llm=ChatOpenAI(model="gpt-4o"),
    ace_model="gpt-4o-mini",
)
results = runner.run(["Find top HN post", "Check weather in NYC"])
runner.save("browser_expert.json")
```

--------------------------------

### LiteLLM Supported Providers

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/litellm.md

Examples of initializing ACELiteLLM with models from different providers like OpenAI, Anthropic, Google, and local Ollama.

```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")
```

--------------------------------

### Install OpenClaw Skill Automatically

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/openclaw.md

Use the setup script to automatically copy the ACE skill into your OpenClaw workspace and update AGENTS.md. The script is idempotent and handles existing configurations.

```bash
git clone https://github.com/Kayba-ai/agentic-context-engine.git
cd agentic-context-engine
python examples/openclaw/setup.py
```

```bash
python examples/openclaw/setup.py --no-agents        # skip AGENTS.md patching
python examples/openclaw/setup.py --openclaw-home /path/to/.openclaw  # custom path
```

--------------------------------

### Prepare Training Samples

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/guides/full-pipeline.md

Create a list of Sample objects, each containing a question, context, and ground truth for training.

```python
from ace import Sample

samples = [
    Sample(question="What is 2+2?", context="", ground_truth="4"),
    Sample(question="Capital of France?", context="", ground_truth="Paris"),
    Sample(question="Who wrote Hamlet?", context="", ground_truth="Shakespeare"),
]
```

--------------------------------

### ACE Live Q&A Training Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/ACE_REFERENCE.md

Shows how to set up and run ACE for live question-answering training with a specified environment. Requires `Agent`, `Reflector`, and `SkillManager`.

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

samples = [
    Sample(question="Capital of France?", ground_truth="Paris"),
    Sample(question="Largest ocean?", ground_truth="Pacific"),
]

ace = ACE.from_roles(
    agent=Agent("gpt-4o-mini"),
    reflector=Reflector("gpt-4o-mini"),
    skill_manager=SkillManager("gpt-4o-mini"),
    environment=SimpleEnvironment(),
)
results = ace.run(samples, epochs=3)
ace.save("geography.json")

```

--------------------------------

### Smoke Test with MCP Inspector

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/mcp-client-setup.md

Verify the ACE MCP server generically using the MCP Inspector. This command checks if the server starts and the six ACE tools appear, indicating a successful server setup.

```bash
npx @modelcontextprotocol/inspector ace-mcp
```

--------------------------------

### configure()

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/tracing.md

Sets up the tracing environment by configuring the API key, base URL, experiment, and folder.

```APIDOC
## configure()

### Description
Set API key, base URL, experiment, and folder for tracing.

### Parameters
- **api_key** (string) - Required - The API key for authentication.
- **base_url** (string) - Optional - The base URL for the tracing service.
- **experiment** (string) - Optional - The name of the experiment.
- **folder** (string) - Optional - The target folder for traces.
```

--------------------------------

### Install ACE Dependencies

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/openclaw.md

Install the necessary dependencies for ACE on the host machine using uv. Ensure you have Python 3.12+ installed.

```bash
cd agentic-context-engine
uv sync
```

--------------------------------

### Full ACE Pipeline Setup

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/getting-started/quick-start.md

Sets up a full ACE pipeline using Agent, Reflector, and SkillManager roles. Trains the pipeline on provided samples and saves the learned strategies.

```python
from ace import (
    ACE, Agent, Reflector, SkillManager,
    Sample, SimpleEnvironment,
)

# Create roles (each takes a model string directly)
agent = Agent("gpt-4o-mini")
reflector = Reflector("gpt-4o-mini")
skill_manager = SkillManager("gpt-4o-mini")

# Build the adaptive pipeline
runner = ACE.from_roles(
    agent=agent,
    reflector=reflector,
    skill_manager=skill_manager,
    environment=SimpleEnvironment(),
)

# Train on samples
samples = [
    Sample(question="What is the capital of France?", context="", ground_truth="Paris"),
    Sample(question="What is 2 + 2?", context="", ground_truth="4"),
]

results = runner.run(samples, epochs=2)
print(f"Learned {len(runner.skillbook.skills())} strategies")
runner.save("trained.json")
```

--------------------------------

### List Integrations

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/ace/cli/commands/kayba-agent-instructions.md

Shows configured integrations. Use --json for machine-readable output.

```bash
kayba integrations list [--json]
```

--------------------------------

### Initialize ACE Offline Adapter and Run

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/examples/agentic-system-prompting/README.md

Initializes the LLM client, ACE components, loads samples, and runs the offline adapter. Saves the generated skillbook to a JSON file.

```python
from ace import (
    Skillbook,
    Sample,
    OfflineACE,
    Reflector,
    SkillManager,
    ReplayAgent,
    SimpleEnvironment,
)
from ace.llm_providers.litellm_client import LiteLLMClient, LiteLLMConfig
from ace.prompts_v3 import PromptManager

# 1. Initialize LLM client
config = LiteLLMConfig(
    model="claude-sonnet-4-5-20250929",
    max_tokens=8192,
    temperature=0.1,
)
llm = LiteLLMClient(config=config)
prompt_mgr = PromptManager()

# 2. Create ACE components
skillbook = Skillbook()
agent = ReplayAgent()  # Dummy agent that replays conversations
reflector = Reflector(llm=llm, prompt_template=prompt_mgr.get_reflector_prompt())
skill_manager = SkillManager(llm=llm, prompt_template=prompt_mgr.get_skill_manager_prompt())

# 3. Load past conversations as samples
samples = [
    Sample(
        question="Your task description here",
        context="The full conversation/trace content",
        ground_truth="",  # Empty for analysis tasks
        metadata={"source": "conversation_1"}
    ),
    # ... more historical data
]

# 4. Create adapter and run
environment = SimpleEnvironment()
adapter = OfflineACE(
    skillbook=skillbook,
    agent=agent,
    reflector=reflector,
    skill_manager=skill_manager,
)
results = adapter.run(samples, environment, epochs=1)

# 5. Review and save generated skills
print(adapter.skillbook.as_prompt())
adapter.skillbook.save_to_file("offline_adapter_skillbook.json")
```

--------------------------------

### Install Kayba Pipeline Skill

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/claude-code.md

Install the 'kayba-pipeline' skill for Claude Code, which provides a 7-stage evaluation and improvement pipeline.

```bash
kayba setup
```

```bash
kayba setup --no-skills
```

--------------------------------

### Ace Models Usage Examples

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/CLI_DESIGN.md

When called without arguments, 'ace models' shows usage examples for searching models.

```bash
$ ace models
Usage: ace models <query>

Examples:
  ace models claude          All Claude models
  ace models gpt 4o          GPT-4o variants
  ace models haiku us        US-region Haiku models
  ace models --provider openai  All OpenAI models

```

--------------------------------

### Install Native Provider Extras

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/ACE_REFERENCE.md

Commands to install optional extras for PydanticAI to enable faster calls with specific LLM providers.

```bash
uv add "pydantic-ai-slim[anthropic]"    # uses ANTHROPIC_API_KEY
uv add "pydantic-ai-slim[openai]"       # uses OPENAI_API_KEY
uv add "pydantic-ai-slim[bedrock]"      # uses AWS credentials
uv add "pydantic-ai-slim[anthropic,openai,bedrock]"  # multiple
```

--------------------------------

### Install ACE Framework with Claude Code Support

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/claude-code.md

Install the necessary ACE framework package that includes support for Claude Code.

```bash
uv add 'ace-framework[claude-code]'
```

--------------------------------

### List Configured Integrations

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/hosted-api.md

Lists all configured integrations. Use the --json flag for machine-readable output.

```bash
kayba integrations list
```

```bash
kayba integrations list --json
```

--------------------------------

### Opik Configuration Example

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/opik.md

A correct configuration for Comet Cloud typically includes the 'url_override' and 'workspace' parameters. Verify these settings if traces are not appearing.

```ini
[opik]
url_override = https://www.comet.com/opik/api/
workspace = your-workspace-name
```

--------------------------------

### Install PydanticAI Extras

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/ACE_ARCHITECTURE.md

Shows how to install PydanticAI with specific provider extras for native provider support. This is required for faster, direct API calls.

```bash
uv add "pydantic-ai-slim[anthropic,openai,bedrock]"
```

--------------------------------

### Deploy ACE with Live Learning

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/examples/ace/ace_demo.ipynb

Initializes and runs ACE with live learning enabled, reusing an evolved skillbook. Shows how to process samples and observe skillbook updates.

```python
ace_phase2 = ACE.from_roles(
    agent=Agent(client),
    reflector=Reflector(client),
    skill_manager=SkillManager(client),
    environment=SimpleEnvironment(),
    skillbook=shared_skillbook,
)

results_phase2 = ace_phase2.run(samples[:3], epochs=1)

print(f"\nPhase 2 — ACE live learning:")
print(f"  Processed {len(results_phase2)} samples")
print(f"  Skills after live learning: {shared_skillbook.stats()}")
```

--------------------------------

### Installation: Add Logfire for Observability

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/claude-sdk.md

Install the Logfire package for enhanced observability with the ACE framework. This is recommended for monitoring and debugging your Claude SDK integrations.

```bash
uv add ace-framework[logfire]
```

--------------------------------

### ace.learn.sample

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/mcp.md

Provide sample question/answer pairs for ACE to learn from. This runs the full ACE pipeline and can be blocked by safe mode.

```APIDOC
## ace.learn.sample

### Description
Provide sample question/answer pairs for ACE to learn from. Runs the full ACE pipeline (Agent, Evaluate, Reflect, Update, Apply).

### Method
APICALL

### Parameters
#### Request Body
- **session_id** (string) - Required - Session identifier.
- **samples** (array) - Required - List of `{question, context?, ground_truth?, metadata?}` items (1–25).
- **epochs** (integer) - Optional - Number of learning passes (default: 1, max: 20).
- **session_config** (object) - Optional - Override model settings.

### Response
#### Success Response
- **processed** (integer) - Number of samples processed.
- **failed** (integer) - Number of samples failed.
- **skill_count_before** (integer) - Skill count before learning.
- **skill_count_after** (integer) - Skill count after learning.
- **new_skill_count** (integer) - Number of new skills created.

### Notes
Blocked by: `ACE_MCP_SAFE_MODE=true`.
```

--------------------------------

### ACE Skillbook Get Request Schema

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/specs/002-ace-mcp-server/contracts/tool-schemas.md

Defines the structure for the request to get skillbook information. Supports session ID, optional limit, and include_invalid flags.

```json
{
  "type": "object",
  "required": ["session_id"],
  "properties": {
    "session_id": { "type": "string", "minLength": 1 },
    "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 },
    "include_invalid": { "type": "boolean", "default": false }
  },
  "additionalProperties": false
}
```

--------------------------------

### Install Prompt into Agent File

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/ace/cli/commands/kayba-agent-instructions.md

Installs a generated prompt into an agent configuration file. Requires target agent, file path, prompt ID, and input file.

```bash
kayba prompts install [--target TARGET] [--file PATH] [--id ID] [--input FILE]
```

--------------------------------

### Loading ACE LiteLLM Client

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/design/CLI_DESIGN.md

Demonstrates different ways to initialize the `ACELiteLLM` client, from setup files, explicit models, or full configuration objects.

```python
from ace import ACELiteLLM

# Option 1: Load from ace.toml + .env (created by `ace setup`)
ace = ACELiteLLM.from_setup()

# Option 2: Explicit model, keys from environment
ace = ACELiteLLM.from_model("gpt-4o-mini")

# Option 3: Full config object
from ace import ACEModelConfig, ModelConfig
ace = ACELiteLLM.from_config(ACEModelConfig(
    default=ModelConfig(model="gpt-4o-mini"),
    agent=ModelConfig(model="claude-sonnet-4-20250514"),
))
```

--------------------------------

### Initialize Full ACE Pipeline

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/api/index.md

Set up the complete adaptive pipeline, including Agent, Reflector, SkillManager, and Environment. Use this for complex adaptation loops requiring multiple components.

```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)
```

--------------------------------

### Start ACE MCP Server

Source: https://github.com/kayba-ai/agentic-context-engine/blob/main/docs/integrations/mcp-client-setup.md

Verify that the ACE MCP server starts correctly by running the `ace-mcp` command. It should log startup information and wait for stdio input.

```bash
ace-mcp
```