Skip to content

ADR-0013: Vector store as a retrieval profile

Decision

This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.

  • Status: Accepted 2026-10-09 by the product owner (amends ADR-0005, which stays in force except where this ADR changes it)
  • Date: 2026-10-09
  • Deciders: Dmitry Khaymov (product owner), 2026-10-09; proposed by the 2026-10 independent review
  • Tags: knowledge, retrieval, vector, tenancy

Context

ADR-0005 names Qdrant as the primary vector store with Azure AI Search as an alternative, and relies on metadata filtering for tenant and classification scoping. The code at the inspected revisions shows:

  • ConnectSoft.Extensions.AI references the Semantic Kernel vector connectors InMemory, Azure AI Search, PgVector, Qdrant (1.74.0-preview) and SQL Server (1.74.1-preview). The user permits these connectors while excluding Semantic Kernel orchestration.
  • In the agent host template, SetupVectorStoreIntegration handles only the InMemory provider; Qdrant, PgVector, SQL Server and Azure AI Search throw NotSupportedException. No persistent vector store can be used by an agent generated from the template today.
  • RetrievalService performs top-k search first and applies tenant/tag filters afterwards in memory; the Agent Framework text-search adapter passes options: null, so no tenant filter reaches retrieval; VectorRecord fixes 1536 dimensions and its Metadata property carries no [VectorStoreData] attribute.
  • Canonical guidance for the MAF retrieval path already exists in ConnectSoft.Documentation (agent-framework-rag.md, vector-ingestion.md, ai-extensions.md) and must be linked rather than duplicated.

Decision

  1. The Factory specifies a retrieval contract, not a product: authorized scope (tenant, project, source ACL) is supplied by the trusted host and enforced by the backend before top-k selection; citations carry source revision, chunk identity, embedding profile and index version; embedding dimension and model are declared by a profile and index compatibility is validated, never assumed.
  2. Vector backends are profiles selected per deployment from the permitted Semantic Kernel connectors. Each profile must evidence: pre-search filtering on the chosen backend, metadata persistence, deletion propagation, rebuild from approved sources, and snapshot/restore. A profile without this evidence is not eligible for tenant-shared collections.
  3. Qdrant remains the reference self-hosted profile and Azure AI Search the reference managed profile, as ADR-0005 intended. Neither is "primary" until a working integration path exists in the agent host and the evidence in point 2 is produced.
  4. Direct bounded reads of approved source snapshots are an acceptable retrieval path for scenarios that do not need an index; indexed retrieval is not a prerequisite for the first governed workflow.
  5. Metadata-based post-filtering of a global top-k result is explicitly not an acceptable isolation mechanism for shared collections.

Consequences

Positive

  • Separates the stable contract (scope, provenance, compatibility) from backend choice.
  • Makes the current gap visible instead of implying a deployed Qdrant.
  • Keeps the user's connector allowance precise: vector connectors yes, orchestration no.

Negative / trade-offs

  • The agent host's vector-store integration must be completed for any persistent profile before the Knowledge plane pages can claim current capability. That is implementation work outside this documentation task.
  • Backend contract tests per profile are new work.

Neutral

  • The in-memory connector stays valid for local development and deterministic tests.

Alternatives considered

Alternative Why not chosen
Keep "Qdrant primary" as written Misstates current capability; a reader would infer a working, isolated Qdrant path that does not exist.
Drop vector retrieval from the Factory Retrieval is part of the Knowledge plane target; the contract is needed regardless of backend.
Replace Semantic Kernel connectors with a different library Connectors are explicitly allowed by the user and already integrated; replacement adds work without evidence of benefit.

Evidence

  • ConnectSoft.AI.SoftwareFactory.AgentTemplate.ApplicationModel/MicrosoftExtensionsAIExtensions.cs L142–163
  • ConnectSoft.AI.SoftwareFactory.AgentTemplate.AIModel/Embeddings/RetrievalService.cs L66–120; VectorRecord.cs L31, L37
  • ConnectSoft.AI.SoftwareFactory.AgentTemplate.AgentFramework/RetrievalAgentTextSearchAdapter.cs L47–52
  • ConnectSoft.Extensions.AI/src/ConnectSoft.Extensions.AI/ConnectSoft.Extensions.AI.csproj L58–62; base-template/Directory.Packages.props L467–472
  • Verification record V-A9, V-A10, V-A11, V-A14
  • ADR-0005 — amended by this ADR
  • ADR-0002 (connector allowance clarified in its review note)
  • ADR-0015 for the scope that retrieval must enforce
  • Canonical: ConnectSoft.Documentation cross-cutting-concerns/ai-machine-learning/agent-framework-rag.md, vector-ingestion.md