shellbrain 0.1.0__py3-none-any.whl

app/core/entities/identity.py

@@ -0,0 +1,48 @@
+"""Core caller-identity concepts used across runtime, episodes, and telemetry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class IdentityTrustLevel(str, Enum):
+    """Supported caller-identity trust levels."""
+
+    TRUSTED = "trusted"
+    UNTRUSTED = "untrusted"
+    UNSUPPORTED = "unsupported"
+
+
+def build_canonical_caller_id(*, host_app: str, host_session_key: str, agent_key: str | None = None) -> str:
+    """Build the canonical caller identifier from one host session and optional agent key."""
+
+    canonical = f"{host_app}:{host_session_key}"
+    if agent_key:
+        canonical = f"{canonical}:agent:{agent_key}"
+    return canonical
+
+
+@dataclass(frozen=True, kw_only=True)
+class CallerIdentity:
+    """Canonical caller identity used to scope episodes, session state, and guidance."""
+
+    host_app: str
+    host_session_key: str
+    agent_key: str | None = None
+    canonical_id: str | None = None
+    trust_level: IdentityTrustLevel = IdentityTrustLevel.UNTRUSTED
+
+    def __post_init__(self) -> None:
+        """Fill the canonical id when the caller omits it."""
+
+        if self.canonical_id is None:
+            object.__setattr__(
+                self,
+                "canonical_id",
+                build_canonical_caller_id(
+                    host_app=self.host_app,
+                    host_session_key=self.host_session_key,
+                    agent_key=self.agent_key,
+                ),
+            )

app/core/entities/memory.py

@@ -0,0 +1,34 @@
+"""This module defines immutable shellbrain entities and core shellbrain enums."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class MemoryKind(str, Enum):
+    """This enum defines ratified atomic shellbrain kinds."""
+
+    PROBLEM = "problem"
+    SOLUTION = "solution"
+    FAILED_TACTIC = "failed_tactic"
+    FACT = "fact"
+    PREFERENCE = "preference"
+    CHANGE = "change"
+
+
+class MemoryScope(str, Enum):
+    """This enum defines shellbrain visibility scope."""
+
+    REPO = "repo"
+    GLOBAL = "global"
+
+
+@dataclass(kw_only=True)
+class Memory:
+    """This dataclass models an immutable shellbrain record."""
+
+    id: str
+    repo_id: str
+    scope: MemoryScope
+    kind: MemoryKind
+    text: str
+    archived: bool = False

app/core/entities/runtime_context.py

@@ -0,0 +1,19 @@
+"""Per-invocation runtime context shared across CLI handlers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.core.contracts.errors import ErrorDetail
+from app.core.entities.identity import CallerIdentity
+
+
+@dataclass(frozen=True)
+class RuntimeContext:
+    """Per-command context captured in CLI main and consumed by handlers."""
+
+    invocation_id: str
+    repo_root: str
+    no_sync: bool = False
+    caller_identity: CallerIdentity | None = None
+    caller_identity_error: ErrorDetail | None = None

app/core/entities/session_state.py

@@ -0,0 +1,31 @@
+"""Core session-state entities for per-caller working memory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class SessionStateResetReason(str, Enum):
+    """Reasons a working session may be reset while preserving caller identity metadata."""
+
+    IDLE_EXPIRED = "idle_expired"
+    CALLER_SWITCHED = "caller_switched"
+
+
+@dataclass(kw_only=True)
+class SessionState:
+    """Per-caller repo-local working state used to drive exact events and guidance."""
+
+    caller_id: str
+    host_app: str
+    host_session_key: str
+    agent_key: str | None = None
+    session_started_at: str
+    last_seen_at: str
+    current_problem_id: str | None = None
+    last_events_episode_id: str | None = None
+    last_events_event_ids: list[str] = field(default_factory=list)
+    last_events_at: str | None = None
+    last_guidance_at: str | None = None
+    last_guidance_problem_id: str | None = None

app/core/entities/telemetry.py

