from orchestrator.agent import BaseAgent

agent = BaseAgent(
    name="support-bot",
    instructions="You are a support agent for Acme Corp. Be concise.",
    model="gpt-4o-mini",
    temperature=0.3,
)

# Stateless — no Redis, no mem0 calls (fastest for prototypes)
agent = BaseAgent(
    name="stateless",
    instructions="...",
    memory_config=AgentMemoryConfig(search_memories=False, store_memories=False),
    config=AgentConfig(log_to_session=False, session_history_turns=0),
)

# Stateful — loads last 20 turns + long-term memories (default)
agent = BaseAgent(
    name="stateful",
    instructions="...",
    memory_config=AgentMemoryConfig(search_memories=True, store_memories=True),
    config=AgentConfig(log_to_session=True, session_history_turns=None),
)

async def on_start(agent, context):
    print(f"Starting {agent.name}")

async def on_tool(agent, tool_name, context):
    print(f"Calling tool: {tool_name}")

agent = BaseAgent(
    name="my-agent",
    instructions="...",
    on_start=on_start,
    on_end=lambda agent, ctx: print("Done"),
    on_error=lambda agent, exc, ctx: print(f"Error: {exc}"),
    on_tool_call=on_tool,
    on_handoff=lambda agent, target, ctx: print(f"Handing off to {target}"),
)

agent = BaseAgent(
    name="regional-agent",
    instructions="You serve customers in {region}. Currency: {currency}.",
    template_vars={"region": "North America", "currency": "USD"},
)

agent = BaseAgent(
    name="classifier",
    instructions="Classify the sentiment of the input.",
    examples=[
        {"input": "I love this product!", "output": "positive"},
        {"input": "This is terrible.",  "output": "negative"},
    ],
)

def add_date(instructions, context):
    return instructions + f"\n\nToday is {context.get('date', 'unknown')}."

agent = BaseAgent(
    name="date-aware",
    instructions="You are an assistant.",
    instruction_modifiers=[add_date],
)

from pydantic import BaseModel

class Review(BaseModel):
    sentiment: str
    score: float
    summary: str

agent = BaseAgent(
    name="reviewer",
    instructions="Analyze the review and return structured output.",
    output_schema=Review,
)

response = await runner.run(agent, "The hotel was fantastic but expensive.")
review: Review = response.structured_output
print(review.score)  # e.g. 0.75

class ParallelCoordinatorAgent(BaseAgent):
    synthesiser: BaseAgent | None = None
    parallel: ParallelAgent | None = None

    async def execute(self, input_text, runner, context, llm_client=None) -> AgentResponse:
        context.suppress_session_log = True

        # Step 1: parallel workers with a fresh stateless context (no history, no save)
        parallel_ctx = create_run_context(
            user_id=context.user_id,
            conversation_id=context.conversation_id,
        )
        parallel_result = await self.parallel.execute(input_text, runner, parallel_ctx)

        # Step 2: synthesiser uses session history + memory; suppress_session_log
        # blocks auto-save but context carries session_id so history loads normally
        final = await runner.run(
            agent=self.synthesiser,
            input=synthesis_input,
            context=context,
        )

        # Step 3: save exactly one clean turn
        await runner.save_turn(
            session_id=context.session_id,
            user_message=input_text,
            assistant_message=final.content,
        )

from orchestrator.agent.workflow import SequentialAgent

pipeline = SequentialAgent(
    name="research-pipeline",
    instructions="Research pipeline coordinator.",
    agents=[researcher, summarizer, formatter],
)

from orchestrator.agent import BaseAgent, AgentRunner, create_sequential_agent

researcher = BaseAgent(name="researcher", instructions="Research the topic. Output key facts.", model="gpt-4o-mini")
writer     = BaseAgent(name="writer",     instructions="Write a short report from the facts.",  model="gpt-4o-mini")
editor     = BaseAgent(name="editor",     instructions="Polish the report for clarity.",         model="gpt-4o-mini")

pipeline = create_sequential_agent(
    name="research-pipeline",
    agents=[researcher, writer, editor],
)
response = await AgentRunner().run(pipeline, "AI in healthcare")
print(response.content)  # editor's final output

from orchestrator.agent.workflow import ParallelAgent
from orchestrator.agent.config import ParallelConfig, MergeStrategy

