Quickstart

Quickstart

Install

git clone https://github.com/rrahimi-uci/agentic-context-engineering && cd agentic-context-engineering
pip install -e .            # core library (numpy + rich only)

For the OpenAI Agents SDK integration and real LLM backends:

pip install "ace-playbook[all]"     # adds openai + openai-agents (SDK needs Python 3.10+)
export OPENAI_API_KEY=sk-...

The core library needs Python 3.9+; the OpenAI Agents SDK integration needs Python 3.10+.

---

Run the headline comparison — no API key required

The bundled SimulatedLLM + TeachingEnvironment make this fully deterministic and offline:

ace demo --html report.html

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Method                      ┃ Accuracy ┃ Playbook ┃ Note        ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ Base LLM (no context)       │ 44.4%    │ 0        │ —           │
│ ACE (offline → eval)        │ 83.3%    │ 5        │ +38.9 pts   │
│ Monolithic rewrite (online) │ 72.2%    │ 4        │ 2 collapses │
│ ACE (online)                │ 83.3%    │ 6        │ no collapse │
└─────────────────────────────┴──────────┴──────────┴─────────────┘

Watch a run adapt live in your terminal:

ace run            # animated dashboard: playbook growth, accuracy, deltas

Other CLI subcommands:

ace playbook       # inspect a saved playbook
ace version        # print the installed version

---

…or in ~10 lines of Python

from ace import ACE, SimulatedLLM, TeachingEnvironment, build_teaching_task
from ace.baselines import StaticAgent

env  = TeachingEnvironment()
task = build_teaching_task()
train, test = task.split()

base = StaticAgent(SimulatedLLM(env)).run(test)        # no learning
ace  = ACE(SimulatedLLM(env))
ace.adapt_offline(train)                               # build a playbook from feedback
result = ace.evaluate(test)                            # measure on held-out data

print(f"Base {base.accuracy:.0f}%  →  ACE {result.accuracy:.0f}%")
print(ace.playbook.render())                           # human-readable playbook

---

Next steps

• How It Works — the mechanics of the adaptation loop.
• OpenAI Agents SDK — make a real agent self-improving in one call.
• Custom Tasks and Feedback — point ACE at your own data and signals.
• Cookbook — 10 short recipes, ordered as a learning path.