@@ -0,0 +1,152 @@
+"""Internal telemetry entities used to persist low-overhead usage analytics."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from app.core.entities.runtime_context import RuntimeContext as OperationDispatchTelemetryContext
+
+
+@dataclass(frozen=True)
+class SessionSelectionSummary:
+    """Resolved session/thread context recorded alongside one command invocation."""
+
+    selected_host_app: str | None = None
+    selected_host_session_key: str | None = None
+    selected_thread_id: str | None = None
+    selected_episode_id: str | None = None
+    matching_candidate_count: int = 0
+    selection_ambiguous: bool = False
+
+
+@dataclass(frozen=True)
+class OperationInvocationRecord:
+    """Append-only parent row for one operational command invocation."""
+
+    id: str
+    command: str
+    repo_id: str
+    repo_root: str
+    no_sync: bool
+    caller_id: str | None
+    caller_trust_level: str | None
+    identity_failure_code: str | None
+    selected_host_app: str | None
+    selected_host_session_key: str | None
+    selected_thread_id: str | None
+    selected_episode_id: str | None
+    matching_candidate_count: int
+    selection_ambiguous: bool
+    outcome: str
+    error_stage: str | None
+    error_code: str | None
+    error_message: str | None
+    total_latency_ms: int
+    poller_start_attempted: bool
+    poller_started: bool
+    created_at: datetime
+    guidance_codes: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ReadSummaryRecord:
+    """One summary row describing a successful read invocation."""
+
+    invocation_id: str
+    query_text: str
+    mode: str
+    requested_limit: int | None
+    effective_limit: int
+    include_global: bool | None
+    kinds_filter: list[str] | None
+    direct_count: int
+    explicit_related_count: int
+    implicit_related_count: int
+    total_returned: int
+    zero_results: bool
+    created_at: datetime
+
+
+@dataclass(frozen=True)
+class ReadResultItemRecord:
+    """One displayed read result item in stable pack order."""
+
+    invocation_id: str
+    ordinal: int
+    memory_id: str
+    kind: str
+    section: str
+    priority: int
+    why_included: str
+    anchor_memory_id: str | None
+    relation_type: str | None
+
+
+@dataclass(frozen=True)
+class WriteSummaryRecord:
+    """One summary row describing a successful create or update invocation."""
+
+    invocation_id: str
+    operation_command: str
+    target_memory_id: str
+    target_kind: str | None
+    update_type: str | None
+    scope: str | None
+    evidence_ref_count: int
+    planned_effect_count: int
+    created_memory_count: int
+    archived_memory_count: int
+    utility_observation_count: int
+    association_effect_count: int
+    fact_update_count: int
+    created_at: datetime
+
+
+@dataclass(frozen=True)
+class WriteEffectItemRecord:
+    """One compact side-effect row attached to a write invocation."""
+
+    invocation_id: str
+    ordinal: int
+    effect_type: str
+    repo_id: str
+    primary_memory_id: str | None
+    secondary_memory_id: str | None
+    params_json: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class EpisodeSyncRunRecord:
+    """One inline or poller sync attempt."""
+
+    id: str
+    source: str
+    invocation_id: str | None
+    repo_id: str
+    host_app: str
+    host_session_key: str
+    thread_id: str
+    episode_id: str | None
+    transcript_path: str | None
+    outcome: str
+    error_stage: str | None
+    error_message: str | None
+    duration_ms: int
+    imported_event_count: int
+    total_event_count: int
+    user_event_count: int
+    assistant_event_count: int
+    tool_event_count: int
+    system_event_count: int
+    created_at: datetime
+
+
+@dataclass(frozen=True)
+class EpisodeSyncToolTypeRecord:
+    """Aggregated per-tool counts for one sync run."""
+
+    sync_run_id: str
+    tool_type: str
+    event_count: int

app/core/entities/utility.py

@@ -0,0 +1,14 @@
+"""This module defines utility-observation entities used for contextual feedback."""
+
+from dataclasses import dataclass
+
+
+@dataclass(kw_only=True)
+class UtilityObservation:
+    """This dataclass models a utility vote linked to shellbrain and problem context."""
+
+    id: str
+    memory_id: str
+    problem_id: str
+    vote: float
+    rationale: str | None = None

app/core/interfaces/__init__.py

@@ -0,0 +1 @@
+"""This package defines core interface abstractions for periphery adapters."""

app/core/interfaces/clock.py

@@ -0,0 +1,12 @@
+"""This module defines an interface for obtaining current time values."""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+
+class IClock(ABC):
+    """This interface defines a deterministic clock boundary."""
+
+    @abstractmethod
+    def now(self) -> datetime:
+        """This method returns the current timestamp."""

app/core/interfaces/config.py

@@ -0,0 +1,28 @@
+"""This module defines configuration provider interfaces for policy and runtime values."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class IConfigProvider(ABC):
+    """This interface defines accessors for policy and runtime configuration sections."""
+
+    @abstractmethod
+    def get_read_policy(self) -> dict[str, Any]:
+        """This method returns read-policy configuration values."""
+
+    @abstractmethod
+    def get_create_policy(self) -> dict[str, Any]:
+        """This method returns create-policy configuration values."""
+
+    @abstractmethod
+    def get_update_policy(self) -> dict[str, Any]:
+        """This method returns update-policy configuration values."""
+
+    @abstractmethod
+    def get_thresholds(self) -> dict[str, Any]:
+        """This method returns threshold configuration values."""
+
+    @abstractmethod
+    def get_runtime(self) -> dict[str, Any]:
+        """This method returns runtime configuration values."""

