Enterprise Advanced RAG · Article 5 of 5

This walkthrough rebuilds the path from raw materials to a working system for: . The focus is operable steps, explicit checks, and code that you can drop into a repo without guessing intent. For the Overview stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

Beyond Top-K: Evidence-Family Retrieval for Complete RAG Answers

When working through the Beyond Top-K Evidence-Family Retrieval stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Measure recall on a fixed question set before tuning prompts. Prompt churn rarely fixes a weak retrieval surface.

Top-K Relevance Is Not Evidence Completeness

When working through the Top-K Relevance Is Not stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest.

Useful context = relevance + required-family coverage + trusted provenance - noise

What Is an Evidence Family?

When working through the What Is an Evidence stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest. When working through the What Is an Evidence stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

Evidence Planning Comes Before Final Selection

The Evidence Planning Comes Before stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Pin dependency versions and record the image digest that ran the demo. Reproducibility beats tribal knowledge.

def evidence_plan(question: str):
    # Returns list of (family_pattern, rescue_query) tuples
    # for recognized composite question shapes
    if asks_about_workload_identity(question):
        return [
            (SECRET_SOURCE_PATTERN,      "Kubernetes Secret credentials Pod"),
            (SERVICE_ACCOUNT_PATTERN,    "Pod ServiceAccount workload identity"),
            (RBAC_SOURCE_PATTERN,        "RBAC least privilege RoleBinding"),
        ]
    return []  # unknown shapes continue through normal retrieval

How Family Membership Is Recognized

The How Family Membership Is stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Pin dependency versions and record the image digest that ran the demo. Reproducibility beats tribal knowledge.

pattern.search(str(chunk.source))

{
  "source": "security-policy.pdf",
  "document_id": "doc-123",
  "chunk_index": 17,
  "evidence_family": "access-control",
  "authority_tier": "official",
  "version": "2026-07"
}

Missing Families Trigger Targeted Rescue

The Missing Families Trigger Targeted stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Pin dependency versions and record the image digest that ran the demo. Reproducibility beats tribal knowledge. The Missing Families Trigger Targeted stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

for family_pattern, rescue_query in plan:
    matches = [c for c in candidates if family_pattern.search(c.source)]

    if len(matches) < desired_candidate_count:
        # Targeted rescue — bounded, not an open retry loop
        rescued = sparse_search(rescue_query, top_k=wide_limit)
        candidates.extend(
            c for c in rescued if family_pattern.search(c.source)
        )

Reranking Chooses the Best Passage, Not the Family

For the Reranking Chooses the Best stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Add a smoke test that exercises the critical path in CI with fixtures, not live paid APIs, whenever budgets allow.

0.4 × normalized cross-encoder score
+ 0.3 × normalized retrieval score
+ 0.3 × lexical overlap
+ conditional exact-token bonus

selected = []

# Step 1: reserve best chunk per required family
for family in required_families:
    best_match = first_ranked_match(family, ranked_chunks)
    if best_match:
        selected.append(best_match)

# Step 2: fill remaining slots by global rank
selected.extend(c for c in ranked_chunks if c not in selected)

final_chunks = selected[:top_k]  # constrained top-k, not an alternative to ranking

Why Same-Source Chunks Sometimes Need to Survive Together

For the Why Same-Source Chunks Sometimes stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Add a smoke test that exercises the critical path in CI with fixtures, not live paid APIs, whenever budgets allow.

Authority and Relevance Are Different Signals

For the Authority and Relevance Are stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Add a smoke test that exercises the critical path in CI with fixtures, not live paid APIs, whenever budgets allow. For the Authority and Relevance Are stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

Relevance:  Does this passage discuss the question?
Authority:  Is this an approved source of truth?
Coverage:   Which required evidence obligation does it satisfy?

CRAG Should Correct Retrieval Without Breaking Coverage

When working through the CRAG Should Correct Retrieval stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Measure recall on a fixed question set before tuning prompts. Prompt churn rarely fixes a weak retrieval surface.

Retrieve broadly
→ shape and rerank candidates
→ reserve family coverage
→ grade evidence (CRAG)
→ restore validated required families
→ build context

A General Architecture for Other RAG Projects

When working through the A General Architecture for stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Measure recall on a fixed question set before tuning prompts. Prompt churn rarely fixes a weak retrieval surface.

The Full Evidence-Family Pipeline

When working through the The Full Evidence-Family Pipeline stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest.

The Pattern Transfers Across Domains

When working through the The Pattern Transfers Across stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest.

Evaluation Must Measure Family Coverage

When working through the Evaluation Must Measure Family stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Measure recall on a fixed question set before tuning prompts. Prompt churn rarely fixes a weak retrieval surface.

Evidence-family recall = covered required families / total required families

# Example: Secret + RBAC covered, ServiceAccount missing
Evidence-family recall = 2/3 = 0.67

# This failure is invisible to standard chunk-relevance metrics

Failure Modes to Expect

When working through the Failure Modes to Expect stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest.

What you Would Improve Next

When working through the What you Would Improve stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Treat effects as synchronization with the outside world, not as a substitute for derived values during render.

Final Takeaway

When working through the Final Takeaway stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments. Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest. When working through the Final Takeaway stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

Project Links

The Project Links stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Pin dependency versions and record the image digest that ran the demo. Reproducibility beats tribal knowledge.

Operational checklist

The Operational checklist stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope.

Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Pin dependency versions and record the image digest that ran the demo. Reproducibility beats tribal knowledge.

Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.

Write a short runbook: how to rotate keys, how to drain the queue, how to roll back the last ingest.

Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion.

Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.

Batch note for 22eaeeb42c59: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.