nomox-semantics 0.1.0__py3-none-any.whl

nomox_semantics/__init__.py

@@ -0,0 +1,89 @@
+"""
+nomox_semantics — the Nomox knowledge model.
+
+Defines everything the system can express about a company's data.
+This package is the shared contract between all Nomox microservices.
+
+Physical layer (what exists):     DataSource, Table, Column
+Semantic layer (what it means):   BusinessDomain, Entity, EntityAttribute, Relationship
+Metrics (authoritative numbers):  Metric
+Glossary (business vocabulary):   GlossaryTerm
+Queries (stored answers):         SavedQuery, QueryTrace, Dashboard
+Root:                             SemanticCatalog
+"""
+
+from .catalog import SemanticCatalog
+from .glossary import GlossaryTerm
+from .metric import (
+    GranularityHint,
+    Metric,
+    MetricColumnRef,
+    MetricFilter,
+    MetricFormat,
+    MetricType,
+)
+from .physical import (
+    Column,
+    ColumnDataType,
+    DataSource,
+    ForeignKeyRef,
+    SourceType,
+    SyncStatus,
+    Table,
+)
+from .query import (
+    Dashboard,
+    QueryOrigin,
+    QueryResult,
+    QueryStatus,
+    QueryTrace,
+    QueryTraceStep,
+    SavedQuery,
+)
+from .semantic import (
+    AttributeRole,
+    BusinessDomain,
+    Entity,
+    EntityAttribute,
+    EntityTableMapping,
+    Relationship,
+    RelationshipCardinality,
+    RelationshipDiscovery,
+    SemanticType,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DataSource",
+    "SourceType",
+    "SyncStatus",
+    "Table",
+    "Column",
+    "ColumnDataType",
+    "ForeignKeyRef",
+    "BusinessDomain",
+    "Entity",
+    "EntityTableMapping",
+    "EntityAttribute",
+    "AttributeRole",
+    "SemanticType",
+    "Relationship",
+    "RelationshipCardinality",
+    "RelationshipDiscovery",
+    "Metric",
+    "MetricType",
+    "MetricFormat",
+    "GranularityHint",
+    "MetricFilter",
+    "MetricColumnRef",
+    "GlossaryTerm",
+    "SavedQuery",
+    "QueryStatus",
+    "QueryOrigin",
+    "QueryTrace",
+    "QueryTraceStep",
+    "QueryResult",
+    "Dashboard",
+    "SemanticCatalog",
+]

nomox_semantics/catalog.py