fan_out = ParallelAgent(
    name="multi-analyst",
    instructions="Run multiple analyses in parallel.",
    agents=[sentiment_agent, topic_agent, entity_agent],
    parallel_config=ParallelConfig(
        merge_strategy=MergeStrategy.LLM_SUMMARIZE,
    ),
)

from orchestrator.agent import create_parallel_agent
from orchestrator.agent.types import MergeStrategy

parallel = create_parallel_agent(
    name="parallel-analysts",
    agents=[analyst_a, analyst_b, analyst_c],
    merge_strategy=MergeStrategy.CONCATENATE,
)

from orchestrator.agent.workflow import LoopAgent
from orchestrator.agent.config import TerminationConfig, TerminationType

loop = LoopAgent(
    name="refinement-loop",
    instructions="Iteratively refine output.",
    agent=writer_agent,
    termination=TerminationConfig(
        type=TerminationType.LLM_DECISION,  # LLM decides when done
        max_iterations=5,
    ),
)

from orchestrator.agent import create_loop_agent
from orchestrator.agent.types import TerminationType

loop = create_loop_agent(
    name="refinement-loop",
    agent=refiner,
    termination_type=TerminationType.OUTPUT_MATCH,
    termination_pattern=r"\bDONE\b",
    max_iterations=3,
)

from orchestrator.agent.workflow import ReflectionAgent
from orchestrator.agent.config import ReflectionConfig

reflective = ReflectionAgent(
    name="quality-writer",
    instructions="Improve output quality via self-critique.",
    agent=writer_agent,
    reflection_config=ReflectionConfig(
        max_reflections=3,
        critique_prompt="Is this response accurate and complete? Reply APPROVED or NEEDS IMPROVEMENT.",
    ),
)

from orchestrator.agent.workflow import RouterAgent, Route

router = RouterAgent(
    name="triage",
    instructions="Route customer requests to the right specialist.",
    routes=[
        Route(agent_name="billing-agent",  description="Billing, payments, invoices"),
        Route(agent_name="tech-support",  description="Technical issues and bugs"),
        Route(agent_name="sales-agent",   description="Pricing and upgrades"),
    ],
    fallback_agent_name="general-agent",
)

from orchestrator.agent import BaseAgent, AgentRunner, create_router_agent

billing   = BaseAgent(name="billing-agent",   instructions="Handle billing questions.")
technical = BaseAgent(name="technical-agent", instructions="Handle technical support.")
general   = BaseAgent(name="general-agent",   instructions="Handle general questions.")

router = create_router_agent(
    name="triage",
    routes=[
        ("billing-agent",   "billing, invoice, payment, subscription, refund"),
        ("technical-agent", "bug, error, crash, not working, how to"),
    ],
    fallback="general-agent",
    strategy="hybrid",
)

runner = AgentRunner(agent_registry={
    "billing-agent": billing, "technical-agent": technical, "general-agent": general,
})
response = await runner.run(router, "My payment failed twice this week")

from orchestrator.agent.workflow import PlannerAgent
from orchestrator.agent.config import PlanningConfig

# Agent-pool mode: LLM routes each step to a specialist
planner = PlannerAgent(
    name="research-planner",
    instructions="Decompose research goals into steps.",
    agents=[web_researcher, analyst, writer],
    planning_config=PlanningConfig(
        max_steps=8,
        enable_replanning=True,
    ),
)

from orchestrator.agent.handoff import Handoff

triage = BaseAgent(
    name="triage",
    instructions="Triage requests and hand off to specialists.",
    handoffs=[
        Handoff(
            target_agent="billing",
            description="Transfer to billing for payment questions.",
            return_to_parent=True,
        ),
        Handoff(
            target_agent="tech-support",
            description="Transfer for technical issues.",
        ),
    ],
)

from orchestrator.agent.handoff import Handoff, HistorySummarizationMode

Handoff(
    target_agent="specialist",
    description="Escalate complex issues.",
    summarization_mode=HistorySummarizationMode.HYBRID,
    recent_turns=4,
)

from orchestrator.agent.runner import AgentRunner
from orchestrator.agent.config import RunnerConfig

runner = AgentRunner(
    config=RunnerConfig(
        default_max_turns=20,
        parallel_tool_calls=True,
        max_parallel_tools=5,
        circuit_breaker_threshold=5,
    )
)

