# praaihub/mai-builder-labs-supplement architecture

> Architecture diagram of the GitHub repository praaihub/mai-builder-labs-supplement, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/praaihub/mai-builder-labs-supplement
- Repository: https://github.com/praaihub/mai-builder-labs-supplement

## Overview

Ami is an Amazon customer-support agent, presented as two independently runnable stages: Stage 1 provides the core agent, while Stage 2 adds authenticated, per-customer access, policy checks, and long-term memory. The main workflow is a customer request entering through chat, passing through planning and model/tool calls, then returning a support answer grounded in retrieved guidance and order data. Evaluation and feedback scripts are omitted because they support development rather than runtime. Some subsystem wiring is documented but not shown in sampled source, so uncertain links are left out.

Main entry points: [`stage2/main.py`](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/main.py) (Terminal chat), [`stage2/ami/llm.py`](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/llm.py) (Model gateway), [`stage2/ami/tools.py`](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/tools.py) (Support tools), [`stage2/web.py`](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/web.py) (Browser chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Chat entrypoints"]
  node_stage2_web["Browser chat<br/>[web.py]"]
  node_stage2_main["Terminal chat<br/>[main.py]"]
  node_stage1_main["Stage 1 chat<br/>[main.py]"]
end

subgraph group_identity["Identity and policy"]
  node_stage2_auth["Auth and sessions<br/>[auth.py]"]
  node_stage2_policy["Input/output policy<br/>[policy.py]"]
end

subgraph group_agent["Agent runtime"]
  node_stage2_react["ReAct planner<br/>[planner.py]"]
  node_stage2_plan["Plan-execute planner<br/>[plan_execute.py]"]
  node_stage2_agent["Baseline agent<br/>[agent.py]"]
  node_stage2_profile["Agent profile<br/>[agent_profile.py]"]
  node_stage2_memory["Conversation memory<br/>[memory.py]"]
  node_stage2_llm["Model gateway<br/>[llm.py]"]
  node_stage1_react["Stage 1 planner<br/>[planner.py]"]
end

subgraph group_support["Support capabilities"]
  node_stage2_tools["Support tools<br/>[tools.py]"]
  node_stage2_store[("Order store<br/>[store.py]")]
  node_stage2_knowledge["Knowledge retrieval<br/>[knowledge.py]"]
  node_stage2_embedder["Local embedder<br/>[embedder.py]"]
  node_stage2_desk["Human support desk<br/>[desk.py]"]
  node_stage1_tools["Stage 1 tools<br/>[tools.py]"]
  node_stage1_store[("Stage 1 order store<br/>[store.py]")]
end

subgraph group_ops["Tracing and cost"]
  node_stage2_observe["Trace logging<br/>[observe.py]"]
  node_stage2_pricing["Call pricing<br/>[pricing.py]"]
end

node_customer(("Customer"))
node_llm_service{{"LLM proxy"}}

node_customer -->|"sends chat"| node_stage2_web
node_customer -->|"sends chat"| node_stage2_main
node_stage2_web -->|"checks session"| node_stage2_auth
node_stage2_main -->|"authenticates key"| node_stage2_auth
node_stage2_main -->|"checks input/output"| node_stage2_policy
node_stage2_main -->|"runs turn"| node_stage2_react
node_stage2_main -->|"runs selected plan"| node_stage2_plan
node_stage2_main -->|"runs baseline"| node_stage2_agent
node_stage2_main -->|"reads and remembers"| node_stage2_memory
node_stage2_react -->|"requests completion"| node_stage2_llm
node_stage2_plan -->|"requests completion"| node_stage2_llm
node_stage2_agent -->|"requests completion"| node_stage2_llm
node_stage2_llm -->|"sends model request"| node_llm_service
node_stage2_main -->|"loads prompt"| node_stage2_profile
node_stage2_tools -->|"reads and changes orders"| node_stage2_store
node_stage2_tools -.->|"creates support ticket"| node_stage2_desk
node_stage2_knowledge -->|"embeds queries"| node_stage2_embedder
node_stage2_llm -->|"logs calls"| node_stage2_observe
node_stage2_llm -->|"prices usage"| node_stage2_pricing
node_stage1_main -->|"runs turn"| node_stage1_react
node_stage1_tools -->|"reads and changes orders"| node_stage1_store

click node_stage2_web "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/web.py"
click node_stage2_main "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/main.py"
click node_stage2_auth "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/auth.py"
click node_stage2_policy "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/policy.py"
click node_stage2_react "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/planner.py"
click node_stage2_plan "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/plan_execute.py"
click node_stage2_agent "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/agent.py"
click node_stage2_profile "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/agent_profile.py"
click node_stage2_memory "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/memory.py"
click node_stage2_llm "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/llm.py"
click node_stage2_tools "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/tools.py"
click node_stage2_store "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/store.py"
click node_stage2_knowledge "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/knowledge.py"
click node_stage2_embedder "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/embedder.py"
click node_stage2_desk "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/desk.py"
click node_stage2_observe "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/observe.py"
click node_stage2_pricing "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/pricing.py"
click node_stage1_main "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage1/main.py"
click node_stage1_react "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage1/ami/planner.py"
click node_stage1_tools "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage1/ami/tools.py"
click node_stage1_store "https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage1/ami/store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stage2_web,node_stage2_main,node_stage1_main toneBlue
class node_stage2_auth,node_stage2_policy toneAmber
class node_stage2_react,node_stage2_plan,node_stage2_agent,node_stage2_profile,node_stage2_memory,node_stage2_llm,node_stage1_react toneMint
class node_stage2_tools,node_stage2_store,node_stage2_knowledge,node_stage2_embedder,node_stage2_desk,node_stage1_tools,node_stage1_store toneRose
class node_stage2_observe,node_stage2_pricing,node_customer,node_llm_service toneIndigo
```

## Components

### Chat entrypoints

- [Browser chat](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/web.py): `stage2/web.py`
- [Terminal chat](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/main.py): `stage2/main.py`
- [Stage 1 chat](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage1/main.py): `stage1/main.py`

### Identity and policy

- [Auth and sessions](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/auth.py): `stage2/ami/auth.py`
- [Input/output policy](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/policy.py): `stage2/ami/policy.py`

### Agent runtime

- [ReAct planner](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/planner.py): `stage2/ami/planner.py`
- [Plan-execute planner](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/plan_execute.py): `stage2/ami/plan_execute.py`
- [Baseline agent](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/agent.py): `stage2/ami/agent.py`
- [Agent profile](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/agent_profile.py): `stage2/ami/agent_profile.py`
- [Conversation memory](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/memory.py): `stage2/ami/memory.py`
- [Model gateway](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/llm.py): `stage2/ami/llm.py`
- [Stage 1 planner](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage1/ami/planner.py): `stage1/ami/planner.py`

### Support capabilities

- [Support tools](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/tools.py): `stage2/ami/tools.py`
- [Order store](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/store.py): `stage2/ami/store.py`
- [Knowledge retrieval](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/knowledge.py): `stage2/ami/knowledge.py`
- [Local embedder](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/embedder.py): `stage2/ami/embedder.py`
- [Human support desk](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/desk.py): `stage2/ami/desk.py`
- [Stage 1 tools](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage1/ami/tools.py): `stage1/ami/tools.py`
- [Stage 1 order store](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage1/ami/store.py): `stage1/ami/store.py`

### Tracing and cost

- [Trace logging](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/observe.py): `stage2/ami/observe.py`
- [Call pricing](https://github.com/praaihub/mai-builder-labs-supplement/blob/main/stage2/ami/pricing.py): `stage2/ami/pricing.py`

### Other components

- **Customer**
- **LLM proxy**

## Connections

- Customer → Browser chat: sends chat
- Customer → Terminal chat: sends chat
- Browser chat → Auth and sessions: checks session
- Terminal chat → Auth and sessions: authenticates key
- Terminal chat → Input/output policy: checks input/output
- Terminal chat → ReAct planner: runs turn
- Terminal chat → Plan-execute planner: runs selected plan
- Terminal chat → Baseline agent: runs baseline
- Terminal chat → Conversation memory: reads and remembers
- ReAct planner → Model gateway: requests completion
- Plan-execute planner → Model gateway: requests completion
- Baseline agent → Model gateway: requests completion
- Model gateway → LLM proxy: sends model request
- Terminal chat → Agent profile: loads prompt
- Support tools → Order store: reads and changes orders
- Support tools → Human support desk: creates support ticket
- Knowledge retrieval → Local embedder: embeds queries
- Model gateway → Trace logging: logs calls
- Model gateway → Call pricing: prices usage
- Stage 1 chat → Stage 1 planner: runs turn
- Stage 1 tools → Stage 1 order store: reads and changes orders