ontocast.onto.ontology_access

Read-only accessors for ontology context on document vs unit workflow state.

Centralizes prompt-effective ontology resolution and serialization target lists so agents and stategraph code do not duplicate ontology_snapshot / ontology_artifacts branching.

DocumentOntologyAccess

Accessor for :class:AgentState (document-level reduce / serialize).

Source code in ontocast/onto/ontology_access.py

class DocumentOntologyAccess:
    """Accessor for :class:`AgentState` (document-level reduce / serialize)."""

    __slots__ = ("_state",)

    def __init__(self, state: AgentState) -> None:
        self._state = state

    def reduced_artifacts(self) -> list[Ontology]:
        if self._state.reduced_ontology_artifacts:
            return list(self._state.reduced_ontology_artifacts)
        return list(self._state.ontology_artifacts)

    def has_any_artifacts(self) -> bool:
        return bool(
            self._state.reduced_ontology_artifacts or self._state.ontology_artifacts
        )

    def has_non_null_artifacts(self) -> bool:
        return any(not ontology.is_null() for ontology in self.reduced_artifacts())

    def ontology_by_anchor(self, anchor_iri: str) -> Ontology | None:
        if anchor_iri in self._state.reduced_ontology_by_anchor:
            return self._state.reduced_ontology_by_anchor[anchor_iri]
        for ontology in self.reduced_artifacts():
            if ontology.iri == anchor_iri:
                return ontology
        return None

    def serialization_targets(self) -> list[Ontology]:
        """Ontologies to version and persist (per-anchor artifacts)."""
        artifacts = self.reduced_artifacts()
        if artifacts:
            return artifacts
        return []

serialization_targets()

Ontologies to version and persist (per-anchor artifacts).

Source code in ontocast/onto/ontology_access.py

def serialization_targets(self) -> list[Ontology]:
    """Ontologies to version and persist (per-anchor artifacts)."""
    artifacts = self.reduced_artifacts()
    if artifacts:
        return artifacts
    return []

OntologyPromptSource

Bases: Protocol

Ontology material used to build LLM prompts (TTL, prefixes, seed checks).

Source code in ontocast/onto/ontology_access.py

class OntologyPromptSource(Protocol):
    """Ontology material used to build LLM prompts (TTL, prefixes, seed checks)."""

    def effective_ontology_for_prompt(self) -> Ontology:
        """Ontology whose graph and metadata should appear in the main prompt."""
        ...

    def ontology_for_prefixes(self) -> Ontology:
        """Ontology used to collect namespace prefixes for TTL repair."""
        ...

    def has_non_null_seed_snapshot(self) -> bool:
        """Whether the immutable snapshot anchor is a real ontology (vs null IRI)."""
        ...

    def domain_prefix_pairs(self) -> list[tuple[str, str]]:
        """Domain ontology prefix/namespace pairs used for prompt instructions."""
        ...

domain_prefix_pairs()

Domain ontology prefix/namespace pairs used for prompt instructions.

Source code in ontocast/onto/ontology_access.py

def domain_prefix_pairs(self) -> list[tuple[str, str]]:
    """Domain ontology prefix/namespace pairs used for prompt instructions."""
    ...

effective_ontology_for_prompt()

Ontology whose graph and metadata should appear in the main prompt.

Source code in ontocast/onto/ontology_access.py

def effective_ontology_for_prompt(self) -> Ontology:
    """Ontology whose graph and metadata should appear in the main prompt."""
    ...

has_non_null_seed_snapshot()

Whether the immutable snapshot anchor is a real ontology (vs null IRI).

Source code in ontocast/onto/ontology_access.py

def has_non_null_seed_snapshot(self) -> bool:
    """Whether the immutable snapshot anchor is a real ontology (vs null IRI)."""
    ...

ontology_for_prefixes()

Ontology used to collect namespace prefixes for TTL repair.

Source code in ontocast/onto/ontology_access.py

def ontology_for_prefixes(self) -> Ontology:
    """Ontology used to collect namespace prefixes for TTL repair."""
    ...

