Skip to content

ontocast.onto.ontology_access

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

Centralizes prompt-effective ontology resolution so agents and stategraph code use :class:~ontocast.onto.ontology_snapshot.OntologySnapshot views (assemble product) rather than treating snapshots as catalog :class:Ontology instances.

Classes

DocumentOntologyAccess

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

Source code in ontocast/onto/ontology_access.py 
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
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-catalog-IRI artifacts after apply)."""
        artifacts = self.reduced_artifacts()
        if artifacts:
            return artifacts
        return []

Attributes

__slots__ = ('_state',) class-attribute instance-attribute

Methods:

__init__(state)
Source code in ontocast/onto/ontology_access.py 
242
243
def __init__(self, state: AgentState) -> None:
    self._state = state
has_any_artifacts()
Source code in ontocast/onto/ontology_access.py 
250
251
252
253
def has_any_artifacts(self) -> bool:
    return bool(
        self._state.reduced_ontology_artifacts or self._state.ontology_artifacts
    )
has_non_null_artifacts()
Source code in ontocast/onto/ontology_access.py 
255
256
def has_non_null_artifacts(self) -> bool:
    return any(not ontology.is_null() for ontology in self.reduced_artifacts())
ontology_by_anchor(anchor_iri)
Source code in ontocast/onto/ontology_access.py 
258
259
260
261
262
263
264
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
reduced_artifacts()
Source code in ontocast/onto/ontology_access.py 
245
246
247
248
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)
serialization_targets()

Ontologies to version and persist (per-catalog-IRI artifacts after apply).

Source code in ontocast/onto/ontology_access.py 
266
267
268
269
270
271
def serialization_targets(self) -> list[Ontology]:
    """Ontologies to version and persist (per-catalog-IRI artifacts after apply)."""
    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 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
class OntologyPromptSource(Protocol):
    """Ontology material used to build LLM prompts (TTL, prefixes, seed checks)."""

    def effective_graph_for_prompt(self) -> RDFGraph:
        """Graph whose triples should appear in the main ontology chapter."""
        ...

    def ontology_graph_for_prefixes(self) -> RDFGraph:
        """Graph used to collect namespace prefixes for TTL repair."""
        ...

    def has_non_empty_seed(self) -> bool:
        """Whether the seed snapshot has triples (vs empty / null context)."""
        ...

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

    def prompt_ontology_description(self) -> str:
        """Human-readable description for ontology-update intros."""
        ...

    def writable_iris(self) -> list[str]:
        """Catalog IRIs that may receive writeback from this unit."""
        ...

Methods:

domain_prefix_pairs()

Domain ontology prefix/namespace pairs used for prompt instructions.

Source code in ontocast/onto/ontology_access.py 
37
38
39
def domain_prefix_pairs(self) -> list[tuple[str, str]]:
    """Domain ontology prefix/namespace pairs used for prompt instructions."""
    ...
effective_graph_for_prompt()

Graph whose triples should appear in the main ontology chapter.

Source code in ontocast/onto/ontology_access.py 
25
26
27
def effective_graph_for_prompt(self) -> RDFGraph:
    """Graph whose triples should appear in the main ontology chapter."""
    ...
has_non_empty_seed()

Whether the seed snapshot has triples (vs empty / null context).

Source code in ontocast/onto/ontology_access.py 
33
34
35
def has_non_empty_seed(self) -> bool:
    """Whether the seed snapshot has triples (vs empty / null context)."""
    ...
ontology_graph_for_prefixes()

Graph used to collect namespace prefixes for TTL repair.

Source code in ontocast/onto/ontology_access.py 
29
30
31
def ontology_graph_for_prefixes(self) -> RDFGraph:
    """Graph used to collect namespace prefixes for TTL repair."""
    ...
prompt_ontology_description()

Human-readable description for ontology-update intros.

Source code in ontocast/onto/ontology_access.py 
41
42
43
def prompt_ontology_description(self) -> str:
    """Human-readable description for ontology-update intros."""
    ...
writable_iris()

Catalog IRIs that may receive writeback from this unit.

Source code in ontocast/onto/ontology_access.py 
45
46
47
def writable_iris(self) -> list[str]:
    """Catalog IRIs that may receive writeback from this unit."""
    ...

UnitFactsOntologyAccess

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

Source code in ontocast/onto/ontology_access.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
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_graph_for_prompt(self) -> RDFGraph:
        return self._state.ontology_snapshot.graph

    def ontology_graph_for_prefixes(self) -> RDFGraph:
        return self._state.ontology_snapshot.graph

    def has_non_empty_seed(self) -> bool:
        return not self._state.ontology_snapshot.is_empty()

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

    def prompt_ontology_description(self) -> str:
        return self._state.ontology_snapshot.describe_for_prompt()

    def writable_iris(self) -> list[str]:
        return list(self._state.writable_iris)

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

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

    def has_non_null_seed_snapshot(self) -> bool:
        return self.has_non_empty_seed()

Attributes

__slots__ = ('_state',) class-attribute instance-attribute

Methods:

__init__(state)
Source code in ontocast/onto/ontology_access.py 
206
207
def __init__(self, state: UnitFactsState) -> None:
    self._state = state
domain_prefix_pairs()
Source code in ontocast/onto/ontology_access.py 
218
219
def domain_prefix_pairs(self) -> list[tuple[str, str]]:
    return self._state.ontology_snapshot.domain_prefix_pairs()
effective_graph_for_prompt()
Source code in ontocast/onto/ontology_access.py 
209
210
def effective_graph_for_prompt(self) -> RDFGraph:
    return self._state.ontology_snapshot.graph
effective_ontology_for_prompt()
Source code in ontocast/onto/ontology_access.py 
227
228
def effective_ontology_for_prompt(self) -> OntologySnapshot:
    return self._state.ontology_snapshot
has_non_empty_seed()
Source code in ontocast/onto/ontology_access.py 
215
216
def has_non_empty_seed(self) -> bool:
    return not self._state.ontology_snapshot.is_empty()
has_non_null_seed_snapshot()
Source code in ontocast/onto/ontology_access.py 
233
234
def has_non_null_seed_snapshot(self) -> bool:
    return self.has_non_empty_seed()
ontology_for_prefixes()
Source code in ontocast/onto/ontology_access.py 
230
231
def ontology_for_prefixes(self) -> OntologySnapshot:
    return self._state.ontology_snapshot
ontology_graph_for_prefixes()
Source code in ontocast/onto/ontology_access.py 
212
213
def ontology_graph_for_prefixes(self) -> RDFGraph:
    return self._state.ontology_snapshot.graph
prompt_ontology_description()
Source code in ontocast/onto/ontology_access.py 
221
222
def prompt_ontology_description(self) -> str:
    return self._state.ontology_snapshot.describe_for_prompt()
writable_iris()
Source code in ontocast/onto/ontology_access.py 
224
225
def writable_iris(self) -> list[str]:
    return list(self._state.writable_iris)

UnitOntologyAccess

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

Source code in ontocast/onto/ontology_access.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class UnitOntologyAccess:
    """Accessor for :class:`UnitOntologyState` (ontology map loop)."""

    __slots__ = ("_state",)

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

    def effective_graph_for_prompt(self) -> RDFGraph:
        if len(self._state.working_graph) > 0:
            return self._state.working_graph
        return self._state.ontology_snapshot.graph

    def ontology_graph_for_prefixes(self) -> RDFGraph:
        return self.effective_graph_for_prompt()

    def has_non_empty_seed(self) -> bool:
        return not self._state.ontology_snapshot.is_empty()

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

    def prompt_ontology_description(self) -> str:
        return self._state.ontology_snapshot.describe_for_prompt()

    def writable_iris(self) -> list[str]:
        return list(self._state.writable_iris)

    # ---- compatibility shims during migration ----
    def effective_ontology_for_prompt(self) -> OntologySnapshot:
        """Return a transient snapshot view of the effective prompt graph."""
        snap = self._state.ontology_snapshot
        return OntologySnapshot(
            graph=self.effective_graph_for_prompt().copy(),
            source_iris=list(snap.source_iris),
            assembly_mode=snap.assembly_mode,
            title=snap.title,
            description=snap.description,
        )

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

    def has_non_null_seed_snapshot(self) -> bool:
        return self.has_non_empty_seed()

Attributes

__slots__ = ('_state',) class-attribute instance-attribute

Methods:

__init__(state)
Source code in ontocast/onto/ontology_access.py 
159
160
def __init__(self, state: UnitOntologyState) -> None:
    self._state = state
domain_prefix_pairs()
Source code in ontocast/onto/ontology_access.py 
173
174
def domain_prefix_pairs(self) -> list[tuple[str, str]]:
    return extract_domain_prefix_pairs_from_graph(self.effective_graph_for_prompt())
effective_graph_for_prompt()
Source code in ontocast/onto/ontology_access.py 
162
163
164
165
def effective_graph_for_prompt(self) -> RDFGraph:
    if len(self._state.working_graph) > 0:
        return self._state.working_graph
    return self._state.ontology_snapshot.graph
effective_ontology_for_prompt()

Return a transient snapshot view of the effective prompt graph.

Source code in ontocast/onto/ontology_access.py 
183
184
185
186
187
188
189
190
191
192
def effective_ontology_for_prompt(self) -> OntologySnapshot:
    """Return a transient snapshot view of the effective prompt graph."""
    snap = self._state.ontology_snapshot
    return OntologySnapshot(
        graph=self.effective_graph_for_prompt().copy(),
        source_iris=list(snap.source_iris),
        assembly_mode=snap.assembly_mode,
        title=snap.title,
        description=snap.description,
    )
has_non_empty_seed()
Source code in ontocast/onto/ontology_access.py 
170
171
def has_non_empty_seed(self) -> bool:
    return not self._state.ontology_snapshot.is_empty()
has_non_null_seed_snapshot()
Source code in ontocast/onto/ontology_access.py 
197
198
def has_non_null_seed_snapshot(self) -> bool:
    return self.has_non_empty_seed()
ontology_for_prefixes()
Source code in ontocast/onto/ontology_access.py 
194
195
def ontology_for_prefixes(self) -> OntologySnapshot:
    return self.effective_ontology_for_prompt()
ontology_graph_for_prefixes()
Source code in ontocast/onto/ontology_access.py 
167
168
def ontology_graph_for_prefixes(self) -> RDFGraph:
    return self.effective_graph_for_prompt()
prompt_ontology_description()
Source code in ontocast/onto/ontology_access.py 
176
177
def prompt_ontology_description(self) -> str:
    return self._state.ontology_snapshot.describe_for_prompt()
writable_iris()
Source code in ontocast/onto/ontology_access.py 
179
180
def writable_iris(self) -> list[str]:
    return list(self._state.writable_iris)

Functions:

build_llm_prefix_map(primary, supplemental=())

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

Accepts a catalog :class:Ontology, an :class:OntologySnapshot, or a raw :class:RDFGraph as primary.

Source code in ontocast/onto/ontology_access.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def build_llm_prefix_map(
    primary: Ontology | OntologySnapshot | RDFGraph,
    supplemental: Iterable[Ontology] = (),
) -> dict[str, str]:
    """Collect namespace prefixes for LLM Turtle/JSON-LD ingest repair.

    Accepts a catalog :class:`Ontology`, an :class:`OntologySnapshot`, or a raw
    :class:`RDFGraph` as primary.
    """
    if isinstance(primary, OntologySnapshot):
        primary_graph = primary.graph
    elif isinstance(primary, Ontology):
        if primary.is_null():
            return _add_semantic_aliases(prefix_lookup_for_ingest())
        primary_graph = primary.graph
        if not isinstance(primary_graph, RDFGraph):
            normalized = RDFGraph()
            for triple in primary_graph:
                normalized.add(triple)
            for prefix, namespace_uri in primary_graph.namespaces():
                normalized.bind(prefix, namespace_uri)
            primary_graph = normalized
    else:
        primary_graph = primary
    return build_llm_prefix_map_from_graphs(primary_graph, supplemental)

build_llm_prefix_map_from_graphs(primary, supplemental=())

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

Source code in ontocast/onto/ontology_access.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def build_llm_prefix_map_from_graphs(
    primary: RDFGraph,
    supplemental: Iterable[RDFGraph | Ontology] = (),
) -> dict[str, str]:
    """Collect namespace prefixes for LLM Turtle/JSON-LD ingest repair from graphs."""
    merged = prefix_lookup_for_ingest()
    _merge_prefix_bindings_from_graph(merged, primary)
    for item in supplemental:
        if isinstance(item, Ontology):
            if item.is_null():
                continue
            graph = item.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=item.prefix or None,
                extra_namespace=item.namespace or None,
            )
        else:
            _merge_prefix_bindings_from_graph(merged, item)
    return _add_semantic_aliases(merged)

document_ontology_access(state)

Source code in ontocast/onto/ontology_access.py 
282
283
def document_ontology_access(state: AgentState) -> DocumentOntologyAccess:
    return DocumentOntologyAccess(state)

ontology_access_for_unit_facts(state)

Source code in ontocast/onto/ontology_access.py 
278
279
def ontology_access_for_unit_facts(state: UnitFactsState) -> UnitFactsOntologyAccess:
    return UnitFactsOntologyAccess(state)

ontology_access_for_unit_ontology(state)

Source code in ontocast/onto/ontology_access.py 
274
275
def ontology_access_for_unit_ontology(state: UnitOntologyState) -> UnitOntologyAccess:
    return UnitOntologyAccess(state)