response = await runner.run(
    agent,
    "What is my account balance?",
    user_id="user-123",
    session_id="sess-456",  # optional — loads Redis history
    conversation_id="conv-789",
    max_turns=15,
    metadata={"channel": "web"},
    tags=["prod"],
)

print(response.content)         # main text output
print(response.status)          # SUCCESS, ERROR, MAX_TURNS_REACHED …
print(response.usage.total_tokens)
print(response.latency_ms)
print(response.trace_id)        # Langfuse trace link

from orchestrator.agent.types import EventType

async for event in runner.run_stream(agent, "Explain quantum entanglement.", user_id="u-1"):
    if event.type == EventType.CONTENT_DELTA:
        print(event.data["content"], end="", flush=True)

    elif event.type == EventType.TOOL_CALL_START:
        print(f"\n[calling tool: {event.data['tool_name']}]")

    elif event.type == EventType.RUN_END:
        print(f"\nDone — {event.data['usage']['total_tokens']} tokens")

# Turn 1 — user's first message
response1 = await runner.run(agent, "My name is Alice.", session_id="sess-1", user_id="u-1")

# Turn 2 — agent remembers context from Redis
response2 = await runner.run(agent, "What's my name?", session_id="sess-1", user_id="u-1")
# → "Your name is Alice."

# Step 1: create or retrieve the session
session_id = await session_client.get_or_create_session(
    session_id=session_id,          # pass existing ID to resume
    user_id="user-123",
    conversation_id="conv-456",   # optional — see below
)

# Step 2: run with that session_id
response = await runner.run(
    agent=agent,
    input="Hello!",
    session_id=session_id,
    user_id="user-123",
)

async def execute(self, input_text, runner, context) -> AgentResponse:
    context.suppress_session_log = True  # blocks auto-save for ALL sub-agent runs

    response = await runner.run(
        agent=sub_agent,
        input=current_input,
        context=context,   # same context object passed every time
    )
    # ... more sub-agent calls ...

    # Save exactly one clean turn at the end
    await runner.save_turn(
        session_id=context.session_id,
        user_message=input_text,        # what user originally sent
        assistant_message=final_output, # what user actually sees
    )

await runner.save_turn(session_id, user_input, last_agent_response.content)

await runner.save_turn(session_id, user_input, top_level_agent_response.content)

from orchestrator import AgentConfig, ContextManagementConfig, CompressionStrategy

agent = BaseAgent(
    name="long-conv",
    instructions="...",
    config=AgentConfig(
        context_management=ContextManagementConfig(
            compression_strategy=CompressionStrategy.SMART,  # SMART / SUMMARIZE_OLD / TRUNCATE_OLDEST
        )
    ),
)

from orchestrator.core import OrchestratorLifecycle, Container

lifecycle = OrchestratorLifecycle()
await lifecycle.startup()   # connects Redis, Langfuse, vector store

# Health checks
health = await lifecycle.health_check()
# → {"redis": "ok", "qdrant": "ok", "langfuse": "ok", "llm": "ok"}

await lifecycle.shutdown()  # flushes Langfuse, closes Redis connections

# Inject custom clients (e.g. in tests or multi-tenant setups)
from orchestrator.core import Container

container = Container()
container.set_llm_client(my_llm_client)
container.set_memory_client(my_memory_client)
container.set_session_client(my_session_client)

runner = AgentRunner(container=container)

from fastapi import FastAPI
from orchestrator.agent import BaseAgent
from orchestrator.agent.runner import AgentRunner

app = FastAPI()
runner = AgentRunner()
agent = BaseAgent(name="api-agent", instructions="You are an API assistant.")

@app.post("/chat")
async def chat(body: dict):
    response = await runner.run(
        agent,
        body["message"],
        user_id=body["user_id"],
        session_id=body.get("session_id"),
    )
    return {"reply": response.content, "session_id": body.get("session_id")}

from orchestrator.temporal import WorkerManager, AgentRegistry

registry = AgentRegistry()
registry.register(my_agent)

worker_manager = WorkerManager(agent_registry=registry)
await worker_manager.start_worker()  # connects to TEMPORAL_HOST

def pii_scanner(text: str) -> str:
    # Replace detected emails with [REDACTED]
    import re
    return re.sub(r'\S+@\S+', '[REDACTED]', text)

