shellbrain 0.1.0__py3-none-any.whl

app/boot/use_cases.py

@@ -0,0 +1,22 @@
+"""This module defines boot-time helpers used by CLI handlers to obtain use-case dependencies."""
+
+from app.boot.embeddings import get_embedding_model_name, get_embedding_provider
+from app.boot.repos import get_uow
+
+
+def get_uow_factory():
+    """This function returns a callable that creates fresh unit-of-work instances."""
+
+    return get_uow
+
+
+def get_embedding_provider_factory():
+    """This function returns a callable that creates fresh embedding providers."""
+
+    return get_embedding_provider
+
+
+def get_embedding_model():
+    """This function returns the model label that should be stored for embedding rows."""
+
+    return get_embedding_model_name()

app/config/__init__.py

@@ -0,0 +1 @@
+"""This package contains configuration loading adapters and defaults."""

app/config/defaults/create_policy.yaml

@@ -0,0 +1,7 @@
+# This file defines default create-policy controls for deterministic side-effect planning.
+gates:
+  - schema
+  - semantic
+  - integrity
+defaults:
+  scope: repo

app/config/defaults/read_policy.yaml

@@ -0,0 +1,25 @@
+# This file defines default read-policy controls for retrieval and context-pack assembly.
+weights:
+  semantic: 1.0
+  keyword: 1.0
+fusion:
+  k_rrf: 20
+limits:
+  targeted: 8
+  ambient: 12
+quotas:
+  targeted:
+    direct: 4
+    explicit: 3
+    implicit: 1
+  ambient:
+    direct: 4
+    explicit: 5
+    implicit: 3
+expansion:
+  semantic_hops: 2
+  include_problem_links: true
+  include_fact_update_links: true
+  include_association_links: true
+  max_association_depth: 2
+  min_association_strength: 0.25

app/config/defaults/runtime.yaml

@@ -0,0 +1,10 @@
+# This file defines runtime defaults for database connectivity and execution mode.
+database:
+  dsn_env: SHELLBRAIN_DB_DSN
+  admin_dsn_env: SHELLBRAIN_DB_ADMIN_DSN
+cli:
+  default_mode: targeted
+  include_global: true
+embeddings:
+  provider: sentence_transformers
+  model: all-MiniLM-L6-v2

app/config/defaults/thresholds.yaml

@@ -0,0 +1,3 @@
+# This file defines threshold defaults for semantic and lexical retrieval gates.
+semantic_threshold: 0.0
+keyword_threshold: 0.0

app/config/defaults/update_policy.yaml

@@ -0,0 +1,5 @@
+# This file defines default update-policy controls for deterministic side-effect planning.
+gates:
+  - schema
+  - semantic
+  - integrity

app/config/loader.py

@@ -0,0 +1,58 @@
+"""This module defines YAML-backed configuration loading for policy and runtime settings."""
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from app.core.interfaces.config import IConfigProvider
+
+
+class YamlConfigProvider(IConfigProvider):
+    """This class loads and serves configuration sections from YAML files."""
+
+    def __init__(self, defaults_dir: Path) -> None:
+        """This method loads all default YAML config files from a directory."""
+
+        self._defaults_dir = defaults_dir
+        self._read_policy = self._load_yaml("read_policy.yaml")
+        self._create_policy = self._load_yaml("create_policy.yaml")
+        self._update_policy = self._load_yaml("update_policy.yaml")
+        self._thresholds = self._load_yaml("thresholds.yaml")
+        self._runtime = self._load_yaml("runtime.yaml")
+
+    def _load_yaml(self, filename: str) -> dict[str, Any]:
+        """This method parses a YAML file into a dictionary."""
+
+        path = self._defaults_dir / filename
+        with path.open("r", encoding="utf-8") as handle:
+            data = yaml.safe_load(handle) or {}
+        if not isinstance(data, dict):
+            raise ValueError(f"Expected mapping in {path}")
+        return data
+
+    def get_read_policy(self) -> dict[str, Any]:
+        """This method returns read-policy configuration values."""
+
+        return deepcopy(self._read_policy)
+
+    def get_create_policy(self) -> dict[str, Any]:
+        """This method returns create-policy configuration values."""
+
+        return deepcopy(self._create_policy)
+
+    def get_update_policy(self) -> dict[str, Any]:
+        """This method returns update-policy configuration values."""
+
+        return deepcopy(self._update_policy)
+
+    def get_thresholds(self) -> dict[str, Any]:
+        """This method returns threshold configuration values."""
+
+        return deepcopy(self._thresholds)
+
+    def get_runtime(self) -> dict[str, Any]:
+        """This method returns runtime configuration values."""
+
+        return deepcopy(self._runtime)