@@ -0,0 +1,126 @@
+"""
+SemanticCatalog — the root object of the Nomox ontology.
+
+One catalog per organisation. It holds the complete knowledge graph:
+physical schema, semantic layer, metrics, and saved queries. This is
+what the Catalog service persists, the Semantic Indexer writes to,
+and every other service reads from.
+
+In-memory representation: dict-keyed by UUID for O(1) lookups.
+Persistence is the Catalog service's responsibility.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+from .glossary import GlossaryTerm
+from .metric import Metric
+from .physical import Column, DataSource, Table
+from .query import Dashboard, QueryStatus, SavedQuery
+from .semantic import BusinessDomain, Entity, EntityAttribute, Relationship
+
+
+class SemanticCatalog(BaseModel):
+    """
+    The complete knowledge graph for one organisation.
+
+    Lookup helpers are provided for the most common access patterns.
+    Services should use these rather than scanning the dicts directly.
+    """
+
+    id: UUID = Field(default_factory=uuid4)
+    organisation_id: UUID
+    name: str
+
+    # Physical layer
+    sources: dict[UUID, DataSource] = Field(default_factory=dict)
+    tables: dict[UUID, Table] = Field(default_factory=dict)
+    columns: dict[UUID, Column] = Field(default_factory=dict)
+
+    # Semantic layer
+    domains: dict[UUID, BusinessDomain] = Field(default_factory=dict)
+    entities: dict[UUID, Entity] = Field(default_factory=dict)
+    attributes: dict[UUID, EntityAttribute] = Field(default_factory=dict)
+    relationships: dict[UUID, Relationship] = Field(default_factory=dict)
+    metrics: dict[UUID, Metric] = Field(default_factory=dict)
+    glossary_terms: dict[UUID, GlossaryTerm] = Field(default_factory=dict)
+
+    # Queries
+    saved_queries: dict[UUID, SavedQuery] = Field(default_factory=dict)
+    dashboards: dict[UUID, Dashboard] = Field(default_factory=dict)
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    # ------------------------------------------------------------------ #
+    # Physical layer helpers
+    # ------------------------------------------------------------------ #
+
+    def tables_for_source(self, source_id: UUID) -> list[Table]:
+        return [t for t in self.tables.values() if t.source_id == source_id]
+
+    def columns_for_table(self, table_id: UUID) -> list[Column]:
+        return sorted(
+            [c for c in self.columns.values() if c.table_id == table_id],
+            key=lambda c: c.ordinal_position,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Semantic layer helpers
+    # ------------------------------------------------------------------ #
+
+    def entity_by_slug(self, slug: str) -> Entity | None:
+        return next((e for e in self.entities.values() if e.slug == slug), None)
+
+    def metric_by_slug(self, slug: str) -> Metric | None:
+        return next((m for m in self.metrics.values() if m.slug == slug), None)
+
+    def golden_metrics(self) -> list[Metric]:
+        return [m for m in self.metrics.values() if m.is_golden and not m.is_deprecated]
+
+    def attributes_for_entity(self, entity_id: UUID) -> list[EntityAttribute]:
+        return [a for a in self.attributes.values() if a.entity_id == entity_id]
+
+    def relationships_for_entity(self, entity_id: UUID) -> list[Relationship]:
+        """All relationships where this entity appears as source or target."""
+        return [
+            r for r in self.relationships.values() if r.source_entity_id == entity_id or r.target_entity_id == entity_id
+        ]
+
+    def entities_in_domain(self, domain_id: UUID) -> list[Entity]:
+        return [e for e in self.entities.values() if e.domain_id == domain_id]
+
+    def child_entities(self, entity_id: UUID) -> list[Entity]:
+        """Direct subtypes of an entity (entities with parent_entity_id == entity_id)."""
+        return [e for e in self.entities.values() if e.parent_entity_id == entity_id]
+
+    def descendant_entities(self, entity_id: UUID) -> list[Entity]:
+        """All transitive subtypes of an entity."""
+        out: list[Entity] = []
+        stack = [entity_id]
+        while stack:
+            current = stack.pop()
+            for child in self.child_entities(current):
+                out.append(child)
+                stack.append(child.id)
+        return out
+
+    def metrics_in_domain(self, domain_id: UUID) -> list[Metric]:
+        return [m for m in self.metrics.values() if m.domain_id == domain_id]
+
+    def glossary_term_by_slug(self, slug: str) -> GlossaryTerm | None:
+        return next((t for t in self.glossary_terms.values() if t.slug == slug), None)
+
+    def glossary_terms_in_domain(self, domain_id: UUID) -> list[GlossaryTerm]:
+        return [t for t in self.glossary_terms.values() if t.domain_id == domain_id]
+
+    # ------------------------------------------------------------------ #
+    # Query helpers
+    # ------------------------------------------------------------------ #
+
+    def example_queries(self, limit: int = 20) -> list[SavedQuery]:
+        return [q for q in self.saved_queries.values() if q.is_example and q.status == QueryStatus.SUCCESS][:limit]

nomox_semantics/glossary.py

@@ -0,0 +1,53 @@
+"""
+Business glossary — internal terms and the context behind them.
+
+A glossary term is for vocabulary that doesn't map to a specific entity,
+attribute, or metric — just words the company uses that an outsider
+(or a new hire, or an AI agent) might not understand.
+
+Examples:
+  "Whale"      — a customer who spends more than €10k/month
+  "Activation" — the moment a user completes their first meaningful action
+  "T0"         — the date a contract goes live, used as the reference
+                 point for all cohort calculations
+
+Glossary terms can optionally point at the entities, attributes, and metrics
+that operationalise them, so agents can follow the link from the conversational
+term to the data that realises it.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class GlossaryTerm(BaseModel):
+    id: UUID = Field(default_factory=uuid4)
+    slug: str
+    name: str
+    aliases: list[str] = Field(
+        default_factory=list,
+        description="Alternative spellings or near-synonyms used for this term in conversation.",
+    )
+    domain_id: UUID | None = None
+    business_context: str = Field(description="What this term means in the company's context.")
+
+    # Linkage to the rest of the ontology. Optional — glossary terms can stand alone.
+    related_entity_ids: list[UUID] = Field(
+        default_factory=list,
+        description="Entities that operationalise or are referenced by this term.",
+    )
+    related_attribute_ids: list[UUID] = Field(
+        default_factory=list,
+        description="EntityAttributes that operationalise or are referenced by this term.",
+    )
+    related_metric_ids: list[UUID] = Field(
+        default_factory=list,
+        description="Metrics that operationalise or are referenced by this term.",
+    )
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

nomox_semantics/metric.py

