nomox-semantics 0.1.0__tar.gz

nomox_semantics-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload dist as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nomox_semantics-0.1.0/.gitignore

@@ -0,0 +1,80 @@
+# Byte-compiled / optimised / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+wheels/
+sdist/
+develop-eggs/
+eggs/
+parts/
+var/
+*.egg
+*.egg-info/
+.installed.cfg
+*.whl
+*.tar.gz
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing / coverage
+.pytest_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+nosetests.xml
+.cache
+
+# Type checking / linting caches
+.mypy_cache/
+.pyright_cache/
+.pytype/
+.ruff_cache/
+.dmypy.json
+
+# Documentation
+docs/_build/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# IDE / editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.ropeproject
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Logs
+*.log
+
+# Secrets / local config
+.env
+.env.*
+!.env.example

nomox_semantics-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: nomox-semantics
+Version: 0.1.0
+Summary: Semantic data model for LLM-consumable data catalog - shared contract across Nomox services.
+Author-email: nomox <admin@get-nomox.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Nomox Semantic Model
+
+The shared knowledge contract between every Nomox service. Describes what data exists (physical layer) and what it means (ontology), and ties the two together so an agent can move from a natural-language concept all the way down to a specific column in a specific table.
+
+## Installation
+
+```bash
+pip install git+https://${GITHUB_TOKEN}@github.com/Nomox-ai/semantics-model.git
+```
+
+Pin to a tag for reproducible installs:
+
+```bash
+pip install git+https://${GITHUB_TOKEN}@github.com/Nomox-ai/semantics-model.git@v0.1.0
+```
+
+## Quickstart
+
+```python
+from uuid import uuid4
+from nomox_semantics import (
+    SemanticCatalog, DataSource, SourceType, Table, Column, ColumnDataType,
+    Entity, EntityAttribute, EntityTableMapping, AttributeRole, SemanticType,
+)
+
+# 1. Physical layer — what exists in the database
+src   = DataSource(slug="prod", name="Prod", source_type=SourceType.POSTGRES)
+users = Table(source_id=src.id, schema_name="public", table_name="users")
+ltv   = Column(table_id=users.id, source_id=src.id, column_name="ltv_cents",
+               ordinal_position=1, data_type=ColumnDataType.BIGINT, raw_data_type="bigint")
+
+# 2. Semantic layer — what the data means in business terms
+customer = Entity(
+    slug="customer", name="Customer", plural_name="Customers",
+    aliases=["user", "account holder"],                      # for natural-language matching
+    table_mappings=[EntityTableMapping(table_id=users.id, source_id=src.id)],  # entity -> table
+)
+
+# An EntityAttribute binds a business field to a physical column
+ltv_attr = EntityAttribute(
+    entity_id=customer.id, column_id=ltv.id, source_id=src.id,
+    name="lifetime_value", display_name="Lifetime Value",
+    role=AttributeRole.MEASURE, default_aggregation="SUM",   # tells the query engine it's aggregatable
+    semantic_type=SemanticType.CURRENCY, unit="EUR",         # values are EUR, not raw cents
+)
+
+# 3. Assemble the catalog — the root object every Nomox service consumes
+catalog = SemanticCatalog(organisation_id=uuid4(), name="Acme")
+catalog.sources[src.id] = src
+catalog.tables[users.id] = users
+catalog.columns[ltv.id] = ltv
+catalog.entities[customer.id] = customer
+catalog.attributes[ltv_attr.id] = ltv_attr
+```
+
+## Documentation
+
+See [docs/](docs/) for the full design documentation.

nomox_semantics-0.1.0/README.md

