Skip to content

ontocast.tool.vector_store.factory

Factory for vector store backend selection.

Backend modules are imported inside the selected branch rather than at module scope: importing :mod:ontocast.tool.vector_store.qdrant pulls the Qdrant SDK (and, through it, gRPC and an ONNX runtime), and OntoCast's base install ships neither. Only the backend actually configured is loaded.

Classes

Functions:

create_vector_store_manager(tool_config, embedding, sparse_embedding=None)

Return a vector store manager for the configured backend.

Selection is driven by VectorStoreConfig.backend. The default, :attr:~ontocast.onto.enum.VectorStoreBackend.AUTO, infers the backend from whichever connection setting is populated and otherwise resolves to :attr:~ontocast.onto.enum.VectorStoreBackend.NONE, returning None. A deployment that configures neither Qdrant nor LanceDB has no vector retrieval: ontology context comes from a single working ontology, which is the default :class:~ontocast.onto.enum.OntologyContextMode.

Parameters:

Name Type Description Default
tool_config ToolConfig

The resolved tool configuration.

 required
embedding EmbeddingTool

Dense embedding provider.

 required
sparse_embedding FastembedBm25SparseTool | None

BM25 sparse provider, required by both backends.

 None

Returns:

Type Description
VectorStoreManager | None

A manager for the selected backend, or None when the backend is
VectorStoreManager | None

explicitly disabled.

Raises:

Type Description
ValueError

If an explicitly requested backend is not configured, or if Qdrant's vector_size contradicts the embedding dimension.
Source code in ontocast/tool/vector_store/factory.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def create_vector_store_manager(
    tool_config: ToolConfig,
    embedding: EmbeddingTool,
    sparse_embedding: FastembedBm25SparseTool | None = None,
) -> VectorStoreManager | None:
    """Return a vector store manager for the configured backend.

    Selection is driven by ``VectorStoreConfig.backend``. The default,
    :attr:`~ontocast.onto.enum.VectorStoreBackend.AUTO`, infers the backend from
    whichever connection setting is populated and otherwise resolves to
    :attr:`~ontocast.onto.enum.VectorStoreBackend.NONE`, returning ``None``.
    A deployment that configures neither Qdrant nor LanceDB has **no** vector
    retrieval: ontology context comes from a single working ontology, which is
    the default :class:`~ontocast.onto.enum.OntologyContextMode`.

    Args:
        tool_config: The resolved tool configuration.
        embedding: Dense embedding provider.
        sparse_embedding: BM25 sparse provider, required by both backends.

    Returns:
        A manager for the selected backend, or ``None`` when the backend is
        explicitly disabled.

    Raises:
        ValueError: If an explicitly requested backend is not configured, or if
            Qdrant's ``vector_size`` contradicts the embedding dimension.
    """
    backend = resolve_backend(tool_config)

    if backend is VectorStoreBackend.NONE:
        return None

    if backend is VectorStoreBackend.QDRANT:
        q_vs = tool_config.qdrant.vector_size
        emb_dim = tool_config.embedding.dimension
        if q_vs is not None and q_vs != emb_dim:
            raise ValueError(
                "QdrantConfig.vector_size must match "
                "EmbeddingConfig.dimension when set "
                f"(got vector_size={q_vs}, embedding.dimension={emb_dim})"
            )
        from ontocast.tool.vector_store.qdrant import QdrantVectorStoreManager

        return QdrantVectorStoreManager(
            store_config=tool_config.vector_store,
            qdrant_config=tool_config.qdrant,
            embedding=embedding,
            sparse_embedding=sparse_embedding,
        )

    from ontocast.tool.vector_store.lancedb import LanceDBVectorStoreManager

    return LanceDBVectorStoreManager(
        store_config=tool_config.vector_store,
        lancedb_config=tool_config.lancedb,
        embedding=embedding,
        sparse_embedding=sparse_embedding,
    )

resolve_backend(tool_config)

Resolve AUTO against the populated connection settings.

AUTO falls back to NONE. Vector retrieval is one of three ontology-context modes and the single-working-ontology mode is the default, so an unconfigured deployment has never had a vector store; silently giving every such deployment one would change indexing behaviour and embedding cost without anyone asking. The two supported backends are Qdrant (server) and LanceDB (embedded), each shipped as its own optional extra.

Source code in ontocast/tool/vector_store/factory.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def resolve_backend(tool_config: ToolConfig) -> VectorStoreBackend:
    """Resolve ``AUTO`` against the populated connection settings.

    ``AUTO`` falls back to ``NONE``. Vector retrieval is one of three
    ontology-context modes and the single-working-ontology mode is the default,
    so an unconfigured deployment has never had a vector store; silently giving
    every such deployment one would change indexing behaviour and embedding cost
    without anyone asking. The two supported backends are Qdrant (server) and
    LanceDB (embedded), each shipped as its own optional extra.
    """
    backend = tool_config.vector_store.backend
    if backend is not VectorStoreBackend.AUTO:
        if backend is VectorStoreBackend.QDRANT and not tool_config.qdrant.uri:
            raise ValueError(
                "VECTOR_STORE_BACKEND=qdrant requires QDRANT_URI to be set."
            )
        return backend
    if tool_config.qdrant.uri:
        return VectorStoreBackend.QDRANT
    if tool_config.lancedb.enabled:
        return VectorStoreBackend.LANCEDB
    return VectorStoreBackend.NONE