@@ -0,0 +1,176 @@
+"""
+Metric — a named, reusable business computation.
+
+Metrics are first-class citizens in the ontology, not just annotated columns.
+They encode the authoritative definition of a business number: what it counts,
+which filters always apply, how it should be displayed, and — crucially —
+what it does NOT include. That last part lives in `business_context` and
+is the primary defence against AI hallucination.
+
+Golden metrics (is_golden=True) are the single company-wide definition for
+a concept. The query engine and agents always prefer a golden metric over
+an ad-hoc column aggregation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class MetricType(str, Enum):
+    """
+    Classification of how the metric is computed.
+    Drives SQL construction in the query engine.
+    """
+
+    SIMPLE = "simple"  # SUM/COUNT/AVG of a single column
+    RATIO = "ratio"  # numerator / denominator
+    CUMULATIVE = "cumulative"  # running total over time
+    PERIOD_OVER_PERIOD = "period_over_period"  # WoW, MoM, YoY
+    DERIVED = "derived"  # computed from other metrics
+    FUNNEL = "funnel"  # multi-step conversion
+    CUSTOM = "custom"  # free-form SQL expression
+
+
+class MetricFormat(str, Enum):
+    """Display format hint for UI and agent responses."""
+
+    NUMBER = "number"
+    CURRENCY = "currency"
+    PERCENTAGE = "percentage"
+    DURATION = "duration"
+    RATIO = "ratio"
+
+
+class GranularityHint(str, Enum):
+    """Finest meaningful time granularity for this metric."""
+
+    HOUR = "hour"
+    DAY = "day"
+    WEEK = "week"
+    MONTH = "month"
+    QUARTER = "quarter"
+    YEAR = "year"
+    NONE = "none"  # metric is not time-series meaningful
+
+
+class MetricFilter(BaseModel):
+    """
+    A named, always-applied filter baked into a metric definition.
+
+    Example: 'Active Customers' always has status = 'active'.
+    The query engine resolves `attribute_id` to a real column reference.
+    """
+
+    attribute_id: UUID
+    operator: str = Field(description="SQL operator: '=', '!=', 'IN', '>', '<', 'LIKE', etc.")
+    value: str | list[str]
+    description: str = ""
+
+
+class MetricColumnRef(BaseModel):
+    """Granular lineage: which physical column feeds this metric."""
+
+    source_id: UUID
+    table_id: UUID
+    column_id: UUID
+    role: str = Field(description="How this column is used: 'numerator', 'denominator', 'dimension', 'filter', 'date'.")
+
+
+class Metric(BaseModel):
+    """
+    A named, reusable business metric.
+
+    The sql_expression is parameterised using {source_slug.schema.table.column}
+    placeholders. The query engine resolves these to actual qualified names at
+    runtime, applying the correct dialect.
+
+    Example:
+        sql_expression = "SUM({prod-postgres.public.orders.amount_cents}) / 100.0"
+
+    For RATIO metrics, use numerator_expression + denominator_expression instead.
+
+    The business_context field is as important as the SQL:
+        "Use for top-line revenue reporting. Does NOT include pending or
+         cancelled orders. For refund-adjusted revenue, use net_revenue_eur."
+
+    This narrative is what agents read to decide WHICH metric to use — and
+    to avoid confidently computing the wrong thing.
+    """
+
+    id: UUID = Field(default_factory=uuid4)
+    slug: str
+    name: str
+    abbreviation: str | None = Field(
+        default=None,
+        description="Single canonical short form, e.g. 'MRR'. Use `aliases` for additional synonyms.",
+    )
+    aliases: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Alternative names used in conversation that should resolve to this metric, e.g. "
+            "['monthly recurring', 'subscription revenue'] for MRR."
+        ),
+    )
+    domain_id: UUID | None = None
+
+    metric_type: MetricType = MetricType.SIMPLE
+
+    # SQL expression — parameterised, dialect-neutral
+    sql_expression: str
+    numerator_expression: str | None = None  # RATIO metrics
+    denominator_expression: str | None = None  # RATIO metrics
+
+    base_filters: list[MetricFilter] = Field(default_factory=list)
+
+    description_auto: str = ""
+    description_human: str = ""
+    business_context: str = Field(
+        default="",
+        description=(
+            "Narrative for agents: what this metric measures, what it does NOT include, "
+            "common misinterpretations to avoid. This is the hallucination guard."
+        ),
+    )
+
+    format: MetricFormat = MetricFormat.NUMBER
+    unit: str | None = Field(default=None, description="E.g. 'EUR', '%', 'days'.")
+    decimal_places: int = Field(default=2, ge=0)
+
+    granularity_hint: GranularityHint = GranularityHint.DAY
+    date_attribute_id: UUID | None = Field(
+        default=None,
+        description="The EntityAttribute used for time-axis slicing (role must be TEMPORAL).",
+    )
+
+    # Lineage
+    entities_referenced: list[UUID] = Field(default_factory=list)
+    column_refs: list[MetricColumnRef] = Field(default_factory=list)
+    derived_from_metric_ids: list[UUID] = Field(
+        default_factory=list,
+        description="For DERIVED metrics: parent metric IDs.",
+    )
+
+    is_golden: bool = Field(
+        default=False,
+        description=(
+            "Golden metrics are the single authoritative definition for this concept. "
+            "Agents and the query engine prefer them over ad-hoc aggregations."
+        ),
+    )
+    is_confirmed: bool = False
+    is_deprecated: bool = False
+    deprecation_note: str | None = None
+    superseded_by_metric_id: UUID | None = None
+
+    tags: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @property
+    def description(self) -> str:
+        return self.description_human or self.description_auto

nomox_semantics/physical.py

@@ -0,0 +1,175 @@
+"""
+Physical layer — raw schema objects discovered from connected data sources.
+
+These represent what physically exists: where data lives and what shape it has.
+The semantic layer maps business meaning on top of these.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class SourceType(str, Enum):
+    POSTGRES    = "postgres"
+    MYSQL       = "mysql"
+    SQLITE      = "sqlite"
+    BIGQUERY    = "bigquery"
+    SNOWFLAKE   = "snowflake"
+    REDSHIFT    = "redshift"
+    TRINO       = "trino"
+    EXCEL       = "excel"
+    GOOGLE_SHEETS = "google_sheets"
+    CSV         = "csv"
+    REST_API    = "rest_api"
+
+
+class ColumnDataType(str, Enum):
+    INTEGER     = "integer"
+    BIGINT      = "bigint"
+    FLOAT       = "float"
+    DECIMAL     = "decimal"
+    BOOLEAN     = "boolean"
+    VARCHAR     = "varchar"
+    TEXT        = "text"
+    UUID        = "uuid"
+    DATE        = "date"
+    TIMESTAMP   = "timestamp"
+    TIMESTAMP_TZ = "timestamp_tz"
+    JSON        = "json"
+    ARRAY       = "array"
+    OTHER       = "other"
+
+
+class SyncStatus(str, Enum):
+    PENDING     = "pending"
+    IN_PROGRESS = "in_progress"
+    SUCCESS     = "success"
+    FAILED      = "failed"
+    STALE       = "stale"
+
+
+class DataSource(BaseModel):
+    """
+    A connected external data source — a database, spreadsheet, or warehouse.
+
+    Credentials are NOT stored here; they live in a secrets manager.
+    This model holds only structural and descriptive metadata.
+    """
+    id: UUID = Field(default_factory=uuid4)
+    slug: str = Field(description="URL-safe unique identifier, e.g. 'prod-postgres'.")
+    name: str
+    source_type: SourceType
+    description: str = ""
+
+    # Non-sensitive connector parameters (host, port, database name, sheet ID, etc.)
+    connector_config: dict[str, Any] = Field(default_factory=dict)
+
+    last_synced_at: datetime | None = None
+    sync_status: SyncStatus = SyncStatus.PENDING
+    sync_error: str | None = None
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class Table(BaseModel):
+    """
+    A table, view, or sheet within a DataSource.
+
+    `schema_name` is empty for flat sources (Excel, CSV).
+    """
+    id: UUID = Field(default_factory=uuid4)
+    source_id: UUID
+    schema_name: str = ""
+    table_name: str
+    is_view: bool = False
+
+    row_count_estimate: int | None = None
+    size_bytes: int | None = None
+
+    # Dual-field description pattern used throughout:
+    # _auto is LLM-generated; _human is the authoritative human override.
+    description_auto: str = ""
+    description_human: str = ""
+
+    is_staging: bool = Field(
+        default=False,
+        description="Marks raw/staging tables not intended for direct querying.",
+    )
+    tags: list[str] = Field(default_factory=list)
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @property
+    def fully_qualified_name(self) -> str:
+        return f"{self.schema_name}.{self.table_name}" if self.schema_name else self.table_name
+
+    @property
+    def description(self) -> str:
+        return self.description_human or self.description_auto
+
+
+class ForeignKeyRef(BaseModel):
+    """A declared or inferred foreign key reference to another column."""
+    target_table_id: UUID
+    target_column_id: UUID
+    is_inferred: bool = Field(
+        default=False,
+        description="True when discovered by heuristics, not declared in the schema.",
+    )
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+
+
+class Column(BaseModel):
+    """
+    A column or field within a Table.
+
+    Stores raw schema metadata and the enriched semantic metadata added
+    during catalog building (descriptions, sample values, sensitivity flags).
+    """
+    id: UUID = Field(default_factory=uuid4)
+    table_id: UUID
+    source_id: UUID  # denormalised for efficient filtering
+
+    column_name: str
+    ordinal_position: int
+    data_type: ColumnDataType
+    raw_data_type: str = Field(description="Original type string from the source, e.g. 'character varying(255)'.")
+
+    is_nullable: bool = True
+    is_primary_key: bool = False
+    is_unique: bool = False
+
+    foreign_key_refs: list[ForeignKeyRef] = Field(default_factory=list)
+
+    description_auto: str = ""
+    description_human: str = ""
+
+    sample_values: list[str] = Field(
+        default_factory=list,
+        max_length=10,
+        description="Representative sample values used during semantic enrichment.",
+    )
+
+    # Heuristic flags set by the DAL during discovery
+    is_temporal: bool = False
+    is_identifier: bool = False
+    is_sensitive: bool = Field(
+        default=False,
+        description="PII or otherwise sensitive — suppressed from agent context.",
+    )
+    tags: list[str] = Field(default_factory=list)
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @property
+    def description(self) -> str:
+        return self.description_human or self.description_auto