@@ -0,0 +1,58 @@
+# Nomox Semantic Model
+
+The shared knowledge contract between every Nomox service. Describes what data exists (physical layer) and what it means (ontology), and ties the two together so an agent can move from a natural-language concept all the way down to a specific column in a specific table.
+
+## Installation
+
+```bash
+pip install git+https://${GITHUB_TOKEN}@github.com/Nomox-ai/semantics-model.git
+```
+
+Pin to a tag for reproducible installs:
+
+```bash
+pip install git+https://${GITHUB_TOKEN}@github.com/Nomox-ai/semantics-model.git@v0.1.0
+```
+
+## Quickstart
+
+```python
+from uuid import uuid4
+from nomox_semantics import (
+    SemanticCatalog, DataSource, SourceType, Table, Column, ColumnDataType,
+    Entity, EntityAttribute, EntityTableMapping, AttributeRole, SemanticType,
+)
+
+# 1. Physical layer — what exists in the database
+src   = DataSource(slug="prod", name="Prod", source_type=SourceType.POSTGRES)
+users = Table(source_id=src.id, schema_name="public", table_name="users")
+ltv   = Column(table_id=users.id, source_id=src.id, column_name="ltv_cents",
+               ordinal_position=1, data_type=ColumnDataType.BIGINT, raw_data_type="bigint")
+
+# 2. Semantic layer — what the data means in business terms
+customer = Entity(
+    slug="customer", name="Customer", plural_name="Customers",
+    aliases=["user", "account holder"],                      # for natural-language matching
+    table_mappings=[EntityTableMapping(table_id=users.id, source_id=src.id)],  # entity -> table
+)
+
+# An EntityAttribute binds a business field to a physical column
+ltv_attr = EntityAttribute(
+    entity_id=customer.id, column_id=ltv.id, source_id=src.id,
+    name="lifetime_value", display_name="Lifetime Value",
+    role=AttributeRole.MEASURE, default_aggregation="SUM",   # tells the query engine it's aggregatable
+    semantic_type=SemanticType.CURRENCY, unit="EUR",         # values are EUR, not raw cents
+)
+
+# 3. Assemble the catalog — the root object every Nomox service consumes
+catalog = SemanticCatalog(organisation_id=uuid4(), name="Acme")
+catalog.sources[src.id] = src
+catalog.tables[users.id] = users
+catalog.columns[ltv.id] = ltv
+catalog.entities[customer.id] = customer
+catalog.attributes[ltv_attr.id] = ltv_attr
+```
+
+## Documentation
+
+See [docs/](docs/) for the full design documentation.

nomox_semantics-0.1.0/docs/README.md

@@ -0,0 +1,71 @@
+# Nomox Semantic Model — Documentation
+
+The Nomox semantic model is the shared knowledge contract between every Nomox service. It describes **what data exists** (the physical layer) and **what it means** (the ontology), and ties the two together so that an agent answering a business question can move from a natural-language concept all the way down to a specific column in a specific table.
+
+This documentation explains the model, the design decisions behind it, and where it currently has gaps.
+
+## Reading order
+
+1. [usage.md](usage.md) — runnable walkthrough; start here to see the model in action
+2. [overview.md](overview.md) — the two-layer architecture and why it exists
+3. [physical-layer.md](physical-layer.md) — `DataSource`, `Table`, `Column`, foreign keys
+4. [ontology.md](ontology.md) — `BusinessDomain`, `Entity`, `EntityAttribute`, `Relationship`
+5. [linkage.md](linkage.md) — how ontology concepts bind to physical objects
+6. [metrics.md](metrics.md) — first-class business numbers
+7. [queries.md](queries.md) — saved queries and reasoning traces
+8. [glossary.md](glossary.md) — business vocabulary that doesn't fit elsewhere
+9. [catalog.md](catalog.md) — the root `SemanticCatalog` object
+10. [gaps.md](gaps.md) — known limitations and recommended next steps
+
+Runnable examples live in [examples/](../examples/); tests in [tests/](../tests/).
+
+## At a glance
+
+```mermaid
+flowchart TB
+    classDef root fill:#1e293b,stroke:#0f172a,color:#f8fafc;
+    classDef phys fill:#dbeafe,stroke:#1e40af,color:#1e3a8a;
+    classDef sem  fill:#fef3c7,stroke:#92400e,color:#78350f;
+    classDef met  fill:#dcfce7,stroke:#166534,color:#14532d;
+    classDef qry  fill:#ede9fe,stroke:#6d28d9,color:#4c1d95;
+
+    SC[SemanticCatalog<br/>one per organisation]:::root
+
+    subgraph Physical["Physical layer"]
+        direction TB
+        DS[DataSource]:::phys --> T[Table]:::phys --> C[Column]:::phys
+    end
+
+    subgraph Semantic["Semantic layer (ontology)"]
+        direction TB
+        BD[BusinessDomain]:::sem --> E[Entity]:::sem
+        E --> EA[EntityAttribute]:::sem
+        E -. via Relationship .-> E
+    end
+
+    subgraph MetGlos["Metrics &amp; glossary"]
+        direction TB
+        M[Metric]:::met
+        G[GlossaryTerm]:::met
+    end
+
+    subgraph Q["Queries"]
+        direction TB
+        SQ[SavedQuery]:::qry --> QT[QueryTrace]:::qry
+        D[Dashboard]:::qry
+    end
+
+    SC --> Physical
+    SC --> Semantic
+    SC --> MetGlos
+    SC --> Q
+
+    EA -- column_id --> C
+    E  -- table_mappings --> T
+    M  -- column_refs --> C
+    M  -- entities_referenced --> E
+    G  -. related_* .-> E
+    G  -. related_* .-> M
+```
+
+Everything an agent sees — entities, attributes, metrics, glossary terms — ultimately resolves to a column in a real source. The ontology is the **interpretation**; the physical layer is the **substrate**.

