Kapso knowledge search backends: graph and navigation

Kapso ships two backends for querying the knowledge graph. Which one you want depends on what you indexed.

Which backend should I use?

Backend	Use it for	Storage	How it retrieves
`kg_graph_search`	Wiki pages built by `learn_knowledge()`	Weaviate + Neo4j	Vector similarity, optional LLM reranking, then graph enrichment
`kg_llm_navigation`	JSON node-and-edge graphs	Neo4j only	An LLM walks the graph, deciding which nodes to visit

Set it with knowledge_search.type in your config, or override per index with kapso index_kg --search-type.

kg_graph_search

The primary backend for wiki-based knowledge. It embeds the query, retrieves from Weaviate, optionally reranks with an LLM, then pulls connected pages from Neo4j.

from kapso.knowledge_base.search import KnowledgeSearchFactory, KGSearchFilters

search = KnowledgeSearchFactory.create("kg_graph_search", params={
    "weaviate_collection": "KapsoKG",
    "embedding_model": "text-embedding-3-large",
    "use_llm_reranker": True,
})

result = search.search(
    query="How to fine-tune an LLM with limited GPU memory?",
    filters=KGSearchFilters(top_k=5, domains=["LLMs", "PEFT"]),
)

for item in result:
    print(f"{item.id}: {item.score:.2f}")

context = result.to_context_string(max_results=3)

Its three presets differ only in how much work they do after the vector search:

Preset	LLM reranking	Connected pages
`DEFAULT`	yes	yes
`FAST`	no	no
`RERANK_ONLY`	yes	no

