context-bridge-memory 0.1.0__py3-none-any.whl

context_bridge/__init__.py

@@ -0,0 +1,5 @@
+"""Context Bridge — shared neural memory middleware for multi-agent systems."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

context_bridge/__main__.py

@@ -0,0 +1,21 @@
+"""Console entry point: run the API server with uvicorn."""
+
+from __future__ import annotations
+
+from context_bridge.config import get_settings
+
+
+def main() -> None:
+    import uvicorn
+
+    settings = get_settings()
+    uvicorn.run(
+        "context_bridge.api.app:app",
+        host=settings.api_host,
+        port=settings.api_port,
+        log_level=settings.log_level,
+    )
+
+
+if __name__ == "__main__":
+    main()

context_bridge/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API layer (FastAPI)."""

context_bridge/api/access.py

@@ -0,0 +1,67 @@
+"""Role-based access control for namespaces.
+
+Each API key resolves to a :class:`Rule`: a set of namespace glob patterns plus
+the operations (``read`` / ``write``) it may perform. This is what makes the
+shared pool safe for multi-tenant use — a key scoped to ``team-a*`` can never
+read or write ``team-b`` memories.
+
+Two configuration shapes feed it (rich overrides simple):
+
+* ``API_KEY_NAMESPACES`` — ``{"key": ["ns-a", "ns-b"]}`` (implies read + write).
+* ``API_KEY_POLICIES``   — ``{"key": {"namespaces": ["team-a*"],
+  "permissions": ["read"]}}``.
+
+With no API keys configured, access is open.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from fnmatch import fnmatch
+
+READ = "read"
+WRITE = "write"
+_ALL = ("*",)
+_RW = frozenset({READ, WRITE})
+
+
+@dataclass(frozen=True)
+class Rule:
+    namespaces: tuple[str, ...]
+    permissions: frozenset[str]
+
+
+class AccessControl:
+    """Resolves and enforces per-key namespace/operation rules."""
+
+    def __init__(self, rules: dict[str, Rule], *, open_access: bool) -> None:
+        self.rules = rules
+        self.open_access = open_access
+
+    @classmethod
+    def build(cls, settings) -> AccessControl:
+        keys = settings.api_key_set()
+        rules: dict[str, Rule] = {}
+
+        for key, namespaces in settings.api_key_namespace_map().items():
+            rules[key] = Rule(tuple(namespaces) or _ALL, _RW)
+
+        for key, policy in settings.api_key_policies_map().items():
+            rules[key] = Rule(
+                tuple(policy.get("namespaces") or _ALL),
+                frozenset(policy.get("permissions") or [READ, WRITE]),
+            )
+
+        # Any configured key without an explicit rule gets full access.
+        for key in keys:
+            rules.setdefault(key, Rule(_ALL, _RW))
+
+        return cls(rules, open_access=not keys)
+
+    def allows(self, key: str | None, namespace: str, operation: str) -> bool:
+        if self.open_access:
+            return True
+        rule = self.rules.get(key or "")
+        if rule is None or operation not in rule.permissions:
+            return False
+        return any(fnmatch(namespace, pattern) for pattern in rule.namespaces)

context_bridge/api/app.py

@@ -0,0 +1,187 @@
+"""FastAPI application factory."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import time
+import uuid
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from context_bridge import __version__
+from context_bridge.api import metrics
+from context_bridge.api.access import AccessControl
+from context_bridge.api.deps import build_container
+from context_bridge.api.routes import (
+    conflicts,
+    graph,
+    health,
+    insights,
+    learning,
+    lessons,
+    maintenance,
+    memory,
+    quality,
+    sessions,
+)
+from context_bridge.api.security import api_key_guard, build_rate_limiter, rate_limit_guard
+from context_bridge.api.tracing import setup_tracing
+from context_bridge.config import Settings, get_settings
+
+logger = logging.getLogger("context_bridge")
+
+API_V1 = "/v1"
+_REQUEST_ID_HEADER = "X-Request-ID"
+
+
+async def _sweep_loop(app: FastAPI, interval: int) -> None:
+    """Periodically purge TTL-expired memories until cancelled."""
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            deleted = await asyncio.to_thread(app.state.container.manager.sweep_expired)
+            if deleted:
+                logger.info("ttl sweep removed %d expired memories", deleted)
+        except Exception:  # pragma: no cover - defensive background task
+            logger.exception("ttl sweep failed")
+
+
+async def _maintenance_loop(app: FastAPI, interval: int) -> None:
+    """Periodically run a full housekeeping cycle until cancelled."""
+    from context_bridge.api.routes.maintenance import _run_maintenance
+
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            settings = app.state.settings
+            result = await asyncio.to_thread(
+                _run_maintenance, app.state.container.manager, settings
+            )
+            logger.info("maintenance cycle: %s", result)
+        except Exception:  # pragma: no cover - defensive background task
+            logger.exception("maintenance cycle failed")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Build the component graph once at startup, tear down at shutdown."""
+    settings: Settings = app.state.settings
+    app.state.container = build_container(settings)
+
+    tasks: list[asyncio.Task] = []
+    if settings.sweep_interval_seconds > 0:
+        tasks.append(asyncio.create_task(_sweep_loop(app, settings.sweep_interval_seconds)))
+    if settings.maintenance_interval_seconds > 0:
+        tasks.append(
+            asyncio.create_task(_maintenance_loop(app, settings.maintenance_interval_seconds))
+        )
+
+    try:
+        yield
+    finally:
+        for task in tasks:
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        app.state.container = None
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Create and configure the Context Bridge API application."""
+    settings = settings or get_settings()
+    app = FastAPI(
+        title="Context Bridge",
+        version=__version__,
+        summary="Shared neural memory middleware for multi-agent systems.",
+        lifespan=lifespan,
+    )
+    app.state.settings = settings
+    app.state.rate_limiter = build_rate_limiter(settings)
+    app.state.access = AccessControl.build(settings)
+
+    setup_tracing(app, settings)
+    _install_middleware(app, settings)
+    _install_error_handler(app)
+
+    @app.get("/", tags=["meta"])
+    def root() -> dict:
+        """Service banner with links to docs, health and metrics."""
+        return {
+            "name": "Context Bridge",
+            "description": "Shared neural memory middleware for multi-agent systems.",
+            "version": __version__,
+            "docs": "/docs",
+            "health": "/health",
+            "metrics": "/metrics" if settings.metrics_enabled else None,
+            "api": API_V1,
+        }
+
+    guarded = [Depends(api_key_guard), Depends(rate_limit_guard)]
+    app.include_router(health.router)
+    if settings.metrics_enabled:
+        app.include_router(metrics.router)
+    app.include_router(memory.router, prefix=API_V1, dependencies=guarded)
+    app.include_router(sessions.router, prefix=API_V1, dependencies=guarded)
+    app.include_router(maintenance.router, prefix=API_V1, dependencies=guarded)
+    app.include_router(conflicts.router, prefix=API_V1, dependencies=guarded)
+    app.include_router(graph.router, prefix=API_V1, dependencies=guarded)
+    app.include_router(learning.router, prefix=API_V1, dependencies=guarded)
+    app.include_router(lessons.router, prefix=API_V1, dependencies=guarded)
+    app.include_router(quality.router, prefix=API_V1, dependencies=guarded)
+    app.include_router(insights.router, prefix=API_V1, dependencies=guarded)
+    return app
+
+
+def _install_middleware(app: FastAPI, settings: Settings) -> None:
+    origins = settings.cors_origin_list()
+    # Browsers reject (and it is unsafe to send) credentials with a "*" origin,
+    # so only enable credentialed CORS when explicit origins are configured.
+    allow_all = origins == ["*"]
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=origins,
+        allow_credentials=not allow_all,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.middleware("http")
+    async def _observability(
+        request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        request_id = request.headers.get(_REQUEST_ID_HEADER) or uuid.uuid4().hex
+        request.state.request_id = request_id
+        start = time.perf_counter()
+        response = await call_next(request)
+        elapsed = time.perf_counter() - start
+        response.headers[_REQUEST_ID_HEADER] = request_id
+        if settings.metrics_enabled:
+            route = request.scope.get("route")
+            endpoint = getattr(route, "path", request.url.path)
+            metrics.REQUEST_LATENCY.labels(
+                method=request.method, endpoint=endpoint, status=str(response.status_code)
+            ).observe(elapsed)
+        return response
+
+
+def _install_error_handler(app: FastAPI) -> None:
+    @app.exception_handler(Exception)
+    async def _unhandled(request: Request, exc: Exception) -> JSONResponse:
+        request_id = getattr(request.state, "request_id", None)
+        logger.exception("unhandled error (request_id=%s)", request_id)
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": {"type": "internal_error", "message": "internal server error"},
+                "request_id": request_id,
+            },
+        )
+
+
+app = create_app()