nomox_semantics-0.1.0/docs/catalog.md

@@ -0,0 +1,83 @@
+# `SemanticCatalog` — the root object
+
+The `SemanticCatalog` is the root of everything. One catalog per organisation; it holds the complete knowledge graph: physical schema, semantic layer, metrics, glossary, and saved queries.
+
+Source: [src/nomox_semantics/catalog.py](../src/nomox_semantics/catalog.py)
+
+## Shape
+
+```python
+class SemanticCatalog(BaseModel):
+    id: UUID
+    organisation_id: UUID
+    name: str
+
+    # Physical layer
+    sources:    dict[UUID, DataSource]
+    tables:     dict[UUID, Table]
+    columns:    dict[UUID, Column]
+
+    # Semantic layer
+    domains:        dict[UUID, BusinessDomain]
+    entities:       dict[UUID, Entity]
+    attributes:     dict[UUID, EntityAttribute]
+    relationships:  dict[UUID, Relationship]
+    metrics:        dict[UUID, Metric]
+    glossary_terms: dict[UUID, GlossaryTerm]
+
+    # Queries
+    saved_queries: dict[UUID, SavedQuery]
+    dashboards:    dict[UUID, Dashboard]
+```
+
+Everything is keyed by UUID in a flat dict for O(1) lookups. References between objects are always by UUID, never by nested object — this keeps serialisation deterministic and avoids cycles.
+
+## Persistence boundary
+
+The catalog is an **in-memory representation**. Persistence is the Catalog service's responsibility — it stores the catalog in whatever shape its database prefers (typically normalised tables, one per dict). Other services hydrate a `SemanticCatalog` from the Catalog service's API and treat it as read-only or do diffs and submit updates.
+
+## Lookup helpers
+
+The catalog exposes common access patterns as methods so services don't have to scan the dicts directly.
+
+### Physical layer
+
+- `tables_for_source(source_id)` — every table in one source
+- `columns_for_table(table_id)` — columns of one table, sorted by `ordinal_position`
+
+### Semantic layer
+
+- `entity_by_slug(slug)` — `Entity | None`
+- `metric_by_slug(slug)` — `Metric | None`
+- `golden_metrics()` — every `is_golden and not is_deprecated` metric
+- `attributes_for_entity(entity_id)`
+- `relationships_for_entity(entity_id)` — both directions (source or target)
+- `entities_in_domain(domain_id)`
+- `metrics_in_domain(domain_id)`
+
+### Entity hierarchy
+
+- `child_entities(entity_id)` — direct subtypes (entities whose `parent_entity_id` matches)
+- `descendant_entities(entity_id)` — all transitive subtypes, walking the hierarchy
+
+### Glossary
+
+- `glossary_term_by_slug(slug)` — `GlossaryTerm | None`
+- `glossary_terms_in_domain(domain_id)`
+
+### Queries
+
+- `example_queries(limit=20)` — high-quality few-shot examples (`is_example=True`, `SUCCESS`)
+
+## What the catalog does NOT do
+
+- It does not enforce **referential integrity** across objects. Validation that every `EntityAttribute.column_id` points at a real column, that every `EntityTableMapping.table_id` exists, that every `Relationship.via_entity_id` resolves, etc., is the responsibility of the writer (the Semantic Indexer or the BI platform). See [gaps.md](gaps.md) for a `validate()` design.
+- It does not enforce **alias uniqueness**. Two entities can share an alias; consumer code decides how to resolve ambiguity.
+- It does not version itself. There's `updated_at` on individual objects, but no history of changes.
+- It does not persist itself. That's the Catalog service.
+
+`EntityAttribute` does enforce its own internal invariant — the column-XOR-expression rule — via a Pydantic `@model_validator`. That is the only structural validation done in-model.
+
+## Missing helpers worth adding
+
+The lookups above cover the common cases. Reverse lookups (column → entity, column → metrics, metric → saved queries) and alias-aware lookups (`entity_by_alias(name)` etc.) are open work — see [gaps.md](gaps.md) under "Catalog ergonomics."

