`. - Footer: plain headings, four groups (Product, Developers, Resources, Company) with the REST and Python references labelled apart, licence / SDK version / edition as a definition list, and a legal bar (Terms, Privacy, Support, Security). - New pages `/support` (documentation entry points, issues and discussions, account and billing, security reports, enterprise, service status), `/privacy` (what the platform stores per table, request content handling, browser storage, processors, retention, access and deletion) and `/terms` (accounts and keys, plans and payment, content, acceptable use, marketplace, availability, suspension, open source, liability). Linked from the footer, the signup form, the dashboard footer, the 404 and error pages, the command palette and the sitemap; the CI container smoke test requests them. - Command palette lists every public page (marketplace, estimate, pricing, REST API, support). Marketplace and declarative stacks - `opensmartroute.stack`: declarative *stacks* - one YAML/JSON document (`osr: "1"`, `kind: stack`) holding targets (plain or OCM), rules, settings, objective and `imports` of other stacks, catalogues or marketplace templates (`registry://slug@version`). `load_stack`, `validate_stack`, `plan_stack` (diff against a deployed stack), `dump_stack`, `starter_stack` and `Stack.router()` mirror the infrastructure-as-code check / diff / apply workflow; the CLI gains `osr stack init | validate | plan | apply` (`--registry`, `--against`, `--out`, `--route`). `examples/stack.yaml` is a complete support-desk example. - Hosted marketplace (`platform/api/osr_platform/registry.py`, tag `marketplace`): listings of kind template, agent, skill, persona, tool, llm and prompt with slug, semver versions and changelog, publisher, licence, tags, Markdown readme, price, installs and star ratings. Public browse and detail (`GET /api/v1/registry`, `/registry/kinds`, `/registry/{slug}`, `/manifest?version=`, `/reviews`), publisher lifecycle draft -> review -> published -> archived (`POST /registry`, `PATCH`, `/submit`, `/versions`, `/archive`, `/unarchive`, `GET /me/listings`), installs and purchases (`POST /registry/{slug}/install`, `GET /me/installs`, one-time Stripe checkout confirmed by webhook), reviews (`PUT`/`DELETE /registry/{slug}/reviews`) and moderation under `/api/v1/admin/registry` (`approve`, `reject`, `flags`, `unpublish`). Manifests are validated against the OCM / stack schemas; template manifests may be sent as `{"yaml": "..."}`. Settings `OSR_PLATFORM_REGISTRY_AUTO_PUBLISH` (free listings go live on submit) and `OSR_PLATFORM_REGISTRY_SEED` (seed the repository's skills, the starter and example templates, a persona and prompts, all verified). - Web: `/marketplace` (kind rail, search, filters, featured, pagination), `/marketplace/{slug}` (about, use-it snippets, manifest, reviews with histogram, versions, install / buy / rate), `/marketplace/publish` (four-step wizard, no code needed for prompts and personas) and `Dashboard -> Marketplace` (my listings with status and reviewer notes, edit page with new-version form, installed items). Marketplace links in the main navigation, footer, dashboard and sitemap. User docs: `docs/MARKETPLACE.md` (site page `/docs/MARKETPLACE`). - OCM cost block accepts `context_tokens`; `capability_from_target` emits it. - `PlatformAPI.optional_principal` dependency (anonymous or authenticated) and `Billing.listing_checkout_url` / `Billing.on_purchase` for one-time purchases. Documentation site - The hosted web app (`platform/web`) now renders the documentation itself as a static Next.js site at `/docs`: `scripts/sync-content.mjs` snapshots the repository Markdown (`README`, `CHANGELOG`, `CONTRIBUTING`, `SECURITY`, `docs/**`, `deploy/README.md`, `spec/ocm/README.md`, `.claude/skills/*/SKILL.md`) into `content/`; `src/lib/docs/catalogue.ts` is the single source of truth for sections, slugs and summaries; `src/lib/docs/render.ts` renders with remark/rehype (GFM, GitHub-compatible heading ids, Shiki highlighting, Mermaid, relative-link rewriting). Pages get a collapsible sidebar, scroll-spy table of contents, breadcrumbs, reading time, code copy buttons, previous/next links and an "Edit on GitHub" link. New pages: every Agent-Skills package (`/docs/skills/`, with its frontmatter), `/docs/deploy`, `/docs/ocm`, `/docs/contributing`, `/docs/security-policy`. `/docs/search.json` feeds documentation pages and headings into the Ctrl/Cmd+K palette; the sitemap lists every page. The docs no longer depend on the platform API being up. - The site is organised for end users of the hosted platform, the Python SDK and the pip package: sections Start, Hosted platform, Python SDK, Self-hosting, Concepts, Security, Agent skills and Releases, with a section tab bar and audience paths on the index. Internal material (`docs/PLATFORM_PLAN.md`, `docs/GO_TO_MARKET.md`, `docs/BRAND.md`, `docs/sales/`, `platform/README.md`) is no longer published on the site and stays in the repository. - `docs/PLATFORM.md`: platform guide for end users (authentication, `/api/v1/route` fields and constraints, the `/api/v1/estimate` quote, execution, the OpenAI-compatible endpoint, feedback, plans and quotas, organizations and roles, organization SSO, tenants, the marketplace, the MCP server, dashboard pages, privacy, error handling). `docs/MARKETPLACE.md` is published under Hosted platform. `docs/GUIDE.md` lists every `osr` subcommand grouped by task. - REST API reference generated from the platform's OpenAPI document: `/docs/api` (authentication schemes, base URL, conventions, endpoint groups) and one page per tag (`/docs/api/routing`, `/docs/api/openai`, `/docs/api/public`, `/docs/api/account`, `/docs/api/workspaces`, `/docs/api/auth`, `/docs/api/billing`, `/docs/api/mcp`, `/docs/api/marketplace`) with parameters, request and response schemas, curl and JSON examples; operations are searchable from the palette. Operator-only `/api/v1/admin/*` paths are left out whatever tag they carry. - Version menu in the docs top bar built from `CHANGELOG.md` (current release, unreleased changes, links to each release section and PyPI). - `.claude/skills/osr-platform`: Agent-Skills package for the hosted platform (API, web app, the documentation site and `azd` deployment); root `AGENTS.md` and `.github/copilot-instructions.md` point coding agents at the gates, the easy-to-break rules and the skill for each task. Platform API - The OpenAPI document declares `bearer` and `apiKey` security schemes (replacing the per-operation `authorization` / `x-api-key` header parameters), tag descriptions for every route group and a richer info block. `platform/api/openapi.json` is a committed snapshot regenerated with `python platform/api/scripts/export_openapi.py`; `--check` (run in CI and by `test_openapi_snapshot_is_current`) fails on drift. Routing SLM and self-improvement - `learning.RouterSLM`: a self-contained small routing model (hashed dual encoder, temperature calibration, target snapshots) that trains on `EvalRow`s, predicts a calibrated distribution and a quality/cost/latency utility per candidate, learns online from outcomes, and saves to a compact JSON file (`save` / `from_file`, `SLM_FORMAT`). `learning.distill_router()` compresses the whole ensemble (rules, capability fit, learners, judge) into one SLM from its traces or propensities. `learning.SLMStrategy` puts it into the ensemble (weight `OSR_WEIGHTS_SLM`) with online updates; `Router` accepts it like any other strategy and `osr --slm model.json route` loads one from the CLI. - `adapters.ModelCatalogue` / `ModelCard`: live model catalogue from OpenRouter (prices, context, modalities, tool support) and Hugging Face model cards (downloads, likes, `model-index` benchmarks -> `quality_from_benchmarks`, `quality_from_popularity`), merged per model id and persisted; `targets()` filters by quality/price into `RouteTarget`s (`card_to_target` replaces injection-risky third-party descriptions), `cost_benchmark()`, `frontier()` (Pareto), `to_markdown()`; fail-soft `refresh()`. - `adapters.WebKnowledge`: web-search discovery with keyless providers (`huggingface_search`, `duckduckgo_search`) and `brave_search` when `BRAVE_API_KEY` is set; `fetch_bytes` / `fetch_json` / `fetch_page_text` / `html_to_text` (https-only, byte-capped, risk-scored pages); a cached hit list that `discover_models()` feeds into the catalogue. - `eval.DatasetCollector` / `DatasetSource` / `KNOWN_SOURCES`: collect routing datasets from the Hugging Face datasets-server (`fetch_hf_rows`, `iter_hf_rows`, `collect_dataset`) into a JSONL cache, plus `rows_from_feedback()` (outcomes -> labelled rows) and `synthetic_rows()` (ontology seed prompts scored by capability fit); `corpus()` dedupes and caps, `split()` is a deterministic holdout. `DEFAULT_SOURCES` are the publicly served pairwise battle sets `routellm-battles` (RouteLLM GPT-4-judged battles) and `arena-55k` (LMArena human preference); the RouterBench and RouterEval presets stay in `KNOWN_SOURCES` flagged `gated` (the Hub does not serve their rows without authentication). `from_pairwise_row()` turns a battle into an `EvalRow` (ties make both sides acceptable); `model_quality()` fits a Bradley-Terry model over the battles and returns each model's win probability against the field, which the catalogue applies as an `arena` quality prior. `ARENA_TIERS` / `tier_of()` / `tier_model_map()` fold the retired arena model names onto the operator's tiers (`osr collect --tier frontier=llm-frontier --tier mid=llm-mid --tier small=llm-small`, also on `osr improve`); `DatasetCollector.derive()` remaps an existing cache offline so tiered corpora never need a second download. `collect()` keeps partial pages when the Hub rate-limits mid-way and never replaces a fuller cache with a shorter one; `fetch_bytes` retries 429/5xx with exponential backoff honouring `Retry-After` (`OSR_SLM_FETCH_RETRIES`, `OSR_SLM_FETCH_BACKOFF_S`, `OSR_SLM_FETCH_BACKOFF_MAX_S`) and pages pause `OSR_SLM_PAGE_PAUSE_S`. - `adapters.fetch_leaderboard_quality()`: Open LLM Leaderboard results (IFEval, BBH, MATH, GPQA, MuSR, MMLU-Pro) per model via the datasets-server; `ModelCatalogue.apply_quality()` maps them (and the arena win rates) onto cards by exact id or `model_key()` (case/variant-insensitive tail), ranking sources popularity < catalogue < arena < leaderboard so a measured prior is never downgraded; `refresh(leaderboard=True)`, `targets(measured=True)` and `osr catalogue --leaderboard --quality-from DATA_DIR --measured`; `osr slm train --catalogue catalogue.json --source NAME` trains on measured, priced catalogue models and on selected caches only. - `adapters.attach_chat_handlers()`: give every LLM target a `chat_handler` on one OpenAI-compatible client (`metadata.model` names the upstream model, or a default). The CLI does this at startup when `OSR_LLM_BASE_URL` is set (`OSR_LLM_API_KEY`, `OSR_LLM_API_KEY_ENV`, `OSR_LLM_MODEL`), so the container's `/v1/chat/completions` executes against OpenAI, Azure OpenAI, vLLM, Ollama, OpenRouter or LiteLLM instead of answering 502. `huggingface_search()` limits model hits to `text-generation` and falls back to per-keyword queries (the Hub matches repo names, not natural language); `fetch_json()` returns `None` for an empty 200 body (DuckDuckGo does that under load). - Deployment: `OSR_SLM` (Docker entrypoint, Helm `config.slm` -> `/config/slm.json`) loads a routing SLM into the served ensemble; `OSR_LLM_BASE_URL` / `OSR_LLM_MODEL` are declared in the image. - `learning.SelfImprover` / `ImprovementReport`: the closed loop - refresh catalogue, discover models and datasets on the web, gather evidence (feedback, collected datasets, synthetic), train a challenger on the train split, calibrate it on the holdout, and promote it over the champion only when holdout accuracy improves by `OSR_SLM_MIN_GAIN`; JSONL history, `run(interval_s)` loop. - CLI: `osr catalogue`, `osr collect`, `osr slm train|eval|predict|info`, `osr improve` and the global `--slm` option; `settings.SLMSettings` (`OSR_SLM_*`) and `WeightSettings.slm`. - Transformer encoders for the SLM. `learning.AttentionEncoder` is a pure-Python transformer block (hashed token embeddings, sinusoidal positions, multi-head self-attention, residual, attention pooling, hand-derived gradients) that `ContrastiveRouter(attention=...)` adds to the hashed query encoder so tokens can condition on each other; opt in with `OSR_SLM_ENCODER=attention` (`OSR_SLM_ATTENTION_HEADS`, `_HEAD_DIM`, `_MAX_TOKENS`, `_VOCAB`); the block is persisted in the model file (`core.encoder`, `core.attention`) and restored by `from_file`. `learning.EmbeddingFeaturizer` / `load_embedder()` append a frozen pretrained sentence-transformer embedding (extra `embeddings`, or any `Callable[[list[str]], list[list[float]]]`) as dense features, so `W` learns a linear head on top of it; `RouterSLM(embedder=...)`, `OSR_SLM_EMBEDDER=` / `OSR_SLM_EMBEDDER_SCALE`, the file records the embedder name and `from_file(embedder=...)` takes a custom one back. - Self-operation: `learning.Autopilot` runs `SelfImprover` cycles inside a live process on a schedule and on drift (`learning.DriftMonitor`, Page-Hinkley over the success indicator and quality of every outcome the router learns from), rate-limited by a minimum gap, hot-swapping an accepted challenger into the served `SLMStrategy` and rewriting the model file; failures are recorded, never fatal. `Router.observers` is the outcome hook it (and any drift monitor or metric) plugs into. `osr serve --autopilot [--autopilot-interval S --cache-dir DIR --catalogue FILE --source NAME --search QUERY --tier TIER=TARGET --offline --min-rows N]`, `create_app(router, autopilot=...)` exposes `autopilot` in `GET /stats` and `POST /autopilot/cycle`; settings `OSR_SLM_AUTOPILOT_INTERVAL_S`, `_MIN_GAP_S`, `_DRIFT_THRESHOLD`, `_DRIFT_MIN_N`, `_REMEMBER`; container / Helm: `OSR_AUTOPILOT=1`, `OSR_AUTOPILOT_ARGS`, `OSR_CACHE_DIR`, `OSR_CATALOGUE`. `status()["busy"]` says a (possibly multi-minute) cycle is in flight. `DatasetCollector.corpus()` / `cached()` skip the improver's own `improve-history.jsonl` and any non-row line in the cache dir - the second cycle used to fail with `EvalRow.__init__() missing 'text'` when the log shared the dir. - Routing datasets: `osr collect` knows ten public sources verified against the datasets-server - the 2024-25 LMArena releases (`arena-100k`, `arena-140k`, `ppe-human`, `webdev-arena`), `mt-bench-human`, `reward-bench`, `ultrafeedback` (per-model judge scores) and `routellm-gpt4` (RouteLLM's own "is the cheap model good enough" labels), next to `routellm-battles` and `arena-55k`; gated ones stay listed but off by default. Parsers understand the newer layouts (typed conversation turns, `winner` labels, per-model score lists) and carry the code / language / math / hard-prompt tags into `context`; `tier_of()` has name rules and a parameter-count fallback for the 2024-26 model generations (`gpt-4o-mini` -> mid, `gemini-2.5-pro` -> frontier, `llama-3.1-8b` -> small ...) and `DatasetSource.tiers` folds every side onto your catalogue at parse time (`--tier` no longer needs an exhaustive model table). Collection is resumable: a `.meta.json` records the raw offset, a run cut short by a 429 keeps its rows and the next `osr collect` continues from there (`DatasetCollector.progress()`); retries back off up to five times / 60 s. `corpus()` fills `OSR_SLM_MAX_ROWS` round-robin across sources so one large dataset cannot crowd the others out. - SLM training is faster and generalises better. With numpy installed (extra `fast`, now in the serve image) `ContrastiveRouter.fit()` runs the same SGD on dense arrays - about 10x faster (18 000 rows in under a minute) - and inference projects through a dense mirror of `W`; `OSR_SLM_BACKEND=auto|numpy|python` picks the arithmetic, both paths seed identically and produce the same model file (tested to 1e-9), so a pure-Python deployment reads a numpy-trained model unchanged. The hashed featurizer caches token hashes. The model gains a learned per-target logit bias (`B`, the base rate a unit-norm dot product cannot express; older files load with none), inverse-time learning-rate decay (`OSR_SLM_LR_DECAY`, default 2) and regularised defaults (`epochs` 4, `l2` 1e-3): on the 18 000-row mixed corpus the previous defaults overfit below the constant "always the mid tier" baseline (0.62 vs 0.64 on a random holdout); the new ones sit at 0.64-0.66 with holdout loss 0.98-1.00 vs 1.11 and are stable across seeds. - The SLM no longer harms mixed catalogues. Scored rows train a softmax over the *scored population* (the targets any row of the corpus scores, plus `OSR_SLM_NULL_TARGETS` learned "none of these" logits) instead of the whole catalogue, so a corpus of LLM battles leaves the embeddings of tools, skills and agents it never compared untouched (they used to be driven to p=0.0005 and any SLM took `examples/eval_dataset.jsonl` from 0.83 to 0.43; it is 0.80 now). `SLMStrategy` / `ContrastiveStrategy` abstain on targets the model has never compared (`ContrastiveRouter.B` records them; `RouterSLM.predict_proba()` with no explicit candidates ranks only those), score the rest centred (best 1.0, mean 0.5, so a flat softmax is "no preference" rather than a boost) and scale confidence by the share of the request's candidates they know. Chosen on three leave-one-source-out suites (PPE 0.561, MT-Bench 0.508, WebDev Arena 0.506 - see `docs/ROADMAP.md` v0.4). - `eval.load_dataset()` raises `ConfigurationError` naming the file and line for a line that is not JSON, not an object or has no text (it used to surface as a `TypeError` traceback), and `osr catalogue | collect | slm | improve` print every SDK error as one `error:` line with its path / line / preset / backend detail and exit 1. `ContrastiveRouter(backend=...)` with an unknown backend is a `ConfigurationError` too. Agentic core (PLATFORM_PLAN Phase 0) - `signals.EventSignal`, `WorkflowSignal`, `parse_event()`, `EventInfo` and the `EVENT_*` lexicons: textless requests (`context["event"]`, `context["workflow"]`) get domain / action signals so events route to workflows and agents; rules match `event:` globs and `workflow: true`. - `strategies.SessionAffinityStrategy` / `SessionState`: keep multi-turn conversations on the target that owns the session unless quality drops; `Router.route(..., exclude=[...])` and fallback candidates; `PLAN_ROLES` is kind-aware (agent / workflow plans need no persona); per-call pricing on targets (`cost.usd_per_call`, `RouteTarget.cost_per_call`, `estimated_cost()`); `observe` hook. - Proxy: `osr/auto:` presets (`cheap`, `fast`, `quality`, `private`, `agentic`, `llm`), `osr` request block (exclude, objective, plan, fallbacks), `X-OSR-App` attribution and `X-OSR-Target` / `X-OSR-Request-Id` response headers; metadata carries alternatives and cost. - Executors: `adapters.http_handler()`, `mcp_tool_handler()` and queue-backed targets (`Queue` protocol, `InMemoryQueue`, `queue_handler()`, `PendingResult`) so agents, tools and human queues execute through the same plan runner. - Open Capability Manifest: `spec/ocm/` (JSON Schema + README), `opensmartroute.ocm` (`validate_capability`, `target_from_capability`, `capability_from_target`, `load_capabilities`, `bind_endpoint`), `load_targets()` accepts manifests and mixed catalogues, `osr validate` and `osr export-ocm`. - Routing Audit and savings: `eval.routing_audit()` / `AuditReport` / `load_audit_log()` replay logged traffic against a catalogue (savings vs baseline, policy violations, route mix); `osr audit logs.jsonl --baseline ... --markdown|--json [--min-savings]`; `enterprise.SavingsLedger` telemetry sink (`RouterBuilder.with_savings()`, `EnterpriseRouter.savings`) with per-request baseline-vs-routed entries and `SavingsReport.to_markdown()`. - CLI: `osr route --constraint KEY=VALUE` (hard constraints) and `--kinds a,b`; `--event`, `--session`, `--exclude`. - Platform: `GET /api/v1/savings`, `GET /api/v1/signals`, `GET /api/v1/admin/pql` (product-qualified leads); web `/roi` calculator, `/compare/{openrouter,litellm,portkey,diy}` pages and the dashboard savings view. - Docs: sales enablement kit under `docs/sales/` (discovery guide, demo script, Routing Audit, pilot charter, ROI calculator, security pack, battlecards, pricing and proposal, case study and QBR). Research track (every previously `Research` roadmap row now has code, tests and a module reference) - `learning.ContrastiveRouter` and `ContrastiveStrategy`: RouterDC-style contrastive training on (query, target) pairs. Softmax cross-entropy over `q . e_t / tau` against a row's *acceptable set* (`acceptable_set(row, slack)`, every target within `slack` of the best score), so several right answers are not penalised; `fit(objective="distilled")` trains against Zooter-style reward-distilled `soft_labels(scores, temperature)` instead of one-hot labels; hashed encoders, pure-Python SGD, online updates from outcomes, `state()/load()`. - `learning.PolicyGradientStrategy`, `decision_reward()`, `decision_regret()` and `RegretReport`: end-to-end REINFORCE routing (Router-R1 / RLCascadeRouter) on hashed request features with an EWMA baseline and entropy bonus, trained on the *decision* utility rather than a quality prediction; `decision_regret(rows, targets, choose, predict)` reports decision regret next to prediction MAE so the two losses can be compared on the same dataset. - `eval.headroom`: `routing_headroom()` splits oracle minus best-single into the label-noise floor and measurable headroom; `target_diversity()` (pairwise disagreement, winner entropy / share); `min_catalogue(rows, targets, fraction)` (smallest subset keeping a fraction of the oracle); `scaling_curve()` (oracle / best-single / headroom against catalogue size); `learnability_by_difficulty()` (per-difficulty-bucket headroom and noise floor, the "least learnable where most valuable" check for agentic pools). - `strategies.MemoryRouter`, `MemoryTier`, `MemoryItem`, `ImportanceGate`, `RecallResult`: BudgetMem-style memory-tier routing. Tiers carry capacity, write / read cost per token and latency; a hashed logistic gate decides what is worth writing and learns from `feedback(used_ids, recalled)`; value decays per `tick()`, lowest-value residents are demoted when a tier is full; `recall(query, budget_tokens)` fills a token budget by relevance x value. - `strategies.ModalityStrategy`, `ModalityEscalation`, `EscalationResult`, `request_modalities()`: penalise text-only targets when a request carries images / screens / audio / video / files that a text surrogate (OCR, caption, transcript) only describes; text-first escalation keeps a Beta posterior on "the surrogate sufficed" per modality set and calls the multimodal target first when that probability is low. - `strategies.SemanticCache`, `SemanticCacheStrategy`, `CacheEntry`, `CacheHit`: a semantic cache as a `DESTINATION` target. `SemanticCache.target()` serves near-duplicate answers (cosine over the router's embedder, TTL, LRU bound, source-based invalidation); the strategy scores only cache targets from the hit similarity and learns per-similarity-band hit quality from outcomes. - `strategies.AnnotatorPool`, `AnnotatorSkill`, `QuorumPlan`, `quorum_accuracy()`, `HumanRoutingStrategy`: QUORUM-style routing among `HUMAN` targets. Per-domain annotator accuracy is estimated by Dawid-Skene EM over labels (with gold labels and direct quality reports as evidence, prior seeded from `quality_prior`); `select_quorum(domain, target_accuracy, budget)` picks the cheapest majority-vote quorum that reaches the target accuracy. - `strategies.SpeculativeCascade`, `SpeculativeResult`, `expected_mode_costs()`: speculative draft / strong cascades. A Beta acceptance posterior per complexity bucket decides between `draft_only`, `speculate` (both in parallel, strong cancelled when the draft is accepted) and `strong_only` by expected cost + latency under the request's `Objective`. - `learning.HistoryTargetStrategy`, `HistoryTargetModel` and `history_vector()`: multi-turn routing on history-target joint embeddings (MTRouter). A logistic model over `h * e_t` (recency-weighted hashed history and current text, catalogue target embedding) with shared weights and a per-target bias learns that the same follow-up routes differently depending on the conversation so far; inductive for unseen targets; `context["last_target"]` earns an incumbent bonus that becomes a penalty when `context["last_failed"]` is set; `state()/load()/merge()`, persisted by `AutoLearner`. - `errors.deprecated(name, since=, removal=, replacement=)` and `errors.OpenSmartRouteDeprecationWarning` implement the public API deprecation policy documented in CONTRIBUTING.md. - `signals.VerbalisedDifficultySignal` and `parse_difficulty()`: a small model's verbalised difficulty (`0.7`, `7/10`, "hard") from `context["difficulty"]` or a callable blends into `complexity` and raises `reasoning_need`. `signals.DraftResponseSignal` and `draft_features()` derive hedging, self-correction, query overlap and length ratio from a cheap draft answer. - `signals.semantic_entropy()`, `semantic_clusters()`, `response_uncertainty()` (meaning clusters over sampled answers, hedging, optional P(True) judge), `signals.UncertaintyGate` (a `Cascade` quality gate / `MixtureOfAgents` trigger built on them) and `signals.EventTrigger` / `TriggerRule` (threshold rules that fire named actions). - `math.DirichletProbe` (evidential Dirichlet head with digamma loss and KL regulariser, pure Python SGD, `predict()` returns probabilities and epistemic uncertainty `K/S`) and `strategies.HiddenStateStrategy(state_fn, targets, dim)` that routes on host hidden states and lowers its confidence on unfamiliar states. - `math.EnergyModel` (per-target ridge fit of `Wh = e0 + e_in * prompt + e_out * output`, gCO2 via a grid factor) and `math.HardwareProfile` / `hardware_profile()` priors for A100, H100, L4, RTX 4090, 16-core CPU and an edge NPU. - `strategies.expand_elastic(parent, [BudgetVariant(...)])` creates `@` siblings of an elastic model; `strategies.TokenBudgetStrategy` scores budget fit (truncation risk vs unused capacity). - `strategies.EdgeCloudStrategy`: Thompson posterior of edge success per complexity bucket, decode time against the latency SLO, upload penalty for the cloud tier and a hard exclusion when the request's data boundary forbids a public target. - `strategies.AuctionStrategy`, `AuctionResult`, `default_bid()`: error-aware reverse auction where each bidder's claimed success is corrected by its observed bias; second-price payment. - `strategies.ProtocolPolicy`, `ProtocolRule`, `DEFAULT_RULES`, `failure_risk()`: risk / budget / task-type rules choose `single`, `cascade`, `aggregate`, `debate` or `handoff`; a per-protocol ledger reports which protocol paid. - `strategies.SelfEscalation` and `wrap_stream()`: Bayesian competence posterior updated per streamed chunk with an optimal-stopping rule; `SelfEscalation.for_target()` seeds the prior from `quality_prior`. - `strategies.MixtureOfAgents`, `majority_vote()`, `AggregateResult`: call the top-k alternatives when the decision is unsure and the budget allows, aggregate by semantic majority (or a supplied synthesiser) and emit one `Outcome` per participant. - `learning.UserAdaptiveStrategy` (per-user Beta posteriors shrunk toward neighbour users and the global posterior; `observe_user()` warm start), `learning.SkillAffinity` (profile-bucket skill relevance for `select_skill_set(relevance=)`), `profile_vector()`, `profile_bucket()`. - `learning.MixtureCureModel` (Weibull mixture-cure on cumulative trajectory risk with censoring, grid MLE) and `learning.HandoffPolicy` (permanent hand-off on eventual-failure probability or horizon hazard; releases the task's `TaskPins` pin). - `opensmartroute.discovery`: `schema_match()` / `extract_entities()` / `SchemaAwareStrategy` (coverage of required `input_schema` properties by typed entities in the request), `CachePreservingSelector` (per-session prefix-stable tool ordering with lazy eviction and `prefix_hit_ratio()`), `SkillGraph` (`requires` / `conflicts` / `composes` edges plus learned co-usage; `compose()` returns a dependency order). - `adapters.recommend_servers()`, `ServerCard`, `ServerRecommendation`: rank MCP servers for a task with BM25 + hashing-cosine fusion over server cards and hard constraint filters. - `adapters.load_semantic_router_config()` / `SemanticRouterImport`: import a vLLM semantic-router `config.yaml` (categories, model scores, reasoning flags, pricing, system prompts) as targets and rules. - `load_skills` exposes `osr-requires`, `osr-conflicts` and `osr-composes` frontmatter as `metadata["requires" | "conflicts" | "composes"]` for `SkillGraph`. - `tests/test_roadmap_research.py` covers every item above; `tests/public_api.json` lists the new names. Decorator SDK - `opensmartroute.sdk`: `ComponentRegistry` plus the decorators `@strategy`, `@signal`, `@policy_rule`, `@middleware`, `@telemetry` and `@target` / `@tool` / `@skill` / `@agent`. Plain functions are adapted through `FunctionStrategy`, `FunctionSignal` and `FunctionMiddleware`; classes are registered as factories. `registry.router()` / `registry.builder()` assemble a `Router` / `RouterBuilder` from everything declared; `include("pkg.mod[:hook]")` and `discover()` (entry-point group `opensmartroute.plugins`) load plugins. The process-wide registry is exported as `opensmartroute.components` and the top-level decorators bind to it. - `RouterBuilder.with_components(registry, targets=, strategies=, signals=, policy=, middleware=, telemetry=)` wires a registry into an existing builder. - `strategies.default_strategies(seed=, settings=, state_dir=)` builds the default ensemble. Settings - `opensmartroute.settings`: immutable `Settings` grouped into `RoutingSettings`, `PolicySettings`, `RulesSettings`, `CapabilitySettings`, `BanditSettings` and `WeightSettings`; `configure()`, `get_settings()`, `Settings.from_env()` (`OSR__` overlay with typed parsing and `ConfigurationError` on bad values) and `Settings.env_keys()`. `Router`, `RouterBuilder`, `Policy`, `RulesStrategy`, `CapabilityStrategy` and `BanditStrategy` accept `settings=`; every previously hardcoded threshold, weight and scale now resolves from it. - `Router.weight_of(strategy)` reports the effective ensemble weight. - `osr settings [--json]` prints the effective tunables, their `OSR_*` keys and which are overridden. Agent skills - `.claude/skills/`: eight Agent-Skills packages (`osr-routing-catalogue`, `osr-decorator-sdk`, `osr-enterprise-builder`, `osr-evaluation`, `osr-security-hardening`, `osr-integrations`, `osr-deploy-serve`, `osr-contributing`) that teach coding agents such as Claude Code how to use and extend the library. They are valid `TargetKind.SKILL` targets: `tests/test_skills.py` loads them with `load_skills`, checks the routing hints against the signal ontology and asserts the router fills the plan's skill slot with the right package for a representative request. - `osr skills [ROOT] [--json]` validates and lists SKILL.md packages (default root `branding.SKILLS_DIR` = `.claude/skills`); `osr --skills ROOT ...` adds them to any routing command. Documentation coverage - `docs/REFERENCE.md`: generated API reference listing every module under `src/opensmartroute` and every exported name with its kind, signature and one-line summary; re-exports link to their definition. Produced by `scripts/api_reference.py` (`write` | `check` | `report`), stdlib only. - Every exported class, function, constant and type alias now carries a one-line summary (docstring, or a same-line comment for constants). `tests/test_docs.py` fails on an undocumented name, a stale reference, a module missing from the reference, or a `docs/*.md` file not linked from the README. Policy composition - `Policy` is an ordered chain of `PolicyRule` callables (`enabled`, `allow_list`, `deny_list`, `allowed_kinds`, `region`, `DataBoundaryRule`, `pii`, `tenant`, `cost_budget`, `latency_slo`, `input_tokens`, `context_window`, `tools`, `modalities`, `LanguageRule`, `JailbreakRule`). `Policy.with_rules(*rules)` appends rules (subclasses that override `check` are folded in as a single rule); `Policy.rule_names` and `default_rules()` expose the chain. Branding - `opensmartroute.branding`: single source of truth for brand-derived names (`BRAND`, `PACKAGE`, `CLI`, `ENV_PREFIX`, `ERROR_CODE_PREFIX`, `METADATA_PREFIX`, `STATE_DIR`, `ENTRY_POINT_GROUP`) with `env_key()`, `error_code()`, `metadata_key()`, `logger()`, `user_agent()` and `version()`. Error codes, `osr-*` frontmatter keys, the HTTP `User-Agent`, MCP `clientInfo`, the OpenAI proxy alias and the FastAPI title/version derive from it. Learning - Judge-score calibration: `LLMJudgeStrategy(calibrate=True, min_fit=20, calibrator=)` keeps an `IsotonicCalibrator` per judge, pairs each raw judge score with the served target's observed outcome and re-fits on every `update()`; `Router.learn()` forwards outcomes to the judge even when it is only used for escalation. Raw scores stay visible in the rationale (`raw=`); state round-trips through `state()` / `load()`. - `learning.warm_start_from_matrix(rows, strategies, weight=)`: offline full-information reward matrix `(prompt, {target: reward})` replayed into every learner (LinUCB ridge per arm, IRT, Thompson posteriors, task table, Markov rewards) before going online. - `MarkovStrategy(state_from="auto" | "task_type" | "domain", decay=)`: conversation state is the learned task type joined with the domain (not only the domain); per-request state memory so an outcome credits the state that was scored. `MarkovChain(decay=)` forgets transition counts, `RoutingMDP(decay=)` keeps exponentially weighted rewards. - Federated merge on every learner: `MarkovChain.merge`, `RoutingMDP.merge`, `MarkovStrategy.merge`, `BanditStrategy.merge`, `TaskTableStrategy.merge`; `learning.merge_learners(local, remote)` pairs same-named strategies across replicas. `AutoLearner.refresh()` implements the writer / reader pattern for replicas sharing one `StateStore`. - Cascade steps feed every learner: `CascadeStep.cost_usd`, `CascadeResult.total_cost_usd`, `CascadeResult.outcomes(request)` (one per-step `Outcome`, rejected steps are failures) and `Router.learn_cascade(request, result)`. Learners keep their per-request memory while `Outcome.step` is set so multi-step trajectories credit every step. - Strategies condition on the plan role: `Router._build_plan` tags sub-route signals with `signals.extra["role"]`; `BanditStrategy` contexts, `TaskTableStrategy` rows (`skill:` plus `family:skill:`), `MarkovStrategy` states and every learner's request memory are keyed by role (`strategies.base.role_of` / `memory_key`), so a target's record as a skill or persona never leaks into its record as the primary answerer. `TaskTableStrategy` now learns from role outcomes. Economics - Energy and carbon as cost dimensions: `RouteTarget.unit_energy` (`cost["wh_per_1k_tokens"]`), `RouteTarget.unit_carbon` (`cost["gco2_per_1k_tokens"]`, or energy x `cost["gco2_per_wh"]`) and `Objective(energy=, carbon=)` weights applied to the log-normalised values in the utility. Resilience - `AutoLearner.load()` quarantines corrupt or incompatible learner state instead of failing: the file is renamed `*.corrupt-` (or the store key copied under `quarantine/`), the learner starts blank and `AutoLearner.quarantined` lists `(strategy, reason)`. A failing `StateStore.get` is recorded, not raised. - `FileAuditSink` resumes its hash chain from the last line on disk across restarts and gains `FileAuditSink.verify(path) -> (ok, n, first_problem)` detecting edited, removed or unparseable lines. - `LLMJudgeStrategy` filters judge output item by item: non-dict items, unparseable / NaN scores and hallucinated or injected target ids are skipped without discarding the rest of the ranking; non-string judge returns are a failure mode with zero confidence. - `scripts/bench.py --scale` sweeps 16 / 64 / 256 / 1024 targets with and without retrieval narrowing and reports p50 / p95 / p99; `docs/ARCHITECTURE.md` documents the measured envelope. - `tests/test_resilience.py`: audit-chain verification, judge JSON failure modes, state-corruption recovery (files and stores), multi-replica hand-off. Deployment - `deploy/Dockerfile` (non-root, multi-stage, `OSR_*` environment to `osr serve`), `deploy/entrypoint.sh` and the Helm chart `deploy/helm/opensmartroute` (ConfigMap-driven catalogue, hardened pod security context, HPA, PDB, NetworkPolicy, optional PVC with a multi-replica warning). Roadmap exit criteria - `eval.criteria`: every offline-measurable exit criterion in `docs/ROADMAP.md` as a simulation that drives the real `Router` / learners and returns a `CriterionResult` - `cold_start_ratio()` (v0.5), `multi_round_vs_best_single()` (v0.6), `match_at_1_at_scale()` with `synthetic_tool_catalogue()` (v0.7), `conformal_coverage()`, `knapsack_never_exceeds_cap()` and `ope_within_live_ci()` (v0.8), plus `bootstrap_ci()` and `run_all()`. `scripts/exit_criteria.py [--full] [--json]` runs them and exits non-zero when one fails. - `osr eval --multi-round [--threshold] [--max-rounds]` compares `MultiRoundExecutor` against the best single target on a dataset whose rows carry per-target `scores`. - Cold-start exploration: `Router(explore_rate=, explore_min_samples=, explore_seed=)` and `RoutingSettings.explore_rate` / `explore_min_samples` occasionally serve the least-seen viable candidate until it has enough outcomes; propensities include the exploration mass and `signals.extra["explored"]` marks the request. - `MultiKnapsackBandit(on_capped="release" | "abstain")` and `capped(scores)`: when every arm would breach a hard cap the bandit can abstain instead of releasing the cheapest arm. - `MultiRoundExecutor(failures_before_switch=)` forwards the switch policy to `ProgressRouter`. - Thread safety: `Router.lock` (re-entrant) guards strategy scoring, every learner update, task pins, request memory, retrieval narrowing and the exploration RNG; the LLM judge is scored outside it. `AutoLearner(lock=)` shares that lock (`EnterpriseRouter` / `RouterBuilder` pass it), snapshots are deep-copied and sequence-numbered so a slow `save()` never overwrites a newer one, and a separate I/O lock orders writers against `load()` / `refresh()`. `SemanticCache`, `MemoryRouter`, `AnnotatorPool` and `ModalityEscalation` lock their own state. - `SpeculativeCascade(concurrency=, draft_timeout_s=, history_size=)`: bounded worker pool sized for concurrent speculative runs, draft timeout, draft exceptions escalate to the strong target (`details["draft_error"]` / `["draft_timeout"]`), late strong failures are swallowed after an accepted draft, `draft_failures` / `strong_failures` counters and `stats()`. - `ModalityEscalation.run` escalates when the text target raises (`details["reason"]`) instead of failing. - `MultiRoundExecutor`: rounds whose handler raised become `Round(error=...)` and the loop continues on another target; one judged learn per round (no provisional + correction double count); `deadline_ms`, `return_best`, `credit_task`, `RoundResult.stop_reason` / `best` / `errors` / `total_cost_usd`; `arun()` for coroutine handlers and an `async` judge. `ProgressRouter.run_step` (`learn=`) routes via `router.route`, records a failed step before re-raising, estimates step cost from the target's unit cost when the handler reports none; `arun_step` twin. - `tests/test_e2e_scenarios.py`: real-scenario suite with no stubs - the shipped `examples/` catalogue and rules driven end to end through an in-process OpenAI-compatible provider fleet over HTTP (PII boundary, tenant deny lists and data boundaries, persona plans, metrics, hash-chained audit, learner state surviving a restart), a provider outage opening and recovering a circuit breaker, the FastAPI service over an `EnterpriseRouter` (OpenAI proxy, feedback, stats, error mapping), the `osr` CLI (`route`, `eval --frontier`, `--min-accuracy` gate, `targets`, `stats`), `ProgressRouter` / `MultiRoundExecutor` agentic loops, a real MCP server subprocess over stdio, and 24 concurrent requests through the full middleware stack. - `EnterpriseRouter.credit_task()`: delivers the delayed task reward through the router and persists the re-credited learner state; `MultiRoundExecutor(EnterpriseRouter)` now closes the task-credit loop. - Execution: a primary target without a handler (an instructions-only skill or persona) runs on the plan's `llm` slot - its instructions are disclosed in the system prompt, the model answers, and the model is credited with a `role="llm"` outcome - instead of failing with "has no handler". - Execution enforces the PII boundary set up by `GuardMiddleware(redact=True)`: targets whose constraints allow PII receive the original text (`context["pii_restored"]`), every other target keeps the placeholders (`context["pii_redacted"]`), and the mapping never reaches a handler. - `create_app()` accepts an `EnterpriseRouter` (middleware, health, telemetry and audit apply to every HTTP request; `/stats` includes the health snapshot) and maps `SecurityError` / `ValidationError` to 400, `NoRouteError` to 422, `TargetUnavailableError` to 503 and `ExecutionError` to 502. - `DomainActionSignal` detects arithmetic and unit conversions (`17% of 2,450`, `12 * 4`, `5 miles to km`, percent / calculate / square root ...) as the `math` domain, so calculator-style tools and `max_complexity` math rules fire; lexicon keywords made of symbols (`%`) now match. - `examples/targets.yaml`: the public cloud models and the research agent carry `constraints.pii_allowed: false`, making PII a hard policy stop instead of only a rule preference. Hosted platform (`platform/`, separate from the zero-dependency SDK): `platform/api` (package `osr-platform-api`, FastAPI) and `platform/web` (`osr-platform-web`, Next.js 16) - `osr_platform.app.create_platform_app()` / `osr-platform-api`: the routing API as a service: `/api/v1/route` (decision, signals, ranked breakdown, policy rejections; `plan` / `execute`), `/feedback`, `/targets`, `/catalogue`, `/usage`, `/keys`, `/tenants`, `/stats`, `/audit`, the OpenAI-compatible `/v1/models` + `/v1/chat/completions` (`model: "auto"` or a pinned target), and `/api/v1/docs` serving the repository Markdown (README, CHANGELOG, `docs/`) rendered to HTML with a table of contents and Mermaid blocks as JSON. `OSR_PLATFORM_WEB_URL` / `OSR_PLATFORM_CORS_ORIGINS` point `/` and Stripe redirects at the web app and allow it as a browser origin. - Web app: landing page with a live catalogue, documentation (sidebar, table of contents, Mermaid), pricing, a playground (decision view with ranked utility bars, signals, policy rejections, plans, execution; OpenAI-compatible chat with `auto` or pinned model), signup / sign-in (key shown once, stored in the browser only) and a dashboard (overview with usage chart, API keys, usage by target and endpoint, tenants editor, audit trail with chain verification, plan and billing). Next.js route handlers proxy `/api/*`, `/v1/*` and `/openapi.json` to `OSR_API_URL`, so the browser only talks to the web origin; server components render from the API at request time. - API keys (`osr_live_...`, SHA-256 at rest, `Authorization: Bearer` or `X-API-Key`), plans (free / pro / enterprise with per-minute and per-day quotas, key and tenant caps, feature gates; `OSR_PLATFORM_PLAN_OVERRIDES`), usage metering per key / endpoint / target with tokens and cost, admin API (`X-Admin-Token`) and an optional Stripe checkout + signed-webhook billing hook that is inert until `OSR_PLATFORM_STRIPE_*` is configured. State is SQLite (WAL, with a rollback-journal fallback for SMB mounts). - Editions: `OSR_PLATFORM_EDITION=community` runs the core `Router`; `enterprise` runs `RouterBuilder` with auto-learning persistence, health circuit breakers, `GuardMiddleware`, metrics and a hash-chained `FileAuditSink`, and unlocks tenants (per-tenant data boundary / region / deny lists / cost caps applied as hard constraints), `/stats` and `/audit` (filtered per account). - `OSR_PLATFORM_PROVIDERS` maps targets to OpenAI-compatible providers (Azure OpenAI, OpenAI, vLLM, Ollama ...) through `adapters.openai_compat`; targets without a provider stay routable as decisions. - `platform/api/Dockerfile` and `platform/web/Dockerfile` (non-root, health checks; the API keeps a `/data` volume), `infra/` Bicep (Container Apps `osr-api` + `osr-web`, Azure Files, ACR, Log Analytics, Azure OpenAI with gpt-4.1 family deployments), `azure.yaml` for `azd up`, and the `Platform` workflow (API tests, web lint/typecheck/build, two-container smoke, OIDC `azd` deploy). Reference deployment: `rg-osr-prod` in Sweden Central. - Public catalogue and rankings, measured on the deployment rather than curated: `GET /api/v1/models` (model cards with capabilities, constraints, pricing per 1k / 1M tokens, executable flag, requests, tokens, cost, success rate, latency, domains and week-over-week trend), `GET /api/v1/models/{id}` (daily series, health, effort siblings), `GET /api/v1/rankings?days=&domain=` (share of tokens and requests, trend, per-domain leaders) and `GET /api/v1/stats/public` (headline figures). Usage rows now store `request_id`, `model`, `domain` and `complexity` (additive SQLite migration) so every figure is reproducible from the same table that meters billing. - `GET /api/v1/activity`: newest-first per-account request log with `endpoint` / `target` / `key` filters and `before=` cursor paging. - `POST /v1/chat/completions` extensions: `models` (candidate list; the router scores only those and falls back down the ranking when an upstream call fails, up to three times), `stream: true` (`text/event-stream` chunks, `[DONE]` terminator) and an `osr` object (`objective`, `constraints`, `tenant`, `plan`, `fallbacks`). The `opensmartroute` metadata gained `plan`, `fallback_from`, `cost_usd` and `latency_ms`; responses carry `X-Request-Id`, `X-OSR-Target`, `X-OSR-Confidence`. - Web: `/models` explorer (search, domain, executable, kind and sort), `/models/{id}` pages with traffic chart, routed-domain bars, capabilities, constraints, examples and copyable call snippets for the live base URL, `/rankings` leaderboard (window, metric and domain filters), dashboard `/activity` with expandable request rows and feedback snippet, playground compare mode (up to four targets in parallel with cheapest / fastest badges and fallback markers; `?model=` deep link from model pages), and a landing page fed by the public stats (hero figures, most-routed targets, domain leaders, candidates + streaming sample, three-step getting started). Sitemap lists models and rankings. - Platform single sign-on: `GET /api/v1/auth/providers`, `GET /auth/{provider}/start?next=` and `POST /auth/{provider}/callback` (PKCE, HMAC-signed state, GitHub / Google / Microsoft / GitLab presets and custom OIDC issuers via `OSR_PLATFORM_SSO_*`), `osr_sess_` browser sessions with 30-day TTL (`GET /auth/sessions`, `POST /auth/logout?everywhere=`, `DELETE /auth/sessions/{id}`), linked identities (`GET /auth/identities`, `DELETE /auth/identities/{provider}`; refuses to remove the only way in), `/api/v1/me` reports `via` and `identities`, `/api/v1/info` lists `sso` providers. New SQLite tables `identities` and `sessions` (additive migration). - Web: "Continue with GitHub / Google / ..." on login and signup, `/auth/callback` exchange page (shows the first API key once when the account is created), `/dashboard/account` (profile, linked identities, browser sessions with revoke and sign out everywhere). Shared UI toolkit under `components/ui` (Radix-based button variants, dialog, dropdown menu, tooltip, select, switch, progress, avatar, table, sonner toasts) and a Recharts chart kit under `components/charts` (`TimeBars`, `TimeArea`, `RankedBars`, `Donut`, `Sparkline`) with one palette and shared tooltip/legend/empty states. Redesigned header (compact nav, Ctrl/Cmd+K catalogue search, account menu), light hero with a prompt box that opens the playground pre-filled (`/playground?q=`), rankings charts (share of requests, traffic by domain), dashboard usage stacked bars and quota progress, and a table view on `/models`. - Platform users, workspaces and roles (B2C and B2B): new SQLite tables `users`, `memberships`, `invites` and `sso_connections`, `accounts.kind` (`personal` / `organization`) and `accounts.slug`; existing databases are migrated on start (every account becomes a personal workspace owned by its user). `POST /signup` and first SSO sign-in create the user plus a personal workspace; `GET/POST /workspaces`, `POST /workspaces/{id}/switch`, `PATCH/DELETE /workspace`, `GET /workspace/members`, `PATCH/DELETE /workspace/members/{user_id}` (owner > admin > member, last owner protected), `POST/DELETE /workspace/invites` (link shown once, 14-day TTL, seats = `plan.max_members`: free 3, pro 10, enterprise 500), `GET /auth/invites/{token}` and `POST /auth/invites/{token}/accept`. Key and tenant mutations need admin; API keys act as owner of their workspace. `/me` adds `user`, `role`, `workspaces`; usage and activity rows carry `user_id`. Organization SSO (enterprise plan feature `sso`): `GET/PUT/DELETE /workspace/sso` stores the company IdP (Google, Microsoft, GitLab, GitHub or any OIDC issuer, allowed email domains, default role), served as provider `org-` with just-in-time membership; `GET /auth/discover?email=` returns the sign-in options for an email domain. - Web: workspace switcher in the dashboard sidebar, `/dashboard/members` (invite, roles, remove, pending invitations), `/dashboard/workspace` (create organization with its first key, rename/slug, organization SSO connection, leave), `/invite/[token]` acceptance page, and the sign-in page discovers company SSO from the typed email ("Continue with "). - Custom domains: Bicep parameters `webAliasDomains`, `apiCustomDomain`, `customDomainCertificates` (managed certificates, TXT validation for the apex), outputs for the static IP and domain verification id; `scripts/domains.ps1` configures Cloudflare DNS, redirects (`.com` to `.ai`, `www` to apex) and SSL settings and binds the domains in two provision phases (see `platform/README.md`). ### Changed - Web: the UI toolkit under `platform/web/src/components/ui` is now the shadcn/ui `new-york` kit (`components.json`, `radix-ui` umbrella package, `class-variance-authority`, `cmdk`, `vaul`, `tw-animate-css`) with the brand tokens mapped onto the kit's CSS variables in `globals.css`. Header (navigation menu with grouped product/resources panels, mobile sheet, command search), footer, dashboard shell (sidebar), docs sidebar (collapsible sections, mobile sheet) and version menu (dropdown) are rebuilt on it. Hand-rolled tables, filter chips, selects, switches, search inputs, stat cards, accordions and sliders across the marketing pages, models explorer/catalogue, marketplace, rankings, playground, estimator, ROI calculator and dashboard pages use the kit primitives (`DataTable`, `StatCard`, `FilterChip`, `SearchInput`, `Select` wrapper, `Switch`, `Progress`, `Accordion`, `Slider`). The per-scope `@radix-ui/react-*` packages, `cn` and `next-themes` dependencies are removed. - `Router(slot_quality_floor=, narrow_above=, narrow_to=)` and `RouterBuilder.with_retrieval(narrow_above=, narrow_to=)` default to `None` (= settings) instead of literals; `Router.calibrator` defaults to `TemperatureScaler(settings.routing.softmax_temperature)` and plan-slot margins use it instead of a private softmax. - `RouterBuilder.with_auto_learning()`, `with_health()` and `with_queue_awareness()` no longer inject hardcoded weights; the defaults come from `WeightSettings`. - `MultiKnapsackBandit`: the sliding-window spend meter is O(1) per step (running sums over a bounded deque); shadow prices are updated in budget units (`avg / B - 1`) so a budget expressed in tokens no longer blows the penalty up; the "release the cheapest arm" fallback only triggers when *every* arm is blocked, not when utilities happen to be negative. - Documentation: the README is a short overview (pitch, install, quick start, what it routes, how it decides, production, security, documentation index, roadmap); the detailed walkthroughs (targets, execution, real providers, learning, decorator SDK, enterprise builder, research-track modules, CLI, routing latency, repository layout) moved to `docs/GUIDE.md`. `docs/ROADMAP.md` marks every research-track row as implemented with its module; `docs/RESEARCH.md` and `docs/MATH.md` describe the corresponding techniques and formulas (sections 10 to 16). ### Fixed - `PageHinkley` accumulated `x - mean - delta`, so a perfectly stationary quality stream alarmed after `threshold / delta` samples and `AutoLearner` reset healthy targets; the tolerance now has the textbook sign (`+ delta`) and a constant stream never drifts. - `Bandit.mean` is abstract and `LinUCB.mean()` returns the intercept estimate instead of a stub. - `OpenAICompatClient` derives its `User-Agent` from the package version instead of a literal. - `enterprise.ops.ABTest.observe` no longer divides by zero when the control arm has no samples yet. - `server.py`: request bodies were parsed as query parameters (HTTP 422) because `from __future__ import annotations` stringified the locally defined pydantic models; removed. - `execute()` re-raised an `ExecutionError` from a provider handler (upstream 4xx, malformed body) without recording a failed outcome, so learners and health never saw those failures. - `EnterpriseRouter.learn()` with auto-learning bypassed the router's feedback store, task-credit buffer and pins (only the strategies were updated); `RouterBuilder.with_feedback()` no longer double-records through a learner sink. - `CacheMiddleware` keyed only on text / constraints / objective, so a pinned (`candidates=`) or `plan=True` call could be served another call's cached decision; per-call routing options are now part of the key. ## [0.4.0] - 2026-09-04 ### Added Execution and plans - `Router.run()`, `AsyncRouter.run()` and `EnterpriseRouter.run()` route and execute the resulting plan through the new `opensmartroute.execution` module: the `skill` slot's handler runs as a pre-processor (may return a rewritten `RouteRequest`, a `str` attached as `context["skill_output"]`, or `None`), persona / skill / primary `instructions` are composed into `context["system"]`, the primary handler (LLM, skill or agent harness) is called, and one `Outcome` per participant is recorded and learned from. Returns `ExecutionResult(response, text, target_id, steps, system_prompt, effective_request, outcomes)`. - `RouteTarget.instructions` (persona prompt, skill body or agent standing instructions, disclosed only when the target is part of the plan), `RouteTarget.effort` (reasoning-effort variant) and `RouteTarget.family` (siblings share breaker and budget state). - `Outcome.task_id`, `Outcome.role` and `Outcome.step` so delayed, task-level rewards can be joined to every call in a trajectory and plan slots learn separately from the primary. - `RouteRequest.profile` (user / tenant attributes) and `RouteRequest.history` (session turns) feed `ProfileSignal` and `HistorySignal`. - `Router(slot_quality_floor=0.5)`: a persona / skill slot is only filled when its best candidate's quality estimate clears the floor. Strategies and learning - `TaskTableStrategy` (static task-type table with Wilson intervals; `fit_task_table()` from outcomes), `DeferStrategy` (learning-to-defer for `TargetKind.HUMAN`), `EffortStrategy` and `decide_effort()` (think vs. no-think), `ProgressRouter` and `MultiRoundExecutor` (progress-guided step routing and a Router-R1 style route / execute / judge loop), `CascadePlanner` with `BeliefTracker` (cascade as a finite-horizon MDP or POMDP with a stop action). - `learning.TaskCredit` (uniform / discounted / last / blended credit assignment from a terminal task reward), `learning.TaskPins` (admission-time pinning), `ExampleMiner`, `RequestMemory`, `SimilarityFallback`, `target_embedding()`, `nearest_targets()` and `warm_start()` for cold-start targets. - `math.calibration`: `TemperatureScaler`, `IsotonicCalibrator`, `ConformalCalibrator` (split conformal candidate sets with a coverage guarantee). `Router(calibrator=, conformal=)` exposes calibrated confidence and `RouteDecision.candidate_set`. - Forgetting (`decay < 1`) in `IRTModel` and `BradleyTerry`; `BradleyTerry.merge()` for federated sufficient statistics; Sherman-Morrison rank-1 updates and surfaced posterior variance in `LinUCB`. Signals - `signals.ontology.TaskOntology` (families, types, subtypes with seed templates) and `signals.models` (`HashedFeaturizer`, `HashedClassifier`, `HashedRegressor`, `synthesize_dataset()`) behind `TaskTypeSignal`, `LearnedDifficultySignal`, `ReasoningNeedSignal`, `OutputLengthSignal`, `SensitivitySignal`; weights ship as JSON (`SignalModelBundle`) and load with `Router(extractors=learned_extractors(SignalModelBundle.from_file(path)))` or `osr --models path`. - `osr train --out models.json [--from rows.jsonl] [--synth] [--gadget detector.json]`. Catalogue interop and scale - `opensmartroute.retrieval`: `BM25Index`, `DenseIndex`, `Retriever`, `rrf()` (reciprocal-rank fusion), `select_skill_set()` (submodular skill-set selection under a token budget), `tool_search_target()` and `execute_tool_target()` meta-tools. `Router(retriever=, narrow_above=500, narrow_to=50)` switches to retrieve-then-rank for large catalogues. - `adapters.mcp`: `tools_from_mcp()`, `connect_mcp()` (stdio JSON-RPC), `enrich_description()`, `sign_manifest()` / `verify_manifest()` (HMAC-SHA256 or Ed25519), `description_risk()`; `osr mcp-manifest sign|verify`. - `adapters.a2a`: `fetch_agent_card()`, `agent_from_card()`, `skills_from_card()`, `a2a_handler()`. - `adapters.frameworks`: `langgraph_node()`, `langgraph_condition()`, `maf_router_executor()`, `openai_tool_spec()`, `route_and_execute()`. - `adapters.personas`: `load_personas()` / `persona_target()` from Markdown, JSON, CSV and Copilot `*.agent.md` / `*.chatmode.md` files. - Agent-harness adapters: `AgentHarness`, `HarnessResult`, `CallableHarness`, `HTTPHarness` (408 / 429 / 5xx map to `TargetUnavailableError`), `SubprocessHarness`, `harness_handler()`. - SKILL.md loader (`load_skill`, `load_skills`, `skill_from_markdown`) for [agentskills.io](https://agentskills.io/specification) folders; works with or without PyYAML. - OpenAI-compatible proxy in the HTTP server: `POST /v1/chat/completions` (`model: "auto"` routes, executes and learns) and `GET /v1/models`; `GET /healthz`. Evaluation - `eval.baselines`: random, cheapest, best-prior, most-expensive, static task table, oracle, `multi_sample_oracle()` and `noise_floor()`; `osr eval --baselines`. - `eval.robustness`: `repeat_flip_rate()`, `paraphrase_robustness()`, `profile_swap_fairness()`, `coreset()`, `diversity()`; `osr eval --robustness`. - `eval.frontier`: `frontier3()`, `hypervolume()`, `ablation_report()`; `osr eval --frontier3 --ablation`. - `eval.ope`: IPS, SNIPS and doubly-robust off-policy estimates with weight clipping and effective sample size; `osr ope logs.jsonl`. - `eval.datasets`: presets for RouterBench, LLMRouterBench, RouterEval, xRouteBench and RouterXBench; `osr eval --preset`. - `calibration_report()` (ECE, Brier, reliability bins); `osr eval --calibration`. - `osr eval --min-accuracy X` exits with status 2 below the threshold; CI uses it as the routing accuracy gate. Enterprise - `enterprise.stores`: `RedisStateStore`, `SQLStateStore` (DB-API 2.0; PostgreSQL, SQLite, MySQL), `VersionedStateStore` (schema envelope with forward migrations), `EncryptedStateStore` (AES-256-GCM, key rotation; `crypto` extra), `BatchedStateStore` (write-behind), `NamespacedStateStore`. `RouterBuilder.with_state_store()` persists learner state through any of them. - `enterprise.ops`: `ShadowMiddleware` and `ABTest` (shadow or A/B routing judged by Wald's SPRT), `FairShareMiddleware` (dominant-resource fairness across tenants), `InflightTracker` and `QueueAwareStrategy` (Erlang-C / Kingman wait estimates from live in-flight counts). `RouterBuilder.with_shadow()`, `.with_fair_share()`, `.with_queue_awareness()`, `.with_calibration()`, `.with_retrieval()`, `.with_router_options()`. - `opensmartroute.settings`: frozen, environment-overridable `Settings` (`OSR__`) for every tunable constant; `opensmartroute.branding` centralises package identifiers. - `deploy/`: non-root reference `Dockerfile`, `entrypoint.sh` and a Helm chart (Deployment, Service, Ingress, HPA, ConfigMap). Releases publish `ghcr.io/isathish/opensmartroute:`. Security - `security.gadget.GadgetDetector` (learned confounder-gadget classifier; `InputGuard(learned=True)`), `security.injection.injection_risk()` and `inspect_injection()`, `security.limits.ResourceLimiter` and `ResourceLimitMiddleware` (per-task caps on steps, tool calls, depth, tokens, cost, wall-clock), `security.provenance.OriginPolicy` (sensitive parameters of state-changing tools must originate from the user turn), `security.safety.run_safety_suite()` (red-team routing cases); `osr safety [--learned-guard]` exits with status 2 on any failure. Project - Public API snapshot test (`tests/public_api.json`, `tests/test_public_api.py`): adding or removing an exported name fails CI until the snapshot is updated deliberately. - Release automation: `scripts/release.py` (version consistency, changelog sections, release preparation), `Prepare release` and `Release` workflows (release PR, tag, GitHub release with changelog notes, PyPI trusted publishing with PEP 740 attestations, SLSA build provenance, GHCR image), CodeQL for Python and workflows, Dependabot for actions and Python dependencies. - CI matrix covers CPython 3.10 to 3.13 on Linux plus 3.12 on Windows, checks formatting, builds and smoke-tests the container image. - `examples/end_to_end.py`, `examples/skills/sql-reporting/SKILL.md`; `instructions` on the example personas and skills. ### Changed - `Router.execute()` / `AsyncRouter.execute()` keep returning the raw handler response but now go through the plan-aware executor. `EnterpriseRouter` gains `execute()` (returns `ExecutionResult`). - `load_targets` and `load_rules` are exported from the package root. - Project metadata: repository URLs point at `isathish/OpenSmartRoute`; classifiers declare CPython 3.13 and `Typing :: Typed`; the sdist no longer ships brand assets and fonts. ### Fixed - `config.load_document` and the eval dataset loader read files as UTF-8 explicitly; on Windows the locale default (cp1252) failed on the shipped `examples/targets.yaml`. ## [0.3.0] - 2026-09-04 ### Added - `opensmartroute.adapters`: stdlib `OpenAICompatClient` (timeouts, exponential backoff with `Retry-After`, typed error mapping, key never logged) with `judge_fn`, `embedder`, `chat_handler` glue; lazy `sentence_transformers_embedder` and `OpenTelemetryTelemetry`. - `opensmartroute.config`: `load_targets` / `load_rules` / `load_document` with `ConfigurationError` reporting file, entry and reason. `TargetRegistry.from_file` now delegates to it. - `scripts/bench.py` — reproducible routing-latency benchmark; `scripts/brand_build.py` — logo system generator with WCAG 2.2 audit and platform-standard exports. - Brand identity: rounded-geometric wordmark (Quicksand) and Poppins text, vendored under OFL; light and dark palettes verified ≥ 4.5:1 text / ≥ 3:1 graphics. - `docs/ROADMAP.md` with per-release exit criteria; `docs/RESEARCH.md` rewritten as a survey with a formal problem statement, taxonomy, systems comparison and idea→module map. ### Fixed - `HealthPolicy` consumed a rate-limit token for **every** admissible candidate on every route; it now only checks availability, and `EnterpriseRouter` reserves one token for the chosen target. - `/feedback` endpoint dropped `complexity`, so IRT never learned from HTTP feedback. ### Changed - `cli._load_rules` (private, but used by examples) replaced by public `config.load_rules`. - Removed the earlier gradient ring / wordmark SVGs in favour of the generated system. ## [0.2.0] - 2026-09-04 ### Added - `opensmartroute.math`: Thompson/UCB1/LinUCB/ε-greedy bandits, cost-aware Lagrangian wrapper, IRT (2PL) model, Bradley–Terry + Elo, Markov chain + routing MDP (value iteration), EWMA/Welford, Page–Hinkley and ADWIN-lite drift, Wilson interval, Pareto/TOPSIS, Erlang-C / Little's law / Kingman queueing. - `opensmartroute.learning`: `IRTStrategy`, `PreferenceStrategy`, `LinUCBStrategy`, `MarkovStrategy`, `AutoLearner` (fan-out + drift detection + atomic persistence). - `opensmartroute.realtime`: circuit breaker, token-bucket rate limit, rolling budget, `HealthRegistry`, `HealthPolicy`, `HealthStrategy`. - `opensmartroute.enterprise`: `RouterBuilder`, `EnterpriseRouter`, middleware chain (`CacheMiddleware`, `TenantMiddleware`, `TimeoutMiddleware`), telemetry ports (`LoggingTelemetry`, `MetricsTelemetry`), `StateStore` ports, hash-chained `FileAuditSink`. - `opensmartroute.security`: `InputGuard` (confounder-gadget detection), `Redactor`, `GuardMiddleware`, `sanitize_for_prompt`, `load_secret`. - `opensmartroute.aio.AsyncRouter`. - Typed exception hierarchy in `opensmartroute.errors`; `py.typed` marker. - Pinned rules (`pin: true`) and `primary: false` plan-only targets. - CI (ruff, mypy, bandit, pytest, eval gate), SECURITY.md, CONTRIBUTING.md. ### Changed - Lexicon matching is now whole-word (regex `\b`) — fixes false positives like `sql` in `australia`. - Cost/latency normalisation is log-scaled; default `Objective` weights lowered. - `NoRouteError` now derives from `OpenSmartRouteError` and carries `details["rejections"]`. ## [0.1.0] - 2026-09-04 - Initial release: core types, registry, signals, policy, rules/capability/similarity/bandit/ llm-judge/cascade strategies, router with plans, feedback store, eval harness, CLI, FastAPI server. Predates the repository history: the code is the initial commit tagged `v0.2.0`.