context_bridge/api/deps.py

@@ -0,0 +1,142 @@
+"""Dependency wiring: build the component graph from settings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from fastapi import Request
+
+from context_bridge.config import Settings
+from context_bridge.core.chunking import build_chunker
+from context_bridge.core.embeddings import build_embedder
+from context_bridge.core.embeddings.base import Embedder
+from context_bridge.core.events import CompositeEmitter, EventEmitter, build_emitter
+from context_bridge.core.graph.extractor import build_extractor
+from context_bridge.core.memory.contradiction import build_detector
+from context_bridge.core.memory.manager import CognitiveServices, MemoryManager
+from context_bridge.core.memory.policy import WritePolicy
+from context_bridge.core.memory.redaction import build_redactor
+from context_bridge.core.memory.summarizer import build_summarizer
+from context_bridge.core.retrieval import Retriever, build_reranker
+from context_bridge.core.retrieval.retriever import RetrievalParams
+from context_bridge.core.vectorstore import build_vector_store
+from context_bridge.core.vectorstore.base import VectorStore
+from context_bridge.core.working import build_working_memory
+from context_bridge.db import (
+    AgentProfileRepository,
+    ConflictRepository,
+    Database,
+    EpisodeRepository,
+    FeedbackRepository,
+    GraphRepository,
+    LessonRepository,
+    ParentRepository,
+    ProcedureRepository,
+)
+
+
+@dataclass(slots=True)
+class Container:
+    """Holds the constructed singletons for the lifetime of the process."""
+
+    settings: Settings
+    embedder: Embedder
+    store: VectorStore
+    db: Database
+    manager: MemoryManager
+
+
+def build_container(settings: Settings) -> Container:
+    """Construct every component from configuration and wire the manager."""
+    embedder = build_embedder(settings)
+    store = build_vector_store(
+        settings, dim=embedder.dense_dim, supports_sparse=embedder.supports_sparse
+    )
+    working = build_working_memory(settings)
+    db = Database(settings.database_url)
+    db.create_all()
+    episodes = EpisodeRepository(db)
+    parents = ParentRepository(db)
+    feedback = FeedbackRepository(db)
+    conflicts = ConflictRepository(db)
+    graph = GraphRepository(db)
+    agents = AgentProfileRepository(db)
+    procedures = ProcedureRepository(db)
+    lessons = LessonRepository(db)
+
+    reranker = build_reranker(settings)
+    retriever = Retriever(
+        embedder=embedder,
+        store=store,
+        reranker=reranker,
+        parent_lookup=parents.get_texts,
+        feedback_lookup=feedback.scores,
+        feedback_weight=settings.feedback_weight,
+        confidence_weight=settings.confidence_weight,
+    )
+
+    policy = WritePolicy(
+        dedup_threshold=settings.dedup_threshold,
+        min_confidence=settings.min_confidence,
+    )
+    defaults = RetrievalParams(
+        top_k=settings.default_top_k,
+        token_budget=settings.default_token_budget,
+        candidate_pool=settings.prefetch_limit,
+        mmr_lambda=settings.mmr_lambda,
+    )
+    cognitive = CognitiveServices(
+        redactor=build_redactor(settings),
+        detector=build_detector(settings),
+        extractor=build_extractor(settings),
+        feedback=feedback,
+        conflicts=conflicts,
+        graph=graph,
+        agents=agents,
+        procedures=procedures,
+        lessons=lessons,
+        graph_extraction=settings.graph_extraction,
+        contradiction_similarity=settings.contradiction_similarity,
+        lessons_enabled=settings.lessons_enabled,
+        lessons_top_k=settings.lessons_top_k,
+        lessons_min_score=settings.lessons_min_score,
+        belief_revision=settings.belief_revision,
+        conflict_loser_decay=settings.conflict_loser_decay,
+    )
+    manager = MemoryManager(
+        chunker=build_chunker(settings, embedder=embedder),
+        embedder=embedder,
+        store=store,
+        retriever=retriever,
+        working=working,
+        episodes=episodes,
+        parents=parents,
+        policy=policy,
+        defaults=defaults,
+        summarizer=build_summarizer(settings),
+        cognitive=cognitive,
+        events=_build_events(settings),
+    )
+    return Container(settings=settings, embedder=embedder, store=store, db=db, manager=manager)
+
+
+def _build_events(settings: Settings) -> EventEmitter:
+    """Compose the event sinks: Prometheus metrics (if enabled) plus webhooks."""
+    from context_bridge.api.metrics import MetricsEmitter
+
+    sinks: list[EventEmitter] = []
+    if settings.metrics_enabled:
+        sinks.append(MetricsEmitter())
+    webhooks = build_emitter(settings.webhook_url_list(), timeout=settings.webhook_timeout_seconds)
+    sinks.append(webhooks)
+    return CompositeEmitter(sinks)
+
+
+def get_container(request: Request) -> Container:
+    """FastAPI dependency: the process-wide container from app state."""
+    return request.app.state.container
+
+
+def get_manager(request: Request) -> MemoryManager:
+    """FastAPI dependency: the shared :class:`MemoryManager`."""
+    return request.app.state.container.manager

context_bridge/api/metrics.py

@@ -0,0 +1,58 @@
+"""Prometheus metrics and the /metrics exposition endpoint.
+
+Counters and histograms are module-level singletons (registered once against
+the default registry) and are incremented from the route handlers — the core
+domain layer stays free of any metrics dependency.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Response
+from prometheus_client import CONTENT_TYPE_LATEST, Counter, Histogram, generate_latest
+
+WRITES = Counter("cb_memory_writes_total", "Total memory write requests")
+CHUNKS_STORED = Counter("cb_chunks_stored_total", "Chunks persisted to the store")
+CHUNKS_DEDUPED = Counter("cb_chunks_deduped_total", "Chunks suppressed as duplicates")
+
+QUERIES = Counter("cb_queries_total", "Total memory query requests")
+QUERY_TOKENS = Histogram(
+    "cb_query_tokens_used",
+    "Tokens in the assembled context per query",
+    buckets=(0, 64, 128, 256, 512, 1024, 2048, 4096, 8192),
+)
+QUERY_CHUNKS = Histogram(
+    "cb_query_chunks_returned",
+    "Chunks returned per query",
+    buckets=(0, 1, 2, 4, 8, 16, 32),
+)
+
+SWEEP_DELETED = Counter("cb_sweep_deleted_total", "Expired memories removed by sweeps")
+MAINTENANCE_RUNS = Counter("cb_maintenance_runs_total", "Maintenance cycles executed")
+
+EVENTS = Counter("cb_events_total", "Notable memory events emitted", labelnames=("type",))
+
+REQUEST_LATENCY = Histogram(
+    "cb_request_latency_seconds",
+    "HTTP request latency",
+    labelnames=("method", "endpoint", "status"),
+)
+
+
+class MetricsEmitter:
+    """An :class:`EventEmitter` that records each event as a Prometheus counter.
+
+    This keeps the core domain layer free of any metrics dependency: events are
+    emitted there, and the wiring layer composes this emitter to observe them.
+    """
+
+    def emit(self, event_type: str, namespace: str, data: dict) -> None:
+        EVENTS.labels(type=event_type).inc()
+
+
+router = APIRouter(tags=["metrics"])
+
+
+@router.get("/metrics")
+def metrics() -> Response:
+    """Expose metrics in the Prometheus text exposition format."""
+    return Response(content=generate_latest(), media_type=CONTENT_TYPE_LATEST)