nomox_semantics-0.1.0/docs/gaps.md

@@ -0,0 +1,122 @@
+# Gap analysis — what's missing
+
+This document tracks what the model currently does not handle. Each item is tagged with severity:
+
+- **🟠 Gap** — meaningful capability missing for the stated goals
+- **🟡 Nice-to-have** — useful but not blocking
+- **✅ Closed** — previously identified gap, now addressed
+
+The bugs section is at the bottom — they're all closed but kept for the record.
+
+---
+
+## ✅ Closed gaps
+
+These were identified in earlier passes and are now implemented.
+
+| Gap | How it's addressed |
+| --- | --- |
+| Synonyms / aliases on entities and attributes | `aliases: list[str]` on `Entity`, `EntityAttribute`, and `Metric` (alongside `Metric.abbreviation` for the single-canonical form). |
+| Entity hierarchy / inheritance | `Entity.parent_entity_id: UUID \| None` for single inheritance, plus `SemanticCatalog.child_entities()` / `descendant_entities()` traversals. |
+| Inverse relationship names | `Relationship.inverse_name: str \| None`. |
+| M:N via associative entity | `Relationship.via_entity_id: UUID \| None` records the join table for M:N relationships. |
+| Computed / derived attributes | `EntityAttribute.expression: str \| None`, with `column_id` and `source_id` now optional. A model validator enforces exactly one of (column-backed, expression). `is_computed` convenience property. |
+| Semantic data type on attributes | New `SemanticType` enum (`CURRENCY`, `PERCENTAGE`, `DURATION`, `COUNT`, `RATIO`, `EMAIL`, `URL`, `PHONE`, `COUNTRY_CODE`, `LATITUDE`, `LONGITUDE`, `IP_ADDRESS`, `OTHER`) on `EntityAttribute`, plus `unit: str \| None`. |
+| Glossary terms link to operationalising concepts | `GlossaryTerm.related_entity_ids` / `related_attribute_ids` / `related_metric_ids`, plus `aliases`. Wired into `SemanticCatalog.glossary_terms` with `glossary_term_by_slug` / `glossary_terms_in_domain` helpers. |
+
+---
+
+## Still open
+
+### 🟡 No quality / freshness metadata on entities and attributes
+
+`DataSource` has `last_synced_at` and `sync_status`, but there's no way to say "the `signup_date` attribute is reliable from 2022 onwards but messy before that" or "this entity is 80% populated." For a system that explicitly tries to avoid hallucination, surfacing data-quality caveats is high-value.
+
+Recommendation: a lightweight `quality_caveat: str` on `Entity` and `EntityAttribute` would do, or a richer `DataQuality` sub-object if there's appetite.
+
+### 🟡 Sample-value cache is capped at 50 known values
+
+`EntityAttribute.known_values` caps at 50. That's fine for low-cardinality dimensions. For medium-cardinality ones (a few hundred to a few thousand — country codes, product SKUs, customer tiers), the cap forces the catalog to either truncate or not record values at all. The query engine then can't resolve user inputs to canonical values.
+
+Recommendation: either raise the cap for confirmed attributes, or store a separate `ValueIndex` per-attribute keyed by source.
+
+### 🟡 No access policies / row-level security model
+
+`Column.is_sensitive: bool` is the only access primitive. There's no notion of "this entity is visible to Sales but not to Engineering," no row-level scoping, no audit hook beyond the saved query trail.
+
+Recommendation: out of scope for v1, but worth a placeholder field (`access_policy_id: UUID | None`) on `Entity`, `EntityAttribute`, and `Metric` so a future policy system can attach without schema churn.
+
+### 🟡 No versioning of definitions
+
+Metric definitions change (the SQL gets refined, filters get added). The current model overwrites in place — `updated_at` records *when* but not *what*. A historical answer in `SavedQuery.result` might no longer match the current metric definition, and there's no way to know.
+
+Recommendation: at minimum, snapshot the metric's `sql_expression` and `base_filters` into the `QueryTrace` at execution time. Long-term, consider a `metric_version` field that increments on definition change.
+
+---
+
+## Catalog ergonomics
+
+Helpers that obvious access patterns will need.
+
+### 🟡 Reverse lookups not provided
+
+- "What entity (if any) owns this column?" — currently requires scanning every `EntityAttribute`.
+- "What metrics reference this column?" — currently requires scanning every `Metric.column_refs`.
+- "What saved queries reference this metric?" — currently requires scanning every `SavedQuery`.
+- "What glossary terms link to this entity?" — same, scan `GlossaryTerm.related_entity_ids`.
+
+These are the natural questions when assessing the blast radius of a schema change. Recommendation: add `entity_for_column(column_id)`, `metrics_for_column(column_id)`, `saved_queries_for_metric(metric_id)`, `glossary_terms_for_entity(entity_id)`.
+
+### 🟡 No alias-aware lookup helpers
+
+Now that `aliases` exists on `Entity`, `EntityAttribute`, and `Metric`, the obvious next step is lookup methods that consult them — `entity_by_alias(name)`, `metric_by_alias(name)`, case-insensitive, matching across slug / name / plural_name / abbreviation / aliases. Without these, every NL-matching consumer rebuilds the same search logic.
+
+### 🟡 No bulk validation pass
+
+The catalog doesn't expose a "validate me" method to check that:
+
+- Every column-backed `EntityAttribute.column_id` resolves and `source_id` matches
+- Every computed `EntityAttribute.expression` parses (best-effort)
+- Every `EntityTableMapping.table_id` resolves
+- Every `Relationship.source/target_attribute_id` resolves and the roles are sensible (FK on source, IDENTIFIER on target)
+- Every `Relationship.via_entity_id` (if set) refers to a real entity, and the relationship is M:N
+- Every `Entity.parent_entity_id` (if set) doesn't introduce a cycle
+- Every `Metric.column_refs[*].column_id` resolves
+- Every `Metric.date_attribute_id` resolves and has `role == TEMPORAL`
+- Every `GlossaryTerm.related_*` id resolves
+
+This would be a single pass returning a list of validation errors and is exactly the kind of safety net a shared contract needs.
+
+---
+
+## Documentation & repository hygiene
+
+All three previously-open hygiene gaps are now closed — kept here as a record of what landed:
+
+- ✅ **`docs/usage.md`** — entry-point quickstart at [docs/usage.md](usage.md).
+- ✅ **`examples/` populated** — three runnable scripts: quickstart, advanced ontology, metrics + queries. See [examples/](../examples/).
+- ✅ **Test suite** — six test files under [tests/](../tests/), 93 tests at ~99% line coverage. Includes round-trip serialisation tests for every model and validator-rejection tests for the column-XOR-expression rule on `EntityAttribute`.
+
+---
+
+## Suggested next steps
+
+1. **Alias-aware lookups** on the catalog — they're now the cheapest way to convert the new `aliases` data into agent value.
+2. **Reverse-lookup helpers** — small surface, large convenience.
+3. **`validate()` pass** — single biggest safety win, especially before the catalog is shared across services.
+4. **Round-trip tests** for every model — protects against future schema drift.
+5. Tackle quality metadata, value-index scaling, access policies, and metric versioning as usage demands them.
+
+---
+
+## ✅ Bugs (resolved, kept for record)
+
+These were live bugs at the start of this work. All five are now closed.
+
+| Bug | Resolution |
+| --- | --- |
+| `__init__.py` imported from non-existent `.models.*` submodules | Imports rewritten to `.physical`, `.semantic`, etc.; package moved to `src/nomox_semantics/`. |
+| `catalog.py` used bare `from metric import …` etc. | Rewritten to relative imports `from .metric import …`. |
+| `pyproject.toml` declared `packages = ["nomox_semantics"]` with no such directory | Package layout moved to `src/nomox_semantics/`; pyproject points at `src/nomox_semantics`. |
+| `GlossaryTerm` defined but not wired up | Exported from `__init__.py`, added as `glossary_terms` field on `SemanticCatalog`, plus lookup helpers. |
+| `datetime.utcnow()` used throughout — deprecated on 3.12+ | Replaced everywhere with `lambda: datetime.now(timezone.utc)`. |

