ontocast.onto.model¶
Attributes¶
FindingKindT = TypeVar('FindingKindT', bound=StrEnum)
module-attribute
¶
TermActionKind = Literal['keep', 'merge_into', 'generalise_to', 'demote_to_property_value', 'drop']
module-attribute
¶
TermKind = Literal['class', 'object_property', 'datatype_property']
module-attribute
¶
Classes¶
BasePydanticModel
¶
Bases: BaseModel
Shared base for the pipeline's Pydantic models.
Carries no behaviour of its own since the JSON save/load helpers were removed with their only consumer; it is kept as the common ancestor the state and report models already declare.
Source code in ontocast/onto/model.py
CoreferenceCandidate
¶
Bases: BaseModel
A pair of unit-minted entities whose identity is put to the model.
kind says why: unconfirmed_merge (merged on a plausible lexical
tier only), near_miss (refused for lexical alone) or
shared_link (same type, different units, pointing to one node by one
predicate).
Source code in ontocast/onto/model.py
CoreferenceReport
¶
Bases: BaseModel
Verdicts for the pairs put to the model; a pair left out is 'unsure'.
Source code in ontocast/onto/model.py
CoreferenceVerdict
¶
Bases: BaseModel
The model's answer for one numbered pair of entities.
Source code in ontocast/onto/model.py
Attributes¶
pair = Field(description="The pair's number, as listed.")
class-attribute
instance-attribute
¶
reason = Field(default='', max_length=300, description='One short sentence on why.')
class-attribute
instance-attribute
¶
verdict = Field(description="'same' when both denote one real-world thing, 'different' when they denote distinct things, 'unsure' when the evidence does not decide.")
class-attribute
instance-attribute
¶
ExternalEvidenceCacheEntry
¶
Bases: BaseModel
Node-scoped external evidence planning/fetch outputs.
Source code in ontocast/onto/model.py
Attributes¶
domains = Field(default_factory=list)
class-attribute
instance-attribute
¶
hits = Field(default_factory=list)
class-attribute
instance-attribute
¶
plan = Field(default_factory=ExternalEvidencePlan)
class-attribute
instance-attribute
¶
source_count = Field(default=0, ge=0)
class-attribute
instance-attribute
¶
text = Field(default='')
class-attribute
instance-attribute
¶
ExternalEvidenceHit
¶
Bases: BaseModel
Normalized external evidence hit metadata.
Source code in ontocast/onto/model.py
ExternalEvidencePlan
¶
Bases: BaseModel
Structured plan for optional external evidence retrieval.
Source code in ontocast/onto/model.py
Attributes¶
confidence = Field(default=0.0, ge=0.0, le=1.0, description='Confidence in the decision.')
class-attribute
instance-attribute
¶
intent = Field(default='none', description='Primary reason for searching external evidence.')
class-attribute
instance-attribute
¶
queries = Field(default_factory=list, description='Targeted search queries.')
class-attribute
instance-attribute
¶
rationale = Field(default='', description='Short explanation of why search is or is not needed.')
class-attribute
instance-attribute
¶
should_search = Field(default=False, description='Whether external evidence retrieval should run for this node.')
class-attribute
instance-attribute
¶
Methods:¶
coerce_rationale(v)
classmethod
¶
Mirror the coercion on ExternalEvidenceRequest.rationale.
normalize_queries(value)
classmethod
¶
Source code in ontocast/onto/model.py
ExternalEvidenceRequest
¶
Bases: BaseModel
Node-level request for optional web search.
Nodes use this to explicitly signal whether downstream evidence planning/fetching should run for another pass.
Source code in ontocast/onto/model.py
Attributes¶
confidence = Field(default=0.0, ge=0.0, le=1.0, description='Confidence in this search decision.')
class-attribute
instance-attribute
¶
initiate_search = Field(default=False, description='Whether this node requests external evidence before retrying.')
class-attribute
instance-attribute
¶
query_hints = Field(default_factory=list, description='Optional focused query hints for planner targeting.')
class-attribute
instance-attribute
¶
rationale = Field(default='', description='Short reason explaining why search is needed (or not needed).')
class-attribute
instance-attribute
¶
Methods:¶
coerce_rationale(v)
classmethod
¶
normalize_query_hints(value)
classmethod
¶
Source code in ontocast/onto/model.py
FactsCompletionReport
¶
Bases: BaseModel
Output of the insert-only facts completion pass.
Structurally the ADD-only slice of :class:FactsCritiqueReport: no
success/score because this pass does not judge the render, and no
systemic_critique_summary because there is nothing to summarize beyond
the fixes themselves. No web-search request either -- the pass runs after
the critic loop has already used its evidence budget.
Source code in ontocast/onto/model.py
Attributes¶
proposed_fixes = Field(default_factory=list, description='One fix per new subject closure, action ADD only -- never REMOVE or REPLACE, and `triple_ids` is unused. `correct_value` holds every triple the closure needs (rdf:type, the recovered measurement, rdfs:label), attached to an existing catalog-typed subject when the EXISTING SUBJECTS chapter offers one for the same entity rather than minting a duplicate.')
class-attribute
instance-attribute
¶
FactsCritiqueReport
¶
Bases: BaseModel
Source code in ontocast/onto/model.py
Attributes¶
actionable_triple_fixes = Field(default_factory=list, description='List of specific fixes to correct the facts graph. For each fix, provide text evidence, action type, and relevant triples in deployment graph syntax (Turtle or JSON-LD per output instructions).')
class-attribute
instance-attribute
¶
external_evidence_request = Field(default_factory=ExternalEvidenceRequest, description='Optional request to run web search before retrying.')
class-attribute
instance-attribute
¶
score = Field(ge=0, le=100, description='Score 0-100 for how well the triples of facts represent the original document. 0 is the worst, 100 is the best.')
class-attribute
instance-attribute
¶
success = Field(description='True if the facts triples fully represent the document, False otherwise.')
class-attribute
instance-attribute
¶
systemic_critique_summary = Field(default='', description='A high-level, non-itemized summary of systemic or pattern-based issues identified across the facts graph.\nFocus on strategic problems rather than individual triple fixes, such as:\n- Consistent failure to extract certain data types (e.g., dates, currencies)\n- Structural patterns like creating entities instead of reusing existing ontology entities\n- Repeated misinterpretation of specific ontology properties or classes\n- Missing coverage of entire categories of information\n\nThis guides strategic improvements to the fact-extraction process.')
class-attribute
instance-attribute
¶
Methods:¶
coerce_score(v)
classmethod
¶
FactsDomainRepairReport
¶
Bases: BaseModel
Output of the facts domain-repair call.
Each fix replaces one listed statement by the same subject and object linked through a property whose domain fits the subject; anything else is dropped before it is applied.
Source code in ontocast/onto/model.py
Attributes¶
proposed_fixes = Field(default_factory=list, description='One REPLACE per statement repaired, citing its id in `triple_ids`; `correct_value` is that statement with the same subject and object and the fitting property. A statement no property fits is left out.')
class-attribute
instance-attribute
¶
FactsGateRepairKind
¶
Bases: StrEnum
Kinds of machine-applied repair at the post-aggregation gate.
Distinct from :class:FactsUnitFindingKind: these are shape-driven and
apply to the merged graph, where the SHACL report is available.
Source code in ontocast/onto/model.py
Attributes¶
CODE_RESOLVED = 'code_resolved'
class-attribute
instance-attribute
¶
DATE_VALUE_ADDED = 'date_value_added'
class-attribute
instance-attribute
¶
DOMAIN_VIOLATION_DROPPED = 'domain_violation_dropped'
class-attribute
instance-attribute
¶
LITERAL_VARIANT_PRUNED = 'literal_variant_pruned'
class-attribute
instance-attribute
¶
MALFORMED_IRI_DROPPED = 'malformed_iri_dropped'
class-attribute
instance-attribute
¶
QUARANTINE_AS_COMMENT = 'quarantine_as_comment'
class-attribute
instance-attribute
¶
SELF_LOOP_DROPPED = 'self_loop_dropped'
class-attribute
instance-attribute
¶
SHACL_CODE_RESOLVED = 'shacl_code_resolved'
class-attribute
instance-attribute
¶
SHACL_PRUNE = 'shacl_prune'
class-attribute
instance-attribute
¶
SHACL_RETYPE = 'shacl_retype'
class-attribute
instance-attribute
¶
UNLINKED_DROPPED = 'unlinked_dropped'
class-attribute
instance-attribute
¶
UNTYPED_DROPPED = 'untyped_dropped'
class-attribute
instance-attribute
¶
FactsIsolatedInstance
¶
Bases: BaseModel
An instance the served facts link to nothing, kept and listed.
kind is read from structure, not vocabulary: holds_value when it
carries a value or a non-annotation literal (a statement with no subject,
such as an observation of nothing), other when it carries neither.
Source code in ontocast/onto/model.py
FactsRenderReport
¶
Bases: BaseModel
Facts rendering output with optional search decision.
Source code in ontocast/onto/model.py
Attributes¶
external_evidence_request = Field(default_factory=ExternalEvidenceRequest, description='Optional request to run web search before retrying.')
class-attribute
instance-attribute
¶
semantic_graph = Field(default_factory=RDFGraph, description='Semantic triples (facts) representing the document. Encoding is defined by deployment llm_graph_format and OUTPUT INSTRUCTION.')
class-attribute
instance-attribute
¶
FactsUnitFinding
¶
Bases: UnitFinding[FactsUnitFindingKind]
One deterministic, machine-found issue in a rendered facts graph.
Source code in ontocast/onto/model.py
FactsUnitFindingKind
¶
Bases: StrEnum
Kinds of deterministic per-unit facts findings.
Source code in ontocast/onto/model.py
Attributes¶
CLASS_ALIAS = 'class_alias'
class-attribute
instance-attribute
¶
CLOSED_RANGE_LITERAL = 'closed_range_literal'
class-attribute
instance-attribute
¶
COMPACT_IRI_LITERAL = 'compact_iri_literal'
class-attribute
instance-attribute
¶
CRITIC_FIX = 'critic_fix'
class-attribute
instance-attribute
¶
DOMAIN_ADHERENCE = 'domain_adherence'
class-attribute
instance-attribute
¶
DOMAIN_VIOLATION = 'domain_violation'
class-attribute
instance-attribute
¶
ENTAILED_TYPE = 'entailed_type'
class-attribute
instance-attribute
¶
LABEL_ONLY_NUMBER = 'label_only_number'
class-attribute
instance-attribute
¶
LITERAL_TYPE_OBJECT = 'literal_type_object'
class-attribute
instance-attribute
¶
NUMERIC_COVERAGE = 'numeric_coverage'
class-attribute
instance-attribute
¶
PAIRED_OBJECT_PROPERTY = 'paired_object_property'
class-attribute
instance-attribute
¶
PROPERTY_ALIAS = 'property_alias'
class-attribute
instance-attribute
¶
QUARANTINED_LITERAL = 'quarantined_literal'
class-attribute
instance-attribute
¶
SCALAR_AS_BOUNDS = 'scalar_as_bounds'
class-attribute
instance-attribute
¶
STATEMENT_WITHOUT_SUBJECT = 'statement_without_subject'
class-attribute
instance-attribute
¶
TRIPLE_REVERSED = 'triple_reversed'
class-attribute
instance-attribute
¶
UNIT_SYMBOL_CASE_MISMATCH = 'unit_symbol_case_mismatch'
class-attribute
instance-attribute
¶
UNKNOWN_TERM = 'unknown_term'
class-attribute
instance-attribute
¶
UNTYPED_INSTANCE = 'untyped_instance'
class-attribute
instance-attribute
¶
FactsValidationFinding
¶
Bases: BaseModel
One invariant violation detected in the aggregated facts graph.
Error-severity findings of the merge-signature kinds
(FUNCTIONAL_VIOLATION, SUSPECT_MULTI_VALUE,
DEGENERATE_COREFERENCE) on subjects that resulted from an identity
merge drive the deterministic un-merge repair (full-cluster pair vetoes
plus re-aggregation). SHACL findings never drive it — a constraint
violation says a node is under-specified, not that two entities were
wrongly identified. Warning findings are telemetry only.
Source code in ontocast/onto/model.py
Attributes¶
component = Field(default='', description='SHACL constraint component IRI (sh:MinCountConstraintComponent, …) for SHACL findings; empty otherwise. Grouping by it is what turns a list of violations into a diagnosis.')
class-attribute
instance-attribute
¶
kind
instance-attribute
¶
message
instance-attribute
¶
predicate = ''
class-attribute
instance-attribute
¶
severity = 'error'
class-attribute
instance-attribute
¶
source_shape = Field(default='', description='SHACL shape that reported the violation; empty otherwise.')
class-attribute
instance-attribute
¶
subject = ''
class-attribute
instance-attribute
¶
values = Field(default_factory=list)
class-attribute
instance-attribute
¶
FactsValidationFindingKind
¶
Bases: StrEnum
Kinds of deterministic post-aggregation facts findings.
Source code in ontocast/onto/model.py
Attributes¶
DANGLING_REFERENCE = 'dangling_reference'
class-attribute
instance-attribute
¶
DEGENERATE_COREFERENCE = 'degenerate_coreference'
class-attribute
instance-attribute
¶
FUNCTIONAL_VIOLATION = 'functional_violation'
class-attribute
instance-attribute
¶
MIXED_OBJECT_KINDS = 'mixed_object_kinds'
class-attribute
instance-attribute
¶
NON_CATALOG_VOCABULARY = 'non_catalog_vocabulary'
class-attribute
instance-attribute
¶
SHACL = 'shacl'
class-attribute
instance-attribute
¶
SUSPECT_MULTI_VALUE = 'suspect_multi_value'
class-attribute
instance-attribute
¶
FreshOntologyRenderReport
¶
Bases: BaseModel
A fresh ontology's terms, rendered under the document's home ontology.
Source code in ontocast/onto/model.py
Attributes¶
external_evidence_request = Field(default_factory=ExternalEvidenceRequest, description='Optional request to run web search before retrying.')
class-attribute
instance-attribute
¶
graph = Field(default_factory=RDFGraph, description="Classes, properties and axioms under the home ontology's namespace. No owl:Ontology header: identity and versioning are written by code.")
class-attribute
instance-attribute
¶
GraphRepairRecord
¶
Bases: BaseModel
One machine-applied deterministic rewrite on a rendered graph.
LLM-free by construction: every repair either rewrites a term the catalog
already declares, removes a node that asserts nothing, or states what a
term's own name already says (a label derived from its local name).
Records what the repair passes changed (near-miss predicate rewrites,
literal rdf:type coercions, shape-driven retyping/pruning, derived
labels) so downstream consumers can distinguish machine-altered triples
from what the LLM asserted. kind is the finding the repair resolves.
Source code in ontocast/onto/model.py
GraphUpdateRenderReport
¶
Bases: BaseModel
Ontology render output: the triples to insert and the triples to delete.
Source code in ontocast/onto/model.py
Attributes¶
delete_graph = Field(default_factory=RDFGraph, description='Triples to REMOVE, matching the stored triples exactly. Encoding is defined by deployment llm_graph_format and OUTPUT INSTRUCTION. Omit or leave empty when removing nothing.')
class-attribute
instance-attribute
¶
external_evidence_request = Field(default_factory=ExternalEvidenceRequest, description='Optional request to run web search before retrying.')
class-attribute
instance-attribute
¶
insert_graph = Field(default_factory=RDFGraph, description='Triples to ADD. Encoding is defined by deployment llm_graph_format and OUTPUT INSTRUCTION. Omit or leave empty when adding nothing.')
class-attribute
instance-attribute
¶
Methods:¶
to_graph_update()
¶
Compile the wire payload into an ordered patch.
Deletes are ordered before inserts, and an empty side contributes no operation. Interleaving the two within a single render is not expressible on this wire: it would only matter for a patch that removes and re-adds the same triple, which nets out to nothing.
Source code in ontocast/onto/model.py
LoopAttempt
¶
Bases: BaseModel
Telemetry record for one attempt inside a per-unit render/critic loop.
Shared by the facts and the ontology loop — the fields are phase-neutral
and a record's home (``UnitFactsState.attempt_log`` vs
``UnitOntologyState.attempt_log``) says which loop produced it.
``n_deterministic_findings`` / ``n_mandatory_findings`` count findings
against the graph as of this record: for ``llm_repair`` records that is the
residual *after* the repair render, so summing the last repair record per
unit yields the true document-level residual.
kind="critic_patch" is the LLM-free application of a critique: it costs
nothing and is recorded separately from the critic call that produced
the fixes, so "what the critique cost" and "what it changed" stay
distinguishable. kind="llm_repair" is retained for artifacts written by
earlier releases, when a separate finding-driven repair render existed.
kind="critic_skipped" records a pass the loop decided not to spend --
no call was made -- with the reason in accept_reason
(empty_render, citation_metadata). A critic record whose
accept_reason is critic_unavailable is a call made that
produced no critique; the unit leaves the loop unreviewed.
kind="completion" is the insert-only completion pass;
kind="domain_repair" the call that gives a statement violating a
declared domain a property that fits its subject.
Source code in ontocast/onto/model.py
1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 | |
Attributes¶
accept_reason = ''
class-attribute
instance-attribute
¶
action_severity_counts = Field(default_factory=dict, description="Proposed fixes keyed 'ACTION:severity'. Severity alone cannot be read: a REMOVE never blocks acceptance whatever its severity, so 'critical' counts mix fixes that gate a render with fixes that cannot. Splitting by action is what makes the two distinguishable from the artifacts.")
class-attribute
instance-attribute
¶
critic_attempt = 0
class-attribute
instance-attribute
¶
delta_triple_count = None
class-attribute
instance-attribute
¶
failure_reason = None
class-attribute
instance-attribute
¶
failure_stage = None
class-attribute
instance-attribute
¶
incumbent_accepted = Field(default=None, description='What the retired score gate would have decided for this critic attempt, recorded so the switch to a findings-based gate can be judged against a distribution rather than an argument.')
class-attribute
instance-attribute
¶
kind = 'render'
class-attribute
instance-attribute
¶
n_actionable_fixes = 0
class-attribute
instance-attribute
¶
n_detached_linked = Field(default=0, description='Completion pass only: instances linked to nothing before the pass that are linked after the inserts that stayed.')
class-attribute
instance-attribute
¶
n_deterministic_findings = 0
class-attribute
instance-attribute
¶
n_fixes_applied = 0
class-attribute
instance-attribute
¶
n_fixes_junk_refused = Field(default=0, description='Inserts refused at compile time for minting a placeholder: a subject named for an ignored token or artifact, or a new node carrying only annotations and no type.')
class-attribute
instance-attribute
¶
n_fixes_noop = Field(default=0, description='Fixes whose delete set and insert set were the same statements. Counted because a critique made mostly of these is a critic producing motion rather than corrections.')
class-attribute
instance-attribute
¶
n_fixes_rolled_back = 0
class-attribute
instance-attribute
¶
n_fixes_targeting_snapshot = 0
class-attribute
instance-attribute
¶
n_fixes_unresolved_prefix = Field(default=0, description='Fixes whose payload named a prefix nothing declared, so the statement it meant could not be identified.')
class-attribute
instance-attribute
¶
n_mandatory_findings = 0
class-attribute
instance-attribute
¶
n_measurements_recovered = Field(default=0, description='Completion pass only: missed measurements the numeric inventory no longer lists after the inserts that stayed.')
class-attribute
instance-attribute
¶
n_subjects_linked = Field(default=0, description='Completion pass only: statement_without_subject findings that no longer hold after the inserts that stayed.')
class-attribute
instance-attribute
¶
n_triples_deleted = 0
class-attribute
instance-attribute
¶
n_triples_inserted = 0
class-attribute
instance-attribute
¶
patch_delete_capped = Field(default=False, description='The delete-share cap fired: the pass kept its inserts and dropped its deletes.')
class-attribute
instance-attribute
¶
patch_rolled_back = Field(default=False, description='At least one fix of the pass was undone for leaving the unit worse. Fixes are applied and judged one at a time, so the rest of the pass stands; ``n_fixes_rolled_back`` says how many went.')
class-attribute
instance-attribute
¶
render_attempt = 0
class-attribute
instance-attribute
¶
repair_delete_only = False
class-attribute
instance-attribute
¶
repair_failed = False
class-attribute
instance-attribute
¶
rolled_back_fixes = Field(default_factory=list, description='The undone fixes, each with the reason it was refused.')
class-attribute
instance-attribute
¶
score = None
class-attribute
instance-attribute
¶
severity_counts = Field(default_factory=dict)
class-attribute
instance-attribute
¶
success = None
class-attribute
instance-attribute
¶
triple_count = 0
class-attribute
instance-attribute
¶
OntologyConsolidationReport
¶
Bases: BaseModel
Term actions for one batch of minted terms.
Source code in ontocast/onto/model.py
OntologyCritiqueReport
¶
Bases: BaseModel
Report from ontology update critique process.
Source code in ontocast/onto/model.py
Attributes¶
actionable_ontology_fixes = Field(default_factory=list, description='List of specific fixes to correct the ontology graph. For each fix, provide text evidence, action type, and relevant triples in deployment graph syntax (Turtle or JSON-LD per output instructions).')
class-attribute
instance-attribute
¶
external_evidence_request = Field(default_factory=ExternalEvidenceRequest, description='Optional request to run web search before retrying.')
class-attribute
instance-attribute
¶
score = Field(ge=0, le=100, description='Score 0-100 for how well the presented ontology serves as the ontology for the document. 0 is the worst, 100 is the best.')
class-attribute
instance-attribute
¶
success = Field(description='True if the presented ontology is appropriate, complete, consistent and represents well the domain of the provided text, False otherwise.')
class-attribute
instance-attribute
¶
systemic_critique_summary = Field(default='', description='A high-level summary of systemic deficiencies in the ontology (e.g., poor hierarchy structure, redundant concepts, lack of appropriate granularity, or general failures in Domain Coverage). This addresses strategic issues beyond individual term fixes.')
class-attribute
instance-attribute
¶
Methods:¶
coerce_score(v)
classmethod
¶
OntologyIdentityProposal
¶
Bases: BaseModel
What the model proposes for a document's home ontology.
The IRI is never proposed: code mints it from ontology_id. A handle
the catalog list shows means the document extends that ontology; any other
value names a new one and must be a mintable id. Validated with the
context key catalog_handles (the shown handles); without it, only a
mintable id passes.
Source code in ontocast/onto/model.py
Attributes¶
description = Field(min_length=1, max_length=1200, description='3-4 sentences: domain, purpose, scope, applicability.')
class-attribute
instance-attribute
¶
ontology_id = Field(description="The handle of a catalog ontology to extend it, or a new short lowercase id (2-32 chars, letters, digits, '_' or '-', starting with a letter), e.g. 'abc' for a hypothetical A... B... C... Ontology.")
class-attribute
instance-attribute
¶
title = Field(min_length=1, max_length=200, description='Ontology title (a short noun phrase).')
class-attribute
instance-attribute
¶
OntologyPlan
¶
Bases: BaseModel
A document's accepted plan: the terms its units may mint or must reuse.
Source code in ontocast/onto/model.py
Attributes¶
generic_sides = 0
class-attribute
instance-attribute
¶
prefixes = Field(default_factory=dict)
class-attribute
instance-attribute
¶
rejected = Field(default_factory=list)
class-attribute
instance-attribute
¶
resolved_to_catalog = 0
class-attribute
instance-attribute
¶
terms = Field(default_factory=list)
class-attribute
instance-attribute
¶
Methods:¶
minted()
¶
OntologyPlanReport
¶
Bases: BaseModel
The model's proposal list for one document: the plan's wire form.
Source code in ontocast/onto/model.py
OntologyPlanTerm
¶
Bases: BaseModel
One accepted plan entry, after the model-free catalog check.
Source code in ontocast/onto/model.py
Attributes¶
decision
instance-attribute
¶
definition = ''
class-attribute
instance-attribute
¶
domain_iri = None
class-attribute
instance-attribute
¶
iri
instance-attribute
¶
kind
instance-attribute
¶
label
instance-attribute
¶
local_name
instance-attribute
¶
nearest = Field(default_factory=list)
class-attribute
instance-attribute
¶
parent_iri = None
class-attribute
instance-attribute
¶
range_iri = None
class-attribute
instance-attribute
¶
OntologySelectorReport
¶
Bases: BasePydanticModel
Base class for ontology selection report.
Note: Use create_ontology_selector_report_model() to create a model with the correct answer_index constraint.
Source code in ontocast/onto/model.py
OntologyTermAction
¶
Bases: BaseModel
One decision about a minted term.
keep leaves it; merge_into replaces it by target everywhere;
generalise_to makes target its only parent; demote_to_property_value
turns a class into a SKOS concept (a value of some property); drop
removes it and every triple naming it.
Source code in ontocast/onto/model.py
Attributes¶
action = Field(description="'keep', 'merge_into', 'generalise_to', 'demote_to_property_value' or 'drop'.")
class-attribute
instance-attribute
¶
rationale = Field(default='', max_length=300)
class-attribute
instance-attribute
¶
target = Field(default=None, description='For merge_into and generalise_to: a listed term, catalog term or well-known term. Empty otherwise.')
class-attribute
instance-attribute
¶
term = Field(description="The term's IRI or CURIE, as listed.")
class-attribute
instance-attribute
¶
OntologyTermProposal
¶
Bases: BaseModel
One term the model proposes a document adds to its domain.
Source code in ontocast/onto/model.py
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 831 832 833 834 835 836 837 838 | |
Attributes¶
definition = Field(default='', max_length=600, description='One sentence: what any instance of the term is, domain-wide.')
class-attribute
instance-attribute
¶
domain = Field(default=None, description="Property only: the most specific class every subject of the property belongs to (a catalog term, a well-known term or another proposal's local name). Thing, Concept or an Agent class only when nothing more specific fits. Empty for a class.")
class-attribute
instance-attribute
¶
justification = Field(default='', max_length=400, description='Why a second document in the domain would use this term: not why this document mentions it.')
class-attribute
instance-attribute
¶
kind = Field(description="'class', 'object_property' or 'datatype_property'.")
class-attribute
instance-attribute
¶
label = Field(min_length=1, max_length=120, description='rdfs:label.')
class-attribute
instance-attribute
¶
local_name = Field(description='Local name in the home namespace: PascalCase for a class, camelCase for a property, letters and digits only.')
class-attribute
instance-attribute
¶
parent = Field(default=None, description="Superclass (class) or superproperty (property): a term listed in the catalog, a well-known vocabulary term, or another proposal's local name. Empty for none.")
class-attribute
instance-attribute
¶
range = Field(default=None, description='Property only: the most specific class every value belongs to, or an XSD datatype for a datatype property. For values from a fixed list, a proposed class of those values under skos:Concept. Thing, Concept or an Agent class only when nothing more specific fits. Empty for a class.')
class-attribute
instance-attribute
¶
reuse = Field(default=None, description='A listed catalog term or well-known term that already names this concept. Set it instead of minting; leave empty for a new term.')
class-attribute
instance-attribute
¶
OntologyUnitFinding
¶
Bases: UnitFinding[OntologyUnitFindingKind]
One deterministic, machine-found issue in a unit's ontology delta.
Source code in ontocast/onto/model.py
OntologyUnitFindingKind
¶
Bases: StrEnum
Kinds of deterministic per-unit ontology findings.
Computed against the unit's net insert/delete delta, never the whole
working graph — validating snapshot+delta would attribute every
pre-existing catalog defect to this unit, and the facts UNKNOWN_TERM
rule is semantically inverted here (minting new terms is the ontology
renderer's job).
Source code in ontocast/onto/model.py
Attributes¶
CARDINALITY_CONTRADICTION = 'cardinality_contradiction'
class-attribute
instance-attribute
¶
CATALOG_DUPLICATE = 'catalog_duplicate'
class-attribute
instance-attribute
¶
DEGENERATE_RESTRICTION = 'degenerate_restriction'
class-attribute
instance-attribute
¶
FOREIGN_DELETE = 'foreign_delete'
class-attribute
instance-attribute
¶
FOREIGN_NAMESPACE = 'foreign_namespace'
class-attribute
instance-attribute
¶
HIERARCHY_TOO_DEEP = 'hierarchy_too_deep'
class-attribute
instance-attribute
¶
LABEL_COLLISION = 'label_collision'
class-attribute
instance-attribute
¶
MISSING_LABEL = 'missing_label'
class-attribute
instance-attribute
¶
ROLE_CONFUSION = 'role_confusion'
class-attribute
instance-attribute
¶
SPECIFIC_LABEL_LEAF = 'specific_label_leaf'
class-attribute
instance-attribute
¶
SUBCLASS_CYCLE = 'subclass_cycle'
class-attribute
instance-attribute
¶
VALUE_SET_SIBLINGS = 'value_set_siblings'
class-attribute
instance-attribute
¶
RolledBackFix
¶
Bases: BaseModel
One critic fix applied and undone on its own for leaving the unit worse.
Carried on the critic_patch attempt that rolled it back, so a dump
shows which correction was refused and why -- previously the whole
pass was undone and the record said only that it had been.
Source code in ontocast/onto/model.py
Suggestions
¶
Bases: BaseModel
Report from knowledge graph critique process.
Attributes:
| Name | Type | Description |
|---|---|---|
systemic_critique_summary |
str
|
A compilation of general improvement suggestions. |
actionable_fixes |
list[TripleFix]
|
An itemized list of concrete suggestions for improvement. |
Source code in ontocast/onto/model.py
1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 | |
Attributes¶
actionable_fixes = Field(default_factory=list, description='An itemized list of concrete suggestions for improvement.')
class-attribute
instance-attribute
¶
systemic_critique_summary = Field(default='', description='A general improvement suggestion.')
class-attribute
instance-attribute
¶
Methods:¶
coerce_systemic_critique_summary(v)
classmethod
¶
from_critique_report(critique)
classmethod
¶
Create Suggestions from any critique report.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
critique
|
OntologyCritiqueReport | FactsCritiqueReport
|
Either an OntologyCritiqueReport or FactsCritiqueReport to convert. |
required |
Returns:
| Type | Description |
|---|---|
Suggestions
|
Suggestions object with actionable fixes and systemic critique summary. |
Source code in ontocast/onto/model.py
to_markdown()
¶
Convert actionable fixes and systemic critique summary to a unified markdown block.
Returns:
| Type | Description |
|---|---|
str
|
Markdown formatted string with both actionable fixes and systemic critique summary. |
Source code in ontocast/onto/model.py
TripleFix
¶
Bases: BaseModel
A single actionable correction to an RDF facts or ontology graph.
incorrect_value / correct_value are plain strings; encoding follows
deployment llm_graph_format and GRAPH FORMAT INSTRUCTION.
Source code in ontocast/onto/model.py
227 228 229 230 231 232 233 234 235 236 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 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 | |
Attributes¶
action = Field(description='Type of fix:\n- ADD: Add new triple, prefix declaration, or missing information\n- REMOVE: Delete incorrect or redundant triple\n- REPLACE: Substitute one entity, property, or literal for another')
class-attribute
instance-attribute
¶
correct_value = Field(default=None, description='Proposed correct triple/entity/value (for ADD and REPLACE). Encoding is defined by deployment llm_graph_format and GRAPH FORMAT INSTRUCTION.')
class-attribute
instance-attribute
¶
explanation = Field(default='', description="Why this fix is needed. Examples:\n- 'Missing xsd:date datatype for temporal literal'\n- 'Namespace prefix fca: not declared'\n- 'Property onto:decidedBy is canonical, not cd:judgedBy'")
class-attribute
instance-attribute
¶
incorrect_value = Field(default=None, description='Legacy. Prefer `triple_ids`. Only consulted when a REMOVE or REPLACE cites no ids, because a retyped statement matches the stored one a minority of the time.')
class-attribute
instance-attribute
¶
severity = Field(description="Severity level: 'critical' (breaks semantic graph), 'important' (significant gap), or 'minor' (polish). Note: 'major' will be automatically converted to 'important'.")
class-attribute
instance-attribute
¶
target = Field(default=None, description="What is being fixed. Examples:\n- 'triple' (for triple-level changes)\n- 'entity' (replacing cd: with ontology entity)\n- 'property' (using correct property)\n- 'datatype' (fixing literal type)\n- 'prefix' (adding namespace declaration)\n- 'language_tag' (adding/fixing @lang)")
class-attribute
instance-attribute
¶
text_fragment = Field(description='Exact quote from source text justifying this change')
class-attribute
instance-attribute
¶
triple_ids = Field(default_factory=list, description='Ids of the statements this fix removes, taken from the bracketed numbers in the graph chapter. REQUIRED for REMOVE and REPLACE. Cite the id; never retype the statement.')
class-attribute
instance-attribute
¶
Methods:¶
coerce_free_text(v)
classmethod
¶
Coerce the two free-text fields.
A provider answering either with a bulleted list would otherwise raise
and discard the whole critique report. explanation defaults to empty:
a fix is actionable without it, and a report missing it is not worth a
second call. Deliberately
not applied to incorrect_value/correct_value: those carry graph
syntax, where joining a list would corrupt the payload rather than
recover it.
Source code in ontocast/onto/model.py
coerce_triple_ids(v)
classmethod
¶
Accept the shapes providers actually return for a list of ints.
A bare 12, a string "12", a stringified list "[12, 13]" and a
list of strings all mean the same thing. This field is the only way a
REMOVE or REPLACE can address anything, so a formatting quirk here would
discard the fix -- and, because the report validates as a whole, every
other fix alongside it.
Source code in ontocast/onto/model.py
normalize_severity(v)
classmethod
¶
Normalize severity values to accepted literals.
Maps 'major' to 'important' for backward compatibility with prompts that use 'major' terminology. This allows the LLM to use either term.
Source code in ontocast/onto/model.py
to_markdown()
¶
Convert this TripleFix to markdown format.
Returns:
| Type | Description |
|---|---|
str
|
Markdown formatted string representing this fix. |
Source code in ontocast/onto/model.py
UnitFailure
¶
Bases: BaseModel
One content unit that produced no usable output.
Carried to the document level so a caller can tell "nothing to extract"
from "every unit failed" -- previously both produced an empty result with
status: success.
Source code in ontocast/onto/model.py
UnitFinding
¶
Bases: BaseModel, Generic[FindingKindT]
One deterministic, machine-found issue in a rendered unit graph.
Base shape shared by the facts and ontology validators; the subclasses
pin kind to their own enum. Mandatory findings are violations the
renderer must fix; non-mandatory findings list candidates the renderer
adjudicates item by item.
Source code in ontocast/onto/model.py
Attributes¶
facet = Field(default='', description="Variant within ``kind`` for findings that come in more than one: numeric coverage is split into 'measurements' (a number written with its unit) and 'unclassified' (a bare number).")
class-attribute
instance-attribute
¶
kind
instance-attribute
¶
mandatory = True
class-attribute
instance-attribute
¶
message
instance-attribute
¶
predicate = ''
class-attribute
instance-attribute
¶
subject = ''
class-attribute
instance-attribute
¶
suggestions = Field(default_factory=list)
class-attribute
instance-attribute
¶
value = ''
class-attribute
instance-attribute
¶
Functions:¶
create_ontology_selector_report_model(num_ontologies)
¶
Create a dynamic OntologySelectorReport model with answer_index constraint.
The answer_index field is constrained to be between 1 and num_ontologies + 1, where: - 1 to num_ontologies: corresponds to the ontology at that index (1-based) - num_ontologies + 1: represents "None" (no suitable ontology)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
num_ontologies
|
int
|
The number of ontologies in the selection list. |
required |
Returns:
| Type | Description |
|---|---|
type[BasePydanticModel]
|
A dynamically created Pydantic model class with the appropriate constraint. |
Source code in ontocast/onto/model.py
format_findings_for_prompt(findings, *, advisory_heading='## Verify numeric coverage')
¶
Render findings as MANDATORY-fixes + advisory blocks for a prompt.
The default advisory heading is the facts loop's (its only advisory kind is numeric coverage) and is part of prompts already in the LLM cache — callers with different advisory content pass their own heading rather than changing the default.