Quick Start

Build from source

git clone https://gitlab.agentstatelabs.com/AgentStateLabs/AgentStateRouter
cd AgentStateRouter
cargo build --release -p aeoe-suggester

Run the Suggester

cargo run --release -p aeoe-suggester -- --http --port 4001

The Suggester writes its history to a local AgentStateGraph store (./router.db by default).

Route a task

curl -X POST http://localhost:4001/route \
  -H "Content-Type: application/json" \
  -d '{
    "task": "code-review",
    "context": 12400,
    "latency_budget_ms": 5000
  }'

Response:

{
  "chosen_model": "claude-sonnet-4.6",
  "predicted_cost": 0.014,
  "predicted_quality": 0.91,
  "confidence": 0.87,
  "reasoning": "prior 64 runs on code-review at this context size; sonnet beats opus on cost-per-unit-of-work by 4.2×"
}

Record an outcome

curl -X POST http://localhost:4001/outcome \
  -d '{
    "route_id": "...",
    "actual_cost": 0.013,
    "actual_latency_ms": 3200,
    "quality_score": 0.93
  }'

The outcome is committed back into AgentStateGraph; the next call for a similar task sees the updated score.

Use it as an OpenAI-compatible proxy

The proxy facade speaks the OpenAI Chat Completions API. Set the base URL and pick model="auto":

from openai import OpenAI
client = OpenAI(
  base_url="http://localhost:4001/v1",
  api_key="sk-aeoe-...",
)
client.chat.completions.create(
  model="auto",   # AEOE picks
  messages=[{"role": "user", "content": "Review this diff: ..."}],
)