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

context_bridge/api/routes/insights.py

@@ -0,0 +1,66 @@
+"""Insight endpoints: namespace health panel and belief timeline (memory diff)."""
+
+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 (
+    BeliefTimelineResponse,
+    HealthPanelResponse,
+    ImportResponse,
+    NamespaceExport,
+)
+from context_bridge.api.security import authorize
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(tags=["insights"])
+
+
+@router.get("/namespaces/{namespace}/health", response_model=HealthPanelResponse)
+def namespace_health(
+    namespace: str,
+    request: Request,
+    manager: MemoryManager = Depends(get_manager),
+) -> HealthPanelResponse:
+    """A single pulse-check: volume, trust distribution, conflicts, lessons, quality."""
+    authorize(request, namespace, "read")
+    return HealthPanelResponse(**manager.namespace_health(namespace=namespace))
+
+
+@router.get("/namespaces/{namespace}/beliefs", response_model=BeliefTimelineResponse)
+def belief_timeline(
+    namespace: str,
+    request: Request,
+    query: str = Query(..., min_length=1),
+    limit: int = Query(default=50, ge=1, le=200),
+    manager: MemoryManager = Depends(get_manager),
+) -> BeliefTimelineResponse:
+    """Trace how belief about a topic evolved over time (a memory diff)."""
+    authorize(request, namespace, "read")
+    events = manager.belief_timeline(query=query, namespace=namespace, limit=limit)
+    return BeliefTimelineResponse(query=query, events=events)
+
+
+@router.get("/namespaces/{namespace}/export", response_model=NamespaceExport)
+def export_namespace(
+    namespace: str,
+    request: Request,
+    manager: MemoryManager = Depends(get_manager),
+) -> NamespaceExport:
+    """Serialize a namespace's memories, lessons and procedures for backup/transfer."""
+    authorize(request, namespace, "read")
+    return NamespaceExport(**manager.export_namespace(namespace=namespace))
+
+
+@router.post("/namespaces/{namespace}/import", response_model=ImportResponse)
+def import_namespace(
+    namespace: str,
+    body: NamespaceExport,
+    request: Request,
+    manager: MemoryManager = Depends(get_manager),
+) -> ImportResponse:
+    """Recreate memories, lessons and procedures from an exported document."""
+    authorize(request, namespace, "write")
+    result = manager.import_namespace(namespace=namespace, payload=body.model_dump())
+    return ImportResponse(**result)

context_bridge/api/routes/learning.py