app/core/__init__.py

@@ -0,0 +1 @@
+"""This package contains pure core domain logic and contracts."""

app/core/contracts/__init__.py

@@ -0,0 +1 @@
+"""This package defines strict request, response, and error contracts."""

app/core/contracts/errors.py

@@ -0,0 +1,29 @@
+"""This module defines structured error contracts and canonical error codes."""
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class ErrorCode(str, Enum):
+    """This enum defines canonical error codes across validation and execution layers."""
+
+    SCHEMA_ERROR = "schema_error"
+    SEMANTIC_ERROR = "semantic_error"
+    INTEGRITY_ERROR = "integrity_error"
+    NOT_FOUND = "not_found"
+    CONFLICT = "conflict"
+    INTERNAL_ERROR = "internal_error"
+    HOST_IDENTITY_UNAVAILABLE = "host_identity_unavailable"
+    HOST_IDENTITY_UNSUPPORTED = "host_identity_unsupported"
+    HOST_IDENTITY_DRIFTED = "host_identity_drifted"
+    HOST_HOOK_MISSING = "host_hook_missing"
+    TRANSCRIPT_SOURCE_NOT_FOUND = "transcript_source_not_found"
+
+
+class ErrorDetail(BaseModel):
+    """This model defines a structured error payload entry."""
+
+    code: ErrorCode
+    message: str
+    field: str | None = None

app/core/contracts/requests.py

