feat(acms): add text, vector, and graph backend protocol implementations #519

2026-03-03T00:03:14Z

freemo commented

2026-03-03 00:03:14 +00:00

Summary

Implements the Backend Abstraction Layer (BAL) for the ACMS, adding TextBackend, VectorBackend, and GraphBackend protocols with corresponding frozen result dataclasses (TextResult, VectorResult, GraphResult)
Provides in-memory stub backends (InMemoryTextBackend, InMemoryVectorBackend, InMemoryGraphBackend) as development placeholders and test doubles
Registers all three backends in the DI container as configurable Singletons with provider override support

Closes #498

Approach

Protocol Design

Each backend protocol is a @runtime_checkable Protocol following the structural subtyping pattern established by ResourceHandler in the codebase
Result types are frozen dataclass instances (not Pydantic) to minimize construction overhead in the context assembly hot path
The scope parameter is typed as frozenset[str] (resource ULIDs) for immutability and hashability, enabling scoped views per the specification's multi-project isolation requirement

Result Dataclasses

TextResult and VectorResult: uko_uri, content, score (0.0-1.0), metadata fields with __post_init__ validation
GraphResult: triples (list of (subject, predicate, object) tuples), metadata fields

DI Container

All three backends registered as providers.Singleton in the Container class
Default: in-memory stubs; production backends (Tantivy, FAISS, Blazegraph, etc.) swap via override_providers()

Testing

Behave BDD: 35 scenarios / 83 steps covering protocol compliance, argument validation, result immutability, and DI resolution
Robot Framework: 6 smoke tests for integration verification
ASV Benchmarks: 4 benchmark suites measuring stub query overhead and instantiation time

Module Locations

Module	Purpose
`src/cleveragents/domain/models/acms/backends.py`	Protocol definitions and result dataclasses
`src/cleveragents/domain/models/acms/stubs.py`	In-memory stub implementations
`src/cleveragents/application/container.py`	DI container backend registration
`docs/reference/acms_backends.md`	Reference documentation

## Summary - Implements the Backend Abstraction Layer (BAL) for the ACMS, adding `TextBackend`, `VectorBackend`, and `GraphBackend` protocols with corresponding frozen result dataclasses (`TextResult`, `VectorResult`, `GraphResult`) - Provides in-memory stub backends (`InMemoryTextBackend`, `InMemoryVectorBackend`, `InMemoryGraphBackend`) as development placeholders and test doubles - Registers all three backends in the DI container as configurable Singletons with provider override support Closes #498 ## Approach ### Protocol Design - Each backend protocol is a `@runtime_checkable` `Protocol` following the structural subtyping pattern established by `ResourceHandler` in the codebase - Result types are frozen `dataclass` instances (not Pydantic) to minimize construction overhead in the context assembly hot path - The `scope` parameter is typed as `frozenset[str]` (resource ULIDs) for immutability and hashability, enabling scoped views per the specification's multi-project isolation requirement ### Result Dataclasses - `TextResult` and `VectorResult`: `uko_uri`, `content`, `score` (0.0-1.0), `metadata` fields with `__post_init__` validation - `GraphResult`: `triples` (list of (subject, predicate, object) tuples), `metadata` fields ### DI Container - All three backends registered as `providers.Singleton` in the `Container` class - Default: in-memory stubs; production backends (Tantivy, FAISS, Blazegraph, etc.) swap via `override_providers()` ### Testing - **Behave BDD**: 35 scenarios / 83 steps covering protocol compliance, argument validation, result immutability, and DI resolution - **Robot Framework**: 6 smoke tests for integration verification - **ASV Benchmarks**: 4 benchmark suites measuring stub query overhead and instantiation time ### Module Locations | Module | Purpose | |--------|--------| | `src/cleveragents/domain/models/acms/backends.py` | Protocol definitions and result dataclasses | | `src/cleveragents/domain/models/acms/stubs.py` | In-memory stub implementations | | `src/cleveragents/application/container.py` | DI container backend registration | | `docs/reference/acms_backends.md` | Reference documentation |

freemo added the

Type

Feature

label 2026-03-03 00:11:08 +00:00

freemo added this to the v3.4.0 milestone 2026-03-03 00:19:53 +00:00

freemo referenced this pull request

2026-03-03 00:50:51 +00:00

feat(acms): add text, vector, and graph backend protocol implementations #498

freemo scheduled this pull request to auto merge when all checks succeed 2026-03-03 03:06:19 +00:00

freemo scheduled this pull request to auto merge when all checks succeed 2026-03-03 03:12:20 +00:00

freemo self-assigned this 2026-03-03 03:12:39 +00:00

freemo force-pushed feature/m5-acms-backends from ac7496f069 to 7479d57e29