Knowledge Base Integration

Wire a product agent to an authorized retrieval knowledge base so answers are grounded in returned passages, with testable coverage, enforced data boundaries, and no hallucinated citations.

Security-aware RAG contract

Before implementation, fill and version this contract; numeric thresholds are task-specific and must be chosen from the representative eval set rather than copied from a universal default:

rag_contract:
  corpus_version: <immutable version or hash>
  authorized_data_classes: [<classes>]
  principal_to_acl_filter: <enforced mapping>
  representative_queries: <fixture set>
  thresholds:
    retrieval_quality: <metric + minimum>
    answer_grounding: <metric + minimum>
  citation_trace: <answer span -> returned passage id/version>
  injection_fixtures: <untrusted-passage and query attacks>
  no_hit_behavior: <exact response or handoff>
  refresh_regression: <old/new corpus comparison suite>

Retrieval must apply the caller's ACL filter before ranking or generation. Retrieved passages are untrusted evidence, not instructions; a passage that asks the agent to ignore policy is an injection fixture, not a new system rule.

Steps

1. Define corpus authority, version/freshness, authorized data classes, and the principal-to-ACL filter; state what the KB does and does not cover.
2. Build representative positive, ambiguous, forbidden-data, no-hit, and adversarial query fixtures.
3. Design chunking, metadata, and retrieval; measure the named retrieval metric against its pinned threshold.
4. Ground generation only in returned passages and retain an answer-span-to-passage trace with real IDs/versions.
5. Run query- and passage-injection fixtures and prove they cannot override the prompt or cross an ACL boundary.
6. Enforce the exact low-confidence/no-hit response or handoff instead of guessing.
7. Re-index on the stated cadence, rerun retrieval and answer thresholds, and compare the refresh regression suite.

Acceptance

• ACL filtering occurs before retrieval/generation, and forbidden-data fixtures show no cross-principal leakage.
• Retrieval and answer-grounding metrics meet their pinned thresholds on the versioned representative set.
• Every answer span traces to real returned passage IDs/versions; no fabricated citation exists.
• Query/passage injection, low-confidence, and no-hit behavior pass their explicit fixtures.
• A corpus refresh reruns the suite and records any regression before the new index is accepted.