From 1317b8024b3792fb2a3263965444e745ac35795b Mon Sep 17 00:00:00 2001 From: infosave2007 Date: Wed, 1 Jul 2026 10:35:29 +0300 Subject: [PATCH] docs: document the allaigate router + launch promo - docs/ROUTER.md + docs/ROUTER.ru.md: what the semantic router does, hosted vs self-hosted, config, API contract, pricing, and the LAUNCH1 $1 Starter promo - README (EN+RU): "The router (allaigate)" section with the promo callout Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 2 ++ README.md | 14 ++++++++ README.ru.md | 14 ++++++++ docs/ROUTER.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++ docs/ROUTER.ru.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 195 insertions(+) create mode 100644 docs/ROUTER.md create mode 100644 docs/ROUTER.ru.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d00b32..b36b7c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). - **Accuracy benchmark**: task-type routing on natural-language prompts (`bench/accuracy.py`, `bench/tasks.jsonl`) — allaigate semantic router 100% (37/37) vs a keyword heuristic 32% (competitors have no semantic task router). +- **Router docs** (`docs/ROUTER.md` + `.ru.md`): what the allaigate/cortiq-router does, how + to point the gateway at it, API contract, pricing, and the current `LAUNCH1` $1 promo. ## [0.2.1] - 2026-06-30 diff --git a/README.md b/README.md index 9e4fe71..9c85abe 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,20 @@ print(resp.choices[0].message.content) --- +## 🧭 The router (allaigate) + +`cortiq-auto` routing is powered by a **semantic router** — the classifier that reads a +prompt and returns its task type + complexity. Use the hosted +**[allaigate](https://api.allaigate.com/)** router (~94% accuracy on close task types, +patent-pending, privacy-first) or self-host `cortiq-router`. Pinned models need no router. + +> 🎉 **Launch promo:** grab a **$1 Starter key** with code **`LAUNCH1`** at +> **[api.allaigate.com](https://api.allaigate.com/)** (limited activations). + +Setup, pricing, API contract and how to verify accuracy: **[docs/ROUTER.md](docs/ROUTER.md)**. + +--- + ## Request flow 1. Client → `POST /v1/chat/completions` (or Anthropic/MCP) with `model: "cortiq-auto"`. diff --git a/README.ru.md b/README.ru.md index 23ce0d8..5ca874b 100644 --- a/README.ru.md +++ b/README.ru.md @@ -125,6 +125,20 @@ print(resp.choices[0].message.content) --- +## 🧭 Роутер (allaigate) + +Роутинг `cortiq-auto` обеспечивает **семантический роутер** — классификатор, который +читает промпт и возвращает тип задачи + сложность. Используйте хостовый +**[allaigate](https://api.allaigate.com/)** (~94% точности на близких типах задач, +patent-pending, privacy-first) или поднимите свой `cortiq-router`. Pinned-моделям роутер не нужен. + +> 🎉 **Акция:** возьмите **Starter-ключ за $1** по промокоду **`LAUNCH1`** на +> **[api.allaigate.com](https://api.allaigate.com/)** (число активаций ограничено). + +Настройка, тарифы, контракт API и как проверить точность: **[docs/ROUTER.ru.md](docs/ROUTER.ru.md)**. + +--- + ## Поток запроса 1. Клиент → `POST /v1/chat/completions` (или Anthropic/MCP) с `model: "cortiq-auto"`. diff --git a/docs/ROUTER.md b/docs/ROUTER.md new file mode 100644 index 0000000..2a2539b --- /dev/null +++ b/docs/ROUTER.md @@ -0,0 +1,83 @@ +*Read this in [Русский](ROUTER.ru.md).* + +# The router (allaigate) + +Cortiq Gateway is a thin, fast proxy — the **intelligence** that decides *which* model +a prompt should go to lives in a separate **router**. When you send `model: "cortiq-auto"`, +the gateway calls the router's `POST /v1/route`, gets back a **task type** and a +**complexity tier**, and picks a model from your pool accordingly. + +> Routing is optional. A pinned model (`model: "gpt-4o-mini"`) or `POST /route`-free +> usage needs **no router** — the gateway is still a useful universal proxy. The router +> is what turns it into a *smart* one. + +## Two ways to get a router + +1. **Hosted — [allaigate](https://api.allaigate.com/)** (fastest to start). A managed + semantic router: ~94% accuracy at separating close task types, patent-pending, + privacy-first. Get a key on the site (see the promo below). +2. **Self-hosted — `cortiq-router`.** Run your own classifier and point the gateway at it. + +## 🎉 Launch promo + +allaigate is currently running a launch offer: + +> **$1 Starter key** — use promo code **`LAUNCH1`** at **https://api.allaigate.com/** +> (limited activations). + +Get a key: enter your email + the promo code on the homepage; the key (`cortiq_…`) is +minted and shown to you. + +### Pricing (as of this writing — check the site for current terms) + +| Plan | Price | Included decisions | Rate limit | Overage | +|---|---|---|---|---| +| **Starter** | **$1/mo** (`LAUNCH1`) | unlimited | 60/min | — | +| Developer | $9/mo | 100k | 120/min | $0.10 / 1k | +| Pro | $49/mo | 1M | 600/min | $0.05 / 1k | +| Scale | $299/mo | 10M | 3000/min | $0.02 / 1k | + +## Point the gateway at the hosted router + +```toml +[router] +url = "https://138.226.222.209" # allaigate routing API +verify_tls = false # cert is bound to an IP +taxonomy_id = "data-assistant" +api_key_env = "CORTIQ_ROUTER_KEY" # your cortiq_… key +timeout_ms = 15000 # allow for oracle escalation on hard prompts +``` + +```bash +export CORTIQ_ROUTER_KEY=cortiq_your_key +cortiq-gateway --config config/gateway.toml +``` + +## API contract + +`POST {router}/v1/route`, `Authorization: Bearer cortiq_…`: + +```jsonc +// request +{ "input": { "text": "Write a Python function to reverse a list" }, "taxonomy_id": "data-assistant" } + +// response +{ + "decision": { + "task_label": "code", + "confidence": 0.99, + "complexity": { "tier": "low", "score": 0.27 } + } +} +``` + +The gateway maps `complexity.tier` (`low`/`medium`/`high`) to your `[routing]` table and +selects a model. On a hard/ambiguous prompt the router may escalate to an oracle LLM +(a few seconds) for a more accurate decision — size `timeout_ms` accordingly. See +[ROUTING.md](ROUTING.md). + +## Verify accuracy yourself + +`bench/accuracy.py` classifies a labeled prompt set through the live router — see +[BENCHMARKS.md](../BENCHMARKS.md). In our run the router scored **100% (37/37)** on +natural-language prompts vs a keyword heuristic's 32%. diff --git a/docs/ROUTER.ru.md b/docs/ROUTER.ru.md new file mode 100644 index 0000000..0b3263f --- /dev/null +++ b/docs/ROUTER.ru.md @@ -0,0 +1,82 @@ +*Read this in [English](ROUTER.md).* + +# Роутер (allaigate) + +Cortiq Gateway — тонкий и быстрый прокси; **интеллект**, решающий *какой* модели +отдать запрос, живёт в отдельном **роутере**. Когда вы шлёте `model: "cortiq-auto"`, +шлюз вызывает `POST /v1/route` роутера, получает **тип задачи** и **полосу сложности** +и выбирает модель из вашего пула. + +> Роутинг опционален. Pinned-модель (`model: "gpt-4o-mini"`) роутер **не требует** — +> шлюз всё равно полезен как универсальный прокси. Роутер делает его *умным*. + +## Два способа получить роутер + +1. **Хостовый — [allaigate](https://api.allaigate.com/)** (быстрее всего начать). + Управляемый семантический роутер: ~94% точности на разделении близких типов задач, + patent-pending, privacy-first. Ключ — на сайте (см. акцию ниже). +2. **Свой — `cortiq-router`.** Поднимите собственный классификатор и укажите его в шлюзе. + +## 🎉 Акция (launch) + +Сейчас у allaigate идёт стартовая акция: + +> **Starter-ключ за $1** — промокод **`LAUNCH1`** на **https://api.allaigate.com/** +> (число активаций ограничено). + +Как получить ключ: введите e-mail и промокод на главной — ключ (`cortiq_…`) сгенерируется +и покажется вам. + +### Тарифы (на момент написания — актуальные условия смотрите на сайте) + +| План | Цена | Включено решений | Rate limit | Сверх лимита | +|---|---|---|---|---| +| **Starter** | **$1/мес** (`LAUNCH1`) | безлимит | 60/мин | — | +| Developer | $9/мес | 100k | 120/мин | $0.10 / 1k | +| Pro | $49/мес | 1M | 600/мин | $0.05 / 1k | +| Scale | $299/мес | 10M | 3000/мин | $0.02 / 1k | + +## Подключение шлюза к хостовому роутеру + +```toml +[router] +url = "https://138.226.222.209" # routing API allaigate +verify_tls = false # серт привязан к IP +taxonomy_id = "data-assistant" +api_key_env = "CORTIQ_ROUTER_KEY" # ваш ключ cortiq_… +timeout_ms = 15000 # запас под oracle-эскалацию на сложных запросах +``` + +```bash +export CORTIQ_ROUTER_KEY=cortiq_your_key +cortiq-gateway --config config/gateway.toml +``` + +## Контракт API + +`POST {router}/v1/route`, `Authorization: Bearer cortiq_…`: + +```jsonc +// запрос +{ "input": { "text": "Write a Python function to reverse a list" }, "taxonomy_id": "data-assistant" } + +// ответ +{ + "decision": { + "task_label": "code", + "confidence": 0.99, + "complexity": { "tier": "low", "score": 0.27 } + } +} +``` + +Шлюз сопоставляет `complexity.tier` (`low`/`medium`/`high`) с таблицей `[routing]` и +выбирает модель. На сложном/неоднозначном запросе роутер может эскалировать к oracle-LLM +(несколько секунд) для более точного решения — подберите `timeout_ms` соответственно. +См. [ROUTING.ru.md](ROUTING.ru.md). + +## Проверьте точность сами + +`bench/accuracy.py` прогоняет размеченный набор промптов через живой роутер — см. +[BENCHMARKS.md](../BENCHMARKS.md). В нашем прогоне роутер дал **100% (37/37)** на +естественных промптах против 32% у keyword-эвристики.