4.5 Consumed External-Dependency Contract Ledger

This showcase runs as a plugin on the vendored Atlas stack (infra/ submodule) and calls several external systems as a client. This ledger records each consumed integration point and the exact pinned version its contract was verified against, so a future dependency bump surfaces as a reviewable diff instead of a silent runtime break.

It is a point-in-time audit, not a live check. Re-verify after bumping the infra/ submodule or any pin below.

• Audited: 2026-08-14 (static contracts re-read at the pin below; live-validated behavior — rows marked "verified live" — was confirmed during the most recent live validation run and is re-checked by the result snapshots, not by this static pass)
• Atlas submodule: 7f2fcf2d (v0.1.0-700-g7f2fcf2d), the Atlas main tip that promotes Qwen3.8 as the default content model with scoped think:false request metadata
• Method: contract fields read from the pinned image/source in infra/ and the dependency's tagged source; no live stack required. The unit suite mocks these boundaries, so a green suite is not evidence of conformance. Where a contract test pins a row (noted below), drift fails the suite.

1. Contract Ledger

Integration point	Consumed by	Pinned version (source)	Contract verified	Status
Atlas bootstrapper start.py (click CLI)	scripts/start-all.sh	infra/ @ 7f2fcf2d	The wrapper canonicalizes ATLAS_CONSUMER_MANIFEST and invokes Atlas's native env backfill, manifest-aware compose validate, and doctor --format json; it then starts gen-ai-rag with --consumer … --no-tui --detach. Compute sources are committed in the manifest (profile: dev + env.values: host-adaptive LLM_PROVIDER_SOURCE: auto, LightRAG container, TEI CPU-container, Docling disabled), so the wrapper passes no per-run --*-source flags. Atlas materializes consumer env for preflight (#451), derives dependency enablement (#503), targets enabled services (#504), and classifies zero-exit one-shots (#508). The showcase retains a bounded compatibility convergence check plus a read-only model-readiness probe and a structured adaptive-webhook readiness gate.	conformant
LiteLLM OpenAI API	backend_plugins/rag/common/litellm.py, compare/judge.py, compare/run_matrix.py, atlas.consumer.yml	ghcr.io/berriai/litellm:v1.83.14-stable.patch.2 (services/litellm/compose.yml; STORE_MODEL_IN_DB=True)	Normal routing uses /v1/embeddings → data[].{embedding,index} and /v1/chat/completions → choices[0].message.{content,tool_calls}; top-level think is forwarded to Ollama. Evaluation requests add top-level cache: {no-cache: true, no-store: true} so a renewed corpus run does not reuse stale gateway responses. Model aliases are declared in atlas.consumer.yml (litellm_models) and compiled by Atlas into config.yaml before the proxy boots, so every alias is discoverable in /v1/models at startup with no consumer-side admin-API mutation or restart.	conformant
Weaviate v4 Python client	backend_plugins/rag/common/vectors.py	weaviate-client>=4.9,<5 (backend_plugins/requirements.txt)	connect_to_custom; collections.{exists,create,delete,get}; Configure.Vectorizer.none; query.near_vector; query.hybrid(..., return_metadata=MetadataQuery(score=True)); batch.dynamic() + failed_objects; o.metadata.score / o.properties	conformant
LightRAG server query API	backend_plugins/rag/common/lightrag.py	ghcr.io/hkuds/lightrag:v1.5.4 (services/lightrag/compose.yml, service.yml)	X-API-Key auth (not Authorization: Bearer); /query {mode, enable_rerank, top_k, chunk_top_k, max_total_tokens} with query min_length 3; response field response/data; modes local/hybrid. Document upload and drain are no longer called by showcase code; they belong to the Atlas ingestion job below.	conformant
TEI reranker	backend_plugins/rag/common/vectors.py	ghcr.io/huggingface/text-embeddings-inference:cpu-1.9@sha256:ad950d…fea07 (services/tei-reranker/compose.yml; --max-client-batch-size=32)	POST /rerank {query, texts} → [{index, score}]; the plugin's TEI_RERANKER_MAX_BATCH default (32) matches the server's client-batch cap	conformant
Atlas LightRAG rerank adapter	atlas.consumer.yml, backend_plugins/rag/common/lightrag.py	infra/ @ 7f2fcf2d (services/backend/app/app/lightrag_rerank_adapter.py)	Authenticated POST /lightrag/rerank accepts LightRAG's {query, documents, top_n} contract, forwards TEI {query, texts} batches no larger than TEI_RERANKER_MAX_CLIENT_BATCH_SIZE=32, remaps batch-local indexes globally, applies one total timeout budget, and rejects the whole request if any batch fails. Live validation covered a 43-document request as 32 + 11 batches.	conformant; Atlas #713/#714 verified live
Atlas n8n workflow seeding + n8n webhook	atlas.consumer.yml, n8n/adaptive-rag.workflow.json, backend_plugins/rag/approaches/n8n.py, scripts/start-all.sh	infra/ @ 7f2fcf2d; n8nio/n8n:2.28.2 (services/n8n)	Atlas validates and normalizes the consumer workflow to atlas-consumer-adaptive-rag, imports it idempotently, and probes opt-in POST /webhook/adaptive-rag; the route accepts {query} and returns {answer, route, approach, rag_showcase}. Queue-mode n8n and its worker explicitly allow the runtime-injected LITELLM_API_KEY expression; both HTTP nodes fail the workflow on auth/runtime errors. With N8N_API_KEY unset, Atlas's seed activates the workflow itself — persisting active: true via n8n publish:workflow and restarting n8n once post-seed (Atlas #720) — so the wrapper performs no manual publish or restart and only requires a non-empty answer plus rag_showcase.schema_version == 1 from an allowed delegated approach.	conformant
datasets (Hugging Face)	corpus/fetch_corpus.py	optional import (not pinned)	load_dataset("yixuantt/MultiHopRAG", "corpus", split="train"); guarded try/except → keyword-docs-only fallback	conformant
Atlas Ollama model catalog	backend_plugins/rag/roles.yaml, LiteLLM calls, n8n classifier	infra/ @ 7f2fcf2d (services/ollama/models.yaml)	qwen3.8:latest is Atlas's default 27B multimodal chat model using the ollama_chat adapter with model-scoped request_defaults: {think: false}; nomic-embed-text remains the default 768-dimension embedder. Rag-showcase delegates request defaults to Atlas and does not inject a second local model-parameter layer. LightRAG EXTRACT, KEYWORD, and QUERY are explicitly routed through LiteLLM so all three receive the scoped request default.	conformant
Atlas backend plugin seam + manifest	backend_plugins/rag/__init__.py, backend_plugins/rag/plugin.yml, backend_plugins/requirements.txt, compose/rag-overlay.yml	infra/ @ 7f2fcf2d (services/backend/app/app/plugin_seam.py, bootstrapper/core/plugin_manifest.py, bootstrapper/schemas/plugin.schema.json)	Discovers immediate subdirs of BACKEND_PLUGINS_DIR containing an importable package/router; installs declared dependencies; validates plugin_manifest_version: 1 before import; rejects malformed, duplicate, overlapping, or reserved route roots; validates required/typed env and masks secrets; derives Kong auth. The RAG plugin declares shared /rag, /rag/health, inherited auth, typed env, and LiteLLM/Weaviate/TEI/LightRAG/n8n dependencies. The backend image now creates a writable runtime home/cache for ingestion libraries, so the consumer overlay does not override HOME or XDG_CACHE_HOME (Atlas #602).	conformant (schema and route set pinned by tests/test_plugin_manifest_contract.py and backend_plugins/rag/tests/test_router.py)
Atlas consumer manifest	atlas.consumer.yml, config/atlas.env.user, compose/rag-overlay.yml, backend_plugins/, n8n/	infra/ @ 7f2fcf2d (bootstrapper/core/consumer_manifest.py, start.py --consumer)	The manifest declares project_name, branding, env file, a profile: dev deployment bundle (atlas#755), durable env.values: BASE_PORT: auto, host-adaptive compute sources, Qwen3.8/nomic catalog aliases, and an empty custom-model list that supersedes stale generated selections. It also declares the external Compose overlay, backend plugin root, 19 consumer-owned LiteLLM models, one n8n workflow, eight RAG ingestion profiles, and four Atlas-managed LightRAG query profiles. Qwen3.8 and nomic-embed-text come from Atlas's default catalog, so the showcase no longer declares an Ollama model sidecar.	conformant (contracts pinned by manifest, model, plugin, workflow, and ingestion-profile tests)
Atlas enabled-service build planning	scripts/start-all.sh	infra/ @ 7f2fcf2d; Docker Compose ≥ v2.20.3 (recommended v2.26.0)	Atlas computes the enabled-service target set from the rendered consumer project and passes it to build/up. Disabled asset-baker remains in the assembled graph but is not built or started for gen-ai-rag; the showcase no longer removes it with a Compose reset.	conformant
Atlas local image freshness	scripts/start-all.sh, upgrade troubleshooting	infra/ @ 7f2fcf2d; Docker Compose ≥ v2.20.3 (recommended v2.26.0)	--force-recreate does not rebuild an existing local image after source drift. Upgrade troubleshooting requires a one-time docker compose build backend; automatic drift handling is tracked in Atlas #506.	conformant after documented rebuild
Atlas generic RAG ingestion jobs	atlas.consumer.yml, ingest/atlas_job.py, scripts/start-all.sh, scripts/run-dataset-ladder.py	infra/ @ 7f2fcf2d (bootstrapper/core/consumer_manifest.py, services/backend/app/app/rag_ingestion/, /api/rag/ingestions)	Consumer profiles declare safe mounted corpus paths, parser order, recursive 800/100 chunking, a namespaced Weaviate target, and a required LightRAG target. Atlas mounts generated profile registries under /atlas-consumer-config/ (#533). The headless client submits and polls the durable job through terminal discover/parse/chunk/embed/vector-write/LightRAG-upload/drain/finalize phases. Atlas retries transient LightRAG pipeline_status failures within the profile deadline and records poll/retry evidence (#673), so no consumer drain exists. Durable vector synchronization and recovery come from #674. Matrix, canonical evidence, and judgments carry job id/profile/revision/digest.	conformant; all three measured profiles verified live
Atlas Ragas evaluation API	compare/evaluation.py, compare/evaluation_summary.py	infra/ @ 7f2fcf2d (POST /api/rag/evaluate; ragas==0.4.3)	Requests carry question, answer, contexts, optional ground truth, selected metrics, and evaluator model overrides. Atlas uses the modern collection-metric async scoring API for faithfulness and answer relevancy, keeps one AsyncOpenAI client on one event loop, and closes it before loop teardown. Numeric finite scores and per-metric errors are returned independently; answer relevancy remains eligible for answer-only rows. Atlas #596, #597, and #659 are resolved at this pin.	conformant; live numeric scoring verified
LiteLLM model listing	scripts/start-all.sh (declared-alias verification gate), tests/test_demo_matrix.py	ghcr.io/berriai/litellm:v1.83.14-stable.patch.2	GET /v1/models (Bearer auth) → data[].id; every alias rendered from the consumer manifest must be present, including the four experimental lazy-graph aliases	conformant
Weaviate server	backend_plugins/rag/common/vectors.py (via the v4 client), scripts/start-all.sh	cr.weaviate.io/semitechnologies/weaviate:1.38.2 (infra/.env.example WEAVIATE_IMAGE)	HTTP 8080 + gRPC 50051; hybrid default fusion = relativeScoreFusion (≥1.24); readiness GET /v1/.well-known/ready	conformant
Showcase contextual enrichment	ingest/contextual.py, backend_plugins/rag/common/vectors.py	Local approach-specific post-step over the Atlas Weaviate schema	Reads Atlas content/source/chunkIndex objects from RagBase_<profile>, generates one contextual_blurb per chunk, embeds those enriched chunks, and atomically rebuilds only RagContextual_<profile>. Empty or embedding-count-mismatch inputs fail before deleting the warm contextual collection.	conformant
Atlas manifest env + active .env	atlas.consumer.yml, config/atlas.env.user, scripts/start-all.sh, compare/run_matrix.py, tests/conftest.py	infra/ @ 7f2fcf2d (ATLAS_CONSUMER_MANIFEST, .env.example)	Manifest scalars provide project/branding, model aliases, and compute sources; env.file provides LightRAG role models, bindings, concurrency, timeout, and evaluator defaults. Atlas merges them into its active .env; compose validate materializes Qwen3.8 and clears the retired custom-model selection. Host tools then read generated ports and secrets from that active file.	conformant
MITRE ATT&CK STIX bundle (public)	corpus/adapters/cyber_threat_intel.py	unpinned public raw URL (attack-stix-data master, enterprise bundle)	STIX 2.1 objects[].{type,id,name,description,external_references[].external_id,revoked,x_mitre_deprecated}; relationship {source_ref,target_ref,relationship_type}	conformant
GDELT DOC 2.0 API (public)	corpus/adapters/gdelt_events.py	unpinned public API	mode=artlist&format=json&maxrecords≤250&startdatetime/enddatetime (YYYYMMDDHHMMSS) → articles[].{url,title,domain,seendate,sourcecountry,language}; 200-with-text error bodies handled	conformant
OpenAlex /works API (public)	corpus/adapters/openalex_scholarly.py	unpinned public API	search, per-page≤200, sort=cited_by_count:desc, mailto (polite pool) → results[].{title,display_name,authorships,topics/concepts,abstract_inverted_index,referenced_works,primary_location.source,doi} (topics preferred; concepts frozen upstream)	conformant
STaRK SKB loader (optional)	corpus/adapters/stark_export.py	stark-qa (host-installed, unpinned; guarded ImportError)	load_skb(name, download_processed=True); skb.node_info / skb.candidate_ids	conformant

2. Re-verification

After bumping infra/ or any pin above, re-check each row against the new pinned contract (image tag / submodule SHA / client version bound). Verify against the pinned source, not the repo's own mocks. The most drift-prone rows are:

• LightRAG — field/header renames have occurred between minor versions (e.g. the X-API-Key vs Authorization: Bearer auth scheme, the file_source insert field). A mismatch surfaces as a 401/422 at runtime.
• Atlas start.py flags — a rejected --*-source choice aborts the whole bring-up before anything starts.