Skip to content

Provider Configuration

This guide is the operational reference for configuring backends used by AgenticRAGSkill and other multi-source skills. The architectural rationale (why providers are pluggable, why backends live behind extras) is recorded in ADR-0002 and ADR-0003. This page is the cookbook.

Install matrix

Pick the extras you need. Each extra installs only the SDKs for that backend family:

# Graph retrieval only (Neo4j)
uv add "mirai-shared-skills[neo4j]"

# Vector search only (Azure AI Search)
uv add "mirai-shared-skills[azure]"

# Reranker only (Cohere or HTTP-based Qwen3)
uv add "mirai-shared-skills[reranker]"

# Full agentic RAG (graph + vector + reranker)
uv add "mirai-shared-skills[rag]"

# Eval harness (deepeval) for testing RAG quality
uv add "mirai-shared-skills[eval]"

If you forget an extra, the provider's constructor raises a typed *UnavailableError with the install hint baked into the message — no debugging stack traces through vendor SDKs.

Provider environment variables

Provider Variable Required Purpose
Neo4jGraphProvider NEO4J_URI yes bolt://host:7687 or neo4j+s://aura-host.
NEO4J_USER yes Default neo4j for new installs.
NEO4J_PASSWORD yes Set during cluster provisioning.
NEO4J_DATABASE no Defaults to neo4j; override for multi-tenant clusters.
AzureSearchProvider AZURE_SEARCH_ENDPOINT yes https://<service>.search.windows.net.
AZURE_SEARCH_API_KEY yes Admin or query key (query is sufficient for retrieval).
AZURE_SEARCH_INDEX yes Index name. The provider does not create indexes.
BrowserWebSearchProvider none — Reuses the agent browser; no extra config.
Cohere reranker COHERE_API_KEY yes Cohere Rerank v4 API key.
Qwen3 reranker QWEN3_RERANKER_BASE yes URL of an HTTP-served Qwen3-Reranker-4B endpoint (no SDK).

Construction examples

from mirai_shared_skills.agentic_rag import AgenticRAGSkill
from mirai_shared_skills.agentic_rag.providers import (
    AzureSearchProvider,
    BrowserWebSearchProvider,
    Neo4jGraphProvider,
    NoOpRerankerProvider,
)

skill = AgenticRAGSkill(
    graph=Neo4jGraphProvider.from_env(),       # reads NEO4J_* vars
    vector=AzureSearchProvider.from_env(),     # reads AZURE_SEARCH_* vars
    web=BrowserWebSearchProvider(),            # no env
    reranker=NoOpRerankerProvider(),           # default no-op
)

Drop a provider you don't have:

skill = AgenticRAGSkill(
    vector=AzureSearchProvider.from_env(),
    web=BrowserWebSearchProvider(),
    # no graph, no reranker — skill skips those branches of the query plan
)

Troubleshooting

Neo4jUnavailableError at construction

mirai_shared_skills.agentic_rag.providers.neo4j_graph.Neo4jUnavailableError:
The `neo4j` extra is not installed. Install with:
    pip install mirai-shared-skills[neo4j]    # or [rag]

You imported Neo4jGraphProvider but the neo4j driver isn't installed. Add the extra and re-sync.

Azure: Index 'foo' not found

AzureSearchProvider does not create indexes — it expects the index to exist. Verify in the Azure portal that:

  1. The index name in AZURE_SEARCH_INDEX matches exactly (case-sensitive).
  2. The index has the fields the skill expects (see agentic_rag/references/azure_search_config.md for the canonical schema).

Empty graph results

Two common causes:

  1. The Cypher template doesn't match your schema. Check mirai_shared_skills/agentic_rag/scripts/cypher_templates.py and override or extend.
  2. Constraints/indexes missing. The provider runs read-only queries; if your graph has no fulltext index, semantic graph expansion returns empty.

Cohere quota errors

Cohere Rerank v4 has per-month free tier. If you hit 429 Too Many Requests, swap NoOpRerankerProvider() in temporarily, or move to the Qwen3 HTTP-served endpoint.

Local Neo4j for testing

The repo ships docker-compose.test.yml for spinning up a throwaway Neo4j 5.x instance:

docker compose -f docker-compose.test.yml up -d neo4j
# Then:
export NEO4J_URI=bolt://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=test1234
uv run pytest tests/agentic_rag/ -m integration

Tear down with docker compose -f docker-compose.test.yml down -v to drop volumes.