ontocast.stategraph.context_resolver¶
Attributes¶
logger = logging.getLogger(__name__)
module-attribute
¶
Classes¶
UnitOntologyContext
¶
Bases: BaseModel
Assembled prompt context: snapshot view + writable catalog IRIs for apply.
Source code in ontocast/stategraph/context_resolver.py
Attributes¶
assembly_mode
property
¶
confidence = 0.0
class-attribute
instance-attribute
¶
patch_sources
property
¶
primary_writable_iri
property
¶
Primary catalog IRI for metrics (first writable, else null).
snapshot
instance-attribute
¶
writable_iris = Field(default_factory=list)
class-attribute
instance-attribute
¶
Functions:¶
admit_facts_context_terms(ctx, plan, tools, *, budget_tracker=None)
¶
Complete a facts ontology context: planned reuses, then named catalog terms.
Every path that resolves a facts context goes through here, so the plan's reuses reach the facts prompt whether the context is the merged document context or a unit's own. Planned terms come first so the named-term pass also admits terms their definitions quote.
Source code in ontocast/stategraph/context_resolver.py
admit_named_catalog_terms(ctx, tools, *, budget_tracker=None)
¶
Add the definitions of catalog terms the prompt names but the snapshot lacks.
The conformance chapter prints every rule of a shape it selects, and a
term's note may quote another term, so a facts prompt can tell the model
to use a catalog term its # ONTOLOGY chapter never defines. Each such
term that the catalog defines gets its defining statements
(:meth:OntologyManager.term_definitions) added to a copy of the
snapshot. Only catalog terms are admitted, and only ones the prompt
already names, so the pass adds no vocabulary the prompt did not mention.
Returns ctx itself when nothing is admitted, else a context over a
new snapshot: a shared document context is never changed in place.
Source code in ontocast/stategraph/context_resolver.py
admit_planned_terms(ctx, plan, tools, *, budget_tracker=None)
¶
Add the terms the document's ontology plan chose to reuse.
A reused term is never minted, so without this the facts prompt never
shows it, and the relation the plan assigned to it is left unstated. A
catalog term brings its catalog definition
(:meth:OntologyManager.term_definitions); a well-known term is declared
from the plan entry: its kind, the plan's label and the plan's definition
of it for this document. Terms the context already defines are skipped.
Returns ctx itself when nothing is added, else a context over a new
snapshot: a shared document context is never changed in place.
Source code in ontocast/stategraph/context_resolver.py
aggregate_writable_metrics(unit_contexts)
¶
Aggregate per-unit writable IRI / source / mode metrics.
Accepts either :class:UnitOntologyContext or legacy
(primary_iri, patch_sources, mode) tuples for map-stage collect.
Source code in ontocast/stategraph/context_resolver.py
build_merged_document_ontology_context(context, catalog_head)
¶
The one ontology context every facts unit of a document is rendered against.
The document's home ontologies as the ontology stage left them, merged
with the catalog ontologies they rest on (:func:_catalog_ontologies):
a home that extends an external catalog, or a fresh home, holds only the
terms documents added, so without the catalog the facts render would
fall back on generic vocabulary. Catalog ontologies are read, never
writable. The result depends only on document-level state, so it is
computed once per document; "ctx/merge_document_ontology.calls" makes
a regression to per-unit calls visible.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
context
|
UnitLoopContext
|
Document-level loop inputs. |
required |
catalog_head
|
Callable[[str], Ontology | None]
|
The catalog's head of an ontology IRI, or |
required |
Returns:
| Type | Description |
|---|---|
UnitOntologyContext | None
|
The merged context, or |
Source code in ontocast/stategraph/context_resolver.py
build_unioned_document_ontology_context(context, tools, units)
async
¶
Resolve every unit's context once and union them into one shared context.
Per-unit retrieval gives each unit a smaller chapter than the union would be, and that is a real saving on the first call for a unit. It is a loss on every call after it: the chapter is the bulk of a facts prompt, no two units get the same one, and a provider's prefix cache can therefore serve none of them -- so a document pays the chapter once per unit at full price instead of once at full price and N-1 times at the cached rate.
Unioning is the trade that makes the second arrangement available. It is recall-safe by construction: the union contains every atom each unit's own retrieval selected, so no unit is shown less than it would have been. What it costs is precision -- a unit also sees its siblings' terms -- and the per-call token count, which is why it is a setting and not the default.
Retrieval runs concurrently, bounded the same way the unit fan-out is. In the vector modes this is embedding and graph work with no LLM call; the LLM-selection mode does spend one call per unit here, exactly as it would have spent inside the fan-out.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
context
|
UnitLoopContext
|
Document-level loop inputs. |
required |
tools
|
ToolBox
|
Toolbox holding the catalog and retrieval. |
required |
units
|
Sequence[SourceUnit]
|
The document's content units. |
required |
Returns:
| Type | Description |
|---|---|
UnitOntologyContext | None
|
The unioned context, or None when no unit resolved anything -- which |
UnitOntologyContext | None
|
leaves the caller on the per-unit path rather than handing every unit an |
UnitOntologyContext | None
|
empty snapshot. |
Source code in ontocast/stategraph/context_resolver.py
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 | |
resolve_unit_ontology_context(context, tools, unit, *, can_create_vocabulary=False)
async
¶
Assemble the ontology context one content unit is rendered against.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
context
|
UnitLoopContext
|
Document-level loop inputs. |
required |
tools
|
ToolBox
|
Toolbox holding the catalog and retrieval. |
required |
unit
|
SourceUnit
|
The content unit being rendered. |
required |
can_create_vocabulary
|
bool
|
Whether the caller can act on an empty context
by inventing vocabulary. True for the ontology loop, which answers
an empty seed with |
False
|
Returns:
| Type | Description |
|---|---|
UnitOntologyContext
|
The resolved context, possibly empty. |
Raises:
| Type | Description |
|---|---|
EmptyOntologyContextError
|
The context is empty, the caller cannot create vocabulary, and this deployment requires a context. |
Source code in ontocast/stategraph/context_resolver.py
740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 | |
show_prefixes(snapshot, tools)
¶
Make a prompt context read under the catalog's prefix table, in place.
Every context a prompt is rendered from passes through here, so the term sheet, its notes, the domain clause and the conformance chapter show one prefix per namespace, the one answers are parsed with.
Source code in ontocast/stategraph/context_resolver.py
snapshot_context_terms(graph, writable_iris)
¶
Every IRI of a snapshot graph, in any position, plus the writable IRIs.
The join key the conformance chapter is selected on: the schema closure carries superclass IRIs as objects, which is how a shape targeting a superclass reaches a unit typed with the subclass.