agent = BaseAgent(
    name="safe-agent",
    instructions="...",
    config=AgentConfig(
        input_scanners=[pii_scanner],
        output_scanners=[pii_scanner],
        injection_detection=True,
    ),
)

# conftest.py
import pytest
import fakeredis.aioredis as fakeredis
from orchestrator.core import Container

@pytest.fixture
async def container():
    c = Container()
    c.set_session_client(SessionClient(redis=fakeredis.FakeRedis()))
    return c

# test_agent.py
import pytest

@pytest.mark.asyncio
async def test_basic_response(container, real_llm_client):
    container.set_llm_client(real_llm_client)
    runner = AgentRunner(container=container)
    response = await runner.run(agent, "Say hello.", user_id="test-user")
    assert response.status.value == "success"
    assert len(response.content) > 0

from orchestrator.tools import MCPServerStdio, MCPServerSse, MCPServerStreamableHttp

# Spawn a subprocess (local Python script or shell command)
fs_server = MCPServerStdio(command="python", args=["-m", "mcp_filesystem"])

# Server-Sent Events (remote server)
sse_server = MCPServerSse(url="https://tools.example.com/mcp/sse")

# StreamableHTTP (recommended for production)
http_server = MCPServerStreamableHttp(url="https://tools.example.com/mcp")

agent = BaseAgent(
    name="tool-agent",
    instructions="You have access to the filesystem.",
    mcp_servers=[fs_server],
)

from orchestrator.tools import MCPUtil, ToolExecutor

# Get tool definitions from a connected server
tool_defs = await MCPUtil.get_function_tools(server)
tools = [t.model_dump() for t in tool_defs]

executor = ToolExecutor({server: None})   # None = expose all tools
await executor.initialize()

agent = BaseAgent(
    name="agent",
    instructions="...",
    tools=tools,
    tool_executor=executor,
)

from orchestrator.agent.config import AgentConfig, ToolAttentionConfig

agent = BaseAgent(
    name="commerce-agent",
    instructions="...",
    mcp_servers=[shop_server],    # 50+ tools
    config=AgentConfig(
        tool_attention=ToolAttentionConfig(
            enabled=True,
            max_tools=10,        # send at most 10 tools per turn
        )
    ),
)

from orchestrator.tools import MCPServerStreamableHttp

# Capture session_id from the login tool result, inject into every subsequent call
shop_server = MCPServerStreamableHttp(
    url="https://shop.example.com/mcp",
    tool_context={
        "capture": {"login": "session_id"},   # tool name → result field to capture
        "inject":  {"session_id": "session_id"}, # param name → captured key
    },
)

response = await runner.run(agent, "Show me the product catalog.")

if response.run_artifacts:
    for artifact_id, artifact in response.run_artifacts.items():
        widget_meta = artifact.get("meta")       # widget template
        structured  = artifact.get("structured_content")
        text        = artifact.get("text_content")

from orchestrator.agent.config import AgentMemoryConfig
from orchestrator.memory.scopes import MemoryScope

agent = BaseAgent(
    name="memory-agent",
    instructions="Remember user preferences.",
    memory_config=AgentMemoryConfig(
        search_memories=True,
        search_scope=MemoryScope.USER,
        search_limit=5,
        store_memories=True,
        store_scope=MemoryScope.USER,
        broadcast_learnings=True,  # share useful facts with other agents
    ),
)

# extraction_prompt — override mem0's default extraction logic
AgentMemoryConfig(
    store_memories=True,
    extraction_prompt=(
        "Only extract long-term facts about the user's pets, animal preferences, "
        "and dietary needs. Do NOT store transient actions like adding to cart or searches."
    ),
)

# pre_store_filter — runs after storage; facts not returned are deleted
def remove_pii(facts: list[str]) -> list[str]:
    return [f for f in facts if "credit card" not in f]

AgentMemoryConfig(store_memories=True, pre_store_filter=remove_pii)

from orchestrator.core.container import get_container

memory_client = get_container().memory_client

# View all memories for a user
memories = await memory_client.get_all(user_id="user-123")
for m in memories:
    print(m.memory, m.id)

# Search by query
results = await memory_client.search("pet preferences", user_id="user-123")

# Delete a specific memory
await memory_client.delete(memory_id="abc-123")

# Delete all memories for a user (GDPR right-to-forget)
await memory_client.delete_all(user_id="user-123")

from orchestrator.memory import IntelligentMemoryClient, IntelligenceConfig

