cleveragents-core/docs/reference/acms_backends.md

ACMS Backend Abstraction Layer

The Backend Abstraction Layer (BAL) provides a uniform interface to heterogeneous data stores used by the Advanced Context Management System. Context strategies query text, vector, and graph backends through protocol-defined APIs, enabling backend implementations to be swapped without changing strategy code.

Architecture

Strategy ──► ScopedView ──► Backend Protocol ──► Physical Store
                │
                └── resource_filter (scope)

Each backend type has a Protocol (structural subtyping) and a corresponding frozen result dataclass. Strategies never instantiate backends directly — they receive scoped views from the Context Assembly Pipeline via dependency injection.

Protocol Contracts

TextBackend

Full-text search over indexed resource content.

Method	Signature	Returns
search	(query: str, *, scope: frozenset[str], max_results: int = 20)	list[TextResult]

Preconditions:

• query must be a non-empty string.
• max_results must be a positive integer.

Postconditions:

• Returns results ordered by descending score.
• Results are restricted to resources whose ULIDs appear in scope.

VectorBackend

Embedding similarity search over chunked resource content.

Method	Signature	Returns
similarity_search	(embedding: list[float], *, scope: frozenset[str], top_k: int = 20)	list[VectorResult]

Preconditions:

• embedding must be a non-empty list of floats.
• top_k must be a positive integer.

Postconditions:

• Returns results ordered by descending score (cosine similarity).
• Results are restricted to resources whose ULIDs appear in scope.

GraphBackend

Knowledge-graph queries and traversals over UKO triples.

Method	Signature	Returns
sparql_query	(query: str, *, scope: frozenset[str])	GraphResult
get_triples	(subject: str)	GraphResult
traverse	(start: str, *, depth: int = 2)	GraphResult

Preconditions:

• query and subject and start must be non-empty strings.
• depth must be a non-negative integer.

Postconditions:

• sparql_query restricts results to resources in scope.
• traverse returns triples discovered within depth hops of start.

Result Types

All result types are frozen (immutable) dataclasses.

TextResult

Field	Type	Description
uko_uri	str	UKO URI of the matching information unit (non-empty)
content	str	Matched text content
score	float	Relevance score, 0.0 -- 1.0
metadata	dict[str, str]	Backend-specific metadata (default: empty)

VectorResult

Field	Type	Description
uko_uri	str	UKO URI of the matching information unit (non-empty)
content	str	Text content of matched chunk
score	float	Cosine similarity, 0.0 -- 1.0
metadata	dict[str, str]	Backend-specific metadata (default: empty)

GraphResult

Field	Type	Description
triples	list[tuple[str, str, str]]	(subject, predicate, object) triples
metadata	dict[str, str]	Backend-specific metadata (default: empty)

Extension Points

Implementing a Custom Backend

To add a new backend (e.g., Tantivy for text search):

1. Create a class that satisfies the corresponding Protocol (e.g., TextBackend).
2. Implement all protocol methods with proper argument validation.
3. Register the backend in the DI container by overriding the provider:

from cleveragents.application.container import override_providers

override_providers(text_backend=TantivyTextBackend(index_path="/data/tantivy"))

In-Memory Stubs

The following stubs are provided for development and testing:

Stub	Protocol	Behaviour
InMemoryTextBackend	TextBackend	Returns empty list; validates args
InMemoryVectorBackend	VectorBackend	Returns empty list; validates args
InMemoryGraphBackend	GraphBackend	Returns empty GraphResult; validates args

Stubs are registered as the default providers in the DI container. They can be overridden at runtime for production or per-test via override_providers().

DI Container Registration

Backends are registered as singletons in the DI container (cleveragents.application.container.Container):

text_backend = providers.Singleton(InMemoryTextBackend)
vector_backend = providers.Singleton(InMemoryVectorBackend)
graph_backend = providers.Singleton(InMemoryGraphBackend)

To swap to a production backend, override the provider before first use:

container = get_container()
container.text_backend.override(providers.Singleton(TantivyTextBackend))

Module Locations

Module	Purpose
cleveragents.domain.models.acms.backends	Protocol definitions and result dataclasses
cleveragents.domain.models.acms.stubs	In-memory stub implementations
cleveragents.application.container	DI container backend registration

Related

• CRP Reference — Context Request Protocol types
• Specification: ACMS > Backend Abstraction Layer — Authoritative design
• ADR-014: Context Management — Architecture decision record