DRIFT

---

The Problem

GPU and AI platforms depend on fast-moving projects such as PyTorch, TensorRT, Triton, vLLM, Transformers, CUTLASS, JAX, and NCCL. A small upstream change can alter an image, benchmark, CUDA assumption, or deployment template — but release review is usually a stream of links and scattered human memory. The signal that matters is buried: what changed, whether it touches your workload, and what to check before rollout.

What DRIFT Does

DRIFT is release intelligence for GPU and AI-infrastructure teams. It turns upstream release-note noise into a cited, engineer-ready answer:

What changed? Why does it matter to my workload? What should I check?

Every answer keeps the useful middle layer visible: a frozen primary-source span, a plain-language summary, workload relevance, confidence, severity, and one bounded action to check. Direct facts stay separate from interpretation, and nothing reaches a live endpoint until a human reviews it.

Built for OpenAI Build Week 2026 · Developer Tools.

Try DRIFT in 60 Seconds

Hosted — nothing to install. The live Railway store serves five human-reviewed Tier.FINAL Insights (JAX v0.11.0, Transformers v5.14.1, vLLM v0.25.1, NCCL v2.30.7-1, TensorRT 11.1); /briefing?top_n=10 returned exactly those five, verified on 2026-07-18. The deployed app build is v0.9.1, verified live the same day (/health reports 0.9.1, /docs returns 200, Vercel-origin CORS allows GET, POST). The local v0.10.0 source adds the MCP thin client and is not yet redeployed.

Surface	Link
Frontend — briefing with inspectable claim evidence	https://dr1ftless.vercel.app
API docs — /health, /briefing, /search, /chat, /openapi.json	https://drift-api-prod.up.railway.app/docs
Grounded chat — cited answer over reviewed evidence (verified provider-backed)	POST /chat in the API docs
Demo video — 3-min narrated walkthrough (Codex + GPT-5.6)	▶ Watch on YouTube (recording before submission)

Local — one command, no API key. The deterministic fixture path brings up the API, PostgreSQL, and the frontend — including the in-app Ask DRIFT grounded-chat box — together:

git clone https://github.com/iarjunganesh/drift.git
cd drift
docker compose up

Open http://localhost:3000 for the frontend and http://localhost:8000/docs for the API. No OpenAI key is required, and every record is clearly labelled example data. Full setup, cross-platform commands, and the live capture path are in Quick Start.

---

How It Works

1. Scout reads configured primary release feeds and normalizes source items.
2. Synthesizer deduplicates, embeds, clusters, and classifies substantive changes.
3. Insight extracts typed direct facts, inferences, and recommended checks with exact source spans.
4. Verifier separately rejects unsupported or misclassified claims.
5. Human review promotes only verifier-passed drafts with recorded notes.
6. Briefing ranks reviewed changes and grounds search/chat in retrieved DRIFT evidence.
7. FastAPI exposes the briefing, search, chat, health, and generated OpenAPI contract.

The currently working path substitutes committed examples for the unfinished live stages:

