shellbrain 0.1.0__py3-none-any.whl

app/periphery/db/models/utility.py

@@ -0,0 +1,19 @@
+"""This module defines SQLAlchemy Core tables for utility observation records."""
+
+from sqlalchemy import CheckConstraint, Column, Float, ForeignKey, String, Table
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+utility_observations = Table(
+    "utility_observations",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("memory_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("problem_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("vote", Float, nullable=False),
+    Column("rationale", String),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    CheckConstraint("vote >= -1 AND vote <= 1", name="ck_utility_observations_vote_range"),
+)

app/periphery/db/models/views.py

@@ -0,0 +1,154 @@
+"""This module defines view SQL strings used to build derived read-model views."""
+
+
+CURRENT_FACT_SNAPSHOT_SQL = """
+CREATE OR REPLACE VIEW current_fact_snapshot AS
+SELECT m.*
+FROM memories m
+WHERE m.kind = 'fact'
+  AND m.archived = FALSE
+  AND NOT EXISTS (
+    SELECT 1 FROM fact_updates fu WHERE fu.old_fact_id = m.id
+  );
+"""
+
+
+GLOBAL_UTILITY_SQL = """
+CREATE OR REPLACE VIEW global_utility AS
+SELECT memory_id, AVG(vote) AS utility_mean, COUNT(*) AS observations
+FROM utility_observations
+GROUP BY memory_id;
+"""
+
+
+USAGE_COMMAND_DAILY_SQL = """
+CREATE OR REPLACE VIEW usage_command_daily AS
+SELECT
+  repo_id,
+  date_trunc('day', created_at AT TIME ZONE 'UTC') AS day_utc,
+  command,
+  outcome,
+  COUNT(*)::INTEGER AS invocation_count,
+  AVG(total_latency_ms)::DOUBLE PRECISION AS avg_latency_ms
+FROM operation_invocations
+GROUP BY repo_id, date_trunc('day', created_at AT TIME ZONE 'UTC'), command, outcome;
+"""
+
+
+USAGE_MEMORY_RETRIEVAL_SQL = """
+CREATE OR REPLACE VIEW usage_memory_retrieval AS
+SELECT
+  oi.repo_id,
+  rri.memory_id,
+  rri.kind,
+  rri.section,
+  COUNT(*)::INTEGER AS retrieval_count,
+  MAX(oi.created_at) AS last_seen_at
+FROM read_result_items rri
+JOIN operation_invocations oi ON oi.id = rri.invocation_id
+GROUP BY oi.repo_id, rri.memory_id, rri.kind, rri.section;
+"""
+
+
+USAGE_WRITE_EFFECTS_SQL = """
+CREATE OR REPLACE VIEW usage_write_effects AS
+SELECT
+  wei.repo_id,
+  date_trunc('day', oi.created_at AT TIME ZONE 'UTC') AS day_utc,
+  wei.effect_type,
+  COUNT(*)::INTEGER AS effect_count
+FROM write_effect_items wei
+JOIN operation_invocations oi ON oi.id = wei.invocation_id
+GROUP BY wei.repo_id, date_trunc('day', oi.created_at AT TIME ZONE 'UTC'), wei.effect_type;
+"""
+
+
+USAGE_SYNC_HEALTH_SQL = """
+CREATE OR REPLACE VIEW usage_sync_health AS
+WITH sync_grouped AS (
+  SELECT
+    repo_id,
+    host_app,
+    date_trunc('day', created_at AT TIME ZONE 'UTC') AS day_utc,
+    COUNT(*)::INTEGER AS sync_run_count,
+    COUNT(*) FILTER (WHERE outcome = 'error')::INTEGER AS failed_sync_count,
+    COALESCE(SUM(imported_event_count), 0)::INTEGER AS imported_event_count
+  FROM episode_sync_runs
+  GROUP BY repo_id, host_app, date_trunc('day', created_at AT TIME ZONE 'UTC')
+),
+tool_grouped AS (
+  SELECT
+    esr.repo_id,
+    esr.host_app,
+    date_trunc('day', esr.created_at AT TIME ZONE 'UTC') AS day_utc,
+    estt.tool_type,
+    SUM(estt.event_count)::INTEGER AS event_count
+  FROM episode_sync_tool_types estt
+  JOIN episode_sync_runs esr ON esr.id = estt.sync_run_id
+  GROUP BY esr.repo_id, esr.host_app, date_trunc('day', esr.created_at AT TIME ZONE 'UTC'), estt.tool_type
+),
+tool_objects AS (
+  SELECT
+    repo_id,
+    host_app,
+    day_utc,
+    jsonb_object_agg(tool_type, event_count ORDER BY tool_type) AS tool_type_counts
+  FROM tool_grouped
+  GROUP BY repo_id, host_app, day_utc
+)
+SELECT
+  sg.repo_id,
+  sg.host_app,
+  sg.day_utc,
+  sg.sync_run_count,
+  sg.failed_sync_count,
+  sg.imported_event_count,
+  COALESCE(toj.tool_type_counts, '{}'::jsonb) AS tool_type_counts
+FROM sync_grouped sg
+LEFT JOIN tool_objects toj
+  ON toj.repo_id = sg.repo_id
+ AND toj.host_app = sg.host_app
+ AND toj.day_utc = sg.day_utc;
+"""
+
+
+USAGE_SESSION_PROTOCOL_SQL = """
+CREATE OR REPLACE VIEW usage_session_protocol AS
+SELECT
+  oi.repo_id,
+  oi.selected_thread_id,
+  COUNT(*) FILTER (WHERE oi.command = 'read')::INTEGER AS read_count,
+  COUNT(*) FILTER (WHERE oi.command = 'events')::INTEGER AS events_count,
+  COUNT(*) FILTER (WHERE oi.command IN ('create', 'update'))::INTEGER AS write_count,
+  COUNT(*) FILTER (
+    WHERE oi.command = 'read'
+      AND COALESCE(ris.zero_results, FALSE)
+  )::INTEGER AS zero_result_read_count,
+  COUNT(*) FILTER (WHERE oi.selection_ambiguous)::INTEGER AS ambiguous_selection_count,
+  COUNT(*) FILTER (
+    WHERE oi.command IN ('create', 'update')
+      AND EXISTS (
+        SELECT 1
+        FROM operation_invocations prior_events
+        WHERE prior_events.repo_id = oi.repo_id
+          AND prior_events.selected_thread_id = oi.selected_thread_id
+          AND prior_events.command = 'events'
+          AND prior_events.created_at < oi.created_at
+      )
+  )::INTEGER AS writes_preceded_by_events_count,
+  COUNT(*) FILTER (
+    WHERE oi.command = 'events'
+      AND NOT EXISTS (
+        SELECT 1
+        FROM operation_invocations later_writes
+        WHERE later_writes.repo_id = oi.repo_id
+          AND later_writes.selected_thread_id = oi.selected_thread_id
+          AND later_writes.command IN ('create', 'update')
+          AND later_writes.created_at > oi.created_at
+      )
+  )::INTEGER AS events_without_following_write_count
+FROM operation_invocations oi
+LEFT JOIN read_invocation_summaries ris ON ris.invocation_id = oi.id
+WHERE oi.selected_thread_id IS NOT NULL
+GROUP BY oi.repo_id, oi.selected_thread_id;
+"""

app/periphery/db/repos/__init__.py

@@ -0,0 +1 @@
+"""This package groups relational and semantic repository implementations."""

app/periphery/db/repos/relational/__init__.py

@@ -0,0 +1 @@
+"""This package contains aggregate-oriented relational repository classes."""

app/periphery/db/repos/relational/associations_repo.py

@@ -0,0 +1,117 @@
+"""This module defines relational repository operations for association structures."""
+
+from datetime import datetime, timezone
+
+from sqlalchemy import case, select, update
+
+from app.core.entities.associations import AssociationEdge, AssociationObservation, AssociationSourceMode, AssociationState
+from app.core.interfaces.repos import IAssociationsRepo
+from app.periphery.db.models.associations import association_edges, association_observations
+
+
+class AssociationsRepo(IAssociationsRepo):
+    """This class provides persistence operations for association edges and observations."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for repository operations."""
+
+        self._session = session
+
+    def upsert_edge(self, edge: AssociationEdge) -> AssociationEdge:
+        """This method inserts or updates an association edge and returns the stored edge."""
+
+        existing = (
+            self._session.execute(
+                select(association_edges).where(
+                    association_edges.c.repo_id == edge.repo_id,
+                    association_edges.c.from_memory_id == edge.from_memory_id,
+                    association_edges.c.to_memory_id == edge.to_memory_id,
+                    association_edges.c.relation_type == edge.relation_type.value,
+                )
+            )
+            .mappings()
+            .first()
+        )
+
+        now = datetime.now(timezone.utc)
+        if existing is None:
+            self._session.execute(
+                association_edges.insert().values(
+                    id=edge.id,
+                    repo_id=edge.repo_id,
+                    from_memory_id=edge.from_memory_id,
+                    to_memory_id=edge.to_memory_id,
+                    relation_type=edge.relation_type.value,
+                    source_mode=edge.source_mode.value,
+                    state=edge.state.value,
+                    strength=edge.strength,
+                    obs_count=0,
+                    positive_obs=0,
+                    negative_obs=0,
+                    salience_sum=0.0,
+                    created_at=now,
+                    updated_at=now,
+                )
+            )
+            return edge
+
+        source_mode = existing["source_mode"]
+        if source_mode != edge.source_mode.value and source_mode != "mixed":
+            source_mode = "mixed"
+        strength = max(float(existing["strength"]), edge.strength)
+        self._session.execute(
+            update(association_edges)
+            .where(association_edges.c.id == existing["id"])
+            .values(
+                source_mode=source_mode,
+                state=edge.state.value,
+                strength=strength,
+                updated_at=now,
+            )
+        )
+        return AssociationEdge(
+            id=existing["id"],
+            repo_id=edge.repo_id,
+            from_memory_id=edge.from_memory_id,
+            to_memory_id=edge.to_memory_id,
+            relation_type=edge.relation_type,
+            source_mode=AssociationSourceMode(source_mode),
+            state=AssociationState(edge.state.value),
+            strength=strength,
+        )
+
+    def append_observation(self, observation: AssociationObservation) -> None:
+        """This method appends an immutable association observation row."""
+
+        now = datetime.now(timezone.utc)
+        self._session.execute(
+            association_observations.insert().values(
+                id=observation.id,
+                repo_id=observation.repo_id,
+                edge_id=observation.edge_id,
+                from_memory_id=observation.from_memory_id,
+                to_memory_id=observation.to_memory_id,
+                relation_type=observation.relation_type.value,
+                source=observation.source,
+                problem_id=observation.problem_id,
+                episode_id=observation.episode_id,
+                valence=observation.valence,
+                salience=observation.salience,
+                created_at=now,
+            )
+        )
+        if observation.edge_id:
+            self._session.execute(
+                update(association_edges)
+                .where(association_edges.c.id == observation.edge_id)
+                .values(
+                    obs_count=association_edges.c.obs_count + 1,
+                    positive_obs=association_edges.c.positive_obs
+                    + case((observation.valence > 0, 1), else_=0),
+                    negative_obs=association_edges.c.negative_obs
+                    + case((observation.valence < 0, 1), else_=0),
+                    salience_sum=association_edges.c.salience_sum + observation.salience,
+                    last_reinforced_at=now,
+                    updated_at=now,
+                )
+            )

app/periphery/db/repos/relational/episodes_repo.py

@@ -0,0 +1,188 @@
+"""This module defines relational repository operations for episodic provenance tables."""
+
+from datetime import datetime, timezone
+from typing import Sequence
+
+from sqlalchemy import func, select, update
+
+from app.core.entities.episodes import Episode, EpisodeEvent, EpisodeEventSource, EpisodeStatus, SessionTransfer
+from app.core.interfaces.repos import IEpisodesRepo
+from app.periphery.db.models.episodes import episode_events, episodes, session_transfers
+
+
+class EpisodesRepo(IEpisodesRepo):
+    """This class provides persistence operations for episodes, events, and transfers."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for repository operations."""
+
+        self._session = session
+
+    def create_episode(self, episode: Episode) -> None:
+        """This method persists an episode row."""
+
+        self._session.execute(
+            episodes.insert().values(
+                id=episode.id,
+                repo_id=episode.repo_id,
+                host_app=episode.host_app,
+                thread_id=episode.thread_id,
+                title=episode.title,
+                objective=episode.objective,
+                status=episode.status.value,
+                started_at=episode.started_at or datetime.now(timezone.utc),
+                ended_at=episode.ended_at,
+                created_at=episode.created_at or datetime.now(timezone.utc),
+            )
+        )
+
+    def get_episode_by_thread(
+        self,
+        *,
+        repo_id: str,
+        thread_id: str,
+    ) -> Episode | None:
+        """This method fetches one episode by canonical host session key."""
+
+        row = (
+            self._session.execute(
+                select(episodes).where(
+                    episodes.c.repo_id == repo_id,
+                    episodes.c.thread_id == thread_id,
+                )
+            )
+            .mappings()
+            .first()
+        )
+        if row is None:
+            return None
+        return Episode(
+            id=row["id"],
+            repo_id=row["repo_id"],
+            host_app=row["host_app"],
+            thread_id=row["thread_id"],
+            title=row["title"],
+            objective=row["objective"],
+            status=EpisodeStatus(row["status"]),
+            started_at=row["started_at"],
+            ended_at=row["ended_at"],
+            created_at=row["created_at"],
+        )
+
+    def list_event_keys(self, *, episode_id: str) -> list[str]:
+        """This method returns already-imported upstream event keys for one episode."""
+
+        rows = self._session.execute(
+            select(episode_events.c.host_event_key).where(episode_events.c.episode_id == episode_id)
+        ).scalars()
+        return [str(value) for value in rows]
+
+    def next_event_seq(self, *, episode_id: str) -> int:
+        """This method returns the next append sequence number for one episode."""
+
+        max_seq = self._session.execute(
+            select(func.max(episode_events.c.seq)).where(episode_events.c.episode_id == episode_id)
+        ).scalar_one()
+        return 1 if max_seq is None else int(max_seq) + 1
+
+    def append_event(self, event: EpisodeEvent) -> None:
+        """This method appends an episode event row."""
+
+        self._session.execute(
+            episode_events.insert().values(
+                id=event.id,
+                episode_id=event.episode_id,
+                seq=event.seq,
+                host_event_key=event.host_event_key,
+                source=event.source.value,
+                content=event.content,
+                created_at=event.created_at or datetime.now(timezone.utc),
+            )
+        )
+
+    def close_episode(self, *, episode_id: str, ended_at: datetime) -> None:
+        """This method marks an active episode closed."""
+
+        self._session.execute(
+            update(episodes)
+            .where(episodes.c.id == episode_id)
+            .values(status="closed", ended_at=ended_at)
+        )
+
+    def append_transfer(self, transfer: SessionTransfer) -> None:
+        """This method appends a session transfer row."""
+
+        self._session.execute(
+            session_transfers.insert().values(
+                id=transfer.id,
+                repo_id=transfer.repo_id,
+                from_episode_id=transfer.from_episode_id,
+                to_episode_id=transfer.to_episode_id,
+                event_id=transfer.event_id,
+                transfer_kind=transfer.transfer_kind,
+                rationale=transfer.rationale,
+                transferred_by=transfer.transferred_by,
+                created_at=transfer.created_at or datetime.now(timezone.utc),
+            )
+        )
+
+    def list_existing_event_ids(self, *, event_ids: Sequence[str]) -> list[str]:
+        """This method returns stored event ids regardless of repo visibility."""
+
+        if not event_ids:
+            return []
+        rows = self._session.execute(
+            select(episode_events.c.id).where(episode_events.c.id.in_(event_ids))
+        ).scalars()
+        return [str(value) for value in rows]
+
+    def list_visible_event_ids(self, *, repo_id: str, event_ids: Sequence[str]) -> list[str]:
+        """This method returns stored event ids visible to one repo."""
+
+        if not event_ids:
+            return []
+        rows = self._session.execute(
+            select(episode_events.c.id)
+            .select_from(episode_events.join(episodes, episode_events.c.episode_id == episodes.c.id))
+            .where(
+                episodes.c.repo_id == repo_id,
+                episode_events.c.id.in_(event_ids),
+            )
+        ).scalars()
+        return [str(value) for value in rows]
+
+    def list_recent_events(
+        self,
+        *,
+        repo_id: str,
+        episode_id: str,
+        limit: int,
+    ) -> list[EpisodeEvent]:
+        """This method returns recent events for one repo-visible episode ordered newest first."""
+
+        rows = (
+            self._session.execute(
+                select(episode_events)
+                .select_from(episode_events.join(episodes, episode_events.c.episode_id == episodes.c.id))
+                .where(
+                    episodes.c.repo_id == repo_id,
+                    episode_events.c.episode_id == episode_id,
+                )
+                .order_by(episode_events.c.seq.desc())
+                .limit(limit)
+            )
+            .mappings()
+            .all()
+        )
+        return [
+            EpisodeEvent(
+                id=row["id"],
+                episode_id=row["episode_id"],
+                seq=row["seq"],
+                host_event_key=row["host_event_key"],
+                source=EpisodeEventSource(row["source"]),
+                content=row["content"],
+                created_at=row["created_at"],
+            )
+            for row in rows
+        ]

app/periphery/db/repos/relational/evidence_repo.py

@@ -0,0 +1,82 @@
+"""This module defines relational repository operations for evidence references and links."""
+
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from sqlalchemy import select, update
+from sqlalchemy.dialects.postgresql import insert
+
+from app.core.entities.evidence import EvidenceRef
+from app.core.interfaces.repos import IEvidenceRepo
+from app.periphery.db.models.associations import association_edge_evidence
+from app.periphery.db.models.evidence import evidence_refs
+from app.periphery.db.models.memories import memory_evidence
+
+
+class EvidenceRepo(IEvidenceRepo):
+    """This class provides persistence operations for evidence references and links."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for repository operations."""
+
+        self._session = session
+
+    def upsert_ref(self, repo_id: str, ref: str) -> EvidenceRef:
+        """This method inserts or returns a canonical evidence reference row."""
+
+        existing = (
+            self._session.execute(
+                select(evidence_refs).where(
+                    evidence_refs.c.repo_id == repo_id,
+                    (evidence_refs.c.episode_event_id == ref) | (evidence_refs.c.ref == ref),
+                )
+            )
+            .mappings()
+            .first()
+        )
+        if existing:
+            if existing["episode_event_id"] is None:
+                self._session.execute(
+                    update(evidence_refs)
+                    .where(evidence_refs.c.id == existing["id"])
+                    .values(episode_event_id=ref, ref=ref)
+                )
+                existing = dict(existing)
+                existing["episode_event_id"] = ref
+                existing["ref"] = ref
+            return EvidenceRef(
+                id=existing["id"],
+                repo_id=existing["repo_id"],
+                ref=existing["ref"],
+                episode_event_id=existing["episode_event_id"],
+            )
+
+        evidence_id = str(uuid4())
+        self._session.execute(
+            evidence_refs.insert().values(
+                id=evidence_id,
+                repo_id=repo_id,
+                ref=ref,
+                episode_event_id=ref,
+                created_at=datetime.now(timezone.utc),
+            )
+        )
+        return EvidenceRef(id=evidence_id, repo_id=repo_id, ref=ref, episode_event_id=ref)
+
+    def link_memory_evidence(self, memory_id: str, evidence_id: str) -> None:
+        """This method creates shellbrain-to-evidence link rows."""
+
+        self._session.execute(
+            insert(memory_evidence)
+            .values(memory_id=memory_id, evidence_id=evidence_id)
+            .on_conflict_do_nothing(index_elements=["memory_id", "evidence_id"])
+        )
+
+    def link_association_edge_evidence(self, edge_id: str, evidence_id: str) -> None:
+        """This method creates association-edge-to-evidence link rows."""
+
+        self._session.execute(
+            insert(association_edge_evidence)
+            .values(edge_id=edge_id, evidence_id=evidence_id)
+            .on_conflict_do_nothing(index_elements=["edge_id", "evidence_id"])
+        )

app/periphery/db/repos/relational/experiences_repo.py

@@ -0,0 +1,41 @@
+"""This module defines relational repository operations for experiential links."""
+
+from datetime import datetime, timezone
+
+from app.core.entities.facts import FactUpdate, ProblemAttempt
+from app.core.interfaces.repos import IExperiencesRepo
+from app.periphery.db.models.experiences import fact_updates, problem_attempts
+
+
+class ExperiencesRepo(IExperiencesRepo):
+    """This class provides persistence operations for problem attempts and fact updates."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for repository operations."""
+
+        self._session = session
+
+    def create_problem_attempt(self, attempt: ProblemAttempt) -> None:
+        """This method persists a problem-attempt link row."""
+
+        self._session.execute(
+            problem_attempts.insert().values(
+                problem_id=attempt.problem_id,
+                attempt_id=attempt.attempt_id,
+                role=attempt.role.value,
+                created_at=datetime.now(timezone.utc),
+            )
+        )
+
+    def create_fact_update(self, fact_update: FactUpdate) -> None:
+        """This method persists a fact-update chain row."""
+
+        self._session.execute(
+            fact_updates.insert().values(
+                id=fact_update.id,
+                old_fact_id=fact_update.old_fact_id,
+                change_id=fact_update.change_id,
+                new_fact_id=fact_update.new_fact_id,
+                created_at=datetime.now(timezone.utc),
+            )
+        )