@@ -0,0 +1,211 @@
+"""This module defines strict internal request contracts for create, read, and update operations."""
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class StrictBaseModel(BaseModel):
+    """This base model enforces strict schemas by rejecting unknown fields."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ReadExpandRequest(StrictBaseModel):
+    """This model defines expansion knobs for read requests."""
+
+    semantic_hops: int | None = Field(default=None, ge=0, le=3)
+    include_problem_links: bool | None = None
+    include_fact_update_links: bool | None = None
+    include_association_links: bool | None = None
+    max_association_depth: int | None = Field(default=None, ge=1, le=4)
+    min_association_strength: float | None = Field(default=None, ge=0.0, le=1.0)
+
+
+class MemoryReadRequest(StrictBaseModel):
+    """This model defines the canonical read request payload."""
+
+    op: Literal["read"] = "read"
+    repo_id: str
+    mode: Literal["ambient", "targeted"]
+    query: str = Field(min_length=1)
+    include_global: bool | None = None
+    kinds: (
+        list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None
+    ) = None
+    limit: int | None = Field(default=None, ge=1, le=100)
+    expand: ReadExpandRequest | None = None
+
+    @field_validator("kinds")
+    @classmethod
+    def _validate_kinds_unique(
+        cls,
+        value: list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None,
+    ) -> list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None:
+        """This validator enforces unique kinds filters for read requests."""
+
+        if value is None:
+            return value
+        if len(value) != len(set(value)):
+            raise ValueError("kinds must be unique")
+        return value
+
+
+class EpisodeEventsRequest(StrictBaseModel):
+    """This model defines the canonical episode-events request payload."""
+
+    op: Literal["events"] = "events"
+    repo_id: str
+    limit: int = Field(default=20, ge=1, le=100)
+
+
+class MemoryCreateAssociationLink(StrictBaseModel):
+    """This model defines a typed explicit association link payload on create."""
+
+    to_memory_id: str
+    relation_type: Literal["depends_on", "associated_with"]
+    confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+    salience: float | None = Field(default=None, ge=0.0, le=1.0)
+    rationale: str | None = None
+
+
+class MemoryCreateLinks(StrictBaseModel):
+    """This model defines optional link payloads on create requests."""
+
+    problem_id: str | None = None
+    related_memory_ids: list[str] = Field(default_factory=list)
+    associations: list[MemoryCreateAssociationLink] = Field(default_factory=list)
+
+    @field_validator("related_memory_ids")
+    @classmethod
+    def _validate_related_unique(cls, value: list[str]) -> list[str]:
+        """This validator enforces unique related-shellbrain references."""
+
+        if len(value) != len(set(value)):
+            raise ValueError("related_memory_ids must be unique")
+        return value
+
+
+class MemoryCreateBody(StrictBaseModel):
+    """This model defines create-body fields for immutable shellbrain records."""
+
+    text: str
+    scope: Literal["repo", "global"]
+    kind: Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]
+    rationale: str | None = None
+    links: MemoryCreateLinks = Field(default_factory=MemoryCreateLinks)
+    evidence_refs: list[str] = Field(min_length=1)
+
+    @field_validator("evidence_refs")
+    @classmethod
+    def _validate_evidence_unique(cls, value: list[str]) -> list[str]:
+        """This validator enforces unique evidence references."""
+
+        if len(value) != len(set(value)):
+            raise ValueError("evidence_refs must be unique")
+        return value
+
+
+class MemoryCreateRequest(StrictBaseModel):
+    """This model defines the canonical create request payload."""
+
+    op: Literal["create"] = "create"
+    repo_id: str
+    memory: MemoryCreateBody
+
+
+class ArchiveStateUpdate(StrictBaseModel):
+    """This model defines archive-state update payload fields."""
+
+    type: Literal["archive_state"]
+    archived: bool
+    rationale: str | None = None
+
+
+class UtilityVoteUpdate(StrictBaseModel):
+    """This model defines utility-vote update payload fields."""
+
+    type: Literal["utility_vote"]
+    problem_id: str
+    vote: float = Field(ge=-1.0, le=1.0)
+    rationale: str | None = None
+    evidence_refs: list[str] = Field(default_factory=list)
+
+    @field_validator("evidence_refs")
+    @classmethod
+    def _validate_evidence_unique(cls, value: list[str]) -> list[str]:
+        """This validator enforces unique utility evidence references."""
+
+        if len(value) != len(set(value)):
+            raise ValueError("evidence_refs must be unique")
+        return value
+
+
+class FactUpdateLinkUpdate(StrictBaseModel):
+    """This model defines fact-update-link payload fields."""
+
+    type: Literal["fact_update_link"]
+    old_fact_id: str
+    new_fact_id: str
+    rationale: str | None = None
+    evidence_refs: list[str] = Field(default_factory=list)
+
+    @field_validator("evidence_refs")
+    @classmethod
+    def _validate_evidence_unique(cls, value: list[str]) -> list[str]:
+        """This validator enforces unique fact-update evidence references."""
+
+        if len(value) != len(set(value)):
+            raise ValueError("evidence_refs must be unique")
+        return value
+
+
+class AssociationLinkUpdate(StrictBaseModel):
+    """This model defines association-link update payload fields."""
+
+    type: Literal["association_link"]
+    to_memory_id: str
+    relation_type: Literal["depends_on", "associated_with"]
+    confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+    salience: float | None = Field(default=None, ge=0.0, le=1.0)
+    rationale: str | None = None
+    evidence_refs: list[str] = Field(min_length=1)
+
+    @field_validator("evidence_refs")
+    @classmethod
+    def _validate_evidence_unique(cls, value: list[str]) -> list[str]:
+        """This validator enforces unique association evidence references."""
+
+        if len(value) != len(set(value)):
+            raise ValueError("evidence_refs must be unique")
+        return value
+
+
+UpdatePayload = Annotated[
+    ArchiveStateUpdate | UtilityVoteUpdate | FactUpdateLinkUpdate | AssociationLinkUpdate,
+    Field(discriminator="type"),
+]
+
+
+class MemoryUpdateRequest(StrictBaseModel):
+    """This model defines the canonical update request payload."""
+
+    op: Literal["update"] = "update"
+    repo_id: str
+    memory_id: str
+    update: UpdatePayload
+
+
+class BatchUtilityVoteItem(StrictBaseModel):
+    """One utility-vote update entry inside a batch update request."""
+
+    memory_id: str
+    update: UtilityVoteUpdate
+
+
+class MemoryBatchUpdateRequest(StrictBaseModel):
+    """This model defines the canonical batch utility-update payload."""
+
+    op: Literal["update"] = "update"
+    repo_id: str
+    updates: list[BatchUtilityVoteItem] = Field(min_length=1)

app/core/contracts/responses.py

@@ -0,0 +1,15 @@
+"""This module defines standardized response envelopes for operation results."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from app.core.contracts.errors import ErrorDetail
+
+
+class OperationResult(BaseModel):
+    """This model defines a deterministic response envelope for all operations."""
+
+    status: Literal["ok", "error"]
+    data: dict[str, Any] = Field(default_factory=dict)
+    errors: list[ErrorDetail] = Field(default_factory=list)

