Define the chunk, tenant, and embedding data contract

Make malformed input fail before it reaches the interesting algorithm. The accepted contract is chunk IDs, tenant_id, body text, embedding model id, and index_version. This boundary matters because dimension mismatch or cross-tenant retrieval often begins as a value that should never have been accepted. Keep transformation functions separate from scoring, retrieval, training, or generation so a test can identify which boundary changed the data.

Dimension is part of the schema, not a soft hint. all-MiniLM-L6-v2 produces 384 floats; if a future query path silently switches to a 1536-d hosted model, every distance becomes meaningless. Validate length before INSERT and before ORDER BY. Tenant_id must come from the session authority.

The artifact's user-facing goal is specific: return five tenant-scoped chunks for a support question without changing the answer API. Its accepted input is chunk IDs, tenant_id, body text, embedding model id, and index_version. Those statements are intentionally narrower than “build an AI system.” Narrow scope lets us inspect every input and expected result, and it prevents a toy result from being presented as a production claim. System shape for this chapter: an ingestion worker chunks documents, an embedding adapter creates fixed-size vectors, PostgreSQL with pgvector stores vectors plus tenant metadata, and a query service embeds one question, applies an authorization filter, and returns five chunks to the answer layer. Keep model calls behind adapters, keep authorization and validation in deterministic code, and carry stable IDs and versions through every response. That separation lets you decide whether a bad result came from input handling, retrieval, inference, validation, or deployment. This page's job is the data contract step: make malformed input fail before it reaches the interesting algorithm. Setup baseline for the chapter (run once per machine, not secrets in git):

docker run --name rag-pg -e POSTGRES_PASSWORD=rag -p 5432:5432 -d pgvector/pgvector:pg16
python -m venv .venv && source .venv/bin/activate
pip install psycopg[binary] pgvector sentence-transformers

If hardware or a hosted provider differs, preserve the interface and expected behavior. Do not present provider syntax as universal—when a vendor adapter is unavoidable, keep it behind a thin boundary and test with a fake first. The deliverable is not “it ran once”; it is a reproducible artifact another developer can inspect, including expected output and one deliberate failure related to dimension mismatch or cross-tenant retrieval. Operationally, write down the owner of this stage, the command you ran, the observed output, and the next page's dependency on that output. If you cannot point to a file, fixture, metric, or config key, the stage is not done. Prefer small, reviewable increments: one contract, one path, one metric, one failure, one gate. When tradeoffs appear—latency versus quality, hit rate versus false hits, local privacy versus cloud quality—record both numbers instead of moving the threshold until the report looks green. The chapter ships only when evidence for recall@5 ≥ 0.90, zero cross-tenant hits, and p95 query latency under 150 ms and a rehearsed recovery path exist beside pgvector index mini-v1/mini-v2 with HNSW after bulk load and env-based version switch.

Save this as lesson.py and run python3 lesson.py. Prefer the standard library or the pinned packages from the setup block so the example stays reproducible.

def validate_chunk(row):
    assert row["tenant_id"], "tenant_id required"
    assert row["body"].strip(), "body required"
    assert len(row["embedding"])==384, f"expected 384 dimensions, not {len(row["embedding"])}"
    assert row["index_version"].startswith("mini-")
    return row
print(validate_chunk({"tenant_id":"acme","body":"ERR-502 upstream timeout","embedding":[0.0]*384,"index_version":"mini-v1"})["index_version"])

Expected output: mini-v1 after validation succeeds. Exact floating-point formatting may vary slightly, but the asserted behavior must not. Read the output as evidence about this stage, not merely proof that the interpreter started.

Print rejected inputs with the violated field names. Silent coercion is how dimension mismatch or cross-tenant retrieval later looks like a model problem. At the data contract stage, save the smallest failing fixture beside the expected result. Change one cause at a time and rerun the exact command printed above; that makes the repair reviewable and keeps this chapter's progressive artifact reproducible.

Contract tests must run offline without credentials when possible. Quality claims wait for labeled sets. For this data contract page, preserve the fixture and result as evidence for the next page. Label observations separately from conclusions: a passing assertion establishes the behavior it names, while broader usefulness requires the chapter's full evaluation set and stated operating limits. Primary metrics for the chapter remain recall@5 ≥ 0.90, zero cross-tenant hits, and p95 query latency under 150 ms.