context_bridge/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API route modules."""

context_bridge/api/routes/conflicts.py

@@ -0,0 +1,51 @@
+"""Truth-maintenance endpoints: inspect and resolve detected contradictions."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+
+from context_bridge.api.deps import get_manager
+from context_bridge.api.schemas import AutoResolveResponse, ConflictResolveRequest
+from context_bridge.api.security import authorize
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(prefix="/conflicts", tags=["conflicts"])
+
+
+@router.get("")
+def list_conflicts(
+    request: Request,
+    namespace: str = Query(default="default"),
+    status_filter: str | None = Query(default=None, alias="status"),
+    manager: MemoryManager = Depends(get_manager),
+) -> dict:
+    authorize(request, namespace, "read")
+    return {"conflicts": manager.list_conflicts(namespace=namespace, status=status_filter)}
+
+
+@router.post("/auto-resolve", response_model=AutoResolveResponse)
+def auto_resolve(
+    request: Request,
+    namespace: str = Query(default="default"),
+    manager: MemoryManager = Depends(get_manager),
+) -> AutoResolveResponse:
+    """Auto-close contradictions where the evidence is decisive (belief revision)."""
+    authorize(request, namespace, "write")
+    settings = request.app.state.settings
+    result = manager.auto_resolve_conflicts(
+        namespace=namespace, min_gap=settings.auto_resolve_min_gap
+    )
+    return AutoResolveResponse(**result)
+
+
+@router.post("/{conflict_id}/resolve", status_code=status.HTTP_204_NO_CONTENT)
+def resolve_conflict(
+    conflict_id: str,
+    req: ConflictResolveRequest,
+    request: Request,
+    namespace: str = Query(default="default"),
+    manager: MemoryManager = Depends(get_manager),
+) -> None:
+    authorize(request, namespace, "write")
+    if not manager.resolve_conflict(conflict_id, winner_id=req.winner_id):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="conflict not found")