app/core/entities/__init__.py

@@ -0,0 +1 @@
+"""This package defines domain entities used throughout the core."""

app/core/entities/associations.py

@@ -0,0 +1,58 @@
+"""This module defines formal association entities and association metadata enums."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class AssociationRelationType(str, Enum):
+    """This enum defines ratified formal association relation types."""
+
+    DEPENDS_ON = "depends_on"
+    ASSOCIATED_WITH = "associated_with"
+
+
+class AssociationSourceMode(str, Enum):
+    """This enum defines whether an association comes from agent or implicit channels."""
+
+    AGENT = "agent"
+    IMPLICIT = "implicit"
+    MIXED = "mixed"
+
+
+class AssociationState(str, Enum):
+    """This enum defines the lifecycle state of an association edge."""
+
+    TENTATIVE = "tentative"
+    CONFIRMED = "confirmed"
+    DEPRECATED = "deprecated"
+
+
+@dataclass(kw_only=True)
+class AssociationEdge:
+    """This dataclass models a formal association edge between two memories."""
+
+    id: str
+    repo_id: str
+    from_memory_id: str
+    to_memory_id: str
+    relation_type: AssociationRelationType
+    source_mode: AssociationSourceMode = AssociationSourceMode.AGENT
+    state: AssociationState = AssociationState.TENTATIVE
+    strength: float = 0.0
+
+
+@dataclass(kw_only=True)
+class AssociationObservation:
+    """This dataclass models an immutable reinforcement observation for associations."""
+
+    id: str
+    repo_id: str
+    from_memory_id: str
+    to_memory_id: str
+    relation_type: AssociationRelationType
+    source: str
+    valence: float
+    salience: float = 0.5
+    edge_id: str | None = None
+    problem_id: str | None = None
+    episode_id: str | None = None

app/core/entities/episodes.py

@@ -0,0 +1,66 @@
+"""This module defines episodic session entities and transfer provenance entities."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+class EpisodeStatus(str, Enum):
+    """This enum defines lifecycle status values for episodes."""
+
+    ACTIVE = "active"
+    CLOSED = "closed"
+    ARCHIVED = "archived"
+
+
+class EpisodeEventSource(str, Enum):
+    """This enum defines allowed source values for episode events."""
+
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+    SYSTEM = "system"
+
+
+@dataclass(kw_only=True)
+class Episode:
+    """This dataclass models a work-session container record."""
+
+    id: str
+    repo_id: str
+    host_app: str
+    thread_id: str | None = None
+    title: str | None = None
+    objective: str | None = None
+    status: EpisodeStatus = EpisodeStatus.ACTIVE
+    started_at: datetime | None = None
+    ended_at: datetime | None = None
+    created_at: datetime | None = None
+
+
+@dataclass(kw_only=True)
+class EpisodeEvent:
+    """This dataclass models a single immutable event inside an episode."""
+
+    id: str
+    episode_id: str
+    seq: int
+    host_event_key: str
+    source: EpisodeEventSource
+    content: str
+    created_at: datetime | None = None
+
+
+@dataclass(kw_only=True)
+class SessionTransfer:
+    """This dataclass models immutable cross-session transfer provenance."""
+
+    id: str
+    repo_id: str
+    from_episode_id: str
+    to_episode_id: str
+    event_id: str
+    transfer_kind: str
+    rationale: str | None = None
+    transferred_by: str | None = None
+    created_at: datetime | None = None

