Semantics

#Resource-Scoped Meaning

Semantic annotations capture business meaning that is specific to one or more catalog resources. They remain separate from source schema and global memory, and they carry evidence plus the catalog revisions against which they were confirmed.

Supported kinds are:

Kind	Typical use
`glossary`	Define a business term
`metric_definition`	Define how a metric is calculated
`grain`	Describe the row-level grain
`time_semantics`	Explain time zones, periods, or date fields
`code_mapping`	Map stored codes to business meaning
`exclusion_rule`	Record required filters or exclusions
`join_hint`	Capture a reviewed relationship between resources
`business_owner`	Identify ownership of a resource or definition
`quality_expectation`	Record a durable data-quality expectation

Global preferences belong in Memory. Procedural instructions belong in Skills.

#Inspect Annotations

python

from pathlib import Path
 
from daita import (
    Agent,
    LocalWorkspace,
    SemanticAnnotationState,
    SemanticKind,
)
 
agent = await Agent.open(
    "atlas",
    workspace=LocalWorkspace(Path("/absolute/path/project")),
)
try:
    active_metrics = await agent.list_semantic_annotations(
        source_id="source-id",
        kind=SemanticKind.METRIC_DEFINITION,
        state=SemanticAnnotationState.ACTIVE,
    )
 
    for view in active_metrics:
        print(view.annotation.id, view.annotation.statement)
 
    selected = await agent.read_semantic_annotation("annotation-id")
finally:
    await agent.close()

You can also filter by resource_id. Each returned SemanticAnnotationView includes the stored annotation, its SHA-256 digest, its current state, and any stale, conflict, duplicate, or supersession information.

#Annotation State

State	Meaning
`active`	Current and eligible for ordinary recall
`stale`	Catalog revisions or resource facts no longer match
`conflicting`	Another current annotation makes an incompatible claim
`duplicate`	Equivalent meaning is already represented
`superseded`	A newer annotation explicitly replaces this one

Daita re-evaluates semantic state against current catalog facts. Stale, conflicting, duplicate, and superseded records are retained for review but are not treated as unqualified current meaning.

#Save and Delete

The Python API accepts a validated SemanticAnnotation record:

python

saved = await agent.save_semantic_annotation(annotation)

Updating an existing record uses optimistic concurrency:

python

view = await agent.read_semantic_annotation("annotation-id")
assert view is not None
 
saved = await agent.save_semantic_annotation(
    replacement,
    expected_sha256=view.sha256,
)

Deletion always requires the current digest:

python

deleted = await agent.delete_semantic_annotation(
    view.annotation.id,
    expected_sha256=view.sha256,
)

During a model run, the equivalent semantic_save and semantic_delete tools are local write capabilities. They require an explicit approval decision before Daita changes the annotation store.

#Evidence and Scope

A valid annotation includes:

current source and resource IDs;
optional field references that belong to those resources;
one or more transcript or tool-result evidence references;
exactly one catalog revision binding per subject resource; and
local-user confirmation timestamps.

These requirements keep semantic recall attributable and prevent a global note from silently overriding source truth.

#Resource-Scoped Meaning

Supported kinds are:

Kind	Typical use
`glossary`	Define a business term
`metric_definition`	Define how a metric is calculated
`grain`	Describe the row-level grain
`time_semantics`	Explain time zones, periods, or date fields
`code_mapping`	Map stored codes to business meaning
`exclusion_rule`	Record required filters or exclusions
`join_hint`	Capture a reviewed relationship between resources
`business_owner`	Identify ownership of a resource or definition
`quality_expectation`	Record a durable data-quality expectation

Global preferences belong in Memory. Procedural instructions belong in Skills.

#Inspect Annotations

python

from pathlib import Path
 
from daita import (
    Agent,
    LocalWorkspace,
    SemanticAnnotationState,
    SemanticKind,
)
 
agent = await Agent.open(
    "atlas",
    workspace=LocalWorkspace(Path("/absolute/path/project")),
)
try:
    active_metrics = await agent.list_semantic_annotations(
        source_id="source-id",
        kind=SemanticKind.METRIC_DEFINITION,
        state=SemanticAnnotationState.ACTIVE,
    )
 
    for view in active_metrics:
        print(view.annotation.id, view.annotation.statement)
 
    selected = await agent.read_semantic_annotation("annotation-id")
finally:
    await agent.close()

#Annotation State

State	Meaning
`active`	Current and eligible for ordinary recall
`stale`	Catalog revisions or resource facts no longer match
`conflicting`	Another current annotation makes an incompatible claim
`duplicate`	Equivalent meaning is already represented
`superseded`	A newer annotation explicitly replaces this one

Daita re-evaluates semantic state against current catalog facts. Stale, conflicting, duplicate, and superseded records are retained for review but are not treated as unqualified current meaning.

#Save and Delete

The Python API accepts a validated SemanticAnnotation record:

python

saved = await agent.save_semantic_annotation(annotation)

Updating an existing record uses optimistic concurrency:

python

view = await agent.read_semantic_annotation("annotation-id")
assert view is not None
 
saved = await agent.save_semantic_annotation(
    replacement,
    expected_sha256=view.sha256,
)

Deletion always requires the current digest:

python

deleted = await agent.delete_semantic_annotation(
    view.annotation.id,
    expected_sha256=view.sha256,
)

During a model run, the equivalent semantic_save and semantic_delete tools are local write capabilities. They require an explicit approval decision before Daita changes the annotation store.

#Evidence and Scope

A valid annotation includes:

current source and resource IDs;
optional field references that belong to those resources;
one or more transcript or tool-result evidence references;
exactly one catalog revision binding per subject resource; and
local-user confirmation timestamps.

These requirements keep semantic recall attributable and prevent a global note from silently overriding source truth.