context_bridge/api/routes/graph.py

@@ -0,0 +1,61 @@
+"""Knowledge-graph endpoints: traverse entities and relations."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query, Request
+
+from context_bridge.api.deps import get_manager
+from context_bridge.api.schemas import (
+    AliasRequest,
+    AliasResponse,
+    AlignRequest,
+    AlignResponse,
+    GraphEdgeOut,
+    GraphResponse,
+)
+from context_bridge.api.security import authorize
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(prefix="/graph", tags=["graph"])
+
+
+@router.get("/neighbors", response_model=GraphResponse)
+def neighbors(
+    request: Request,
+    entity: str = Query(..., min_length=1),
+    namespace: str = Query(default="default"),
+    hops: int = Query(default=1, ge=1, le=4),
+    manager: MemoryManager = Depends(get_manager),
+) -> GraphResponse:
+    """Return relations reachable from ``entity`` within ``hops`` edges."""
+    authorize(request, namespace, "read")
+    edges = manager.graph_neighbors(namespace=namespace, entity=entity, hops=hops)
+    return GraphResponse(entity=entity, edges=[GraphEdgeOut(**e) for e in edges])
+
+
+@router.post("/aliases", response_model=AliasResponse)
+def add_alias(
+    request: Request,
+    body: AliasRequest,
+    manager: MemoryManager = Depends(get_manager),
+) -> AliasResponse:
+    """Declare that ``alias`` refers to the same entity as ``canonical``."""
+    authorize(request, body.namespace, "write")
+    registered = manager.add_alias(
+        namespace=body.namespace, alias=body.alias, canonical=body.canonical
+    )
+    return AliasResponse(
+        registered=registered, aliases=manager.list_aliases(namespace=body.namespace)
+    )
+
+
+@router.post("/align", response_model=AlignResponse)
+def align(
+    request: Request,
+    body: AlignRequest,
+    manager: MemoryManager = Depends(get_manager),
+) -> AlignResponse:
+    """Auto-merge surface variants of the same entity onto one canonical name."""
+    authorize(request, body.namespace, "write")
+    result = manager.align_graph(namespace=body.namespace)
+    return AlignResponse(**result)

context_bridge/api/routes/health.py

@@ -0,0 +1,49 @@
+"""Liveness and readiness endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import text
+
+from context_bridge.api.deps import Container, get_container
+from context_bridge.api.schemas import HealthResponse
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health", response_model=HealthResponse)
+def health() -> HealthResponse:
+    """Liveness check — the process is up and serving."""
+    return HealthResponse(status="ok", components={})
+
+
+@router.get("/healthz", response_model=HealthResponse)
+def readiness(container: Container = Depends(get_container)) -> HealthResponse:
+    """Readiness check — verify backing services are reachable."""
+    components: dict[str, str] = {}
+
+    try:
+        with container.db.session() as session:
+            session.execute(text("SELECT 1"))
+        components["database"] = "ok"
+    except Exception as exc:  # pragma: no cover - depends on live infra
+        components["database"] = f"error: {exc}"
+
+    try:
+        container.store.get("readiness-probe")
+        components["vector_store"] = "ok"
+    except Exception as exc:  # pragma: no cover - depends on live infra
+        components["vector_store"] = f"error: {exc}"
+
+    settings = container.settings
+    if "redis" in (settings.working_provider, settings.rate_limit_backend):
+        try:  # pragma: no cover - depends on live infra
+            import redis
+
+            redis.Redis.from_url(settings.redis_url).ping()
+            components["redis"] = "ok"
+        except Exception as exc:  # pragma: no cover - depends on live infra
+            components["redis"] = f"error: {exc}"
+
+    status = "ok" if all(v == "ok" for v in components.values()) else "degraded"
+    return HealthResponse(status=status, components=components)