memory = IntelligentMemoryClient(
    intelligence_config=IntelligenceConfig(
        enable_scoring=True,       # LLM scores each memory at store time
        enable_decay=True,         # recent memories get a relevance boost
        prune_threshold=0.15,      # delete memories below this score
    )
)

# Accepts strings, list of strings, or message dicts
await memory.add(
    [{"role": "user", "content": "I prefer dark mode."}],
    user_id="user-123",
)

results = await memory.search("user preferences", user_id="user-123")

from orchestrator.session import SessionClient

session = SessionClient()

# Create or resume a session
session_id = await session.get_or_create_session(user_id="user-123")

# Read history (e.g. to display in a chat UI)
messages = await session.get_conversation_history(session_id)

# Clear messages but keep the session
await session.clear_session(session_id)

# Delete the session entirely
await session.delete_session(session_id)

from orchestrator.temporal import TemporalClient
from orchestrator.temporal.workflows import AgentWorkflow
from orchestrator.temporal.types import AgentStep, ApprovalStep, ParallelStep

steps = [
    AgentStep(agent_name="researcher", input="Analyze market trends"),
    ApprovalStep(
        description="Review analysis before proceeding",
        approvers=["manager@acme.com"],
        timeout=86400,  # 24 hours
    ),
    AgentStep(agent_name="writer"),  # receives researcher output
]

client = TemporalClient()
handle = await client.execute_workflow(AgentWorkflow, {"steps": steps})

from orchestrator.temporal.workflows import LoopAgentWorkflow

handle = await client.execute_workflow(
    LoopAgentWorkflow,
    {
        "agent_name": "refinement-agent",
        "initial_input": "Draft a product description.",
        "max_iterations": 5,
        "termination_condition": "output_match",
        "termination_pattern": "APPROVED",
    },
)

ApprovalStep(
    description="Approve the generated email before sending to customers",
    approvers=["alice@company.com", "bob@company.com"],
    timeout=3600,           # 1 hour, then auto-expires
    auto_approve_if="low_risk",  # skip approval if condition agent returns this
)

agent = BaseAgent(name="gpt-agent", instructions="...", model="gpt-4o")

agent = BaseAgent(name="claude-agent", instructions="...", model="claude-sonnet-4-5")

agent = BaseAgent(name="gemini-agent", instructions="...", model="gemini/gemini-2.5-flash")

from orchestrator.agent import BaseAgent
from orchestrator.llm import LLMConfig
import os

config = LLMConfig(
    model="azure/gpt-4o",
    api_key=os.environ["AZURE_API_KEY"],
    api_base=os.environ["AZURE_API_BASE"],
    api_version=os.environ["AZURE_API_VERSION"],
)
agent = BaseAgent(name="azure-agent", instructions="...", llm_config=config)

# .env — primary OpenAI, fallback to Gemini
DEFAULT_LLM_MODEL=gpt-4o
FALLBACK_LLM_MODEL=gemini/gemini-1.5-flash
LLM_ENABLE_FALLBACK=true

# docker-compose.yml ships Langfuse at http://localhost:3000
# .env
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=http://localhost:3000

from orchestrator.observability import observe

@observe("preprocess_input")
async def preprocess(text: str) -> str:
    return text.strip().lower()

from orchestrator.observability import trace_tool

@trace_tool("search_products")
async def search_products(query: str):
    # creates a tool-type span with input/output captured
    return await db.search(query)

from orchestrator.observability import trace_agent

@trace_agent("my-specialist")
async def run_specialist(input: str):
    # span tagged as agent-type in Langfuse
    ...

# .env
VECTOR_STORE_PROVIDER=qdrant
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION=orchestrator_memories

# .env (default — no change needed if using docker compose)
VECTOR_STORE_PROVIDER=milvus
MILVUS_HOST=localhost
MILVUS_PORT=19530

# Request lifecycle (Continuum agent → Smart Inference gateway → provider)

inbound request
  ─► requireValidKey            # bearer → virtualKey lookup, fail-closed 401
  ─► requestValidator           # content-type, custom-host checks
  ─► hooks (pre)                # plugin pre-hooks (PII, prompt-shield…)
  ─► memoryCache                # semantic cache (Redis, opt-in)
  ─► classifier                 # stamp complexity + domain
  ─► budget                     # pre-flight cost + reservation
  ─► router                     # model namespace → candidate list → top pick
  ─► provider handler           # native API call (OpenAI / Anthropic / Google / …)
  ─► response transform         # normalise to OpenAI shape
  ─► hooks (post)               # plugin post-hooks
  ─► observability              # flush trace to Langfuse