nomox_semantics/query.py

@@ -0,0 +1,188 @@
+"""
+Query models — saved queries and their execution traces.
+
+Every answer Nomox produces is a persisted object: the natural language
+question, the SQL generated, the reasoning trace, and the result.
+
+The trace is the trust mechanism. It lets non-technical users verify
+answers and lets analysts build on them. It's also the few-shot corpus
+the query engine learns from: SavedQuery.is_example=True marks a query
+as a high-quality example for future SQL generation.
+
+Dashboards are named collections of pinned SavedQueries.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class QueryStatus(str, Enum):
+    PENDING     = "pending"
+    RUNNING     = "running"
+    SUCCESS     = "success"
+    PARTIAL     = "partial"       # returned results but with caveats
+    FAILED      = "failed"
+    UNSUPPORTED = "unsupported"   # question outside the catalog's scope
+    AMBIGUOUS   = "ambiguous"     # question needs clarification before answering
+
+
+class QueryOrigin(str, Enum):
+    BI_PLATFORM = "bi_platform"
+    MCP_SERVER  = "mcp_server"
+    API         = "api"
+    DASHBOARD   = "dashboard"     # scheduled refresh
+    SYSTEM      = "system"        # internal catalog-building query
+
+
+class QueryTraceStep(BaseModel):
+    """
+    One reasoning step in the chain from natural language to SQL.
+
+    Each step has a SQL fragment and a plain-English explanation of why
+    it was written. Together they form a transparent, inspectable audit
+    trail — "reading a clear explanation from a colleague, not a black box."
+    """
+    step_number: int
+    title: str = Field(description="Short label, e.g. 'Filter by date range'.")
+    sql_fragment: str
+    explanation: str = Field(description="Plain English: what this step does and why.")
+
+    # Catalog objects referenced in this step (for lineage and analytics)
+    entities_used: list[UUID] = Field(default_factory=list)
+    attributes_used: list[UUID] = Field(default_factory=list)
+    metrics_used: list[UUID] = Field(default_factory=list)
+    relationships_used: list[UUID] = Field(default_factory=list)
+
+
+class QueryTrace(BaseModel):
+    """
+    Full reasoning trace for a query execution.
+
+    Contains ordered steps, the final assembled SQL, and aggregate lineage.
+    This is the artifact that agents expose and humans inspect.
+    """
+    steps: list[QueryTraceStep] = Field(default_factory=list)
+    final_sql: str
+    sql_dialect: str = Field(
+        default="ansi",
+        description="SQL dialect the query was generated for.",
+    )
+
+    # Aggregate lineage across all steps
+    entities_used: list[UUID] = Field(default_factory=list)
+    attributes_used: list[UUID] = Field(default_factory=list)
+    metrics_used: list[UUID] = Field(default_factory=list)
+    sources_queried: list[UUID] = Field(default_factory=list)
+
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+    caveats: list[str] = Field(
+        default_factory=list,
+        description="Warnings or assumptions the user should be aware of.",
+    )
+    ambiguities_resolved: list[str] = Field(
+        default_factory=list,
+        description="Ambiguous terms encountered and how they were resolved.",
+    )
+
+
+class QueryResult(BaseModel):
+    """
+    The output of executing a query.
+
+    Full result sets are streamed to the client and not persisted.
+    We store the schema and a row sample for re-display without re-execution.
+    """
+    columns: list[str]
+    row_count: int
+    row_sample: list[list[Any]] = Field(
+        default_factory=list,
+        max_length=100,
+        description="Up to 100 rows stored for fast re-display.",
+    )
+    suggested_chart_type: str | None = Field(
+        default=None,
+        description="Suggested visualisation: 'bar', 'line', 'table', 'metric', 'pie'.",
+    )
+    x_axis_column: str | None = None
+    y_axis_columns: list[str] = Field(default_factory=list)
+
+
+class SavedQuery(BaseModel):
+    """
+    A persisted query — the combination of question, SQL, trace, and result.
+
+    Saved queries serve multiple purposes:
+      - Re-execution without re-reasoning (fast dashboard refreshes)
+      - Few-shot SQL examples for the query engine (is_example=True)
+      - Audit trail
+      - Usage analytics (which entities and metrics are most queried)
+    """
+    id: UUID = Field(default_factory=uuid4)
+
+    natural_language: str = Field(description="The original question, verbatim.")
+    canonical_question: str = Field(
+        default="",
+        description="Normalised form for similarity matching.",
+    )
+
+    status: QueryStatus = QueryStatus.PENDING
+    origin: QueryOrigin = QueryOrigin.BI_PLATFORM
+
+    trace: QueryTrace | None = None
+    result: QueryResult | None = None
+    error_message: str | None = None
+
+    # Catalog objects this query is about (derived from trace)
+    entities_referenced: list[UUID] = Field(default_factory=list)
+    metrics_referenced: list[UUID] = Field(default_factory=list)
+    domain_ids: list[UUID] = Field(default_factory=list)
+
+    created_by: str | None = None
+    session_id: str | None = None
+
+    is_pinned: bool = Field(default=False, description="Pinned queries appear in the catalog UI.")
+    is_example: bool = Field(
+        default=False,
+        description="High-quality example for few-shot SQL generation.",
+    )
+    title: str | None = None
+    description: str = ""
+
+    execution_time_ms: int | None = None
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    last_executed_at: datetime | None = None
+
+
+class Dashboard(BaseModel):
+    """
+    A named, shareable collection of pinned SavedQueries.
+
+    Each panel in the dashboard is a SavedQuery. Layout and per-panel
+    visualisation config are stored in panel_layout.
+    """
+    id: UUID = Field(default_factory=uuid4)
+    slug: str
+    name: str
+    description: str = ""
+    domain_id: UUID | None = None
+
+    query_ids: list[UUID] = Field(default_factory=list)
+    panel_layout: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="UI layout per panel: {query_id, x, y, w, h, chart_type}.",
+    )
+
+    refresh_interval_minutes: int | None = None
+    created_by: str | None = None
+    is_public: bool = False
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

nomox_semantics/semantic.py

@@ -0,0 +1,338 @@
+"""
+Semantic layer — business meaning mapped over the physical layer.
+
+This is where raw tables and columns become Customers, Orders, Revenue,
+and the relationships between them. The ontology lives here.
+
+Three concepts form the core:
+  Entity      — a named business concept (Customer, Order, Product)
+  EntityAttribute — a meaningful field on an entity (plan_type, created_at)
+  Relationship — a link between two entities (Order → Customer)
+
+BusinessDomain groups them for navigation and scoping.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class BusinessDomain(BaseModel):
+    """
+    A top-level business domain used to classify entities and metrics.
+
+    Examples: Sales, Operations, Finance, Product, Marketing.
+    Domains are the primary navigation axis for human users and the
+    first scoping hint passed to agents.
+    """
+    id: UUID = Field(default_factory=uuid4)
+    slug: str
+    name: str
+    description: str = ""
+    color: str = Field(default="#6366f1", description="Hex color for UI.")
+    icon: str = Field(default="database", description="Icon name for UI.")
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class EntityTableMapping(BaseModel):
+    """
+    Maps a business Entity to a physical table.
+
+    An entity can span multiple tables (e.g. a Customer entity backed by
+    both `users` and `customer_profiles`). One table is primary; extensions
+    are joined on the identifier attribute.
+    """
+    table_id: UUID
+    source_id: UUID  # denormalised
+    is_primary: bool = True
+    join_condition: str | None = Field(
+        default=None,
+        description="SQL JOIN fragment for extension tables, e.g. 'users.id = customer_profiles.user_id'.",
+    )
+
+
+class Entity(BaseModel):
+    """
+    A named business concept — the fundamental unit of the semantic layer.
+
+    Entities correspond to things the business talks about: Customer, Order,
+    Product, Invoice, Supplier. They are discovered automatically from schema
+    patterns by the Semantic Indexer and validated by humans.
+
+    An entity always maps to at least one physical table. The mapping tells
+    the query engine where to look; the entity itself is what agents reference.
+
+    Entities support single inheritance via `parent_entity_id` for cases like
+    IndividualCustomer / BusinessCustomer both being kinds of Party. Subtypes
+    inherit attributes conceptually; the inheritance is for ontology navigation
+    and abstract grouping, not SQL-level polymorphism.
+    """
+    id: UUID = Field(default_factory=uuid4)
+    slug: str = Field(description="Stable machine-readable identifier, e.g. 'customer'.")
+    name: str
+    plural_name: str = Field(description="Used in UI and agent context, e.g. 'Customers'.")
+    aliases: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Alternative names used in conversation that should resolve to this entity. "
+            "Drives natural-language matching, e.g. ['user', 'account holder'] for Customer."
+        ),
+    )
+    domain_id: UUID | None = None
+
+    parent_entity_id: UUID | None = Field(
+        default=None,
+        description=(
+            "Optional parent entity for is-a hierarchies. "
+            "E.g. IndividualCustomer and BusinessCustomer both have parent_entity_id = Party."
+        ),
+    )
+
+    description_auto: str = ""
+    description_human: str = ""
+
+    table_mappings: list[EntityTableMapping] = Field(default_factory=list)
+
+    # Discovery provenance
+    is_confirmed: bool = Field(
+        default=False,
+        description="False = auto-discovered by the Semantic Indexer, not yet human-validated.",
+    )
+    discovery_confidence: float = Field(
+        default=1.0, ge=0.0, le=1.0,
+        description="Indexer confidence score. 1.0 for human-defined entities.",
+    )
+
+    tags: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @property
+    def description(self) -> str:
+        return self.description_human or self.description_auto
+
+    @property
+    def primary_table_id(self) -> UUID | None:
+        for m in self.table_mappings:
+            if m.is_primary:
+                return m.table_id
+        return None
+
+
+class AttributeRole(str, Enum):
+    """
+    Semantic role of an attribute.
+
+    Drives how the query engine uses this attribute when translating
+    natural language to SQL. An agent reading a MEASURE knows it can
+    be aggregated; a TEMPORAL knows it can be used as a time axis.
+    """
+    IDENTIFIER  = "identifier"   # primary key / surrogate id
+    DIMENSION   = "dimension"    # groupable categorical field
+    MEASURE     = "measure"      # numeric field, directly aggregatable
+    TEMPORAL    = "temporal"     # date/timestamp for time-series slicing
+    LABEL       = "label"        # human-readable name field (e.g. customer_name)
+    FLAG        = "flag"         # boolean status
+    FOREIGN_KEY = "foreign_key"  # FK to another entity
+    OTHER       = "other"
+
+
+class SemanticType(str, Enum):
+    """
+    Semantic interpretation of an attribute's values, beyond its SQL type.
+
+    Distinct from `AttributeRole` (which says how the attribute is used in SQL)
+    and from `Column.data_type` (which is the storage type). This describes what
+    the values *mean*: a `BIGINT` column might be a `CURRENCY` in cents or a
+    `DURATION` in milliseconds or just a `COUNT`. Agents and UIs use this to
+    format values and to refuse arithmetically nonsensical operations
+    (e.g. don't sum two LATITUDE values).
+    """
+    CURRENCY     = "currency"      # monetary amount; pair with `unit` for ISO code
+    PERCENTAGE   = "percentage"    # 0–1 or 0–100, record which in description
+    DURATION     = "duration"      # time span; pair with `unit` (seconds, days, …)
+    COUNT        = "count"         # integer count of something
+    RATIO        = "ratio"         # dimensionless ratio
+    EMAIL        = "email"
+    URL          = "url"
+    PHONE        = "phone"
+    COUNTRY_CODE = "country_code"  # ISO 3166
+    LATITUDE     = "latitude"
+    LONGITUDE    = "longitude"
+    IP_ADDRESS   = "ip_address"
+    OTHER        = "other"
+
+
+class EntityAttribute(BaseModel):
+    """
+    A business-meaningful attribute on an Entity.
+
+    Maps one semantic attribute name either to a physical column (`column_id`)
+    or to a SQL expression (`expression`). The attribute name and description
+    are what agents and users see; the column or expression is how the query
+    engine resolves it.
+
+    Examples on a Customer entity:
+        customer_id    → IDENTIFIER  (backed by users.id)
+        name           → LABEL       (backed by users.full_name)
+        signup_date    → TEMPORAL    (backed by users.created_at)
+        plan_type      → DIMENSION   (known_values: free, starter, pro, enterprise)
+        lifetime_value → MEASURE     (default_aggregation: SUM)
+        full_name      → LABEL       (computed: first_name || ' ' || last_name)
+
+    Exactly one of `column_id` or `expression` must be set. Computed attributes
+    (with `expression`) leave `column_id` and `source_id` as None — the expression
+    is the resolution path instead.
+    """
+    id: UUID = Field(default_factory=uuid4)
+    entity_id: UUID
+
+    column_id: UUID | None = Field(
+        default=None,
+        description="Physical column backing this attribute. None for computed attributes.",
+    )
+    source_id: UUID | None = Field(
+        default=None,
+        description="Denormalised source id. None for computed attributes.",
+    )
+    expression: str | None = Field(
+        default=None,
+        description=(
+            "SQL expression for computed attributes, e.g. "
+            "\"first_name || ' ' || last_name\" or \"amount_cents / 100.0\". "
+            "Must be None when column_id is set."
+        ),
+    )
+
+    name: str = Field(description="Business-facing attribute name, e.g. 'signup_date'.")
+    display_name: str = Field(description="UI/agent label, e.g. 'Signup Date'.")
+    aliases: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Alternative names for natural-language matching, e.g. "
+            "['registration date', 'created'] for signup_date."
+        ),
+    )
+    role: AttributeRole = AttributeRole.OTHER
+
+    description_auto: str = ""
+    description_human: str = ""
+
+    # Semantic typing (distinct from the column's SQL data_type)
+    semantic_type: SemanticType | None = Field(
+        default=None,
+        description="What the values mean semantically (currency, percentage, …).",
+    )
+    unit: str | None = Field(
+        default=None,
+        description="Unit for this attribute's values: 'EUR', '%', 'seconds', 'days', 'm'.",
+    )
+
+    # For MEASURE role
+    default_aggregation: str | None = Field(
+        default=None,
+        description="Default SQL aggregation: SUM, AVG, COUNT, MIN, MAX.",
+    )
+
+    # For DIMENSION role — populated when cardinality is low enough to enumerate
+    known_values: list[str] = Field(
+        default_factory=list,
+        max_length=50,
+        description="Known categorical values for low-cardinality dimensions.",
+    )
+
+    is_sensitive: bool = False  # propagated from Column; suppressed in agent context
+    tags: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @model_validator(mode="after")
+    def _check_column_xor_expression(self) -> EntityAttribute:
+        has_column = self.column_id is not None
+        has_expression = self.expression is not None and self.expression.strip() != ""
+        if has_column == has_expression:
+            raise ValueError(
+                "EntityAttribute must have exactly one of column_id or expression set "
+                "(column-backed attributes use column_id; computed attributes use expression)."
+            )
+        if has_column and self.source_id is None:
+            raise ValueError("Column-backed attributes must also set source_id.")
+        return self
+
+    @property
+    def description(self) -> str:
+        return self.description_human or self.description_auto
+
+    @property
+    def is_computed(self) -> bool:
+        return self.expression is not None and self.column_id is None
+
+
+class RelationshipCardinality(str, Enum):
+    ONE_TO_ONE  = "one_to_one"
+    ONE_TO_MANY = "one_to_many"
+    MANY_TO_ONE = "many_to_one"
+    MANY_TO_MANY = "many_to_many"
+
+
+class RelationshipDiscovery(str, Enum):
+    """How this relationship was discovered."""
+    DECLARED_FK     = "declared_fk"      # explicit foreign key in schema
+    INFERRED_NAME   = "inferred_name"    # column name heuristic
+    INFERRED_SAMPLE = "inferred_sample"  # sample value overlap
+    HUMAN_DEFINED   = "human_defined"
+
+
+class Relationship(BaseModel):
+    """
+    A directed relationship between two Entities.
+
+    Relationships are the edges of the ontology graph. They tell the query
+    engine how to JOIN entities, and tell agents which cross-entity questions
+    are answerable.
+
+    Direction convention:
+        source_entity (many side) → target_entity (one side)
+    e.g. Order → Customer  (many orders per customer)
+
+    For MANY_TO_MANY relationships realised through an associative table
+    (e.g. Order ↔ Product via OrderItem), set `via_entity_id` to the
+    associative Entity. The query engine then knows to insert that table
+    into the JOIN path.
+    """
+    id: UUID = Field(default_factory=uuid4)
+    slug: str
+    name: str = Field(description="Forward-direction label, e.g. 'Order belongs to Customer'.")
+    inverse_name: str | None = Field(
+        default=None,
+        description=(
+            "Reverse-direction label read from the target side, e.g. "
+            "'Customer has Orders'. When omitted, callers should fall back to `name`."
+        ),
+    )
+
+    source_entity_id: UUID
+    target_entity_id: UUID
+
+    # Which attributes form the join key
+    source_attribute_id: UUID = Field(description="FK attribute on the source entity.")
+    target_attribute_id: UUID = Field(description="PK attribute on the target entity.")
+
+    cardinality: RelationshipCardinality = RelationshipCardinality.MANY_TO_ONE
+    via_entity_id: UUID | None = Field(
+        default=None,
+        description=(
+            "For MANY_TO_MANY relationships, the associative entity that joins source and target "
+            "(e.g. OrderItem between Order and Product). None for direct relationships."
+        ),
+    )
+    discovery: RelationshipDiscovery = RelationshipDiscovery.INFERRED_NAME
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
+
+    is_confirmed: bool = False
+    description: str = ""
+
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