app/core/entities/evidence.py

@@ -0,0 +1,29 @@
+"""This module defines evidence reference entities and evidence link entities."""
+
+from dataclasses import dataclass
+
+
+@dataclass(kw_only=True)
+class EvidenceRef:
+    """This dataclass models a canonical evidence reference entry."""
+
+    id: str
+    repo_id: str
+    ref: str
+    episode_event_id: str | None = None
+
+
+@dataclass(kw_only=True)
+class MemoryEvidenceLink:
+    """This dataclass models a many-to-many link between shellbrain and evidence."""
+
+    memory_id: str
+    evidence_id: str
+
+
+@dataclass(kw_only=True)
+class AssociationEdgeEvidenceLink:
+    """This dataclass models a many-to-many link between association edges and evidence."""
+
+    edge_id: str
+    evidence_id: str

app/core/entities/facts.py

@@ -0,0 +1,30 @@
+"""This module defines fact-chain and problem-attempt linkage entities."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ProblemAttemptRole(str, Enum):
+    """This enum defines the role of an attempt linked to a problem."""
+
+    SOLUTION = "solution"
+    FAILED_TACTIC = "failed_tactic"
+
+
+@dataclass(kw_only=True)
+class ProblemAttempt:
+    """This dataclass models a direct problem-to-attempt link."""
+
+    problem_id: str
+    attempt_id: str
+    role: ProblemAttemptRole
+
+
+@dataclass(kw_only=True)
+class FactUpdate:
+    """This dataclass models an immutable fact-update chain record."""
+
+    id: str
+    old_fact_id: str
+    change_id: str
+    new_fact_id: str

app/core/entities/guidance.py

@@ -0,0 +1,47 @@
+"""Guidance entities used to nudge agents without adding new top-level commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, kw_only=True)
+class PendingUtilityCandidate:
+    """One memory that still appears to need a utility vote for the active problem."""
+
+    memory_id: str
+    kind: str
+    retrieval_count: int
+    last_seen_at: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class GuidanceDecision:
+    """One guidance item that may be attached to a successful operation result."""
+
+    code: str
+    severity: str
+    message: str
+    problem_id: str | None = None
+    memory_ids: list[str] = field(default_factory=list)
+    vote_scale_hint: dict[str, float] | None = None
+    setup_hint: str | None = None
+
+    def to_payload(self) -> dict[str, Any]:
+        """Serialize one guidance decision into the public response shape."""
+
+        payload: dict[str, Any] = {
+            "code": self.code,
+            "severity": self.severity,
+            "message": self.message,
+        }
+        if self.problem_id is not None:
+            payload["problem_id"] = self.problem_id
+        if self.memory_ids:
+            payload["memory_ids"] = list(self.memory_ids)
+        if self.vote_scale_hint is not None:
+            payload["vote_scale_hint"] = dict(self.vote_scale_hint)
+        if self.setup_hint is not None:
+            payload["setup_hint"] = self.setup_hint
+        return payload