backend/fixtures/source_evidence/*.txt + insights.json → InsightStore → FastAPI → briefing/search/chat

Fixture records are explicitly labelled examples, backed by checked-in synthetic source text whose hashes and spans are verified in tests. They are never described as fresh live release analysis.

---

Architecture

_{The trust boundary at a glance. Everything left of the gate is untrusted machine output; a human reviewer is the only path to what an engineer sees. · light SVG / dark SVG}

Detailed pipeline diagram — the same six typed stages, as the maintainable Mermaid source of truth

_{Click to enlarge: light SVG / dark SVG · Downloadable light PNG / dark PNG · Source: arch-pipeline.mmd}

In short: the fixture path is complete and no-key. The local live path now persists source evidence, generates and separately verifies claim-grounded drafts, embeds them, and retains two model-run audits. Drafts are quarantined; only a human reviewer can publish them, and live read paths filter to reviewed, verifier-passed records. On 2026-07-15, the prior hosted v0.5.1 deployment migrated Railway PostgreSQL and served one bounded, unreviewed vLLM capture through /briefing. On 2026-07-16, Railway PostgreSQL was verified through 0003_claim_evidence_review_gate using its public TCP proxy. Later that day, the hosted v0.6.1 app passed /health, an empty fail-closed /briefing, /docs, Vercel canonical-banner source, and Vercel-to-Railway CORS checks. It then published four human-reviewed Insights (Transformers v5.14.1, vLLM v0.25.1, NCCL v2.30.7-1, TensorRT 11.1) through the review gate, and hosted /briefing, /search, and /chat were verified provider-backed — /chat returning a grounded gpt-5.6-terra answer with primary-source citations. This is a small, bounded reviewed set, not a broad live-release-analysis claim.

Deep dive → docs/ARCHITECTURE.md — runtime paths, stage ownership, provenance, retrieval, safety invariants, failure handling, and the Vercel/Railway deployment topology.

Codex project initiatives

The baseline, publication follow-up, bounded release milestones, and documentation follow-up are tied to fourteen project initiatives. The grounded live-chat row remains the primary v0.4.0 implementation session; v0.5.0 adds the bounded local capture path.

Initiative	Session ID	Focus
Foundation and inspectable vertical slice	019f61e7-1ea1-7742-9acc-99d62f39b888	Fixture API, typed contracts, agent boundaries, safety invariants, tests
Publication and judge-readiness baseline	019f61fc-c32e-7d92-9d2e-0bd9083d08e7	Documentation, architecture assets, CI/Codecov, deployment and submission surfaces
Hosted deployment and README follow-up	019f6253-ddfc-7272-8077-e34dfb3aee84	Railway/Vercel URLs, release badges, and public demo documentation
Grounded live chat, resilience, and locked delivery	019f62b9-10b7-7d82-a463-e6eb1192141c	Primary 0.2.0 candidate work: local live chat, async safeguards, locked delivery, and full implemented-code coverage
Day 1/Day 2 implementation follow-up	019f62e8-6715-70e2-a92a-fe28254f7b71	Scout feeds, async PostgreSQL/pgvector foundation, Tier.DEV embeddings/clustering/classification, session instructions, and status cleanup
Day 3/Day 4 Insight structured output	019f6336-3690-7022-a8ef-c8c0947e240f	Standalone generate_insight() structured parsing, strict validation, citations, confidence, and model provenance
Bounded capture, provenance, and status cleanup	019f66b4-78b8-7943-a41d-91e836d28f00	One-shot persisted capture, all-call budget/retry controls, live briefing adapter, evidence UI, and documentation synchronization
Grounding guardrails and capture readiness	019f6773-0e96-7363-9657-0e0531c3d594	Claim spans/hashes, separate verifier, review-gated publication, cross-references, calibration cases, manual notebook, and all-source capture preflight
Submission audit and frontend evidence presentation	019f6a46-e3eb-7de2-81b1-91515ae80043	Handwritten-next-step audit, explicit briefing states, system-theme presentation, canonical API-served banners, and status synchronization
Reviewed-evidence release hardening and hosted verification	019f6a78-6fa2-7121-9059-85ac8ceb9904	Evidence-byte integrity, database-only review notes, display-only results artifact, v0.7.0 hosted verification, and the v0.8.0 grounded-chat / verifiable-fixture hosted release
Freeze-plan audit and documentation synchronization	019f7190-912d-70e3-be6d-fcc81bf8e203	Audited the frozen scope against tracked implementation, corrected unshipped MCP/timeline/IDE claims, aligned demo requirements, and synchronized records
v0.9.0 evidence cleanup and session synchronization	019f7213-be19-7e50-92ac-a48bd5ecaacb	Retracted superseded Luna Insights through the audited review helper, verified the five-record Sol briefing, synchronized release status, and made the Luna results artifact explicit
v0.9.1 Terra grounded-chat evidence and screenshot pass	019f7278-ee77-7f02-bafd-6eba8bf046d2	Captured eight bounded Terra questions, refreshed the nine-image Luna/Sol/Terra gallery, and preserved the no-write boundary
v0.10.0 MCP thin-client integration	019f7607-aa5a-79b2-8101-4cd634495fbe	Thin-client MCP server (integrations/mcp/, ADR-011) over the public API — three stdio tools, no credentials, nothing changed under backend/; fixture-verified at $0 with 40 mocked-HTTP tests, and corrected stale hosted-version records to v0.9.1

See the full project initiative record.

How Codex and GPT-5.6 were used

Codex was used to build and audit the typed FastAPI stages, fixture contracts, tests, deployment files, architecture records, and the bounded async model-call path. The primary core-functionality session is 019f62b9-10b7-7d82-a463-e6eb1192141c; the Day 1/Day 2 implementation follow-up session is 019f62e8-6715-70e2-a92a-fe28254f7b71. The earlier initiative records preserve the foundation, publication, and hosted-demo work; the Day 3/Day 4 Insight implementation session is 019f6336-3690-7022-a8ef-c8c0947e240f; the grounding guardrail and capture-readiness follow-up is 019f6773-0e96-7363-9657-0e0531c3d594; and the submission-audit/frontend-presentation follow-up is 019f6a46-e3eb-7de2-81b1-91515ae80043; the reviewed-evidence hardening, hosted-verification, and v0.8.0 release session is 019f6a78-6fa2-7121-9059-85ac8ceb9904. The freeze-plan audit and documentation-synchronization session is 019f7190-912d-70e3-be6d-fcc81bf8e203; the v0.9.0 evidence-cleanup and session-synchronization follow-up is 019f7213-be19-7e50-92ac-a48bd5ecaacb; the v0.9.1 evidence and screenshot synchronization session is 019f7278-ee77-7f02-bafd-6eba8bf046d2; and the v0.10.0 MCP thin-client implementation session is 019f7607-aa5a-79b2-8101-4cd634495fbe.

GPT-5.6 is used only when an operator explicitly enables DRIFT_MODE=live and provides an API key. The local capture job routes embeddings, classification, claim drafting, and a separate verifier through the bounded provider boundary; it records source hashes, exact evidence spans, upstream references, and both model-run audits. The verifier is model-aided screening, not proof: a human must review and publish the draft before it can appear in live endpoints. Fixture mode makes no provider call. One paid, unreviewed vLLM capture is recorded as historical scrubbed evidence from the previous hosted deployment; it is not broad live-release analysis or evidence that the new gate is hosted.

Architecture Decision Records

Eleven decisions currently constrain the implementation. They are intentionally short; the architecture document explains how they compose.

ADR	Decision
001	Fixture-first judge path with an honest live boundary
002	Typed hand-rolled stages instead of a heavyweight agent framework
003	Citations, confidence, audit labels, and uncertainty are visible
004	Local spend guard around live iteration
005	PostgreSQL + pgvector for the live store
006	CI gates with a 100% implemented-code floor
007	Vercel frontend + Railway API/database deployment shape
008	Live grounded chat over the cited fixture store
009	Bounded model resilience and locked delivery
010	Claim-level evidence, separate verification, and review-first publication
011	MCP integration as a thin client over the reviewed API (v0.10.0)

---

Model Router & Safety Boundary

Provider calls belong behind model_router.py. Agent code must not hard-code provider model names. The intended tiers are:

Tier	Intended job	Status
dev / Luna	Classification, clustering, and prompt iteration	Produced the four reviewed Insights published 2026-07-16; run only with an explicit live key
live / Terra	Retrieve-first grounded chat	Serves hosted grounded chat over reviewed pgvector rows; verified provider-backed 2026-07-16
final / Sol	Three to five reviewed demo insights	Produced the five reviewed Tier.FINAL Insights now served by the live Railway store (v0.9.1, verified 2026-07-18)

Every live insight must preserve:

• one or more typed claims with frozen exact primary-source excerpts, offsets, and source hashes;
• direct facts distinct from inferences and recommended checks;
• confidence in [0, 1];
• the exact model identifier or an explicit fixture audit label; and
• a concrete, bounded what_to_check action.

Release text is untrusted data. It can be summarized and reasoned over, but it must never become model instructions or authorization to act on infrastructure. breaking and security are review priorities, not automation triggers. Upstream release type is separate from potential operator risk; neither is a compatibility verdict.

The local SpendGuard is a development safeguard; provider-side limits remain required for a deployed service.

Live model requests are additionally bounded by a retry envelope, local spend reservation, configured client timeout, and a closed/open/half-open circuit breaker. Interactive chat also has a queue timeout and concurrency bulkhead. A cancelled, failed, or usage-unknown provider attempt is accounted for conservatively; it is never silently treated as free.

---

Tech Stack

Layer	Technology	Role
Backend		Typed HTTP API and explicit pipeline stages
Contracts		Typed raw-item, insight, briefing, and chat contracts
Agent Pattern		Small lifecycle-wrapped functions; no orchestration framework
Release Feeds		Configured primary-source feed definitions and parsing
Live Store		Durable raw items, insights, and vector retrieval
Model Boundary		Provider isolation, GPT-5.6 Luna/Terra/Sol tiers, and budget control
Quality		Lint, types, tests, coverage evidence, and CI enforcement
Frontend		Operator-facing briefing view
Hosting		Railway API/database; Vercel Next.js frontend
Observability		Structured logs and explicit request/stage boundaries

Python dependencies are declared in pyproject.toml and resolved once in uv.lock; local, CI, and container installs all use that frozen lockfile. JavaScript dependencies are locked in frontend/package-lock.json.

---

Deployment status

Both tiers are live and the deployed app is v0.9.1, verified on 2026-07-18 — the live links live up top in Try DRIFT in 60 Seconds:

Surface	Status
Current hosted release	v0.9.1 live — verified 2026-07-18: /health and / report 0.9.1, /docs returns 200, /briefing?top_n=10 returns the five reviewed Insights, and Vercel-origin CORS allows GET, POST. Paid /search and /chat were not re-invoked
Current source release	v0.10.0 — thin-client MCP integration (integrations/mcp/) over the existing public API, fixture-verified at $0; changes nothing under backend/. Not yet redeployed (hosted is v0.9.1); hosted MCP evidence remains pending
Prior hosted release	v0.8.0 live — verified 2026-07-17: /health reported 0.8.0, /docs returned 200, the public Vercel page rendered Ask DRIFT, and Vercel CORS allowed GET, POST
Earlier hosted release	v0.7.0 live — /briefing (four reviewed Insights, review notes redacted), /openapi.json, and the deployed Vercel bundle's top_n=10 request were verified
Live reviewed store	/briefing?top_n=10 verified 2026-07-18 with exactly five reviewed, verifier-passed Tier.FINAL Insights: 10, 11, 13, 15, and 16
Database schema	Railway PostgreSQL at 0003_claim_evidence_review_gate, verified through its public TCP proxy
Branding	Swagger banner frame and canonical API-served banner pair follow the same system light/dark preference
Historical	v0.5.1 served one unreviewed vLLM Insight through /briefing on 2026-07-15 — retained as pre-gate evidence only

This is a small, bounded reviewed set, not broad live-release analysis. The Swagger contract groups the backend into System, Briefing, Search, and Chat sections so reviewers can navigate the API by job.

---

Screenshots & Evidence

These are captures of the DRIFT app and its reviewed evidence — not mockups. They follow DRIFT's tiered flow: the landing page, the briefing and its frozen claim evidence at the gpt-5.6-luna dev tier and the current reviewed gpt-5.6-sol final tier, the Terra-powered Ask DRIFT chat, and the branded API contract. Click any image to open it full size.

DRIFT landing page

The briefing is shown at two model tiers — gpt-5.6-luna (the cheap dev tier used for iteration) and gpt-5.6-sol (the final tier behind the current reviewed live-store capture):

Briefing — Luna dev tier	Briefing — Sol final tier

Claim evidence — Luna	Claim evidence — Sol

The Next.js briefing view exposes each record's status label, confidence, model/audit label, rationale, bounded action, source links, and—when present— claim-type evidence. On 2026-07-16, the hosted UI was verified against the review-gated API; reviewed evidence has since been published, so /briefing now serves the five reviewed Tier.FINAL Insights in the live store. The public app is the deployed v0.9.1 build, verified live on 2026-07-18 (/health and / report 0.9.1, /docs returns 200, /briefing returns the five reviewed Insights, and Vercel CORS allows GET, POST); the local v0.10.0 source is not yet redeployed. v0.7.0 deployed the review-note redaction and ten-item briefing request; Railway, CORS, public-contract, and Vercel-bundle checks are recorded in the changelog. v0.8.0 deployed the grounded Ask DRIFT UI and tag-pinned synthetic fixture evidence; Railway health/docs, the public UI, and CORS were verified. Paid /search and /chat were not re-invoked for the v0.9.1 verification.

Ask DRIFT answers questions live at the gpt-5.6-terra tier, grounded in the reviewed Insights:

Ask DRIFT box	Grounded NCCL answer	Grounded TensorRT answer

The Terra answer frames are visual captures from the bounded run and retain the IDs shown at capture time. For current publication state and exact Terra grounding, use the scrubbed archive in assets/evidence/: the live reviewed set is IDs 10, 11, 13, 15, and 16.

The branded Swagger contract is also available as visual evidence:

API documentation

The scrubbed hosted capture evidence is stored separately in assets/evidence/, including the verified unreviewed vLLM briefing response and its explicit operational limitations. After a human publishes a new notebook capture, its archive cell writes a new dated reviewed record and SHA-256 manifest there without including review notes or secrets.

---

Quick Start

One command (recommended)

The fastest judge path brings up the API, PostgreSQL, and the frontend together in fixture mode — no OpenAI key, identical on macOS, Linux, and Windows:

git clone https://github.com/iarjunganesh/drift.git
cd drift
docker compose up

Open http://localhost:3000 for the frontend and http://localhost:8000/docs for the API. Every record is labelled example data.

Manual setup

Requirements: Python 3.14, uv, and Node.js 24.x for the frontend. Every command below is shown for both shells; run whichever matches your platform.

bash — macOS / Linux

# 1. Clone the public repository
git clone https://github.com/iarjunganesh/drift.git
cd drift

# 2. Configure the no-key fixture path
cp .env.example .env

# 3. Install locked Python dependencies
uv venv .venv
uv sync --locked --group dev

# 4. Start the API
uv run uvicorn backend.main:app --reload

PowerShell — Windows

# 1. Clone the public repository
git clone https://github.com/iarjunganesh/drift.git
cd drift

# 2. Configure the no-key fixture path
Copy-Item .env.example .env

# 3. Install locked Python dependencies
uv venv .venv
uv sync --locked --group dev

# 4. Start the API
uv run uvicorn backend.main:app --reload

Open http://127.0.0.1:8000/docs, or try the endpoints:

bash / curl

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/briefing
curl "http://127.0.0.1:8000/search?q=vllm"
curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"What should I check for vLLM?"}'

PowerShell

Invoke-RestMethod http://127.0.0.1:8000/health
Invoke-RestMethod http://127.0.0.1:8000/briefing
Invoke-RestMethod http://127.0.0.1:8000/search?q=vllm
Invoke-RestMethod http://127.0.0.1:8000/chat `
  -Method Post -ContentType application/json `
  -Body '{"question":"What should I check for vLLM?"}'

Run the frontend in another terminal (same command on every platform). This is also where the in-app Ask DRIFT box calls /chat for a grounded, cited answer:

npm --prefix frontend ci
npm --prefix frontend run dev

Set NEXT_PUBLIC_API_URL in frontend/.env.local if the API is not on http://localhost:8000.

For the durable PostgreSQL path, start the configured database and run make migrate (or uv run alembic upgrade head) before connecting a live store. The fixture path does not require a database.

For a judge-ready all-source demonstration, use the DRIFT Manual Run in notebooks/drift_manual_run.ipynb. It makes the proof chain visible—source roster, spend-gated capture, frozen evidence, human review, and immutable archive—while starting with one item per configured source (at most eight). It creates drafts only and has a separate empty-by-default human publication cell. It needs local PostgreSQL or an operator-provided public/tunneled database URL; Railway's private postgres.railway.internal hostname cannot be resolved from a local notebook. When Railway provides a public TCP proxy, retain its complete private DATABASE_URL and set DRIFT_DATABASE_PUBLIC_HOST/ DRIFT_DATABASE_PUBLIC_PORT; DRIFT replaces only the host and port locally. Launch it with uv run --with jupyterlab jupyter lab notebooks/drift_manual_run.ipynb.

The underlying capture command is also draft-only. Enable live mode, provide an API key, and select a deliberately small source set. Start with dev for prompt iteration and use final only for selected, already-reviewed sources:

# bash — macOS / Linux
export DRIFT_MODE=live
uv run python -m backend.pipeline --source vllm --source tensorrt --source pytorch --tier dev

# PowerShell — Windows
$env:DRIFT_MODE='live'
uv run python -m backend.pipeline --source vllm --source tensorrt --source pytorch --tier dev

This command makes paid provider calls and writes quarantined draft rows. It is not a scheduled feed service and does not publish or verify the hosted deployment.

---

Use DRIFT inside your AI assistant (MCP)

DRIFT's reviewed release intelligence is also available to any MCP-compatible assistant — in the browser, over HTTP, and inside your AI assistant. The integrations/mcp/ server (ADR-011) is a thin client over the same public API the frontend uses. It exposes exactly three tools, each a one-to-one call to an existing endpoint:

Tool	Calls	Returns
drift_briefing(top_n)	GET /briefing	The ranked reviewed briefing
drift_search(query)	GET /search	Cited reviewed insights matching a query
ask_drift(question)	POST /chat	A grounded, cited answer — or a decline when nothing in the reviewed corpus matches

The server is configured with only DRIFT_API_URL (plus an optional DRIFT_MCP_TIMEOUT_SECONDS request timeout) and holds no OpenAI key, no database URL, and no credential of any kind. Every guarantee the API enforces — reviewed-only reads, redacted review notes, spend guards, resilience — applies automatically, because there is no second path to the store. The MCP server cannot draft, verify, publish, or retract an Insight.

Install the optional SDK group (the core install is unchanged):

uv sync --group integrations

Configure a client. Point DRIFT_API_URL at a local fixture instance (http://localhost:8000, zero cost) or the hosted API (https://drift-api-prod.up.railway.app). For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "drift": {
      "command": "uv",
      "args": ["run", "--group", "integrations", "python", "-m", "integrations.mcp"],
      "env": { "DRIFT_API_URL": "http://localhost:8000" }
    }
  }
}

Cursor (.cursor/mcp.json) and other stdio MCP clients use the same command/args/env shape.

Judge testing path (no key, $0): start the fixture API with uv run uvicorn backend.main:app, then in your MCP client run drift_briefing, drift_search for vllm, and ask_drift a GPU/AI-infra release question. ask_drift a question outside the reviewed corpus (e.g. an unrelated library) and watch it decline rather than guess.

MCP is an additional consumption channel, not a repositioning: DRIFT stays release intelligence for GPU and AI infrastructure — cited, bounded, and inspectable. The tools can offer nothing the public API does not; new capability requires a reviewed API change first, never an MCP side door. Hosted MCP evidence and a client screenshot are pending; the deployed app is v0.9.1 (the v0.10.0 source is not yet redeployed).

---

Synthetic Fixture Data

The fixture path uses backend/fixtures/insights.json. These records are committed examples for deterministic development and judging; they are not current release analysis. Each record carries typed claims with frozen example excerpts, offsets, and source hashes, so the Inspect claim evidence panel renders in no-key fixture mode exactly as it does for a reviewed live capture. Each record preserves the contract that the live path must also satisfy:

Field	Purpose
citations	Source URLs supporting the insight
claims	Typed direct_fact / inference / recommended_check statements, each with a frozen example evidence span
confidence	Visible certainty in [0, 1]
model_used	Fixture audit label or exact live model identifier
what_to_check	Bounded engineering action
severity	Review priority, never an automation trigger

---

Project Structure

drift/
├── backend/
│   ├── agents/               # base, scout, synthesizer, insight, briefing stages
│   ├── core/                 # config, model_router, store, live_store, budget, resilience
│   ├── models/schema.py      # Pydantic domain, claim-evidence, and API contracts
│   ├── fixtures/insights.json # deterministic example insights with claim evidence
│   ├── main.py               # FastAPI app: health, briefing, search, chat, /brand
│   ├── pipeline.py           # bounded one-shot live capture CLI (draft-only)
│   ├── review.py             # explicit human publication gate
│   ├── evidence_archive.py   # reviewed-evidence archive + SHA-256 manifest writer
│   └── sources.yaml          # primary release-feed configuration
├── frontend/                 # Next.js + React + TypeScript briefing view
│   ├── app/                  # page.tsx, layout.tsx, AskDrift.tsx (grounded chat box)
│   ├── .nvmrc                # Node.js 24.x local/runtime selection
│   └── vercel.json           # Vercel build settings and Railway API URL
├── integrations/mcp/         # thin-client MCP server (no credentials, stdio) + mocked tests
│   ├── client.py · config.py # one-to-one HTTP wrapper; DRIFT_API_URL only
│   ├── formatting.py · server.py # response formatters + drift_briefing/drift_search/ask_drift
│   └── tests/                # 40 mocked-HTTP tests, 100% integrations coverage
├── assets/
│   ├── architecture/         # arch-* presentation (build_arch.py) + arch-pipeline-* Mermaid
│   ├── brand/                # DRIFT brand banners (build_banner.py); API-served
│   ├── evidence/             # scrubbed hosted-capture records + SHA-256 manifests
│   └── screenshots/          # live-state UI captures used in the README
├── tests/
│   ├── unit/                 # agent, budget, resilience, and configuration tests
│   └── integration/          # API, lifespan, and evidence-boundary tests
├── docs/
│   ├── ARCHITECTURE.md       # runtime and deployment deep dive
│   ├── INITIATIVES.md        # Codex project initiative/session records
│   ├── BUILD_SEQUENCE.md     # implementation sequence and GitHub/Codecov setup
│   ├── RUNBOOK.md · CODEX_PROMPTS.md  # demo procedure and prompt records
│   └── adr/                  # Architecture Decision Records 001–011
├── notebooks/                # local bounded capture/review workflow + results record
├── scripts/                  # check_openai_spend.py (read-only spend reconciliation)
├── migrations/               # Alembic env + versions (schema and provenance revisions)
├── submission/               # Developer Tools handoff, checklist, Devpost, demo script
├── Dockerfile · docker-compose.yml   # Railway image + local API/PostgreSQL/frontend
├── alembic.ini · Makefile · railway.json · codecov.yml  # tooling and deploy config
├── pyproject.toml · uv.lock  # Python project + reproducible dependency lock
├── .gitattributes            # pins evidence JSON to LF for byte-exact manifests
└── .github/workflows/        # CI quality gate and tagged release workflow

---

Production & Quality

push → Ruff → mypy → pytest (100% coverage gate) → Codecov → frontend build → docs hygiene

The current local result is 160 tests passed and 100.00% backend coverage. The enforceable floor is 100% for implemented code, including branch-critical error paths. Explicit, documented live-pipeline boundaries remain visible while the fixture and standalone Insight stages are covered with tests.

Run the gates locally:

uv run ruff check backend tests
uv run mypy backend
uv run pytest tests --cov=backend --cov-report=term-missing --cov-fail-under=100
npm --prefix frontend ci
npm --prefix frontend run build

Pytest writes coverage.xml. CI uploads it with codecov.yml to the repository-specific Codecov report.

Load & Resilience

The live-chat boundary and synchronous capture calls have deterministic budget, retry, circuit, and provider-failure coverage. The initial reviewed PostgreSQL capture and provider-backed hosted /search//chat smoke tests were completed on 2026-07-16; a larger reviewed capture and load testing remain future work before any production-readiness claim.

---

GitHub + Codecov Operations

GitHub main, the Railway API, and the Vercel frontend are published. The two repository-operations steps documented in docs/BUILD_SEQUENCE.md are now complete:

1. the pytest upload is confirmed on Codecov — the repository and flag=pytest coverage badges both resolve to 100%; and
2. main branch protection is enabled, requiring the five CI quality-gate checks (Ruff lint, Mypy type check, Tests and coverage, Frontend build, Documentation hygiene) to pass, with strict up-to-date merges.

The earlier populated v0.5.1 /briefing response was verified on 2026-07-15. On 2026-07-16, hosted v0.6.1 health, /briefing (four reviewed Insights), /docs, Vercel canonical-banner source, CORS, and Railway PostgreSQL migration 0003 were verified, and hosted provider-backed /search//chat were smoke-tested. The API-docs banner frame follows the selected system theme.

---

Future Roadmap

Working locally: a bounded one-shot capture path from primary release feed to frozen claim evidence, separate verification, pgvector embedding, two model-run audit rows, and a human publication gate before live briefing/search/chat retrieval; the fixture demo, evidence UI, typed contracts, model-router boundary, architecture evidence, CI gates, and deployed Vercel frontend.

Shipped as a consumption channel (v0.10.0): a thin-client MCP server (integrations/mcp/, ADR-011) exposing drift_briefing, drift_search, and ask_drift over the existing public API — no credentials, nothing changed under backend/, fixture-verified at $0 with 40 mocked-HTTP tests. See Use DRIFT inside your AI assistant (MCP). It is a channel, not new capability: the tools can offer nothing the public API does not.

Next implementation slices:

• capture bounded hosted MCP evidence (a live-API run archived with a SHA-256 manifest) and add a real MCP-client screenshot; keep the MCP surface a thin channel — any new capability requires a reviewed API change first, never an MCP side door;
• redeploy the v0.10.0 source (the deployed app is v0.9.1) once the hosted MCP evidence is captured;
• expand beyond the initial reviewed capture (the first eight-source run produced six verifier-passed drafts and four reviewed Insights on 2026-07-16);
• exercise the Alembic migration and capture path against a clean PostgreSQL instance, then add a real integration run to delivery verification;
• add scheduled Scout execution only after the reviewed capture path is proven;
• maintain 100% implemented-code coverage as each live stage becomes real;
• schedule a repeatable reviewed-capture cadence (the first reviewed database-backed capture and its hosted search/chat smoke tests are complete);
• record and submit the public narrated demo.

Full decisions and sequencing live in docs/adr/, docs/BUILD_SEQUENCE.md, docs/INITIATIVES.md, and CHANGELOG.md.

---

Trust Model

Release notes are untrusted input, and DRIFT treats them that way. That constraint is the product: it is what makes every answer inspectable instead of a black-box verdict.

• Frozen source span. Every factual claim carries an exact primary-source excerpt with character offsets and a source SHA-256 hash, so reasoning is always traceable back to what the release actually said.
• Separate verifier pass. A second, independently routed model call rejects unsupported or misclassified claims — model-aided screening, not proof.
• Human review gate. Verifier-passed drafts stay private until a person reviews the evidence and records notes; only then can a claim reach /briefing, /search, or /chat.
• Facts kept separate from interpretation. Direct facts, inferences, and recommended checks are labelled distinctly, and confidence plus the model/audit label are always visible.

Because of that boundary, DRIFT deliberately does not certify compatibility, replace upstream release notes, or authorize changes to production infrastructure. Fixture records are synthetic, clearly labelled examples and are never presented as live release analysis. breaking and security are review priorities, not automation triggers.

Built for the OpenAI Build Week 2026 Developer Tools track. Human review remains required for source fidelity, prompt iteration, final examples, and breaking or security-labelled results.

See LICENSE for the MIT license.