UnitFactsOntologyAccess

Accessor for :class:UnitFactsState; facts prompts use snapshot context only.

Source code in ontocast/onto/ontology_access.py

class UnitFactsOntologyAccess:
    """Accessor for :class:`UnitFactsState`; facts prompts use snapshot context only."""

    __slots__ = ("_state",)

    def __init__(self, state: UnitFactsState) -> None:
        self._state = state

    def effective_ontology_for_prompt(self) -> Ontology:
        return self._state.ontology_snapshot

    def ontology_for_prefixes(self) -> Ontology:
        return self._state.ontology_snapshot

    def has_non_null_seed_snapshot(self) -> bool:
        return not self._state.ontology_snapshot.is_null()

    def domain_prefix_pairs(self) -> list[tuple[str, str]]:
        return extract_domain_prefix_pairs(self.effective_ontology_for_prompt())

UnitOntologyAccess

Accessor for :class:UnitOntologyState (ontology map loop).

Source code in ontocast/onto/ontology_access.py

class UnitOntologyAccess:
    """Accessor for :class:`UnitOntologyState` (ontology map loop)."""

    __slots__ = ("_state",)

    def __init__(self, state: UnitOntologyState) -> None:
        self._state = state

    def effective_ontology_for_prompt(self) -> Ontology:
        return self._state.current_ontology or self._state.ontology_snapshot

    def ontology_for_prefixes(self) -> Ontology:
        return self.effective_ontology_for_prompt()

    def has_non_null_seed_snapshot(self) -> bool:
        return not self._state.ontology_snapshot.is_null()

    def domain_prefix_pairs(self) -> list[tuple[str, str]]:
        return extract_domain_prefix_pairs(self.effective_ontology_for_prompt())

build_llm_prefix_map(primary, supplemental=())

Collect namespace prefixes for LLM Turtle/JSON-LD ingest repair.

Layers (first wins on prefix name conflicts after ingest vocabulary): 1. prefix_lookup_for_ingest() (COMMON + WELL_KNOWN) 2. Primary ontology graph bindings + implicit stems 3. Supplemental ontology graphs (same extraction) 4. Semantic URI-tail aliases (relations, concepts, etc.)

Source code in ontocast/onto/ontology_access.py

def build_llm_prefix_map(
    primary: Ontology,
    supplemental: Iterable[Ontology] = (),
) -> dict[str, str]:
    """Collect namespace prefixes for LLM Turtle/JSON-LD ingest repair.

    Layers (first wins on prefix name conflicts after ingest vocabulary):
    1. ``prefix_lookup_for_ingest()`` (COMMON + WELL_KNOWN)
    2. Primary ontology graph bindings + implicit stems
    3. Supplemental ontology graphs (same extraction)
    4. Semantic URI-tail aliases (``relations``, ``concepts``, etc.)
    """
    merged = prefix_lookup_for_ingest()
    ontologies: list[Ontology] = [primary, *supplemental]
    for ontology in ontologies:
        if ontology.is_null():
            continue
        graph = ontology.graph
        if not isinstance(graph, RDFGraph):
            normalized = RDFGraph()
            for triple in graph:
                normalized.add(triple)
            for prefix, namespace_uri in graph.namespaces():
                normalized.bind(prefix, namespace_uri)
            graph = normalized
        _merge_prefix_bindings_from_graph(
            merged,
            graph,
            extra_prefix=ontology.prefix or None,
            extra_namespace=ontology.namespace or None,
        )
    return _add_semantic_aliases(merged)

known_prefixes_for_llm_parse(source)

Collect namespace prefixes for TTL/JSON-LD repair during LLM output parsing.

Source code in ontocast/onto/ontology_access.py

def known_prefixes_for_llm_parse(source: OntologyPromptSource) -> dict[str, str]:
    """Collect namespace prefixes for TTL/JSON-LD repair during LLM output parsing."""
    return build_llm_prefix_map(source.ontology_for_prefixes())