experiential README

README проекта с github.com/experientiallabs/experiential. Одним файлом markdown: README.md.

Experiential

gateway latency

Experiential is an open source gateway and router for agent workflows:

  1. Use hosted, BYOK, and local models through one OpenAI-compatible API.
  2. Control which users and agents can use which models, for which use cases, and how much they can spend.
  3. Turn production traffic into a custom router or model optimized for quality, speed, and cost.

Experiential workspace usage dashboard showing model traffic, identities, and spend

🌐 Platform | 📚 Docs | Discord

Getting 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:

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"}],
    )

Coding Agent

exp code runs exp-code, Experiential's open-source coding and cowork agent built on Pi. It needs Node.js 22.19 or newer and uses your running local gateway, or the hosted gateway after exp login:

exp code                       # interactive terminal UI
exp code -p "Summarize sales.csv into report.docx"

Every argument goes to exp-code, so its print, JSON, and RPC modes work through exp code too.

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.

experiential (experientiallabs/experiential)

Ищем в базе…

Что это такое?Experiential — это шлюз и маршрутизатор с открытым исходным кодом для агентных рабочих процессов. Через один API, совместимый с OpenAI, вы можете использовать размещённые модели, модели в режиме BYOK (со своими ключами) и локальные модели. Также можно контролировать, кто и сколько тратит на те или иные модели, и превращать рабочий трафик в собственный оптимизированный маршрутизатор или вашу дообученную модель.
Это шлюз, который я запускаю сам, или только облачный сервис?И то, и другое. Вы можете запустить локальный шлюз, совместимый с OpenAI, сами через CLI exp, или воспользоваться управляемой облачной платформой на platform.experientiallabs.ai, которая предоставляет тот же API без какой-либо локальной настройки.
Как запустить шлюз?Выполните exp (или exp run), чтобы запустить локальный шлюз. Мастер настройки при первом запуске проведёт вас через выбор провайдера, модели и уровня усилий на рассуждение, установит бюджет команд по умолчанию в $50.00 и выведет одноразовый API-ключ, который вы затем используете для отправки запросов.
Нужны ли мне собственные ключи API провайдеров, чтобы пользоваться этим?В режиме BYOK вы подключаете свои ключи OpenAI, Anthropic, Gemini, Azure, Bedrock, Fireworks или OpenRouter для бесплатной передачи запросов. Также поддерживаются размещённые и локальные модели, если вы не хотите использовать собственные ключи.
Каких агентов для кода можно направить на шлюз?В документации по настройке описано, как перенаправить на эндпоинт шлюза, совместимый с OpenAI и Anthropic, такие агенты для кода, как Claude Code, Cursor, Codex, Aider и похожие, а также Conductor.
Отслеживает ли он мои промпты или данные?Анонимная агрегированная телеметрия PostHog включена по умолчанию, но прямо исключает промпты, трассировки, действия, наблюдения, пути, названия моделей, учётные данные и исходное содержимое клиентов. Настройка согласия на участие хранится локально.
Как он оптимизирует расходы на основе моего трафика?Он принимает трассировки OpenTelemetry из трафика ваших агентов, проводит вас через мастер сборки для провайдеров, моделей и бюджета, а затем может дообучить принадлежащую вам модель с открытым исходным кодом с помощью Tinker на основе этих трассировок.
Для чего здесь используется Tinker?После сбора трассировок с вашего маршрутизатора Experiential использует Tinker, чтобы дообучить модель с открытым исходным кодом, которой вы владеете и которую контролируете, а не зависеть от закрытой модели поставщика.
Могу ли я сначала опробовать процесс оптимизации без своего трафика?Да, есть публичный набор данных OTLP с терминальными задачами, который можно скачать, чтобы протестировать процесс оптимизации на основе трассировок до загрузки своих данных.
Поддерживает ли он формат API Anthropic или только OpenAI?Шлюз обслуживает и API, совместимый с OpenAI, и API, совместимый с Anthropic Messages, с одного и того же эндпоинта.
Какие есть похожие проекты?bifrost, router, casbin-gateway, OmniRoute, gateway, ThinkWatch-Lite, opencodex, OrcaRouter-Lite
Размер
113.3 MB
Звёзды
17.6K
Возраст
4 мес
Коммиты · 90 дней