Practical notes: Beyond RAG: Why AI Systems Need a Semantic Layer

This walkthrough rebuilds the path from raw materials to a working system for: Beyond RAG: Why AI Systems Need a Semantic Layer. 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. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

RAG Is Powerful — But It Solves Only Part of the Problem

When working through the RAG Is Powerful But 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.

1. Fragmented retrieval

When working through the 1 Fragmented retrieval 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. Measure recall on a fixed question set before tuning prompts. Prompt churn rarely fixes a weak retrieval surface.

Chunk 1: Atlas Enterprise — vendor, category
Chunk 2: Pricing — base fee, usage fee
Chunk 3: Risks — lock-in, migration, data residency

2. No relationship traversal

When working through the 2 No relationship traversal 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. Measure recall on a fixed question set before tuning prompts. Prompt churn rarely fixes a weak retrieval surface. When working through the 2 No relationship traversal 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.

NVIDIA
   ↓ HAS_STRATEGIC_PARTNER
Company
   ↓ HELD_BY
ETF

?nvidia corp:hasStrategicPartner ?company .
?etf etf:hasConstituent ?company .

3. Entity ambiguity

The 3 Entity ambiguity 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. Separate chunking policy from retrieval policy. Changing one should not force a rewrite of the other when quality metrics move.

NVIDIA     → Company
NVIDIA International  → Subsidiary
NVIDIA AI Enterprise    → Product

4. No precise numerical filtering

The 4 No precise numerical 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. Separate chunking policy from retrieval policy. Changing one should not force a rewrite of the other when quality metrics move.

SELECT customer_id
FROM customer_metrics
WHERE annual_revenue > 1000000
  AND churn_probability < 0.05;

One Question Needs Multiple Engines

The One Question Needs Multiple 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. Separate chunking policy from retrieval policy. Changing one should not force a rewrite of the other when quality metrics move. The One Question Needs Multiple 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.

Vector → meaning and unstructured text
BM25   → exact lexical matching
Graph  → relationships and multi-hop traversal
SQL    → filters, numbers and aggregation

The Real Challenges: Decomposition, Routing, and Mapping

For the The Real Challenges Decomposition 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. Cite the passages that actually grounded the answer. Without citations, operators cannot tell hallucination from an indexing gap.

Decomposition

For the Decomposition 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. Cite the passages that actually grounded the answer. Without citations, operators cannot tell hallucination from an indexing gap.

1. Resolve NVIDIA as a Company
2. Find its strategic partners
3. Find ETFs holding those companies
4. Filter AUM > $1B
5. Retrieve the latest research reports
6. Identify positive views

Routing

For the Routing 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. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph. Cite the passages that actually grounded the answer. Without citations, operators cannot tell hallucination from an indexing gap. For the Routing 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.

relationships → Graph
AUM           → SQL
research view → Vector Search

Mapping

When working through the Mapping 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.

NET_ASSET_AMT
AUM_USD
FUND_NET_ASSET

Enter the Semantic Layer

When working through the Enter the Semantic Layer 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. Measure recall on a fixed question set before tuning prompts. Prompt churn rarely fixes a weak retrieval surface.

Company
Strategic Partner
ETF
Constituent
Assets Under Management
Research Report

Assets Under Management
 ├─ business definition
 ├─ currency / unit
 ├─ effective date
 ├─ authoritative source
 └─ physical column

What does this look like in practice?

When working through the What does this look 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. Measure recall on a fixed question set before tuning prompts. Prompt churn rarely fixes a weak retrieval surface. When working through the What does this look 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.

semantic_layer/
├── ontology/
│   ├── tbox.ttl              # classes and relationships
│   └── vocabulary.yaml       # business terms and synonyms
├── schemas/
│   ├── rdb.yaml              # tables, columns, types
│   ├── graph.yaml            # entities, predicates, graph paths
│   └── vector.yaml           # indexes and document metadata
├── semantics/
│   ├── metrics.yaml          # governed metrics such as AUM
│   ├── mappings.yaml         # concept → physical source mapping
│   └── relationships.yaml    # cross-domain relationships
├── query/
│   ├── routing.yaml          # Graph vs SQL vs Vector routing
│   └── examples.yaml         # representative query plans
└── validation/
    └── rules.yaml            # allowed fields and business rules

From Semantic Layer to Semantic Runtime

The From Semantic Layer to 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. Separate chunking policy from retrieval policy. Changing one should not force a rewrite of the other when quality metrics move.

User → LLM → Tools

User
 ↓
Semantic Resolution
 ↓
Logical Query Plan
 ↓
Validated Execution
 ↓
Evidence
 ↓
LLM

Why Open Semantic Interchange Matters

The Why Open Semantic Interchange 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. Separate chunking policy from retrieval policy. Changing one should not force a rewrite of the other when quality metrics move.

version: "0.2.0.dev0"
semantic_model:
  - name: investment_products
    datasets:
      - name: etf
        source: analytics.dim_etf
        fields:
          - name: aum
            datatype: Decimal
            ai_context:
              synonyms: ["assets under management", "net assets"]
    metrics:
      - name: total_aum
        expression:
          dialects:
            - dialect: ANSI_SQL
              expression: SUM(etf.aum)

┌→ BI
                  ├→ Analytics
Semantic Model ───┼→ AI Agents
                  ├→ Data Catalogs
                  └→ Data Applications

Customer is an Organization
Company HAS_SUBSIDIARY Company
Company OWNS_PRODUCT Product
Document DESCRIBES Entity

Putting It All Together

The Putting It All Together 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. Separate chunking policy from retrieval policy. Changing one should not force a rewrite of the other when quality metrics move. The Putting It All Together 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.

The Bigger Shift

For the The Bigger Shift 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. Cite the passages that actually grounded the answer. Without citations, operators cannot tell hallucination from an indexing gap.

LLM + Prompt
     ↓
LLM + RAG
     ↓
LLM + Tools
     ↓
LLM + Federated Data
     ↓
Semantic Layer + Federated Execution + LLM

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.

Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish.

Separate chunking policy from retrieval policy. Changing one should not force a rewrite of the other when quality metrics move.

Add a smoke test that exercises the critical path in CI with fixtures, not live paid APIs, whenever budgets allow.

Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline.

Separate chunking policy from retrieval policy. Changing one should not force a rewrite of the other when quality metrics move.

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 9b6fa92e9bf6: 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.