Architecture

How the platform composes. Every request and every pod step flows through the same ordered set of layers. This is the high-level view; the implementation, configuration, and keys are private.

Request lifecycle

  client (OpenAI SDK,        ┌──────────────────────────────────────────────┐
  Anthropic SDK, curl,       │            api.cognitum.one  (cloud)          │
  agentic hosts, …)          │                                              │
        │  authenticated key │   routes:  /v1/chat/completions              │
        ▼ ─────────────────► │            /v1/completions · /v1/messages    │
                             │            /v1/models · /v1/pods/* · /healthz │
                             │                                              │
                             │   1. AUTH         key → tenant + scopes      │
                             │   2. XLATE        Anthropic ↔ canonical      │
                             │   3. TIER ROUTER  difficulty → low|mid|high  │
                             │                   min/max clamp · hot params │
                             │   4. RESERVE      worst-case · fail-closed    │
                             │   5. PROVIDER     commodity model call        │
                             │   6. METERING     token count → usage ledger  │
                             │   7. COMMIT       actual cost                  │
                             │   8. RATE LIMIT   scatter-gather throughput    │
                             │        ▼                                       │
                             │   response + {resolved_tier, escalated, price} │
                             └──────────────────────────────────────────────┘
                                   │                          ▲
                                   ▼ usage ledger             │ routing params (hot-reload)
                          ┌──────────────────┐      ┌───────────────────────┐
                          │ async rollup     │ ───► │  FLYWHEEL             │
                          └──────────────────┘      │  assumed → MEASURED   │
                                                    └───────────────────────┘

  ── Darwin-Loop pods ride the SAME substrate ───────────────────────────────
  /v1/pods/spawn → pod = {domain × HOST × tier}
       loop:  SPAWNED → EXECUTING → EVALUATING → IDLE   (each step metered + budgeted)
       gate:  EVALUATING → ESCALATING → AWAITING_APPROVAL (reservation HELD)
                          → approve = COMMIT  |  reject = RELEASE  |  timeout = auto-reject
       bench: scores real captured artifacts → escalate on non-conformance

Layer by layer

1. Auth — multi-tenant identity. A key is hashed and looked up to yield its scopes and the account that defines the tenant. Every owned resource is scoped to that account; cross-tenant access and non-existence both return the same response, so existence never leaks.
2. Anthropic translation. The Anthropic Messages shape (system blocks, tool-use, tool-result, tool-choice) is translated to and from the canonical internal request — including full tool-use forwarding — for both streaming and non-streaming. An honesty guard ensures the reported model always reflects the real resolved model.
3. Tier router. An intrinsic difficulty signal, computed from the input alone, selects the tier, then clamps to the request's floor/cap and the key's highest scope. The weights, bands, and thresholds are hot-reloadable, so a calibration applies without a redeploy.
4. Budget reserve / commit. An atomic two-phase tracker reserves a worst-case estimate before the provider call and commits the actual cost after. It is sharded for concurrency; no headroom means no reservation and the provider is never invoked (fail-closed), with an account hard-cap backstop.
5. Provider. An abstraction over a commodity-model pool, with a zero-cost mock for tests and local development. The cognitum-* aliases map to vendor models via tier pools; raw vendor ids are never exposed.
6. Metering. Every request is metered with a family-correct progressive tokenizer; the local count is the billing floor on disconnect, and usage is rolled up asynchronously.
7. Rate limit. A scatter-gather limiter bounds throughput without serializing on a counter, plus tenant-scoped idempotency to dedupe retries.

The pod substrate & flywheel

Darwin-Loop pods reuse the same auth → tier → reserve → provider → meter → commit pipeline for each step. A plugin firewall (a fail-closed dynamic-import boundary) underpins both the host registry and third-party plugins: a load or contract failure is isolated and audited while the core stays online — a graceful skip, never a faked success.

The flywheel turns the heuristic routing priors into measured parameters by aggregating the usage ledger into an observed tier-mix and per-tier rates, then writing the hot-reloadable params. Honestly: the current sample is small, so this is a measured-from-limited-data calibration that sharpens with volume — a learned router would additionally need a per-request quality label the ledger does not yet carry.

Deployment posture

The service runs as a managed container on Google Cloud behind an authenticated public endpoint. Continuous integration is emulator-first and zero-cost; continuous deployment is keyless (workload-identity federation, least-privilege) and deploys only the exact commit that passed CI. Provider credentials live in a managed secret store, read by the runtime at request time — never baked into an image or a CI secret. Specific project identifiers, service-account names, and secret names are intentionally omitted from this public document.