app/core/interfaces/embeddings.py

@@ -0,0 +1,12 @@
+"""This module defines a boundary for generating embedding vectors from text."""
+
+from abc import ABC, abstractmethod
+from typing import Sequence
+
+
+class IEmbeddingProvider(ABC):
+    """This interface defines embedding generation for create-time shellbrain writes."""
+
+    @abstractmethod
+    def embed(self, text: str) -> Sequence[float]:
+        """This method returns an embedding vector for the given text."""

app/core/interfaces/idgen.py

@@ -0,0 +1,11 @@
+"""This module defines an interface for generating stable identifiers."""
+
+from abc import ABC, abstractmethod
+
+
+class IIdGenerator(ABC):
+    """This interface defines generation of unique string identifiers."""
+
+    @abstractmethod
+    def new_id(self) -> str:
+        """This method returns a new unique identifier string."""

app/core/interfaces/repos.py

@@ -0,0 +1,279 @@
+"""This module defines repository interfaces for relational and semantic data access."""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any, Sequence
+
+from app.core.entities.associations import AssociationEdge, AssociationObservation
+from app.core.entities.evidence import EvidenceRef
+from app.core.entities.episodes import Episode, EpisodeEvent, SessionTransfer
+from app.core.entities.facts import FactUpdate, ProblemAttempt
+from app.core.entities.memory import Memory
+from app.core.entities.telemetry import (
+    EpisodeSyncRunRecord,
+    EpisodeSyncToolTypeRecord,
+    OperationInvocationRecord,
+    ReadResultItemRecord,
+    ReadSummaryRecord,
+    WriteEffectItemRecord,
+    WriteSummaryRecord,
+)
+from app.core.entities.guidance import PendingUtilityCandidate
+from app.core.entities.utility import UtilityObservation
+
+
+class IMemoriesRepo(ABC):
+    """This interface defines persistence operations for shellbrain aggregates."""
+
+    @abstractmethod
+    def create(self, memory: Memory) -> None:
+        """This method persists a shellbrain record."""
+
+    @abstractmethod
+    def get(self, memory_id: str) -> Memory | None:
+        """This method fetches a shellbrain by identifier."""
+
+    @abstractmethod
+    def list_by_ids(self, ids: Sequence[str]) -> Sequence[Memory]:
+        """This method fetches memories in the input identifier order."""
+
+    @abstractmethod
+    def set_archived(self, *, memory_id: str, archived: bool) -> bool:
+        """This method updates the archived state for a shellbrain and reports whether a row changed."""
+
+    @abstractmethod
+    def upsert_embedding(self, *, memory_id: str, model: str, vector: Sequence[float]) -> None:
+        """This method inserts or updates the embedding vector record for a memory."""
+
+
+class IExperiencesRepo(ABC):
+    """This interface defines persistence operations for problem attempts and fact updates."""
+
+    @abstractmethod
+    def create_problem_attempt(self, attempt: ProblemAttempt) -> None:
+        """This method persists a problem-attempt link."""
+
+    @abstractmethod
+    def create_fact_update(self, fact_update: FactUpdate) -> None:
+        """This method persists a fact-update chain row."""
+
+
+class IAssociationsRepo(ABC):
+    """This interface defines persistence operations for association edges and observations."""
+
+    @abstractmethod
+    def upsert_edge(self, edge: AssociationEdge) -> AssociationEdge:
+        """This method inserts or updates an association edge."""
+
+    @abstractmethod
+    def append_observation(self, observation: AssociationObservation) -> None:
+        """This method appends an immutable association observation."""
+
+
+class IUtilityRepo(ABC):
+    """This interface defines persistence operations for utility observations."""
+
+    @abstractmethod
+    def append_observation(self, observation: UtilityObservation) -> None:
+        """This method appends a utility observation entry."""
+
+
+class IEpisodesRepo(ABC):
+    """This interface defines persistence operations for episodes and events."""
+
+    @abstractmethod
+    def create_episode(self, episode: Episode) -> None:
+        """This method persists an episode row."""
+
+    @abstractmethod
+    def get_episode_by_thread(
+        self,
+        *,
+        repo_id: str,
+        thread_id: str,
+    ) -> Episode | None:
+        """This method fetches one episode by canonical host session key."""
+
+    @abstractmethod
+    def list_event_keys(self, *, episode_id: str) -> Sequence[str]:
+        """This method returns already-imported upstream event keys for one episode."""
+
+    @abstractmethod
+    def next_event_seq(self, *, episode_id: str) -> int:
+        """This method returns the next append sequence number for one episode."""
+
+    @abstractmethod
+    def append_event(self, event: EpisodeEvent) -> None:
+        """This method appends an event into an episode stream."""
+
+    @abstractmethod
+    def close_episode(self, *, episode_id: str, ended_at: datetime) -> None:
+        """This method marks an active episode closed."""
+
+    @abstractmethod
+    def append_transfer(self, transfer: SessionTransfer) -> None:
+        """This method appends a cross-session transfer row."""
+
+    @abstractmethod
+    def list_existing_event_ids(self, *, event_ids: Sequence[str]) -> Sequence[str]:
+        """This method returns episode-event ids that exist anywhere in storage."""
+
+    @abstractmethod
+    def list_visible_event_ids(self, *, repo_id: str, event_ids: Sequence[str]) -> Sequence[str]:
+        """This method returns episode-event ids visible within one repo."""
+
+    @abstractmethod
+    def list_recent_events(
+        self,
+        *,
+        repo_id: str,
+        episode_id: str,
+        limit: int,
+    ) -> Sequence[EpisodeEvent]:
+        """This method returns recent events for one visible episode ordered newest first."""
+
+
+class IEvidenceRepo(ABC):
+    """This interface defines persistence operations for evidence references and links."""
+
+    @abstractmethod
+    def upsert_ref(self, repo_id: str, ref: str) -> EvidenceRef:
+        """This method inserts or returns an evidence reference."""
+
+    @abstractmethod
+    def link_memory_evidence(self, memory_id: str, evidence_id: str) -> None:
+        """This method links a shellbrain to an evidence reference."""
+
+    @abstractmethod
+    def link_association_edge_evidence(self, edge_id: str, evidence_id: str) -> None:
+        """This method links an association edge to an evidence reference."""
+
+
+class ISemanticRetrievalRepo(ABC):
+    """This interface defines semantic-lane retrieval against embeddings."""
+
+    @abstractmethod
+    def query_semantic(
+        self,
+        *,
+        repo_id: str,
+        include_global: bool,
+        query_vector: Sequence[float],
+        kinds: Sequence[str] | None,
+        limit: int,
+    ) -> Sequence[dict[str, Any]]:
+        """This method returns semantic retrieval candidates with scores."""
+
+    @abstractmethod
+    def list_semantic_neighbors(
+        self,
+        *,
+        repo_id: str,
+        include_global: bool,
+        anchor_memory_id: str,
+        kinds: Sequence[str] | None,
+        limit: int | None = None,
+    ) -> Sequence[dict[str, Any]]:
+        """This method returns implicit semantic neighbors for one anchor memory."""
+
+
+class IKeywordRetrievalRepo(ABC):
+    """This interface defines keyword-lane retrieval against the lexical relevance engine."""
+
+    @abstractmethod
+    def query_keyword(
+        self,
+        *,
+        repo_id: str,
+        mode: str,
+        include_global: bool,
+        query_text: str,
+        kinds: Sequence[str] | None,
+        limit: int,
+    ) -> Sequence[dict[str, Any]]:
+        """This method returns lexical retrieval candidates with scores."""
+
+
+class IReadPolicyRepo(ABC):
+    """This interface defines read-path visibility and explicit expansion queries."""
+
+    @abstractmethod
+    def list_problem_attempt_neighbors(
+        self,
+        *,
+        repo_id: str,
+        include_global: bool,
+        anchor_memory_id: str,
+        kinds: Sequence[str] | None,
+    ) -> Sequence[dict[str, Any]]:
+        """This method returns visible problem-attempt neighbors for an anchor memory."""
+
+    @abstractmethod
+    def list_fact_update_neighbors(
+        self,
+        *,
+        repo_id: str,
+        include_global: bool,
+        anchor_memory_id: str,
+        kinds: Sequence[str] | None,
+    ) -> Sequence[dict[str, Any]]:
+        """This method returns visible fact-update neighbors for an anchor memory."""
+
+    @abstractmethod
+    def list_association_neighbors(
+        self,
+        *,
+        repo_id: str,
+        include_global: bool,
+        anchor_memory_id: str,
+        kinds: Sequence[str] | None,
+        min_strength: float,
+    ) -> Sequence[dict[str, Any]]:
+        """This method returns visible association neighbors for an anchor memory."""
+
+
+class ITelemetryRepo(ABC):
+    """This interface defines append-heavy telemetry persistence operations."""
+
+    @abstractmethod
+    def insert_operation_invocation(self, record: OperationInvocationRecord) -> None:
+        """This method appends one command-level telemetry row."""
+
+    @abstractmethod
+    def insert_read_summary(
+        self,
+        summary: ReadSummaryRecord,
+        items: Sequence[ReadResultItemRecord],
+    ) -> None:
+        """This method persists one read summary row and its ordered result items."""
+
+    @abstractmethod
+    def insert_write_summary(
+        self,
+        summary: WriteSummaryRecord,
+        items: Sequence[WriteEffectItemRecord],
+    ) -> None:
+        """This method persists one write summary row and its ordered effect items."""
+
+    @abstractmethod
+    def insert_episode_sync_run(
+        self,
+        run: EpisodeSyncRunRecord,
+        tool_types: Sequence[EpisodeSyncToolTypeRecord],
+    ) -> None:
+        """This method appends one sync-run row and its per-tool aggregates."""
+
+    @abstractmethod
+    def update_operation_polling(self, invocation_id: str, *, attempted: bool, started: bool) -> None:
+        """This method patches the poller-start flags for one existing invocation row."""
+
+    @abstractmethod
+    def list_pending_utility_candidates(
+        self,
+        *,
+        repo_id: str,
+        caller_id: str,
+        problem_id: str,
+        since_iso: str,
+    ) -> Sequence[PendingUtilityCandidate]:
+        """This method returns retrieved memories that still lack a utility vote for one problem."""

app/core/interfaces/retrieval.py

@@ -0,0 +1,20 @@
+"""This module defines lower-level retrieval interfaces for embedding and lexical operations."""
+
+from abc import ABC, abstractmethod
+from typing import Sequence
+
+
+class IVectorSearch(ABC):
+    """This interface defines vector embedding and similarity lookup capabilities."""
+
+    @abstractmethod
+    def embed_query(self, text: str) -> Sequence[float]:
+        """This method returns an embedding vector for query text."""
+
+
+class IKeywordSearch(ABC):
+    """This interface defines lexical lookup capabilities for query text."""
+
+    @abstractmethod
+    def normalize_query(self, text: str) -> str:
+        """This method normalizes text before lexical retrieval."""