nomox_semantics-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+nomox_semantics/__init__.py,sha256=NQFTlXXgjyowB8ozD64G3_cUj9eQBrhLxR-THzalsNg,1901
+nomox_semantics/catalog.py,sha256=uvvvZCJ-c_E-6x8BnWeK1GOy9IKCvS5W-F_4kocoPDo,5320
+nomox_semantics/glossary.py,sha256=EAkGys6ui9YvkggZPNxWLwmP7PFuktx38jdj6vIt26k,2048
+nomox_semantics/metric.py,sha256=Rmwfqe0-dTS4sPzmsPFgGEA3adwWsCae5SnXuH66n-A,5935
+nomox_semantics/physical.py,sha256=lpi1uMhYhKbA0GN518rfF04fKK3qV_gwk3_akKdVx24,5361
+nomox_semantics/query.py,sha256=xNh36QfM-8hVMDSt-HpyiRYqGi3NYE3jbb4oi7RFQFU,6581
+nomox_semantics/semantic.py,sha256=d8eXVwcmxklPL6-0Lt8KKVkSQtbHhzNrvqz3PGVEejU,13048
+nomox_semantics-0.1.0.dist-info/METADATA,sha256=p-Y8QNUAr_J9fVuMZcfwIRU17-Ex1Z5BXbDTttYLnRE,3051
+nomox_semantics-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nomox_semantics-0.1.0.dist-info/RECORD,,

nomox_semantics-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any