# experientiallabs/experiential architecture

> Architecture diagram of the GitHub repository experientiallabs/experiential, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/experientiallabs/experiential
- Repository: https://github.com/experientiallabs/experiential

## Overview

Experiential combines an OpenAI-compatible model gateway with tooling that turns agent traces into evaluated and optimized routers. The main workflow is: capture or ingest traces, build project data, simulate and evaluate candidate behavior, then fit and serve a router. Separate branches cover gateway setup and governance, judge calibration, and model fine-tuning. The graph emphasizes documented workflows and relationships visible in the supplied source index; many implementation files were not sampled, so uncertain internal calls are omitted.

Main entry points: [`exp/runtime/gateway/routing.py`](https://github.com/experientiallabs/experiential/blob/main/exp/runtime/gateway/routing.py) (Request routing), [`exp/runtime/gateway/native/src/server.rs`](https://github.com/experientiallabs/experiential/blob/main/exp/runtime/gateway/native/src/server.rs) (Native API server), [`exp/common/project/store.py`](https://github.com/experientiallabs/experiential/blob/main/exp/common/project/store.py) (Project artifacts), [`exp/optimize/router/fit/workflow.py`](https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/fit/workflow.py) (Router fitting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway and runtime"]
  node_cli["CLI<br/>[app.py]"]
  node_gateway_setup["Gateway setup<br/>[app.py]"]
  node_gateway_app["Gateway application<br/>[application.py]"]
  node_gateway_server["Native API server<br/>[server.rs]"]
  node_gateway_routing["Request routing<br/>[routing.py]"]
  node_models["Model catalog<br/>[catalog.py]"]
  node_provider["Model providers<br/>[transport.py]"]
end

subgraph group_data["Traffic and projects"]
  node_capture["Traffic capture<br/>[policy.py]"]
  node_trace_ingest["Trace ingestion"]
  node_project_store[("Project artifacts<br/>[store.py]")]
  node_mining["Trace mining<br/>[service.py]"]
  node_world_model["World model<br/>[application.py]"]
end

subgraph group_optimize["Evaluation and optimization"]
  node_evaluation["Evaluation service<br/>[service.py]"]
  node_router_fit["Router fitting<br/>[workflow.py]"]
  node_auto_optimize["Automatic optimization<br/>[service.py]"]
  node_router_runtime["Router runtime<br/>[runtime.py]"]
end

subgraph group_judging["Judging and training"]
  node_judge_cli["Judge commands<br/>[app.py]"]
  node_judge_service["Judge calibration<br/>[service.py]"]
  node_judge_review["Review persistence<br/>[review.py]"]
  node_sft["Model fine-tuning<br/>[training.py]"]
end

node_user(("Developer"))
node_provider_service{{"Model provider"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"configures gateway"| node_gateway_setup
node_user -->|"sends API request"| node_gateway_server
node_gateway_app -->|"starts data plane"| node_gateway_server
node_gateway_server -->|"routes requests"| node_gateway_routing
node_gateway_routing -->|"resolves models"| node_models
node_gateway_routing -->|"dispatches requests"| node_provider
node_provider -.->|"calls inference"| node_provider_service
node_user -->|"captures traffic"| node_capture
node_user -->|"uploads traces"| node_trace_ingest
node_trace_ingest -.->|"stores trace data"| node_project_store
node_user -->|"builds project"| node_mining
node_mining -.->|"persists project artifacts"| node_project_store
node_project_store -.->|"supplies project data"| node_world_model
node_user -->|"evaluates behavior"| node_evaluation
node_evaluation -.->|"provides evaluation"| node_router_fit
node_user -->|"optimizes router"| node_auto_optimize
node_auto_optimize -->|"fits router"| node_router_fit
node_router_fit -.->|"produces router"| node_router_runtime
node_user -->|"calibrates judge"| node_judge_cli
node_judge_cli -->|"runs calibration"| node_judge_service
node_judge_service -->|"records reviews"| node_judge_review
node_user -->|"fine-tunes model"| node_sft

click node_cli "https://github.com/experientiallabs/experiential/blob/main/exp/cli/app.py"
click node_gateway_setup "https://github.com/experientiallabs/experiential/blob/main/exp/cli/gateway/app.py"
click node_gateway_app "https://github.com/experientiallabs/experiential/blob/main/exp/runtime/router/application.py"
click node_gateway_server "https://github.com/experientiallabs/experiential/blob/main/exp/runtime/gateway/native/src/server.rs"
click node_gateway_routing "https://github.com/experientiallabs/experiential/blob/main/exp/runtime/gateway/routing.py"
click node_models "https://github.com/experientiallabs/experiential/blob/main/exp/common/models/catalog.py"
click node_provider "https://github.com/experientiallabs/experiential/blob/main/exp/runtime/models/providers/transport.py"
click node_capture "https://github.com/experientiallabs/experiential/blob/main/exp/runtime/capture/policy.py"
click node_trace_ingest "https://github.com/experientiallabs/experiential/tree/main/exp/common/traces/ingest"
click node_project_store "https://github.com/experientiallabs/experiential/blob/main/exp/common/project/store.py"
click node_mining "https://github.com/experientiallabs/experiential/blob/main/exp/simulation/mining/service.py"
click node_world_model "https://github.com/experientiallabs/experiential/blob/main/exp/simulation/world_model/application.py"
click node_evaluation "https://github.com/experientiallabs/experiential/blob/main/exp/optimize/evaluation/service.py"
click node_router_fit "https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/fit/workflow.py"
click node_auto_optimize "https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/automatic/service.py"
click node_router_runtime "https://github.com/experientiallabs/experiential/blob/main/exp/runtime/router/runtime.py"
click node_judge_cli "https://github.com/experientiallabs/experiential/blob/main/exp/cli/judge/app.py"
click node_judge_service "https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/judging/service.py"
click node_judge_review "https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/judging/review.py"
click node_sft "https://github.com/experientiallabs/experiential/blob/main/exp/optimize/model/sft/training.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_cli,node_gateway_setup,node_gateway_app,node_gateway_server,node_gateway_routing,node_models,node_provider toneBlue
class node_capture,node_trace_ingest,node_project_store,node_mining,node_world_model toneAmber
class node_evaluation,node_router_fit,node_auto_optimize,node_router_runtime toneMint
class node_judge_cli,node_judge_service,node_judge_review,node_sft toneRose
class node_user,node_provider_service toneIndigo
```

## Components

### Gateway and runtime

- [CLI](https://github.com/experientiallabs/experiential/blob/main/exp/cli/app.py): `exp/cli/app.py`
- [Gateway setup](https://github.com/experientiallabs/experiential/blob/main/exp/cli/gateway/app.py): `exp/cli/gateway/app.py`
- [Gateway application](https://github.com/experientiallabs/experiential/blob/main/exp/runtime/router/application.py): `exp/runtime/router/application.py`
- [Native API server](https://github.com/experientiallabs/experiential/blob/main/exp/runtime/gateway/native/src/server.rs): `exp/runtime/gateway/native/src/server.rs`
- [Request routing](https://github.com/experientiallabs/experiential/blob/main/exp/runtime/gateway/routing.py): `exp/runtime/gateway/routing.py`
- [Model catalog](https://github.com/experientiallabs/experiential/blob/main/exp/common/models/catalog.py): `exp/common/models/catalog.py`
- [Model providers](https://github.com/experientiallabs/experiential/blob/main/exp/runtime/models/providers/transport.py): `exp/runtime/models/providers/transport.py`

### Traffic and projects

- [Traffic capture](https://github.com/experientiallabs/experiential/blob/main/exp/runtime/capture/policy.py): `exp/runtime/capture/policy.py`
- [Trace ingestion](https://github.com/experientiallabs/experiential/tree/main/exp/common/traces/ingest): `exp/common/traces/ingest`
- [Project artifacts](https://github.com/experientiallabs/experiential/blob/main/exp/common/project/store.py): `exp/common/project/store.py`
- [Trace mining](https://github.com/experientiallabs/experiential/blob/main/exp/simulation/mining/service.py): `exp/simulation/mining/service.py`
- [World model](https://github.com/experientiallabs/experiential/blob/main/exp/simulation/world_model/application.py): `exp/simulation/world_model/application.py`

### Evaluation and optimization

- [Evaluation service](https://github.com/experientiallabs/experiential/blob/main/exp/optimize/evaluation/service.py): `exp/optimize/evaluation/service.py`
- [Router fitting](https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/fit/workflow.py): `exp/optimize/router/fit/workflow.py`
- [Automatic optimization](https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/automatic/service.py): `exp/optimize/router/automatic/service.py`
- [Router runtime](https://github.com/experientiallabs/experiential/blob/main/exp/runtime/router/runtime.py): `exp/runtime/router/runtime.py`

### Judging and training

- [Judge commands](https://github.com/experientiallabs/experiential/blob/main/exp/cli/judge/app.py): `exp/cli/judge/app.py`
- [Judge calibration](https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/judging/service.py): `exp/optimize/router/judging/service.py`
- [Review persistence](https://github.com/experientiallabs/experiential/blob/main/exp/optimize/router/judging/review.py): `exp/optimize/router/judging/review.py`
- [Model fine-tuning](https://github.com/experientiallabs/experiential/blob/main/exp/optimize/model/sft/training.py): `exp/optimize/model/sft/training.py`

### Other components

- **Developer**
- **Model provider**

## Connections

- Developer → CLI: runs commands (evidence: `README.md`)
- CLI → Gateway setup: configures gateway (evidence: `exp/cli/app.py`)
- Developer → Native API server: sends API request (evidence: `README.md`)
- Gateway application → Native API server: starts data plane (evidence: `exp/runtime/router/application.py`)
- Native API server → Request routing: routes requests (evidence: `exp/runtime/gateway/native/src/server.rs`)
- Request routing → Model catalog: resolves models (evidence: `exp/runtime/gateway/routing.py`)
- Request routing → Model providers: dispatches requests (evidence: `exp/runtime/gateway/routing.py`)
- Model providers → Model provider: calls inference
- Developer → Traffic capture: captures traffic (evidence: `README.md`)
- Developer → Trace ingestion: uploads traces (evidence: `README.md`)
- Trace ingestion → Project artifacts: stores trace data
- Developer → Trace mining: builds project (evidence: `README.md`)
- Trace mining → Project artifacts: persists project artifacts
- Project artifacts → World model: supplies project data
- Developer → Evaluation service: evaluates behavior (evidence: `README.md`)
- Evaluation service → Router fitting: provides evaluation
- Developer → Automatic optimization: optimizes router (evidence: `README.md`)
- Automatic optimization → Router fitting: fits router (evidence: `exp/optimize/router/automatic/service.py`)
- Router fitting → Router runtime: produces router
- Developer → Judge commands: calibrates judge (evidence: `README.md`)
- Judge commands → Judge calibration: runs calibration (evidence: `exp/cli/judge/app.py`)
- Judge calibration → Review persistence: records reviews (evidence: `exp/optimize/router/judging/service.py`)
- Developer → Model fine-tuning: fine-tunes model (evidence: `README.md`)
