Facts validation¶
The facts critic, repairs, acceptance rules and SHACL validation.
FACTS_OBJECT_PROPERTY_LITERAL_CHECK¶
Quarantine string literals sitting on predicates whose schema range is a class (e.g. qudt:unit with range qudt:Unit). Quarantined triples are surfaced to the facts critic so the renderer resolves the token to an IRI from the ontology context.
FACTS_CRITIC_PASSES¶
Review-and-patch passes per facts unit, in LLM calls. Each pass re-runs the deterministic checks for free, sends the graph and its findings to the critic, and applies what comes back as a compiled patch. At the default of 1 a unit costs two provider calls: one extraction, one review. Set 0 for extraction only, leaving findings to the LLM-free repairs and the gate.
FACTS_CRITIC_MAX_DELETE_SHARE¶
Largest share of a unit graph one critic pass may remove. Beyond it, fixes that remove statements are returned as residual findings and only pure additions are applied: a critique that removes this much is rewriting the graph rather than correcting it.
FACTS_CRITIC_MIN_DELETES¶
Deletions always permitted regardless of share. Without a floor the share cap is strictest on short units, where a single legitimate correction is already a large fraction of the graph.
FACTS_CRITIC_ALLOW_SUBJECT_RENAME¶
Whether a critic REPLACE fix may delete statements about one subject while writing about another. That is a rename, and applied literally it orphans the old node and leaves the new one bare.
FACTS_PROPERTY_ALIAS_MIN_RATIO¶
Similarity floor (SequenceMatcher ratio) for choosing among candidates in the near-miss property rewrite. A predicate found neither in the unit's context nor in the catalog is rewritten only to a catalog term whose name tokens contain, are contained in, or equal its own; when several qualify, the best wins if it clears this ratio. Similarity alone never triggers a rewrite.
FACTS_MERGE_REPAIR_PASSES¶
Deterministic un-merge budget at the post-aggregation validation gate: error findings on merged subjects turn into full-cluster pair vetoes and the facts units are re-aggregated, up to this many passes. 0 records findings without repairing.
FACTS_ACCEPT_BLOCKING_SEVERITY¶
Which critic-assigned severities keep a unit in the render/critic loop. Deterministic mandatory findings always block; this threshold applies only to the severity label the LLM critic gives its own fixes. The critic labels most fixes 'important', so 'critical' is the only level that discriminates. 'never' lets deterministic findings decide alone.
FACTS_NUMERIC_IDENTIFIER_GUARD¶
Leave digit groups that belong to an identifier, such as a file number, a date or a citation, out of the numeric-coverage inventory, so the critic is not asked to model them as quantities. Only digits joined to an identifier inside one token are dropped; a number with a unit attached ('5mg') still counts. false lists every digit group.
FACTS_CONTEXT_FROM_UNITS¶
In facts-only runs, build the document-level ontology context from the snapshots the units resolved. With no ontology stage that context is otherwise empty: entity merging loses the type and functionality declarations its guards read, and validation skips every check that needs a vocabulary (reported as validated_without_ontology_context in the retrieval metrics).
FACTS_SUSPECT_MULTI_VALUE_SEVERITY¶
Severity of SUSPECT_MULTI_VALUE gate findings (multiple distinct numeric values on one predicate, or multiple objects on a dominantly single-valued predicate). Only error findings drive the un-merge repair.
FACTS_SUSPECT_MULTI_VALUE_REQUIRE_CROSS_UNIT¶
Report a multi-valued IRI predicate as an error only when the values came from merging different units; otherwise report a warning. Errors trigger the un-merge repair, which would remove a statement that one unit genuinely made with two objects. Numeric and string values are not affected: two distinct quantities on one node are always a defect.
FACTS_DOMAIN_ADHERENCE_MIN_SHARE¶
Minimum fraction of a render's distinct schema terms (predicates and rdf:type objects, excluding minted instances and RDF, RDFS, OWL, XSD, SKOS, DC and PROV) that must come from the unit's ontology context; below it a mandatory DOMAIN_ADHERENCE finding asks for a rewrite. It catches renders that use a generic vocabulary throughout, which every per-triple check and shape accepts. 0 disables it; keep it disabled when extracting without a catalog, and calibrate it from domain_adherence in the facts findings.
FACTS_DOMAIN_ADHERENCE_MIN_TERMS¶
Fewest distinct schema terms a render must use before its catalog share is judged at all. A share over one or two terms is noise: a front-matter unit that types an identifier and an author with generic vocabulary has not abandoned the catalog, and the mandatory finding it raised drove the critic into retyping the identifier as a quantity value. 0 judges every non-empty render.
FACTS_ADDITIONAL_STANDARD_NAMESPACES¶
Namespaces exempt from UNKNOWN_TERM findings in addition to the RDF/OWL substrate and annotation/provenance terms. Only meta-vocabularies are built in; a domain vocabulary a deployment genuinely shares across catalogs (SOSA/SSN, CSVW, FOAF, schema.org, Dublin Core application profiles) is exempted here. schema.org is the default because the shipped citation vocabulary uses it.
FACTS_QUANTITY_FALLBACK_VOCABULARY¶
Vocabulary the facts prompt offers for quantities when the retrieved context has no suitable class, as a role-to-IRI mapping: value_class, numeric_value and unit, plus optional lower_bound, upper_bound and roles containing 'inclusive'. Defaults to QUDT; an empty mapping forbids the fallback. Terms named here are exempt from UNKNOWN_TERM and NON_CATALOG_VOCABULARY. When numeric_value and both bounds are set, a range with equal bounds becomes a single value; the unit role also drives the LABEL_ONLY_NUMBER finding.
FACTS_FUNCTIONAL_MIN_SINGLE_SUPPORT¶
Minimum number of single-valued subjects a predicate needs before the gate treats it as empirically functional. Below this the evidence is too thin to call a second value a violation.
FACTS_LITERAL_VARIANT_DEDUPE¶
LLM-free gate repair: collapse duplicate literals that differ only in language tag or datatype on one (subject, predicate) — 'X'@en alongside 'X'^^xsd:string alongside 'X'. The language-tagged form wins, then the plain form; reified provenance moves to the surviving triple.
FACTS_SHAPES_DIR¶
Directory of SHACL shape files (.ttl, searched recursively) loaded at startup into the tenant's shapes partition of the triple store, as ONTOCAST_ONTOLOGY_DIRECTORY is for ontologies. Validation reads the partition, so shapes uploaded through /shapes apply as well. Requires the 'shacl' extra; without it, or with no readable shapes, a warning is logged.
FACTS_SHACL_INFERENCE¶
Inference pyshacl applies before evaluating shapes. 'rdfs' (default) lets a shape that names a superproperty match the more specific predicate the renderer emits, which SHACL property paths do not do on their own; turning it off raises the violation count. Use 'none' for shapes written against exactly the terms the graph uses, or when validation time dominates.
FACTS_SHACL_ADVANCED¶
Enable the SHACL Advanced Features extension (sh:sparql constraints, node expressions). Shapes that do not use it are unaffected.
FACTS_SHAPES_PROMPT_CONTRACT¶
Show the loaded SHACL shapes to the facts renderer and critic as a conformance chapter, so they are prompted with the rules validation applies. Each shape contributes its sh:message, or a generated line when it has none. 'off': no chapter. 'full': every shape, up to shapes_prompt_max_lines. 'context': only shapes whose targets appear in the unit's ontology snapshot. 'auto': 'full' while the catalog fits the line cap, 'context' once it does not. Without shapes the prompt is the same in every mode. Terms the shapes require are exempt from UNKNOWN_TERM.
FACTS_SHAPES_PROMPT_MAX_LINES¶
Cap on rule lines in the shapes conformance chapter. A size guard, not a ranking; when it truncates, the chapter says so, so the model does not read a missing rule as no rule.
FACTS_NUMERIC_COVERAGE_LIMIT¶
Cap on missing-numeric mentions listed in a NUMERIC_COVERAGE finding. Bounds prompt size; ordering is shortest-first presentation order, not relevance. 0 disables the finding entirely.
FACTS_NUMERIC_COVERAGE_MANDATORY¶
Which NUMERIC_COVERAGE findings block a unit's acceptance: 'off' keeps them advisory; 'measurements' blocks on numbers written with a unit that are missing from the graph; 'all' also blocks on bare numbers. true and false are accepted as 'all' and 'off'. Advisory by default because the critic decides per mention whether a number is a quantity.
FACTS_CRITIC_MIN_TRIPLES¶
Skip the facts critic for a unit whose render holds fewer triples than this. A critic shown an empty graph scores it perfect and bills a call for nothing; the default skips exactly the empty renders, which are then recorded as skipped rather than reviewed. 0 reviews every unit.
FACTS_COMPLETION_PASSES¶
Insert-only completion passes per facts unit, in LLM calls, run after the critic loop when numbers written with a unit are still missing from the graph. A pass sees a term sheet, the unit's typed subjects, the text and the missing measurements, and each subject it adds is kept or rolled back by the same regression check as a critic fix. 0 disables it.
FACTS_SHACL_MAX_TRIPLES¶
Skip SHACL validation, with a warning, for graphs larger than this. pyshacl cost grows with graph x shapes, and a skipped run must be visible rather than read as 'conforms'. 0 disables the guard.
FACTS_SHACL_AUTOFIX¶
Repair of SHACL violations without an LLM call. 'rewrite' retypes a literal to the sh:datatype it parses as, and replaces a string with the catalog IRI whose label it matches exactly and uniquely. 'prune' also drops placeholder nodes that violate sh:minCount and state nothing beyond a type and label. Neither invents a value: a node with real data but a missing property stays a finding. 'off' reports only.
FACTS_SHACL_AUTOFIX_PASSES¶
Bounded validate -> autofix -> revalidate loop at the gate. A pass is kept only if it strictly reduces the violation count, so a repair that trades conformance for nothing is reverted.
FACTS_CODE_PREDICATES¶
Predicates whose literal objects are machine codes (UCUM codes, symbols, notations). A code the model emitted, such as qudt:ucumCode 'd' on a value node with no qudt:unit, is resolved to the one catalog individual that declares it. Matching is exact and case-sensitive.