client ◄┘

# Continuum side — .env
SMART_GATEWAY_URL=http://localhost:8787/v1     # gateway base URL
SMART_GATEWAY_API_KEY=ck-prod-2026-05-19       # bearer (matches a virtual key)
SMART_GATEWAY_DEFAULT_MODE=modest              # strict | modest | quality

// Smart Inference side — conf.json (excerpt)
{
  "integrations": [
    {
      "provider": "anthropic",
      "slug": "dev_team_anthropic",
      "bearer_token": "ck-prod-2026-05-19",
      "credentials": { "api_key_env": "ANTHROPIC_API_KEY" },
      "budget_usd": 100,
      "allowed_models": [
        "auto", "auto/cheap", "auto/mid", "auto/quality",
        "openai/gpt-4o-mini",
        "anthropic/claude-haiku-4-5-20251001",
        "anthropic/claude-opus-4-7",
        "google/gemini-2.0-flash"
      ]
    }
  ]
}

from orchestrator.agent import BaseAgent, AgentRunner

# Auto-routing — gateway picks the model per turn.
agent = BaseAgent(
    name="shop-assistant",
    instructions="You are a friendly pet shop assistant.",
    model="auto",
    gateway_mode="modest",    # "strict" | "modest" | "quality"
)

response = await AgentRunner().run(agent, "Show me dog leashes", user_id="alice")
print(response.content)

# Triage routes fast; specialist reasons carefully.
triage    = BaseAgent(name="triage", model="auto", gateway_mode="strict")
specialist = BaseAgent(name="specialist", model="auto", gateway_mode="quality")

{
  "model": "auto",
  "messages": [{"role": "user", "content": "…"}],
  "metadata": {
    "session_id": "s-001",
    "complexity": "complex",
    "domain": "code"
  }
}

from orchestrator.tools.tool_attention.config import ToolAttentionConfig

agent = BaseAgent(
    name="ops",
    instructions="…",
    tools=large_tool_set,        # 30+ tools
    config=AgentConfig(
        tool_attention=ToolAttentionConfig(k=5, min_tools=10),
    ),
)

def tier_aware(prompt: str, ctx: RunContext) -> str:
    tier = ctx.metadata.get("user_tier", "free")
    if tier == "enterprise":
        return prompt + "\n\nThis is an enterprise user. Prioritise SLA."
    return prompt

agent = BaseAgent(
    name="support",
    instructions="You are helping {user_name}.",
    template_vars={"user_name": "Alice"},
    instruction_modifiers=[tier_aware],
)

from orchestrator.memory import MemoryClient, PIIPolicy

memory = MemoryClient(pii_policy=PIIPolicy.REDACT)

response = await runner.run(agent, "checkout", user_id="alice")
for art in response.artifacts:
    print(art.tool_name, art.structured_content)
    # e.g. ('checkout', {'order_id': 'ORD-92151', 'total_cents': 699})

from orchestrator.evaluation import build_golden_dataset

dataset = await build_golden_dataset(
    project="shop-assistant",
    tags=["good_response"],
    since="2026-04-01",
)
# Use with pytest-asyncio + DeepEval as a CI gate.

┌──────────────┐    HTTP    ┌────────────────┐    OpenAI    ┌──────────────────┐
│  Browser     │ ─────────► │  FastAPI UI    │              │  Smart Inference │
│  /chat       │   POST     │  (web.py :8081)│              │  Gateway :8787   │
└──────────────┘            └────────┬───────┘              └────────┬─────────┘
                                     │                               │
                                     │ Continuum AgentRunner         │ pick model
                                     ▼                               ▼
                            ┌────────────────┐              ┌──────────────────┐
                            │  BaseAgent     │  ◄── tools ──│  OpenAI /        │
                            │  (agent.py)    │              │  Anthropic /     │
                            └────────┬───────┘              │  Google          │
                                     │                      └──────────────────┘
                                     │ MCP StreamableHTTP
                                     ▼
                            ┌────────────────┐              ┌──────────────────┐
                            │  Shop server   │              │  Langfuse :3005  │
                            │  (server.py    │              │  ◄── traces ──── │
                            │   :8888)       │              └──────────────────┘
                            └────────────────┘

