shellbrain 0.1.0__py3-none-any.whl

app/core/interfaces/session_state_store.py

@@ -0,0 +1,33 @@
+"""Storage interface for repo-local per-caller working state."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from pathlib import Path
+
+from app.core.entities.session_state import SessionState
+
+
+class ISessionStateStore(ABC):
+    """Abstract persistence for repo-local session state."""
+
+    @abstractmethod
+    def load(self, *, repo_root: Path, caller_id: str) -> SessionState | None:
+        """Load one caller state when it exists."""
+
+    @abstractmethod
+    def save(self, *, repo_root: Path, state: SessionState) -> None:
+        """Persist one caller state."""
+
+    @abstractmethod
+    def delete(self, *, repo_root: Path, caller_id: str) -> None:
+        """Delete one caller state if it exists."""
+
+    @abstractmethod
+    def list(self, *, repo_root: Path) -> Sequence[SessionState]:
+        """Return all caller states for one repo root."""
+
+    @abstractmethod
+    def gc(self, *, repo_root: Path, older_than_iso: str) -> list[str]:
+        """Delete caller states last seen before the given cutoff and return deleted caller ids."""

app/core/interfaces/unit_of_work.py

@@ -0,0 +1,50 @@
+"""This module defines the unit-of-work interface used to enforce transaction boundaries."""
+
+from abc import ABC, abstractmethod
+from typing import Self
+
+from app.core.interfaces.repos import (
+    IAssociationsRepo,
+    IEpisodesRepo,
+    IEvidenceRepo,
+    IExperiencesRepo,
+    IKeywordRetrievalRepo,
+    IMemoriesRepo,
+    IReadPolicyRepo,
+    ISemanticRetrievalRepo,
+    ITelemetryRepo,
+    IUtilityRepo,
+)
+from app.core.interfaces.retrieval import IVectorSearch
+
+
+class IUnitOfWork(ABC):
+    """This interface defines transactional access to all repositories."""
+
+    memories: IMemoriesRepo
+    experiences: IExperiencesRepo
+    associations: IAssociationsRepo
+    utility: IUtilityRepo
+    episodes: IEpisodesRepo
+    evidence: IEvidenceRepo
+    semantic_retrieval: ISemanticRetrievalRepo
+    keyword_retrieval: IKeywordRetrievalRepo
+    read_policy: IReadPolicyRepo
+    telemetry: ITelemetryRepo
+    vector_search: IVectorSearch | None
+
+    @abstractmethod
+    def __enter__(self) -> Self:
+        """This method opens a transaction scope and returns itself."""
+
+    @abstractmethod
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """This method exits the transaction scope with commit-or-rollback behavior."""
+
+    @abstractmethod
+    def commit(self) -> None:
+        """This method commits the current transaction."""
+
+    @abstractmethod
+    def rollback(self) -> None:
+        """This method rolls back the current transaction."""

app/core/policies/__init__.py

@@ -0,0 +1 @@
+"""This package defines core create, read, and update policy packages."""

app/core/policies/_shared/__init__.py

@@ -0,0 +1 @@
+"""This package defines minimal shared internals for create and update policies."""

app/core/policies/_shared/executor.py

@@ -0,0 +1,132 @@
+"""This module defines shared side-effect execution for create and update policies."""
+
+from app.core.entities.associations import (
+    AssociationEdge,
+    AssociationObservation,
+    AssociationRelationType,
+    AssociationSourceMode,
+    AssociationState,
+)
+from app.core.entities.facts import FactUpdate, ProblemAttempt, ProblemAttemptRole
+from app.core.entities.memory import Memory, MemoryKind, MemoryScope
+from app.core.entities.utility import UtilityObservation
+from app.core.interfaces.embeddings import IEmbeddingProvider
+from app.core.interfaces.unit_of_work import IUnitOfWork
+
+
+def apply_side_effects(
+    plan: list[dict[str, object]],
+    uow: IUnitOfWork,
+    *,
+    embedding_provider: IEmbeddingProvider | None = None,
+) -> None:
+    """This function executes a deterministic side-effect plan inside one transaction."""
+
+    for effect in plan:
+        effect_type = str(effect["effect_type"])
+        params = effect["params"]
+        assert isinstance(params, dict)
+
+        if effect_type == "memory.create":
+            uow.memories.create(
+                Memory(
+                    id=str(params["memory_id"]),
+                    repo_id=str(params["repo_id"]),
+                    scope=MemoryScope(str(params["scope"])),
+                    kind=MemoryKind(str(params["kind"])),
+                    text=str(params["text"]),
+                )
+            )
+            continue
+
+        if effect_type == "memory_embedding.upsert":
+            if embedding_provider is None:
+                raise RuntimeError("Embedding provider is required for memory_embedding.upsert")
+            uow.memories.upsert_embedding(
+                memory_id=str(params["memory_id"]),
+                model=str(params["model"]),
+                vector=embedding_provider.embed(str(params["text"])),
+            )
+            continue
+
+        if effect_type == "memory_evidence.attach":
+            refs = params["refs"]
+            assert isinstance(refs, list)
+            for ref in refs:
+                evidence = uow.evidence.upsert_ref(repo_id=str(params["repo_id"]), ref=str(ref))
+                uow.evidence.link_memory_evidence(memory_id=str(params["memory_id"]), evidence_id=evidence.id)
+            continue
+
+        if effect_type == "problem_attempt.create":
+            uow.experiences.create_problem_attempt(
+                ProblemAttempt(
+                    problem_id=str(params["problem_id"]),
+                    attempt_id=str(params["attempt_id"]),
+                    role=ProblemAttemptRole(str(params["role"])),
+                )
+            )
+            continue
+
+        if effect_type == "memory.archive_state":
+            updated = uow.memories.set_archived(memory_id=str(params["memory_id"]), archived=bool(params["archived"]))
+            if not updated:
+                raise LookupError(f"Target shellbrain not found for archive update: {params['memory_id']}")
+            continue
+
+        if effect_type == "utility_observation.append":
+            uow.utility.append_observation(
+                UtilityObservation(
+                    id=str(params["id"]),
+                    memory_id=str(params["memory_id"]),
+                    problem_id=str(params["problem_id"]),
+                    vote=float(params["vote"]),
+                    rationale=str(params["rationale"]) if params.get("rationale") is not None else None,
+                )
+            )
+            continue
+
+        if effect_type == "fact_update.create":
+            uow.experiences.create_fact_update(
+                FactUpdate(
+                    id=str(params["id"]),
+                    old_fact_id=str(params["old_fact_id"]),
+                    change_id=str(params["change_id"]),
+                    new_fact_id=str(params["new_fact_id"]),
+                )
+            )
+            continue
+
+        if effect_type == "association.upsert_and_observe":
+            edge = uow.associations.upsert_edge(
+                AssociationEdge(
+                    id=str(params["edge_id"]),
+                    repo_id=str(params["repo_id"]),
+                    from_memory_id=str(params["from_memory_id"]),
+                    to_memory_id=str(params["to_memory_id"]),
+                    relation_type=AssociationRelationType(str(params["relation_type"])),
+                    source_mode=AssociationSourceMode(str(params["source_mode"])),
+                    state=AssociationState(str(params["state"])),
+                    strength=float(params["strength"]),
+                )
+            )
+            uow.associations.append_observation(
+                AssociationObservation(
+                    id=str(params["observation_id"]),
+                    repo_id=str(params["repo_id"]),
+                    edge_id=edge.id,
+                    from_memory_id=str(params["from_memory_id"]),
+                    to_memory_id=str(params["to_memory_id"]),
+                    relation_type=AssociationRelationType(str(params["relation_type"])),
+                    source=str(params["observation_source"]),
+                    valence=float(params["valence"]),
+                    salience=float(params["salience"]),
+                )
+            )
+            evidence_refs = params.get("evidence_refs", [])
+            assert isinstance(evidence_refs, list)
+            for ref in evidence_refs:
+                evidence = uow.evidence.upsert_ref(repo_id=str(params["repo_id"]), ref=str(ref))
+                uow.evidence.link_association_edge_evidence(edge_id=edge.id, evidence_id=evidence.id)
+            continue
+
+        raise ValueError(f"Unsupported side effect type: {effect_type}")

app/core/policies/_shared/side_effects.py

@@ -0,0 +1,9 @@
+"""This module defines shared side-effect descriptor helpers."""
+
+from typing import Any
+
+
+def make_side_effect(effect_type: str, params: dict[str, Any]) -> dict[str, Any]:
+    """This function creates a normalized side-effect descriptor object."""
+
+    return {"effect_type": effect_type, "params": params}

app/core/policies/create_policy/__init__.py

@@ -0,0 +1 @@
+"""This package defines deterministic create-policy planning and execution."""

app/core/policies/create_policy/pipeline.py

@@ -0,0 +1,96 @@
+"""This module defines create-policy planning and execution helpers."""
+
+from uuid import uuid4
+from typing import Any
+
+from app.core.entities.associations import AssociationSourceMode, AssociationState
+from app.core.entities.memory import MemoryKind
+from app.core.interfaces.embeddings import IEmbeddingProvider
+from app.core.interfaces.unit_of_work import IUnitOfWork
+from app.core.policies._shared.executor import apply_side_effects
+from app.core.policies._shared.side_effects import make_side_effect
+
+
+def build_create_plan(payload: dict[str, Any], *, embedding_model: str = "unknown") -> list[dict[str, Any]]:
+    """This function converts a validated create payload into deterministic side effects."""
+
+    memory = payload["memory"]
+    repo_id = payload["repo_id"]
+    memory_id = payload["memory_id"]
+    plan: list[dict[str, Any]] = [
+        make_side_effect(
+            "memory.create",
+            {
+                "memory_id": memory_id,
+                "repo_id": repo_id,
+                "scope": memory["scope"],
+                "kind": memory["kind"],
+                "text": memory["text"],
+            },
+        ),
+        make_side_effect(
+            "memory_embedding.upsert",
+            {
+                "memory_id": memory_id,
+                "model": embedding_model,
+                "text": memory["text"],
+            },
+        ),
+        make_side_effect(
+            "memory_evidence.attach",
+            {
+                "memory_id": memory_id,
+                "repo_id": repo_id,
+                "refs": list(memory["evidence_refs"]),
+            },
+        ),
+    ]
+
+    problem_id = (memory.get("links") or {}).get("problem_id")
+    if memory["kind"] in {MemoryKind.SOLUTION.value, MemoryKind.FAILED_TACTIC.value} and problem_id:
+        plan.append(
+            make_side_effect(
+                "problem_attempt.create",
+                {
+                    "problem_id": problem_id,
+                    "attempt_id": memory_id,
+                    "role": memory["kind"],
+                },
+            )
+        )
+
+    for association in (memory.get("links") or {}).get("associations", []):
+        confidence = association.get("confidence")
+        salience = association.get("salience")
+        plan.append(
+            make_side_effect(
+                "association.upsert_and_observe",
+                {
+                    "repo_id": repo_id,
+                    "edge_id": str(uuid4()),
+                    "from_memory_id": memory_id,
+                    "to_memory_id": association["to_memory_id"],
+                    "relation_type": association["relation_type"],
+                    "source_mode": AssociationSourceMode.AGENT.value,
+                    "state": AssociationState.TENTATIVE.value,
+                    "strength": confidence if confidence is not None else 0.5,
+                    "observation_id": str(uuid4()),
+                    "observation_source": "agent_explicit",
+                    "valence": confidence if confidence is not None else 0.5,
+                    "salience": salience if salience is not None else 0.5,
+                    "evidence_refs": list(memory["evidence_refs"]),
+                },
+            )
+        )
+    return plan
+
+
+def apply_create_plan(
+    plan: list[dict[str, Any]],
+    uow: IUnitOfWork,
+    *,
+    embedding_provider: IEmbeddingProvider,
+) -> None:
+    """This function executes a deterministic create plan inside one transaction."""
+
+    apply_side_effects(plan, uow, embedding_provider=embedding_provider)

app/core/policies/read_policy/__init__.py

@@ -0,0 +1 @@
+"""This package defines read-policy retrieval and context-pack assembly stages."""

app/core/policies/read_policy/bm25.py

@@ -0,0 +1,114 @@
+"""Helpers for scoring lexical candidates with Okapi BM25 and coverage-aware admission."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from math import log
+from typing import Literal, Sequence
+
+
+_K1 = 1.2
+_B = 0.75
+_COVERAGE_THRESHOLD_BY_MODE = {
+    "targeted": 0.65,
+    "ambient": 0.80,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class BM25Document:
+    """Normalized document representation used for BM25 scoring."""
+
+    memory_id: str
+    terms: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class BM25ScoredDocument:
+    """Scored lexical candidate with query-coverage metadata."""
+
+    memory_id: str
+    score: float
+    coverage: float
+
+
+def score_documents(
+    query_terms: Sequence[str],
+    documents: Sequence[BM25Document],
+    *,
+    k1: float = _K1,
+    b: float = _B,
+) -> list[BM25ScoredDocument]:
+    """Return BM25 scores and weighted query coverage for partially matching documents."""
+
+    normalized_query_terms = tuple(query_terms)
+    if not normalized_query_terms or not documents:
+        return []
+
+    term_frequencies = {document.memory_id: Counter(document.terms) for document in documents}
+    corpus_size = len(documents)
+    average_length = sum(len(document.terms) for document in documents) / corpus_size
+    if average_length <= 0.0:
+        return []
+
+    inverse_document_frequencies = {
+        term: _inverse_document_frequency(
+            sum(1 for document in documents if term in term_frequencies[document.memory_id]),
+            corpus_size,
+        )
+        for term in normalized_query_terms
+    }
+    total_query_weight = sum(inverse_document_frequencies.values())
+    if total_query_weight <= 0.0:
+        return []
+
+    scored: list[BM25ScoredDocument] = []
+    for document in documents:
+        frequencies = term_frequencies[document.memory_id]
+        matched_terms = tuple(term for term in normalized_query_terms if term in frequencies)
+        if not matched_terms:
+            continue
+
+        score = 0.0
+        matched_query_weight = 0.0
+        document_length = len(document.terms)
+        normalization = k1 * (1 - b + b * document_length / average_length)
+        for term in matched_terms:
+            inverse_document_frequency = inverse_document_frequencies[term]
+            term_frequency = frequencies[term]
+            score += inverse_document_frequency * ((term_frequency * (k1 + 1)) / (term_frequency + normalization))
+            matched_query_weight += inverse_document_frequency
+
+        if score > 0.0:
+            scored.append(
+                BM25ScoredDocument(
+                    memory_id=document.memory_id,
+                    score=score,
+                    coverage=matched_query_weight / total_query_weight,
+                )
+            )
+
+    return sorted(scored, key=lambda item: (-item.score, item.memory_id))
+
+
+def admit_scored_documents(
+    scored_documents: Sequence[BM25ScoredDocument],
+    *,
+    mode: Literal["ambient", "targeted"],
+) -> list[dict[str, object]]:
+    """Apply the mode-aware weighted query-coverage gate to scored lexical candidates."""
+
+    threshold = _COVERAGE_THRESHOLD_BY_MODE[mode]
+    admitted = [
+        {"memory_id": document.memory_id, "score": document.score}
+        for document in scored_documents
+        if document.coverage >= threshold
+    ]
+    return sorted(admitted, key=lambda item: (-float(item["score"]), str(item["memory_id"])))
+
+
+def _inverse_document_frequency(document_frequency: int, corpus_size: int) -> float:
+    """Return the BM25 IDF weight for one query term in the current visible corpus."""
+
+    return log(1 + (corpus_size - document_frequency + 0.5) / (document_frequency + 0.5))

app/core/policies/read_policy/context_pack_builder.py

@@ -0,0 +1,140 @@
+"""This module defines bounded context-pack assembly with quotas, dedupe, and hard caps."""
+
+from typing import Any
+
+from app.boot.read_policy import resolve_read_limit, resolve_read_quotas
+
+
+_BUCKET_ORDER = ("direct", "explicit", "implicit")
+_SECTION_NAMES = {
+    "direct": "direct",
+    "explicit": "explicit_related",
+    "implicit": "implicit_related",
+}
+_BUCKET_PRIORITY = {bucket_name: index for index, bucket_name in enumerate(_BUCKET_ORDER)}
+
+
+def assemble_context_pack(scored_candidates: dict[str, list[dict[str, Any]]], payload: dict[str, Any]) -> dict[str, Any]:
+    """This function assembles a final context pack from bucketed candidate groups."""
+
+    mode = str(payload["mode"])
+    limit = resolve_read_limit(mode=mode, explicit_limit=payload.get("limit"))
+    quotas = resolve_read_quotas(mode=mode)
+    sorted_buckets = {
+        bucket_name: sorted(
+            scored_candidates.get(bucket_name, []),
+            key=lambda item: (-float(item["score"]), str(item["memory_id"])),
+        )
+        for bucket_name in _BUCKET_ORDER
+    }
+
+    selected_by_bucket: dict[str, list[dict[str, Any]]] = {bucket_name: [] for bucket_name in _BUCKET_ORDER}
+    seen_memory_ids: set[str] = set()
+    spill_pool: list[tuple[str, dict[str, Any]]] = []
+    remaining = limit
+
+    for bucket_name in _BUCKET_ORDER:
+        section_quota = min(int(quotas.get(bucket_name, 0)), remaining)
+        selected_count = 0
+        for candidate in sorted_buckets[bucket_name]:
+            memory_id = str(candidate["memory_id"])
+            if memory_id in seen_memory_ids:
+                continue
+            if selected_count < section_quota:
+                seen_memory_ids.add(memory_id)
+                selected_by_bucket[bucket_name].append(candidate)
+                selected_count += 1
+                remaining -= 1
+            else:
+                spill_pool.append((bucket_name, candidate))
+
+    if remaining > 0:
+        spill_pool.sort(
+            key=lambda item: (
+                -float(item[1]["score"]),
+                _BUCKET_PRIORITY[item[0]],
+                str(item[1]["memory_id"]),
+            )
+        )
+        for bucket_name, candidate in spill_pool:
+            if remaining <= 0:
+                break
+            memory_id = str(candidate["memory_id"])
+            if memory_id in seen_memory_ids:
+                continue
+            seen_memory_ids.add(memory_id)
+            selected_by_bucket[bucket_name].append(candidate)
+            remaining -= 1
+
+    sections = {
+        "direct": [_shape_item(candidate, "direct") for candidate in selected_by_bucket["direct"]],
+        "explicit_related": [_shape_item(candidate, "explicit") for candidate in selected_by_bucket["explicit"]],
+        "implicit_related": [_shape_item(candidate, "implicit") for candidate in selected_by_bucket["implicit"]],
+    }
+    _assign_priorities(sections)
+    return {
+        "meta": {
+            "mode": mode,
+            "query": payload.get("query"),
+            "limit": limit,
+            "counts": {
+                "direct": len(sections["direct"]),
+                "explicit_related": len(sections["explicit_related"]),
+                "implicit_related": len(sections["implicit_related"]),
+            },
+        },
+        "direct": sections["direct"],
+        "explicit_related": sections["explicit_related"],
+        "implicit_related": sections["implicit_related"],
+    }
+
+
+def _shape_item(candidate: dict[str, Any], bucket_name: str) -> dict[str, Any]:
+    """Project one internal candidate into the compact LLM-facing item shape."""
+
+    item: dict[str, Any] = {
+        "memory_id": str(candidate["memory_id"]),
+        "why_included": _resolve_why_included(candidate, bucket_name),
+    }
+    if "kind" in candidate:
+        item["kind"] = _normalize_kind(candidate["kind"])
+    if "text" in candidate:
+        item["text"] = str(candidate["text"])
+    if bucket_name != "direct" and "anchor_memory_id" in candidate:
+        item["anchor_memory_id"] = str(candidate["anchor_memory_id"])
+    if "relation_type" in candidate:
+        item["relation_type"] = str(candidate["relation_type"])
+    return item
+
+
+def _resolve_why_included(candidate: dict[str, Any], bucket_name: str) -> str:
+    """Resolve a stable user-facing inclusion reason from candidate metadata."""
+
+    if "why_included" in candidate:
+        return str(candidate["why_included"])
+    if bucket_name == "direct":
+        return "direct_match"
+    if bucket_name == "implicit":
+        return "semantic_neighbor"
+    expansion_type = str(candidate.get("expansion_type", ""))
+    return {
+        "problem_attempt": "problem_attempt",
+        "fact_update": "fact_update",
+        "association": "association_link",
+    }.get(expansion_type, expansion_type or "related_memory")
+
+
+def _normalize_kind(kind: Any) -> str:
+    """Normalize shellbrain kind values from entities or strings into JSON-safe text."""
+
+    return str(getattr(kind, "value", kind))
+
+
+def _assign_priorities(sections: dict[str, list[dict[str, Any]]]) -> None:
+    """Assign one global priority order across displayed sections."""
+
+    priority = 1
+    for section_name in ("direct", "explicit_related", "implicit_related"):
+        for item in sections[section_name]:
+            item["priority"] = priority
+            priority += 1