nomox_semantics-0.1.0/docs/glossary.md

@@ -0,0 +1,77 @@
+# Business glossary
+
+The glossary captures internal vocabulary that doesn't map cleanly onto a specific entity, attribute, or metric — just words the company uses that an outsider, a new hire, or an AI agent might not understand.
+
+Source: [src/nomox_semantics/glossary.py](../src/nomox_semantics/glossary.py)
+
+## When to use a glossary term
+
+Use it for **language**, not for **structure**. If the concept can be expressed as an entity, attribute, or metric, model it that way and skip the glossary. Glossary terms are the fallback for things that are real in conversation but don't sit cleanly on the graph — but a term can still *point at* the structural concepts that realise it (see "Linking to the rest of the catalog" below).
+
+Good candidates:
+
+- **"Whale"** — a customer who spends more than €10k/month. Useful as a term, but it's a fuzzy threshold applied across multiple metrics, not an entity in its own right.
+- **"Activation"** — the moment a user completes their first meaningful action. Defined informally; the exact moment may vary across product lines.
+- **"T0"** — the date a contract goes live, used as the reference point for all cohort calculations.
+- **"North Star"** — the team's primary KPI, currently `weekly_active_paid_users` but historically others.
+
+Bad candidates (model these elsewhere):
+
+- "Customer" → that's an `Entity`.
+- "MRR" → that's a `Metric` with `abbreviation="MRR"`.
+- "signup_date" → that's an `EntityAttribute`.
+
+## The shape
+
+```python
+class GlossaryTerm(BaseModel):
+    id: UUID
+    slug: str
+    name: str
+    aliases: list[str]
+    domain_id: UUID | None
+    business_context: str   # what this term means in the company's context
+
+    related_entity_ids: list[UUID]
+    related_attribute_ids: list[UUID]
+    related_metric_ids: list[UUID]
+
+    created_at: datetime
+    updated_at: datetime
+```
+
+A term has:
+
+- A `slug` and human `name`, plus optional `aliases` for near-synonyms
+- An optional `domain_id` to scope it to a `BusinessDomain`
+- A `business_context` narrative — the only required content field
+- Optional `related_*` lists pointing at the structural concepts that operationalise the term
+
+The narrative is the heart of a glossary term. Everything else is navigation.
+
+## Linking to the rest of the catalog
+
+The three `related_*` lists are how a glossary term becomes a navigable connective in the graph rather than a dangling note.
+
+A `"Whale"` term might link to the `Customer` entity and the `monthly_spend` metric:
+
+```python
+GlossaryTerm(
+    slug="whale",
+    name="Whale",
+    business_context="A customer with monthly spend ≥ €10,000. Used in account-tier discussions.",
+    related_entity_ids=[customer.id],
+    related_metric_ids=[monthly_spend_metric.id],
+)
+```
+
+When an agent reads the term, it can follow the links to the `Customer` entity and propose answering "how many whales do we have right now?" by filtering customers on `monthly_spend >= 10000`. Without the links, the term is just text — useful for humans, opaque to the query engine.
+
+Keep the links **descriptive**, not prescriptive. A glossary term saying *"Whale relates to Customer"* doesn't bake a hard SQL rule into the catalog; it just helps agents find the right starting point.
+
+## Wiring
+
+`GlossaryTerm` is exported from the package and stored on `SemanticCatalog.glossary_terms`. Lookup helpers:
+
+- `catalog.glossary_term_by_slug(slug)`
+- `catalog.glossary_terms_in_domain(domain_id)`