Session/memory:  Redis (:6380)  ·  Milvus (:19530)

# LLM / routing
SMART_GATEWAY_URL=http://localhost:8787/v1
SMART_GATEWAY_API_KEY=ck-prod-2026-05-19
SMART_GATEWAY_DEFAULT_MODE=modest

# Observability
LANGFUSE_ENABLED=true
LANGFUSE_HOST=http://localhost:3005           # continuum's docker-compose maps Langfuse to 3005
LANGFUSE_PUBLIC_KEY=pk-lf-…
LANGFUSE_SECRET_KEY=sk-lf-…

# Sessions + memory
SESSION_REDIS_PORT=6380
VECTOR_STORE_PROVIDER=milvus
MILVUS_PORT=19530

OPENAI_API_KEY=sk-…
ANTHROPIC_API_KEY=sk-ant-…
GEMINI_API_KEY=AIza…

# From inside docker, reach the host's Langfuse
LANGFUSE_PUBLIC_KEY=pk-lf-…
LANGFUSE_SECRET_KEY=sk-lf-…
LANGFUSE_BASE_URL=http://host.docker.internal:3005

# playground/gateway-local-shop/server.py (excerpt)
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("local-shop")

PRODUCTS = [
    {"id": "p1", "name": "Dog Food (Dry) 5kg", "price": 29.99, "animal": "dog"},
    # … more products …
]
_carts: dict[str, list] = {}

@mcp.tool()
def search_products(query: str = "", animal: str = "") -> list:
    """Filter products by query / animal."""
    return [p for p in PRODUCTS if (not animal or p["animal"] == animal)]

@mcp.tool()
def add_to_cart(session_id: str, product_id: str, quantity: int = 1) -> dict:
    cart = _carts.setdefault(session_id, [])
    cart.append({"product_id": product_id, "quantity": quantity})
    return {"cart_size": len(cart)}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(mcp.streamable_http_app(), host="0.0.0.0", port=8888)

python playground/gateway-local-shop/server.py     # MCP server on :8888

# playground/gateway-local-shop/agent.py (excerpt)
from orchestrator import AgentConfig, AgentMemoryConfig, AgentMemoryScope, \
    AgentRunner, BaseAgent, MCPServerStreamableHttp, ToolExecutor
from orchestrator.tools.tool_attention.config import ToolAttentionConfig
from orchestrator.tools.types import ToolContextConfig, ToolContextVariable

mcp_server = MCPServerStreamableHttp(
    params={"url": "http://localhost:8888/mcp"},
    context_config=ToolContextConfig(
        variables=[ToolContextVariable(name="session_id",
                  inject_into=["add_to_cart", "view_cart", "checkout"])]
    ),
)
await mcp_server.connect()

executor = ToolExecutor({mcp_server: None})
await executor.initialize()

agent = BaseAgent(
    name="shop-assistant",
    instructions="You are a friendly pet shop assistant.",
    model="auto",                        # gateway picks
    gateway_mode=None,                    # falls back to SMART_GATEWAY_DEFAULT_MODE
    tools=executor.get_tool_definitions(),
    tool_executor=executor,
    memory_config=AgentMemoryConfig(
        search_memories=True, store_memories=True,
        search_scope=AgentMemoryScope.USER,
        store_scope=AgentMemoryScope.USER,
    ),
    config=AgentConfig(
        max_turns=3,
        log_to_session=True,
        tool_attention=ToolAttentionConfig(k=3, min_tools=3),
    ),
)

# cli.py
import asyncio
from agent import agent, executor

async def main():
    runner = AgentRunner(tool_executor=executor)
    runner.register_agent(agent)
    while True:
        msg = input("you ❭ ").strip()
        if not msg: break
        r = await runner.run(agent, msg, user_id="alice", conversation_id="local")
        print("agent ❭", r.content)

asyncio.run(main())

# web.py — POST /chat returns the agent's reply as JSON
@app.post("/chat")
async def chat(req: ChatRequest):
    response = await shop_agent.chat(
        req.message,
        user_id=req.user_id,
        conversation_id=req.conversation_id,
    )
    return {"response": response}

python playground/gateway-local-shop/web.py    # open http://localhost:8081