Experiential
Experiential is an open source gateway and router for agent workflows:
- Use hosted, BYOK, and local models through one OpenAI-compatible API.
- Control which users and agents can use which models, for which use cases, and how much they can spend.
- Turn production traffic into a custom router or model optimized for quality, speed, and cost.
DiscordGetting Started
Start a local OpenAI-compatible gateway. On first run, the setup wizard uses the shared provider,
model, and reasoning-effort selectors, persists every selected provider connection, then shows
defaults for the public alias, identity, and $50.00 command budget before printing a one-time key:
pip install experiential
exp
Choose a public alias such as opus-5, capture the issued key, and send a request:
export EXP_GATEWAY_KEY=...
curl http://127.0.0.1:8000/v1/chat/completions \
-H "Authorization: Bearer $EXP_GATEWAY_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"opus-5","messages":[{"role":"user","content":"Help me"}]}'
Setup / get started with the hosted gateway
Prefer a managed gateway to running one locally? The hosted platform at
platform.experientiallabs.ai serves the same
OpenAI-compatible (and Anthropic Messages) API at https://api.experientiallabs.ai/v1.
See SETUP.md for copy-paste prompts you hand to your coding agent
(Claude Code, Cursor, Codex, and similar); the agent runs the setup for you. It
collects four prompts:
- Upload your LLM traces as telemetry: create an account instantly from your email, then pull or upload your existing LLM traces onto the platform as telemetry.
- Connect your inference provider keys (BYOK): create an account, then connect your own OpenAI, Anthropic, Gemini, Azure, Bedrock, Fireworks, or OpenRouter keys for free pass-through.
- Start calling models on the gateway: make your first
/v1call with the OpenAI and Anthropic SDKs using anxpl_key, and optionally repoint your existing coding agents. - Full onboarding: create an account instantly from your email, connect your keys, import your spend, then repoint every coding agent (Claude Code, Cursor, Codex, Aider, and similar) or Conductor at the gateway.
Using the API
Start the local gateway with exp (or exp run); the compiled native data plane
serves every route on loopback. From Python, load a fitted project router as an
official OpenAI client backed by its own private gateway:
import exp
with exp.load_router("my-project") as client:
response = client.chat.completions.create(
model="my-project",
messages=[{"role": "user", "content": "hello"}],
)
Capture Traffic
Capture is designed to collect supported traces from the Codex and Claude Code desktop apps using your existing ChatGPT or Claude subscription, while requests go directly to OpenAI or Anthropic. It requires macOS, Python 3.13 or newer, and approval for its extension and certificate:
exp capture
Capture is experimental; macOS network reliability is still under investigation.
Use Experiential's gateway as middleware to control costs, enforce guardrails, and optimize quality, costs, and speed. Leave the terminal open while you work. Press Ctrl+C to stop capture. View your capture telemetry.
Optimize from Traffic
First, collect OpenTelemetry traces from your current agent. If you just want to try it out, grab the public terminal-tasks OTLP dataset:
curl -L -o traces.otel.jsonl \
https://huggingface.co/datasets/experiential-labs/wmo-terminal-tasks-traces/resolve/540883e451dc13d34fb50fdd36b143cb0f1fb0db/traces.otel.jsonl
Then build a project. The build command walks you through providers, models, and budget, and asks for your trace file:
# Build simulation from your agent traces and optimize a router against it
exp build support-agent
After collecting traces from your router, fine-tune an open source model you own using Tinker.
exp optimize model support-agent
Telemetry
Anonymous aggregate PostHog product telemetry is enabled by default. It never includes prompts, traces, actions, observations, paths, model names, credentials, or raw customer content.
exp config telemetry status
exp config telemetry disable
exp config telemetry enable
The preference is stored locally in .exp/settings.toml.
Development
uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest -q
Repository and documentation conventions live in AGENTS.md.
1 maintainer
Release files for experiential 0.7.120
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| experiential-0.7.120.tar.gz | 5.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| experiential-0.7.120-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 10.0 MB
Release files / experiential-0.7.120.tar.gz
| Download URL | experiential-0.7.120.tar.gz |
|---|---|
| Size | 5.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a5b9615aa59d304791380f77a4a661429985b6c64f62bd11c937546c67aa44b8
|
|
BLAKE2b-256 checksum How to use checksums |
9199cbaf87e528284af9f89f4e87cf17c5ebbfe6c9a86b73f5167d65dca12b3a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / experiential-0.7.120-py3-none-any.whl
| Download URL | experiential-0.7.120-py3-none-any.whl |
|---|---|
| Size | 4.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fd765cdea8ed17bb899354ab82c92d183cf15e542463de20c3696cb1dfc0f71d
|
|
BLAKE2b-256 checksum How to use checksums |
60eafe9c76161366bc225995e43a96734448757560a74b3178bf35a4a0442f3b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
