Skip to content

ontocast.onto.retrieval_capabilities

Vector retrieval prerequisites for selected_vector_search_ontology context mode.

Classes

EmptyOntologyContextError

Bases: OntologyContextConfigError

Raised when a unit's ontology context resolves to zero triples.

An empty context is not a milder version of a good one. The renderer is instructed to extract "based on provided domain ontology"; handed nothing, it falls back on whatever standard vocabulary the prompt names, and the SHACL gate then finds no node its shapes target -- so the run reports a vacuous pass over an empty focus set. Continuing produces a finished, plausible, ungrounded graph, which is worse than stopping.

Source code in ontocast/onto/retrieval_capabilities.py 
54
55
56
57
58
59
60
61
62
63
64
65
class EmptyOntologyContextError(OntologyContextConfigError):
    """Raised when a unit's ontology context resolves to zero triples.

    An empty context is not a milder version of a good one. The renderer is
    instructed to extract "based on provided domain ontology"; handed nothing,
    it falls back on whatever standard vocabulary the prompt names, and the
    SHACL gate then finds no node its shapes target -- so the run reports a
    vacuous pass over an empty focus set. Continuing produces a finished,
    plausible, ungrounded graph, which is worse than stopping.
    """

    error_code: str = "EMPTY_ONTOLOGY_CONTEXT"

Attributes

error_code = 'EMPTY_ONTOLOGY_CONTEXT' class-attribute instance-attribute

OntologyContextConfigError

Bases: ValueError

Raised when vector-search ontology context mode is requested without a vector store.

Source code in ontocast/onto/retrieval_capabilities.py 
 9
10
class OntologyContextConfigError(ValueError):
    """Raised when vector-search ontology context mode is requested without a vector store."""

VectorStoreUnavailableError

Bases: OntologyContextConfigError

Raised when vector retrieval is requested but vector infra is unavailable.

Source code in ontocast/onto/retrieval_capabilities.py 
13
14
15
16
class VectorStoreUnavailableError(OntologyContextConfigError):
    """Raised when vector retrieval is requested but vector infra is unavailable."""

    error_code: str = "VECTOR_STORE_UNAVAILABLE"

Attributes

error_code = 'VECTOR_STORE_UNAVAILABLE' class-attribute instance-attribute

Functions:

require_vector_retrieval(tools)

Raise a single canonical error if vector ensemble cannot run.

Source code in ontocast/onto/retrieval_capabilities.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def require_vector_retrieval(tools: ToolBox) -> None:
    """Raise a single canonical error if vector ensemble cannot run."""
    if vector_retrieval_available(tools):
        return
    last_error = tools.vector_store_last_error
    details = ""
    if last_error is not None:
        details = f" Last vector-store init error: {last_error}"
    raise VectorStoreUnavailableError(
        "ontology_context_mode='selected_vector_search_ontology' requires a vector "
        "store: set QDRANT_URI or LANCEDB_ENABLED=true, with an embedding "
        "dimension matching the index, so the vector store and patch retriever "
        "are available and initialized."
        f"{details}"
    )

validate_ontology_context_mode(ontology_context_mode, tools)

Raise if the requested ontology context mode cannot be satisfied.

Source code in ontocast/onto/retrieval_capabilities.py 
45
46
47
48
49
50
51
def validate_ontology_context_mode(
    ontology_context_mode: OntologyContextMode,
    tools: ToolBox,
) -> None:
    """Raise if the requested ontology context mode cannot be satisfied."""
    if ontology_context_mode == OntologyContextMode.SELECTED_VECTOR_SEARCH_ONTOLOGY:
        require_vector_retrieval(tools)

vector_retrieval_available(tools)

True when a vector store (Qdrant or LanceDB) and the patch retriever are ready.

Source code in ontocast/onto/retrieval_capabilities.py 
19
20
21
22
23
24
25
def vector_retrieval_available(tools: ToolBox) -> bool:
    """True when a vector store (Qdrant or LanceDB) and the patch retriever are ready."""
    return (
        tools.vector_store is not None
        and tools.patch_retriever is not None
        and tools.is_vector_store_ready()
    )