Shipped defaults are embedding_provider: openai, embedding_model: text-embedding-3-large, weaviate_collection: KapsoKG, include_connected_pages: true, use_llm_reranker: false and reranker_overview_max_chars: 300. A preset overrides them; anything a preset omits falls back to these. The stores themselves are parameters too: weaviate_url (default http://localhost:8080), weaviate_grpc_port (50051), neo4j_uri (bolt://localhost:7687) and neo4j_user (neo4j). The Neo4j password is the one connection secret and is read from NEO4J_PASSWORD. An index records the endpoints in its backend_refs, so a search or merge opened from an index reaches the stores it was built on: a test index built on its own Weaviate and Neo4j never touches the production ones.

This is a different setting from defaults.models.embedding in the main config, which is text-embedding-3-small and is used for memory rather than for this backend.

Embedding with Google Vertex AI

Set embedding_provider: vertex to embed pages and queries with a serverless Vertex AI model instead of OpenAI:

search = KnowledgeSearchFactory.create("kg_graph_search", params={
    "weaviate_collection": "MyKG",
    "embedding_provider": "vertex",
    "embedding_model": "gemini-embedding-2",
    "vertex_project": "my-gcp-project",   # required; there is no default
    "vertex_location": "global",          # the default; "us" and "eu" also serve it
})

Credentials. Google Application Default Credentials, read by google-auth itself: gcloud auth application-default login on a workstation, or a service account / workload identity for a service. The identity needs aiplatform.endpoints.predict on the project.
What is embedded. gemini-embedding-2 has no task-type parameter, so the task goes in the text, in Google’s documented retrieval format: a page is sent as title: <page name> | text: <description>, a query as task: search result | query: <query>.
Size. embedding_dimensions sets the output size (128–3072); unset keeps the model’s default of 3072.
Failures raise. Inputs over the model’s limit are rejected rather than truncated, rate limits and server errors are retried with backoff (embedding_max_attempts, embedding_backoff_seconds), and any other error stops the call. This holds for both providers: a page that cannot be embedded stops an index build instead of silently going missing from it.

An index records its provider, model, size and Vertex project in backend_refs, and a search built from that index embeds queries the same way. You never have to repeat these settings at search time, and vectors from two different models are never compared.

kg_llm_navigation

For JSON graphs, where an LLM navigates the structure instead of embedding it. No embeddings are involved, so it works with any graph shape.

import json
from kapso.knowledge_base.search import KnowledgeSearchFactory

search = KnowledgeSearchFactory.create("kg_llm_navigation")

with open("kg_data.json") as handle:
    search.index(json.load(handle))

result = search.search(
    query="Best practices for feature engineering",
    context="Working on a tabular data competition",
)

Its four presets trade exploration against cost:

Preset	`search_top_k`	`navigation_steps`	`expansion_limit`
`DEFAULT`	1	3	3
`DEEP_SEARCH`	3	5	5
`SHALLOW`	1	2	2
`MINIMAL`	1	1	1

All four use search_node_type: specialization.

What comes back from a search

Both backends return a KGOutput.

@dataclass
class KGOutput:
    query: str
    filters: Optional[KGSearchFilters]
    results: List[KGResultItem]
    total_found: int
    search_metadata: Dict[str, Any]

    is_empty: bool          # property
    top_result: Optional[KGResultItem]   # property

    def get_by_type(self, page_type: str) -> List[KGResultItem]
    def get_by_domain(self, domain: str) -> List[KGResultItem]
    def get_above_score(self, min_score: float) -> List[KGResultItem]
    def to_context_string(self, max_results=5) -> str

Each result is a KGResultItem with id, score, page_type, overview, content and metadata, plus domains, sources and last_updated as properties. Narrow a search with KGSearchFilters:

@dataclass
class KGSearchFilters:
    top_k: int = 10
    min_score: Optional[float] = None
    page_types: Optional[List[str]] = None
    domains: Optional[List[str]] = None
    include_content: bool = True

How do I index content?

Indexing writes a .index file that campaigns load with --kg-index. See index_kg().

from kapso import Kapso

kapso = Kapso()

kapso.index_kg(
    wiki_dir="data/wikis",
    save_to="data/indexes/finetuning.index",
    force=True,
)

For a JSON graph, point at the file and name the backend:

kapso.index_kg(
    data_path="benchmarks/mle/data/kg_data.json",
    save_to="data/indexes/kaggle.index",
    search_type="kg_llm_navigation",
)

The .index file is a small JSON reference, not the data itself:

{
  "version": "1.0",
  "created_at": "2026-01-15T10:30:00Z",
  "data_source": "data/wikis",
  "search_backend": "kg_graph_search",
  "backend_refs": {
    "weaviate_url": "http://localhost:8080",
    "weaviate_grpc_port": 50051,
    "neo4j_uri": "bolt://localhost:7687",
    "neo4j_user": "neo4j",
    "weaviate_collection": "KapsoKG",
    "embedding_provider": "openai",
    "embedding_model": "text-embedding-3-large"
  },
  "page_count": 99
}

Indexing needs Weaviate and Neo4j running. See Optional: knowledge-graph backends.

What happens when knowledge search is off?

KnowledgeSearchFactory.create_null() returns a no-op backend whose search() gives an empty KGOutput. MINIMAL mode ships with knowledge_search.enabled: false and uses it, so a campaign runs without any knowledge-graph infrastructure.

Can I add my own backend?

from kapso.knowledge_base.search.base import KnowledgeSearch
from kapso.knowledge_base.search.factory import register_knowledge_search

@register_knowledge_search("my_custom_search")
class MyCustomSearch(KnowledgeSearch):
    def index(self, data: KGIndexInput) -> None:
        ...

    def search(self, query: str, filters=None, context=None) -> KGOutput:
        ...

    def get_page(self, page_title: str) -> Optional[WikiPage]:
        ...

    def edit(self, data: KGEditInput) -> bool:
        ...

Add its presets to knowledge_search.yaml beside the two shipped backends.

Knowledge graph

What the graph holds and where it comes from

Learning pipeline

How sources become wiki pages

Related pages: Knowledge graph · Learning pipeline · Knowledge graph Kapso is an open-source framework by Leeroo that builds software toward measurable goals through experiment campaigns. Source code: github.com/Leeroo-AI/kapso · Install: pip install leeroo-kapso · Every page as plain text: llms.txt.

Getting started

Evolve system

Knowledge graph

Trajectory learning

Research

Deployment

Benchmarks

Kapso knowledge search backends: graph and navigation

Which backend should I use?

kg_graph_search

Embedding with Google Vertex AI

kg_llm_navigation

What comes back from a search

How do I index content?

What happens when knowledge search is off?

Can I add my own backend?

Knowledge graph

Learning pipeline

​Which backend should I use?

​kg_graph_search

​Embedding with Google Vertex AI

​kg_llm_navigation

​What comes back from a search

​How do I index content?

​What happens when knowledge search is off?

​Can I add my own backend?

​Related

Knowledge graph

Learning pipeline

Which backend should I use?

kg_graph_search

Embedding with Google Vertex AI

kg_llm_navigation

What comes back from a search

How do I index content?

What happens when knowledge search is off?

Can I add my own backend?

Related