@@ -0,0 +1,95 @@
+"""Collective-learning endpoints: agent reputation, outcomes, procedures."""
+
+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 (
+    AgentsResponse,
+    OutcomeRequest,
+    OutcomeResponse,
+    ProcedureCreate,
+    ProcedureCreated,
+    ProcedureOutcomeRequest,
+    ProceduresResponse,
+)
+from context_bridge.api.security import authorize
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(tags=["learning"])
+
+
+@router.get("/agents", response_model=AgentsResponse)
+def agent_leaderboard(
+    request: Request,
+    namespace: str = Query(default="default"),
+    limit: int = Query(default=20, ge=1, le=100),
+    manager: MemoryManager = Depends(get_manager),
+) -> AgentsResponse:
+    """Rank agents by accumulated reputation in a namespace."""
+    authorize(request, namespace, "read")
+    return AgentsResponse(agents=manager.agent_leaderboard(namespace=namespace, limit=limit))
+
+
+@router.post("/outcomes", response_model=OutcomeResponse)
+def record_outcome(
+    req: OutcomeRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> OutcomeResponse:
+    """Credit a session's memories and agents by its task outcome."""
+    authorize(request, req.namespace, "write")
+    result = manager.record_outcome(
+        session_id=req.session_id,
+        namespace=req.namespace,
+        success=req.success,
+        weight=req.weight,
+        lesson=req.lesson,
+        lesson_trigger=req.lesson_trigger,
+        severity=req.severity,
+    )
+    return OutcomeResponse(**result)
+
+
+@router.post("/procedures", response_model=ProcedureCreated)
+def create_procedure(
+    req: ProcedureCreate, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> ProcedureCreated:
+    """Store a reusable playbook (procedural memory)."""
+    authorize(request, req.namespace, "write")
+    proc_id = manager.create_procedure(
+        namespace=req.namespace,
+        title=req.title,
+        steps=req.steps,
+        tags=req.tags,
+        created_by=req.created_by,
+    )
+    return ProcedureCreated(id=proc_id or "")
+
+
+@router.get("/procedures", response_model=ProceduresResponse)
+def list_procedures(
+    request: Request,
+    namespace: str = Query(default="default"),
+    query: str | None = Query(default=None),
+    limit: int = Query(default=50, ge=1, le=200),
+    manager: MemoryManager = Depends(get_manager),
+) -> ProceduresResponse:
+    """List playbooks for a namespace, best-performing first."""
+    authorize(request, namespace, "read")
+    return ProceduresResponse(
+        procedures=manager.list_procedures(namespace=namespace, query=query, limit=limit)
+    )
+
+
+@router.post("/procedures/{procedure_id}/outcome", status_code=status.HTTP_204_NO_CONTENT)
+def procedure_outcome(
+    procedure_id: str,
+    req: ProcedureOutcomeRequest,
+    request: Request,
+    namespace: str = Query(default="default"),
+    manager: MemoryManager = Depends(get_manager),
+) -> None:
+    """Record whether using a playbook succeeded, so good ones rise."""
+    authorize(request, namespace, "write")
+    if not manager.record_procedure_outcome(procedure_id, success=req.success):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="procedure not found")

context_bridge/api/routes/lessons.py

@@ -0,0 +1,88 @@
+"""Failure-memory endpoints: capture, list and apply lessons from mistakes."""
+
+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 (
+    LessonCreated,
+    LessonRequest,
+    LessonsDistilled,
+    LessonsResponse,
+    PreflightRequest,
+    PreflightResponse,
+)
+from context_bridge.api.security import authorize
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(tags=["lessons"])
+
+
+@router.post("/lessons", response_model=LessonCreated)
+def record_lesson(
+    req: LessonRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> LessonCreated:
+    """Capture a lesson so a past mistake can be flagged before it recurs."""
+    authorize(request, req.namespace, "write")
+    lesson_id = manager.record_lesson(
+        namespace=req.namespace,
+        trigger=req.trigger,
+        guidance=req.guidance,
+        severity=req.severity,
+        created_by=req.created_by,
+        session_id=req.session_id,
+    )
+    return LessonCreated(id=lesson_id or "")
+
+
+@router.get("/lessons", response_model=LessonsResponse)
+def list_lessons(
+    request: Request,
+    namespace: str = Query(default="default"),
+    limit: int = Query(default=100, ge=1, le=500),
+    manager: MemoryManager = Depends(get_manager),
+) -> LessonsResponse:
+    """List a namespace's lessons, most-proven first."""
+    authorize(request, namespace, "read")
+    return LessonsResponse(lessons=manager.list_lessons(namespace=namespace, limit=limit))
+
+
+@router.post("/lessons/distill", response_model=LessonsDistilled)
+def distill_lessons(
+    request: Request,
+    namespace: str = Query(default="default"),
+    manager: MemoryManager = Depends(get_manager),
+) -> LessonsDistilled:
+    """Cluster memories implicated in failures into auto-drafted lessons."""
+    authorize(request, namespace, "write")
+    settings = request.app.state.settings
+    result = manager.distill_lessons(
+        namespace=namespace,
+        min_cluster=settings.lesson_distill_min_cluster,
+        similarity=settings.lesson_distill_similarity,
+    )
+    return LessonsDistilled(**result)
+
+
+@router.post("/lessons/{lesson_id}/confirm", status_code=status.HTTP_204_NO_CONTENT)
+def confirm_lesson(
+    lesson_id: str,
+    request: Request,
+    namespace: str = Query(default="default"),
+    manager: MemoryManager = Depends(get_manager),
+) -> None:
+    """Record that a surfaced lesson actually helped, so it ranks higher."""
+    authorize(request, namespace, "write")
+    if not manager.confirm_lesson(lesson_id):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="lesson not found")
+
+
+@router.post("/preflight", response_model=PreflightResponse)
+def preflight(
+    req: PreflightRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> PreflightResponse:
+    """Brief an agent on what the collective knows before it starts a task."""
+    authorize(request, req.namespace, "read")
+    result = manager.preflight(task=req.task, namespace=req.namespace, limit=req.limit)
+    return PreflightResponse(**result)

context_bridge/api/routes/maintenance.py

@@ -0,0 +1,76 @@
+"""Maintenance endpoints (TTL sweep and other housekeeping)."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query, Request
+
+from context_bridge.api import metrics
+from context_bridge.api.deps import get_manager
+from context_bridge.api.schemas import (
+    ConsolidateResponse,
+    MaintenanceRunResponse,
+    SweepResponse,
+)
+from context_bridge.api.security import authorize
+from context_bridge.config import Settings
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(prefix="/maintenance", tags=["maintenance"])
+
+
+def _run_maintenance(manager: MemoryManager, settings: Settings) -> dict:
+    """Run one full housekeeping cycle using the configured policy."""
+    return manager.run_maintenance(
+        auto_resolve=settings.maintenance_auto_resolve,
+        consolidate=settings.maintenance_consolidate,
+        distill_lessons=settings.maintenance_distill_lessons,
+        min_gap=settings.auto_resolve_min_gap,
+        consolidation_min_cluster=settings.consolidation_min_cluster,
+        consolidation_similarity=settings.consolidation_similarity,
+        lesson_distill_min_cluster=settings.lesson_distill_min_cluster,
+        lesson_distill_similarity=settings.lesson_distill_similarity,
+    )
+
+
+@router.post("/sweep", response_model=SweepResponse)
+def sweep_expired(request: Request, manager: MemoryManager = Depends(get_manager)) -> SweepResponse:
+    """Physically delete TTL-expired memories from the semantic store.
+
+    A global maintenance action: requires write access across all namespaces.
+    """
+    authorize(request, "*", "write")
+    deleted = manager.sweep_expired()
+    metrics.SWEEP_DELETED.inc(deleted)
+    return SweepResponse(deleted=deleted)
+
+
+@router.post("/consolidate", response_model=ConsolidateResponse)
+def consolidate(
+    request: Request,
+    namespace: str = Query(default="default"),
+    manager: MemoryManager = Depends(get_manager),
+) -> ConsolidateResponse:
+    """Cluster a namespace's memories and write back synthesized insights."""
+    authorize(request, namespace, "write")
+    settings = request.app.state.settings
+    result = manager.consolidate(
+        namespace=namespace,
+        min_cluster=settings.consolidation_min_cluster,
+        similarity=settings.consolidation_similarity,
+    )
+    return ConsolidateResponse(**result)
+
+
+@router.post("/run", response_model=MaintenanceRunResponse)
+def run_maintenance(
+    request: Request, manager: MemoryManager = Depends(get_manager)
+) -> MaintenanceRunResponse:
+    """Run one full housekeeping cycle: sweep + per-namespace upkeep.
+
+    A global maintenance action: requires write access across all namespaces.
+    """
+    authorize(request, "*", "write")
+    result = _run_maintenance(manager, request.app.state.settings)
+    metrics.SWEEP_DELETED.inc(result["swept"])
+    metrics.MAINTENANCE_RUNS.inc()
+    return MaintenanceRunResponse(**result)

context_bridge/api/routes/memory.py

@@ -0,0 +1,221 @@
+"""Memory read/write endpoints — the core agent-facing contract."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from fastapi.responses import StreamingResponse
+
+from context_bridge.api import metrics
+from context_bridge.api.deps import get_manager
+from context_bridge.api.schemas import (
+    ChunkOut,
+    FeedbackRequest,
+    ForgetResponse,
+    ListResponse,
+    QueryRequest,
+    QueryResponse,
+    SummarizeRequest,
+    SummarizeResponse,
+    WriteBatchRequest,
+    WriteBatchResponse,
+    WriteRequest,
+    WriteResponse,
+)
+from context_bridge.api.security import authorize
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(prefix="/memory", tags=["memory"])
+
+
+def _do_write(manager: MemoryManager, req: WriteRequest) -> WriteResponse:
+    result = manager.write(
+        content=req.content,
+        agent_id=req.agent_id,
+        session_id=req.session_id,
+        task_id=req.task_id,
+        namespace=req.namespace,
+        tags=req.tags,
+        confidence=req.confidence,
+        metadata=req.metadata,
+        source=req.source,
+        ttl_seconds=req.ttl_seconds,
+        dedup=req.dedup,
+        summarize_before_store=req.summarize_before_store,
+    )
+    metrics.WRITES.inc()
+    metrics.CHUNKS_STORED.inc(result.stored)
+    metrics.CHUNKS_DEDUPED.inc(result.deduped)
+    return WriteResponse(
+        ids=result.ids, stored=result.stored, deduped=result.deduped, skipped=result.skipped
+    )
+
+
+@router.post("/write", response_model=WriteResponse)
+def write_memory(
+    req: WriteRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> WriteResponse:
+    authorize(request, req.namespace, "write")
+    return _do_write(manager, req)
+
+
+@router.post("/write_batch", response_model=WriteBatchResponse)
+def write_memory_batch(
+    req: WriteBatchRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> WriteBatchResponse:
+    for item in req.items:
+        authorize(request, item.namespace, "write")
+    return WriteBatchResponse(results=[_do_write(manager, item) for item in req.items])
+
+
+@router.post("/query", response_model=QueryResponse)
+def query_memory(
+    req: QueryRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> QueryResponse:
+    authorize(request, req.namespace, "read")
+    assembled = manager.query(
+        query=req.query,
+        namespace=req.namespace,
+        agent_id=req.agent_id,
+        session_id=req.session_id,
+        top_k=req.top_k,
+        token_budget=req.token_budget,
+        filters=req.filters,
+        rerank=req.rerank,
+        expand_parents=req.expand_parents,
+        include_dates=req.include_dates,
+        since=req.since,
+        until=req.until,
+        with_lessons=req.with_lessons,
+    )
+    metrics.QUERIES.inc()
+    metrics.QUERY_TOKENS.observe(assembled.tokens_used)
+    metrics.QUERY_CHUNKS.observe(len(assembled.chunks))
+    return QueryResponse.from_assembled(assembled)
+
+
+def _sse(event: str, data: dict) -> str:
+    return f"event: {event}\ndata: {json.dumps(data)}\n\n"
+
+
+@router.post("/query/stream")
+def query_memory_stream(
+    req: QueryRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> StreamingResponse:
+    """Recall as a Server-Sent Events stream: one event per chunk, then 'done'.
+
+    Lets an agent render or forward context progressively instead of waiting
+    for the whole assembled block.
+    """
+    authorize(request, req.namespace, "read")
+    assembled = manager.query(
+        query=req.query,
+        namespace=req.namespace,
+        agent_id=req.agent_id,
+        session_id=req.session_id,
+        top_k=req.top_k,
+        token_budget=req.token_budget,
+        filters=req.filters,
+        rerank=req.rerank,
+        expand_parents=req.expand_parents,
+    )
+    metrics.QUERIES.inc()
+    metrics.QUERY_TOKENS.observe(assembled.tokens_used)
+    metrics.QUERY_CHUNKS.observe(len(assembled.chunks))
+
+    def generate() -> Iterator[str]:
+        for chunk in assembled.chunks:
+            yield _sse(
+                "chunk",
+                {
+                    "id": chunk.id,
+                    "content": chunk.content,
+                    "score": chunk.score,
+                    "agent_id": chunk.provenance.agent_id,
+                    "source": chunk.provenance.source,
+                },
+            )
+        yield _sse(
+            "done",
+            {
+                "tokens_used": assembled.tokens_used,
+                "num_chunks": len(assembled.chunks),
+                "sources": assembled.sources,
+            },
+        )
+
+    return StreamingResponse(generate(), media_type="text/event-stream")
+
+
+@router.get("", response_model=ListResponse)
+def list_memory(
+    request: Request,
+    namespace: str = Query(default="default"),
+    limit: int = Query(default=50, ge=1, le=500),
+    cursor: str | None = Query(default=None),
+    manager: MemoryManager = Depends(get_manager),
+) -> ListResponse:
+    authorize(request, namespace, "read")
+    chunks, next_cursor = manager.list_records(namespace=namespace, limit=limit, cursor=cursor)
+    return ListResponse(chunks=[ChunkOut.from_chunk(c) for c in chunks], next_cursor=next_cursor)
+
+
+@router.delete("", response_model=ForgetResponse)
+def forget_memory(
+    request: Request,
+    namespace: str | None = Query(default=None),
+    session_id: str | None = Query(default=None),
+    manager: MemoryManager = Depends(get_manager),
+) -> ForgetResponse:
+    """Erase all memory for a namespace and/or session (right-to-be-forgotten)."""
+    if not namespace and not session_id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="provide a namespace and/or session_id",
+        )
+    authorize(request, namespace or "*", "write")
+    return ForgetResponse(**manager.forget(namespace=namespace, session_id=session_id))
+
+
+@router.get("/{record_id}", response_model=ChunkOut)
+def get_memory(record_id: str, manager: MemoryManager = Depends(get_manager)) -> ChunkOut:
+    chunk = manager.get(record_id)
+    if chunk is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="record not found")
+    return ChunkOut.from_chunk(chunk)
+
+
+@router.delete("/{record_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_memory(record_id: str, manager: MemoryManager = Depends(get_manager)) -> None:
+    manager.delete([record_id])
+
+
+@router.post("/feedback", status_code=status.HTTP_204_NO_CONTENT)
+def submit_feedback(
+    req: FeedbackRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> None:
+    """Signal whether a recalled memory was useful; re-ranks future recall."""
+    authorize(request, req.namespace, "write")
+    manager.record_feedback(
+        memory_id=req.memory_id,
+        namespace=req.namespace,
+        useful=req.useful,
+        weight=req.weight,
+    )
+
+
+@router.post("/summarize", response_model=SummarizeResponse)
+def summarize_session(
+    req: SummarizeRequest, request: Request, manager: MemoryManager = Depends(get_manager)
+) -> SummarizeResponse:
+    authorize(request, req.namespace, "write")
+    result = manager.summarize_session(
+        session_id=req.session_id,
+        namespace=req.namespace,
+        agent_id=req.agent_id,
+        max_sentences=req.max_sentences,
+        store_summary=req.store_summary,
+    )
+    return SummarizeResponse(summary=result["summary"], chunk_ids=result["chunk_ids"])

context_bridge/api/routes/quality.py

@@ -0,0 +1,23 @@
+"""Collaboration-quality endpoint: a single metric for how well agents share."""
+
+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 QualityResponse
+from context_bridge.api.security import authorize
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(tags=["quality"])
+
+
+@router.get("/quality", response_model=QualityResponse)
+def collaboration_quality(
+    request: Request,
+    namespace: str = Query(default="default"),
+    manager: MemoryManager = Depends(get_manager),
+) -> QualityResponse:
+    """Return a composite 0-100 score of collaboration health for a namespace."""
+    authorize(request, namespace, "read")
+    return QualityResponse(**manager.collaboration_quality(namespace=namespace))

context_bridge/api/routes/sessions.py

@@ -0,0 +1,68 @@
+"""Session-level views over episodic / provenance memory."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query, Request, status
+
+from context_bridge.api.deps import get_manager
+from context_bridge.api.schemas import (
+    DistillRequest,
+    DistillResponse,
+    TimelineResponse,
+    TurnRequest,
+    TurnsResponse,
+)
+from context_bridge.api.security import authorize
+from context_bridge.core.memory.manager import MemoryManager
+
+router = APIRouter(prefix="/sessions", tags=["sessions"])
+
+
+@router.get("/{session_id}/timeline", response_model=TimelineResponse)
+def session_timeline(
+    session_id: str,
+    limit: int = Query(default=100, ge=1, le=1000),
+    manager: MemoryManager = Depends(get_manager),
+) -> TimelineResponse:
+    episodes = manager.timeline(session_id, limit=limit)
+    return TimelineResponse(session_id=session_id, episodes=episodes)
+
+
+@router.post("/{session_id}/turns", status_code=status.HTTP_204_NO_CONTENT)
+def add_turn(
+    session_id: str,
+    req: TurnRequest,
+    manager: MemoryManager = Depends(get_manager),
+) -> None:
+    """Append an ephemeral conversational turn to working memory (cheap, TTL'd)."""
+    manager.remember_turn(
+        session_id, {"kind": req.kind, "agent_id": req.agent_id, "content": req.content}
+    )
+
+
+@router.get("/{session_id}/turns", response_model=TurnsResponse)
+def recent_turns(
+    session_id: str,
+    limit: int = Query(default=20, ge=1, le=200),
+    manager: MemoryManager = Depends(get_manager),
+) -> TurnsResponse:
+    return TurnsResponse(session_id=session_id, turns=manager.recent_turns(session_id, limit=limit))
+
+
+@router.post("/{session_id}/distill", response_model=DistillResponse)
+def distill_session(
+    session_id: str,
+    req: DistillRequest,
+    request: Request,
+    manager: MemoryManager = Depends(get_manager),
+) -> DistillResponse:
+    """Promote the session's most salient turns into durable, cross-session memory."""
+    authorize(request, req.namespace, "write")
+    result = manager.distill_session(
+        session_id=session_id,
+        namespace=req.namespace,
+        agent_id=req.agent_id,
+        max_promote=req.max_promote,
+        min_score=req.min_score,
+    )
+    return DistillResponse(**result)