Ontology retrieval¶
How each unit's slice of the ontology catalog is retrieved and sized.
Retrieval¶
VECTOR_STORE_BACKEND¶
Which vector store implementation to use: 'auto' (infer from QDRANT_URI / LANCEDB_ENABLED, disabling vector retrieval when neither is configured), 'qdrant', 'lancedb', or 'none' to disable vector retrieval entirely.
VECTOR_STORE_TOP_K¶
Fused hits each query window offers to ontology-patch retrieval. This is the candidate pool, not the result size: ONTOLOGY_PATCH_MAX_ATOMS caps what is kept, so a deeper pool fills the same budget from a wider field. Costs search time, not prompt size.
VECTOR_STORE_BM25_TOP_K¶
Depth of the sparse (BM25) lane; unset uses TOP_K. Lanes are fused by reciprocal rank, so every hit in a lane votes at full lane weight and depth acts as weight. Lower it to keep the sparse lane for what it finds best (symbols, notations, formulae) without letting its weak tail vote.
VECTOR_STORE_INDUCED_SUBGRAPH_DEPTH¶
Neighborhood expansion depth for induced subgraph retrieval.
VECTOR_STORE_INDUCED_SUBGRAPH_HUB_SEED_COUNT¶
Induced subgraph: number of top-relevance seeds that receive full BFS hub expansion. 0 disables hub-only BFS (all seeds expand).
VECTOR_STORE_INDUCED_SUBGRAPH_ANCESTOR_CLOSURE_DEPTH¶
Induced subgraph schema shell: max rdfs:subClassOf hops upward per class seed.
VECTOR_STORE_INDUCED_SUBGRAPH_MAX_TOTAL_TRIPLES¶
Hard cap on triples returned for induced subgraph retrieval. This, not the atom cap, is what binds in practice: set it too low and every seed-side knob (top_k, max_atoms, MMR, the atom floors) is flat, because the snapshot is already pinned at the cap. Raise this before tuning anything below it; it saturates.
VECTOR_STORE_INDUCED_SUBGRAPH_ESTIMATED_TRIPLES_PER_QUERY¶
Estimated triples per query window, used to divide the induced subgraph's triple budget among seed entities.
VECTOR_STORE_INDUCED_SUBGRAPH_TYPE_PROMOTION_SCORE_FACTOR¶
Fraction of a retrieved seed's score inherited by its promoted rdf:type IRIs during induced-subgraph budgeting. The seed always keeps its own score; this only scales the copy banked on the type. (Transferring the score to the type and zeroing the individual collapsed all typed individuals into a relevance-0 tie broken by raw IRI order, which starved high-ranked seeds under tight triple budgets.)
VECTOR_STORE_INDUCED_SUBGRAPH_SEED_ORDER¶
Seed expansion order under the induced-subgraph triple budget: 'score' expands in global relevance order; 'ontology_round_robin' interleaves seeds across source ontologies so no ontology is starved by another's high scorers. 'score' is the default.
VECTOR_STORE_INDUCED_SUBGRAPH_SYMBOL_PREDICATES¶
Predicate IRIs admitted as seed descriptions in the induced subgraph, between names and glosses (default mirrors lexical_trigger_predicates). Without them a unit individual reaches the prompt label-only and the LLM cannot map surface tokens like 'meV' to its IRI. Empty disables.
VECTOR_STORE_INDUCED_SUBGRAPH_CANDIDATE_PUSHDOWN¶
Build the induced-subgraph working graph from a SPARQL CONSTRUCT of the seeds' bounded neighborhood instead of the merged ontology graphs. Bounds memory and wire volume on large catalogs; on small ones the neighborhood is essentially the whole ontology and there is nothing to gain. Requires a backend with supports_sparql_construct(); falls back silently otherwise.
VECTOR_STORE_PROPOSITION_WINDOW_SENTENCES¶
Sentence window size used for proposition-level retrieval slicing. Bounded in practice by the embedding model's sequence limit, not by this setting: a window longer than the encoder accepts is truncated by the encoder, silently, so widening past that point discards query text rather than matching more of it. Watch chapter/query truncation in the retrieval metrics when raising it.
VECTOR_STORE_PROPOSITION_WINDOW_STRIDE¶
Sentences advanced between query windows; unset strides by the full window, so windows do not overlap. A smaller stride overlaps them, so a statement split across a window boundary still lands in one window, at the cost of more queries.
VECTOR_STORE_PROPOSITION_WINDOW_MAX_CHARS¶
Characters per retrieval query window, used instead of PROPOSITION_WINDOW_SENTENCES when set. Length, not sentence count, decides whether a query works: sentences vary widely in length, and the encoder silently truncates long input. Windows take sentences until the budget is met, which also joins short fragments. Keep it below the encoder's sequence limit (characters per token are in the retrieval metrics). Query side only: no reindex needed.
VECTOR_STORE_PROPOSITION_WINDOW_MAX_TOKENS¶
Encoder tokens per query window; when set it takes precedence over PROPOSITION_WINDOW_SENTENCES and PROPOSITION_WINDOW_MAX_CHARS. Set below the encoder's sequence limit, it makes truncation impossible, and it splits a sentence longer than the budget at a word boundary. Needs an embedding provider that exposes its tokenizer; otherwise it falls back to a character estimate and logs that it did. Query side only: no reindex needed.
VECTOR_STORE_PROPOSITION_WINDOW_OVERLAP¶
Fraction of a window repeated at the start of the next one, under a character or token budget. 0.0 (default) leaves windows disjoint. PROPOSITION_WINDOW_STRIDE is the sentence-granular spelling of the same idea and does not apply under a budget, where a sentence says nothing about how much text is shared. Overlap multiplies queries, so it costs embedding time and, once PROPOSITION_MAX_WINDOWS binds, coverage elsewhere in the unit.
VECTOR_STORE_PROPOSITION_ABBREVIATION_AWARE¶
Rejoin window fragments that the sentence splitter cut at an abbreviation, an initial or a citation, where a window can otherwise hold a few characters with nothing to retrieve. Uses general English and bibliographic patterns only, never a domain vocabulary. Off by default because it changes every window's boundaries.
VECTOR_STORE_PROPOSITION_MEASUREMENT_AWARE¶
Forbid a window break between a number and the unit it is written with, or inside a range, using the number/unit shapes in the shared measurement lexicon (shapes, not a unit vocabulary). Only binds where a cut inside a sentence is possible, which means PROPOSITION_WINDOW_MAX_TOKENS with a sentence over budget: a window ending on 'a red shift of ~10' retrieves nothing that the number and its unit together would.
VECTOR_STORE_PROPOSITION_MAX_WINDOWS¶
Upper bound on proposition windows generated per document excerpt. Over the bound windows are subsampled evenly rather than truncated, so the excerpt stays covered end to end -- but the text in the dropped windows reaches no dense or sparse lane at all.
VECTOR_STORE_PROPOSITION_RETRIEVAL_ENABLED¶
Enable proposition-level multi-query retrieval for induced graph mode.
VECTOR_STORE_CONSISTENCY_CRITIC_MIN_FUSED_SCORE¶
Minimum fused retrieval score for the consistency critic to report a possible conflict between ontologies. A weighted reciprocal-rank score summed over the core, neighborhood and BM25 lanes, not a cosine similarity: each lane adds its normalized weight divided by the rank. With BM25 enabled and default weights, a rank-1 hit in one lane alone scores below 0.5 (about 0.42 for the core lane), so 0.5 requires at least two lanes to agree on the term.
VECTOR_STORE_EMBEDDING_BATCH_SIZE¶
Batch size used for embedding requests during indexing.
VECTOR_STORE_REINDEX_CONCURRENCY¶
Max ontologies to materialize/reindex concurrently during ToolBox initialize. Dense embeds are serialized via a process-wide lock; higher values mainly overlap triple-store I/O and BM25 with waits.
VECTOR_STORE_WIPE_ON_INIT¶
When true, ToolBox.initialize drops the current ontology/facts vector partition before recreating schema and reindexing. Use for clean-slate recovery (e.g. after embedding-model changes).
VECTOR_STORE_PRUNE_ORPHAN_IRIS_ON_INIT¶
When true, ToolBox.initialize deletes indexed ontology IRIs that are not in the synchronized catalog (covers IRI renames without a full wipe).
VECTOR_STORE_FUSION_CORE_WEIGHT¶
Core vector score weight for dual-vector ranking fusion. Weights are normalized across the three lanes before use, so only their ratio matters.
VECTOR_STORE_FUSION_NEIGHBORHOOD_WEIGHT¶
Weight of the neighborhood lane in rank fusion. The neighborhood text describes a term's relations rather than the term, so it mainly corroborates the core lane; keep it below the core weight.
VECTOR_STORE_FUSION_BM25_WEIGHT¶
Weight of the sparse (BM25) lane in rank fusion, normalized with the core and neighborhood weights when BM25 is enabled. Terms whose surface form is a symbol or notation (unit symbols, chemical formulae, gene symbols) are often found only by this lane, so a low weight lets any dense hit outvote them.
VECTOR_STORE_FUSION_RANK_CONSTANT¶
Constant added to each rank in lane fusion: a lane contributes weight / (constant + rank). At 0 the first rank dominates, so fusion follows whichever lane put a term first. Raising it makes agreement across lanes count for more than position within one; far above TOP_K it makes all ranks nearly equal.
VECTOR_STORE_MINIMAL_LABEL_LIMIT¶
Maximum declared surface forms (rdfs:label, skos:prefLabel, dcterms:title, skos:altLabel) folded into each atom's sparse BM25 text. A vocabulary may declare more aliases than this; symbol aliases sort last and are dropped first, so raising this widens what the sparse lane can match. Changing it changes stored sparse vectors and requires a reindex.
VECTOR_STORE_INDEX_UNDESCRIBED_IRIS¶
Index every IRI in an ontology, including those that appear only as an object or predicate. By default only terms the ontology describes (as a subject, or with a label) are indexed: a merely referenced IRI has no text but its local name, and such strings embed as generic hubs that match every query and crowd out real terms. Referenced IRIs stay reachable through induced-subgraph expansion. Changing this requires a reindex.
VECTOR_STORE_EMBED_STANDARD_VOCAB_IRIS¶
If True, atomize focal IRIs in standard RDF/OWL/SKOS/DC/SHACL/schema.org namespaces instead of skipping them. These are scaffolding an ontology reuses rather than terms it defines, so they carry no retrieval signal for the document being processed. Changing this requires a reindex.
VECTOR_STORE_EXTRA_EXCLUDED_NAMESPACE_PREFIXES¶
IRI prefixes never indexed from ontology sources, in addition to the standard vocabularies. Use it for an upper ontology or external vocabulary that a catalog includes but that should not compete in retrieval (BFO, SOSA, OM-2); merely referenced vocabularies are already skipped while index_undescribed_iris is false. Changing this requires a reindex.
VECTOR_STORE_DEDUP_MODE¶
Row/point identity policy for ontology vectors: 'iri' stores one logical record per entity key, while 'atom_id' keeps every atom variant separate.
VECTOR_STORE_DEDUP_INCLUDE_VERSION¶
When dedup_mode='iri', include ontology_version in the identity key so different ontology versions remain isolated.
VECTOR_STORE_DEDUP_INCLUDE_HASH¶
When dedup_mode='iri', include ontology_hash in the identity key so different ontology snapshots remain isolated.
VECTOR_STORE_DEDUP_QUERY_HITS_BY_IRI¶
Drop duplicate retrieval hits sharing the same logical IRI key and keep the best-scoring one.
VECTOR_STORE_ONTOLOGY_TABLE¶
Ontology atom table/collection name; derived like FUSEKI_DATASET, and replaced the same way by ontocast serve and ontocast process.
VECTOR_STORE_FACTS_TABLE¶
Facts table/collection reserved for future fact vectors; created on init.
VECTOR_STORE_LABEL_PREDICATES¶
Predicate IRIs whose literal objects are indexed as declared labels, in descending priority (default: rdfs:label, skos:prefLabel, dcterms:title, skos:altLabel, dcterms:alternative). Changing this changes stored vectors and requires a reindex.
VECTOR_STORE_SYMBOL_PREDICATES¶
Predicates whose literal objects are indexed as symbols or notations (default: skos:notation, qudt:symbol, qudt:ucumCode). The indexing counterpart of INDUCED_SUBGRAPH_SYMBOL_PREDICATES; set both together. Changing this requires a reindex.
VECTOR_STORE_LEXICAL_TRIGGER_ENABLED¶
Enable the lexical-trigger lane: scan raw chunk text for notation/symbol tokens and inject matching atoms as additive retrieval seeds.
VECTOR_STORE_LEXICAL_TRIGGER_PREDICATES¶
Predicate IRIs whose literal objects become case-preserved lexical triggers (default: skos:notation, qudt:symbol, qudt:ucumCode).
VECTOR_STORE_LEXICAL_TRIGGER_HEURISTIC_ENABLED¶
Promote bare code-shaped rdfs:label/skos:altLabel values as triggers when no predicate-declared notation exists for the entity.
VECTOR_STORE_LEXICAL_TRIGGER_MIN_LEN¶
Minimum length for heuristic label/altLabel trigger promotion.
VECTOR_STORE_LEXICAL_TRIGGER_MAX_LEN¶
Maximum length for heuristic label/altLabel trigger promotion.
VECTOR_STORE_LEXICAL_TRIGGER_HEURISTIC_MAX_PER_ENTITY¶
Cap on heuristic triggers per entity.
VECTOR_STORE_LEXICAL_TRIGGER_MAX_ATOMS¶
Maximum lexical-trigger atoms injected per retrieval call, additive to the semantic atom budget.
VECTOR_STORE_LEXICAL_TRIGGER_SCORE¶
Score given to lexical-trigger hits, on the fused reciprocal-rank scale: with BM25 enabled and default weights, a rank-1 core hit alone scores about 0.42. Keep it below that, so trigger hits join the semantic seeds rather than outrank all of them.
VECTOR_STORE_LEXICAL_TRIGGER_FUSION¶
How lexical-trigger hits combine with semantic hits: 'max_merge' raises an already retrieved atom to the higher of its two scores and appends unseen atoms; 'append' only appends unseen atoms, so the trigger adds nothing to an atom retrieval already found.
VECTOR_STORE_QUERY_UNIT_SIGNALS_ENABLED¶
Match the tokens that follow numbers in the unit text ('4-15 days', '200 kV', '0.5 %') against catalog labels, symbols and UCUM codes, ignoring case and plurals, and add the matched terms as seeds at lexical_trigger_score, outside the semantic atom budget. Recovers the units and qualifiers a measurement needs. Query side only: no reindex needed. Turn it off when the facts extracted are not quantities, or the catalog's labels are not in Latin script.
VECTOR_STORE_SYMBOL_CASE_MISMATCH_POLICY¶
Treatment of retrieved atoms whose symbol (skos:notation, qudt:symbol, qudt:ucumCode) matches a query token only when case is ignored. The BM25 index is case-folded, so 'meV' in the text also retrieves the unit with symbol 'MeV', a factor of 10^9 apart. 'demote' multiplies the score by symbol_case_mismatch_demote_factor, 'drop' removes the atom, 'off' keeps it. Exact-case and label matches are never affected.
VECTOR_STORE_SYMBOL_CASE_MISMATCH_DEMOTE_FACTOR¶
Factor a case-mismatched symbol's score is multiplied by when VECTOR_STORE_SYMBOL_CASE_MISMATCH_POLICY is demote. 0 ranks it last, 1 leaves it unchanged.
Patch sizing¶
ONTOLOGY_PATCH_MIN_MERGED_MAX_SCORE¶
Relevance floor below which a unit is treated as having no relevant ontology and gets an empty patch. A fraction of the best fused score a window can reach (an atom ranked first in every lane), not an absolute score, so it stays meaningful when lane weights or VECTOR_STORE_FUSION_RANK_CONSTANT change. 0 disables it.
ONTOLOGY_PATCH_MERGED_SCORE_RATIO¶
Advanced: after merging hits across queries, keep atoms whose score is at least this fraction of the merged top score. 0 disables (default).
ONTOLOGY_PATCH_CROSS_QUERY_MERGE_MODE¶
Cross-window merge: max_score (default; entity best score across windows) or sum_score (sum of per-window scores, so a term several windows agree on outranks one window's top hit). Both are followed by the same round-robin / cap stage, and single-window retrieval makes them identical.
ONTOLOGY_PATCH_PER_ONTOLOGY_SEED_QUOTA¶
Maximum seeds kept per ontology when filling the seed list round-robin. 0 means no per-ontology cap: seeds are taken in global score order, so the budget is not spread across ontologies that merely scored something.
ONTOLOGY_PATCH_PER_ONTOLOGY_ATOM_FLOOR¶
Reserve pass before the global fill: each ontology contributing candidates is guaranteed min(floor, its candidate count) seed slots, allocated round-robin. Unlike per_ontology_seed_quota (a ceiling), the floor protects small modules from being starved by one dominant ontology at the atom cap. 0 disables.
ONTOLOGY_PATCH_SMALL_MODULE_CLOSURE_MAX_TRIPLES¶
Include a source ontology whole (header stripped) when it has at least one retrieved atom and at most this many triples. A small vocabulary shown in part pushes the renderer to invent near-miss property names, and modules such as qualified-quantity or observation patterns are only useful whole. Takes effect only for modules that win a seed, so it pairs with per_ontology_atom_floor. 0 disables it.
ONTOLOGY_PATCH_SMALL_MODULE_CLOSURE_MAX_TOTAL_TRIPLES¶
Ceiling on the triples that whole-module inclusions may add to one snapshot; unset means no ceiling. Modules are admitted in order of their best atom's retrieval score until the budget is spent, and a module too large for what remains is skipped so a smaller one can still fit. Ordering by score rather than seed count keeps small, sharply relevant vocabularies in. See module_closure_iris, module_closure_declined_iris and module_closure_triples in the run manifest.
ONTOLOGY_PATCH_PER_ROLE_ATOM_FLOOR¶
Reserve pass guaranteeing predicate-role atoms a share of the seed budget before the global fill, in the same floor-not-ceiling shape as per_ontology_atom_floor. Dense similarity between prose and a noun phrase beats a verb phrase, so classes and individuals win a shared ranking and the properties carrying the graph structure are crowded out. 0 disables.
ONTOLOGY_PATCH_SCHEMA_CLOSURE_MAX_ENTITIES¶
Cap on terms admitted by rdfs:domain/rdfs:range closure over the retrieved seeds: properties whose domain or range names an admitted class (or its ancestors), and the domain/range classes of admitted properties. A class with no property that can link it is inert context. 0 disables.
ONTOLOGY_PATCH_SCHEMA_CLOSURE_ANCESTOR_DEPTH¶
How far to walk rdfs:subClassOf upward when matching a property's declared domain/range against an admitted class. Properties are usually declared on an ancestor of the class the text mentions.
ONTOLOGY_PATCH_MMR_LAMBDA¶
MMR trade-off over dense core+neighborhood vectors: 1.0 keeps pure relevance (default; skips MMR), lower values increase diversity.
ONTOLOGY_PATCH_SEEDS_PER_WINDOW¶
Target seeds per proposition window when scaling the effective atom cap: min(max_atoms, max(max_atoms_base, seeds_per_window * n_queries)).
ONTOLOGY_PATCH_MAX_ATOMS_BASE¶
Minimum effective atom cap before window scaling (0 defers entirely to seeds_per_window * n_queries). The cap does not grow with catalog size, so a floor below max_atoms discards candidates the per-lane top_k has already retrieved.
ONTOLOGY_PATCH_MAX_ATOMS¶
Hard cap on atoms kept after merging and optional MMR; 0 means unlimited. The effective cap is min(max_atoms, max(max_atoms_base, seeds_per_window * n_queries)). On multi-window input this is the main lever on how many relevant terms reach the snapshot; above it, the induced-subgraph triple budget becomes the limit.
ONTOLOGY_PATCH_DUMP_ONTOLOGY_RANKS¶
Collect per-ontology rank diagnostics (best rank/score per channel, fused rank, whether the ontology survived the atom cut) into retrieval metrics under 'ontology_rank_diagnostics'. Diagnostic only: it walks every channel hit list per query and does not change retrieval behaviour.