shellbrain 0.1.0__py3-none-any.whl

app/core/use_cases/create_memory.py

@@ -0,0 +1,26 @@
+"""This module defines the create-shellbrain use-case orchestration entry point."""
+
+from uuid import uuid4
+
+from app.core.contracts.requests import MemoryCreateRequest
+from app.core.contracts.responses import OperationResult
+from app.core.interfaces.embeddings import IEmbeddingProvider
+from app.core.interfaces.unit_of_work import IUnitOfWork
+from app.core.policies.create_policy.pipeline import apply_create_plan, build_create_plan
+
+
+def execute_create_memory(
+    request: MemoryCreateRequest,
+    uow: IUnitOfWork,
+    *,
+    embedding_provider: IEmbeddingProvider,
+    embedding_model: str,
+) -> OperationResult:
+    """This function orchestrates create flow for an already-validated request."""
+
+    memory_id = str(uuid4())
+    payload = request.model_dump(mode="python")
+    payload["memory_id"] = memory_id
+    plan = build_create_plan(payload, embedding_model=embedding_model)
+    apply_create_plan(plan, uow, embedding_provider=embedding_provider)
+    return OperationResult(status="ok", data={"memory_id": memory_id, "planned_side_effects": plan})

app/core/use_cases/manage_session_state.py

@@ -0,0 +1,159 @@
+"""Core working-session lifecycle rules for per-caller session state."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime, timedelta, timezone
+
+from app.core.entities.identity import CallerIdentity, IdentityTrustLevel
+from app.core.entities.session_state import SessionState
+from app.core.interfaces.clock import IClock
+from app.core.interfaces.session_state_store import ISessionStateStore
+
+
+IDLE_EXPIRY = timedelta(hours=24)
+GC_EXPIRY = timedelta(days=7)
+
+
+class SessionStateManager:
+    """Application service for loading, touching, and mutating working session state."""
+
+    def __init__(self, *, store: ISessionStateStore, clock: IClock | None = None) -> None:
+        """Capture the persistence store and optional clock dependency."""
+
+        self._store = store
+        self._clock = clock
+
+    def load_active_state(self, *, repo_root, caller_identity: CallerIdentity | None) -> SessionState | None:
+        """Load and touch the active caller state when identity is trusted."""
+
+        if caller_identity is None or caller_identity.trust_level != IdentityTrustLevel.TRUSTED:
+            return None
+        now_iso = self._now_iso()
+        state = self._store.load(repo_root=repo_root, caller_id=caller_identity.canonical_id or "")
+        if state is None:
+            state = SessionState(
+                caller_id=caller_identity.canonical_id or "",
+                host_app=caller_identity.host_app,
+                host_session_key=caller_identity.host_session_key,
+                agent_key=caller_identity.agent_key,
+                session_started_at=now_iso,
+                last_seen_at=now_iso,
+            )
+        else:
+            state = self.reset_if_idle(state, now_iso=now_iso)
+            state.last_seen_at = now_iso
+        self._store.save(repo_root=repo_root, state=state)
+        return state
+
+    def record_events(
+        self,
+        *,
+        repo_root,
+        caller_identity: CallerIdentity | None,
+        episode_id: str,
+        event_ids: list[str],
+    ) -> SessionState | None:
+        """Persist the latest events context for one trusted caller."""
+
+        state = self.load_active_state(repo_root=repo_root, caller_identity=caller_identity)
+        if state is None:
+            return None
+        now_iso = self._now_iso()
+        state.last_events_episode_id = episode_id
+        state.last_events_event_ids = list(event_ids)
+        state.last_events_at = now_iso
+        state.last_seen_at = now_iso
+        self._store.save(repo_root=repo_root, state=state)
+        return state
+
+    def record_problem(
+        self,
+        *,
+        repo_root,
+        caller_identity: CallerIdentity | None,
+        problem_id: str,
+    ) -> SessionState | None:
+        """Persist the active problem for one trusted caller."""
+
+        state = self.load_active_state(repo_root=repo_root, caller_identity=caller_identity)
+        if state is None:
+            return None
+        state.current_problem_id = problem_id
+        state.last_seen_at = self._now_iso()
+        self._store.save(repo_root=repo_root, state=state)
+        return state
+
+    def record_guidance(
+        self,
+        *,
+        repo_root,
+        caller_identity: CallerIdentity | None,
+        problem_id: str,
+    ) -> SessionState | None:
+        """Persist the latest emitted guidance timestamp for one trusted caller."""
+
+        state = self.load_active_state(repo_root=repo_root, caller_identity=caller_identity)
+        if state is None:
+            return None
+        now_iso = self._now_iso()
+        state.last_guidance_problem_id = problem_id
+        state.last_guidance_at = now_iso
+        state.last_seen_at = now_iso
+        self._store.save(repo_root=repo_root, state=state)
+        return state
+
+    def clear_for_caller(self, *, repo_root, caller_id: str) -> None:
+        """Delete one caller state."""
+
+        self._store.delete(repo_root=repo_root, caller_id=caller_id)
+
+    def garbage_collect(self, *, repo_root) -> list[str]:
+        """Delete states older than the configured GC threshold."""
+
+        cutoff_iso = (self._now() - GC_EXPIRY).isoformat()
+        return self._store.gc(repo_root=repo_root, older_than_iso=cutoff_iso)
+
+    @staticmethod
+    def reset_if_idle(state: SessionState, *, now_iso: str) -> SessionState:
+        """Reset working-session fields when the caller has been idle too long."""
+
+        try:
+            last_seen = _parse_iso(state.last_seen_at)
+        except ValueError:
+            last_seen = datetime.min.replace(tzinfo=timezone.utc)
+        now = _parse_iso(now_iso)
+        if now - last_seen < IDLE_EXPIRY:
+            return state
+        return replace(
+            state,
+            session_started_at=now_iso,
+            last_seen_at=now_iso,
+            current_problem_id=None,
+            last_events_episode_id=None,
+            last_events_event_ids=[],
+            last_events_at=None,
+            last_guidance_at=None,
+            last_guidance_problem_id=None,
+        )
+
+    def _now(self) -> datetime:
+        """Return the current UTC time using the injected clock when present."""
+
+        if self._clock is not None:
+            return self._clock.now()
+        return datetime.now(timezone.utc)
+
+    def _now_iso(self) -> str:
+        """Return the current UTC time in ISO-8601 form."""
+
+        return self._now().isoformat()
+
+
+def _parse_iso(value: str) -> datetime:
+    """Parse one ISO timestamp into a timezone-aware datetime."""
+
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)

app/core/use_cases/read_memory.py

@@ -0,0 +1,21 @@
+"""This module defines the read-shellbrain use-case orchestration entry point."""
+
+from app.core.contracts.requests import MemoryReadRequest
+from app.core.contracts.responses import OperationResult
+from app.core.interfaces.unit_of_work import IUnitOfWork
+from app.core.policies.read_policy.pipeline import build_context_pack
+
+
+def execute_read_memory(request: MemoryReadRequest, uow: IUnitOfWork) -> OperationResult:
+    """This function orchestrates read flow with retrieval and context-pack policy hooks."""
+
+    payload = request.model_dump(mode="python")
+    context_pack = build_context_pack(
+        payload,
+        keyword_retrieval=uow.keyword_retrieval,
+        memories=uow.memories,
+        semantic_retrieval=uow.semantic_retrieval,
+        read_policy=uow.read_policy,
+        vector_search=uow.vector_search,
+    )
+    return OperationResult(status="ok", data={"pack": context_pack})

app/core/use_cases/record_episode_sync_telemetry.py

@@ -0,0 +1,19 @@
+"""Thin orchestration for sync-run telemetry writes."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from app.core.entities.telemetry import EpisodeSyncRunRecord, EpisodeSyncToolTypeRecord
+from app.core.interfaces.unit_of_work import IUnitOfWork
+
+
+def record_episode_sync_telemetry(
+    *,
+    uow: IUnitOfWork,
+    run: EpisodeSyncRunRecord,
+    tool_types: Sequence[EpisodeSyncToolTypeRecord] = (),
+) -> None:
+    """Persist one sync-run row and its per-tool aggregates."""
+
+    uow.telemetry.insert_episode_sync_run(run, tuple(tool_types))

app/core/use_cases/record_operation_telemetry.py

@@ -0,0 +1,32 @@
+"""Thin orchestration for operation-level telemetry writes."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from app.core.entities.telemetry import (
+    OperationInvocationRecord,
+    ReadResultItemRecord,
+    ReadSummaryRecord,
+    WriteEffectItemRecord,
+    WriteSummaryRecord,
+)
+from app.core.interfaces.unit_of_work import IUnitOfWork
+
+
+def record_operation_telemetry(
+    *,
+    uow: IUnitOfWork,
+    invocation: OperationInvocationRecord,
+    read_summary: ReadSummaryRecord | None = None,
+    read_items: Sequence[ReadResultItemRecord] = (),
+    write_summary: WriteSummaryRecord | None = None,
+    write_items: Sequence[WriteEffectItemRecord] = (),
+) -> None:
+    """Persist one invocation row and any attached read or write summaries."""
+
+    uow.telemetry.insert_operation_invocation(invocation)
+    if read_summary is not None:
+        uow.telemetry.insert_read_summary(read_summary, tuple(read_items))
+    if write_summary is not None:
+        uow.telemetry.insert_write_summary(write_summary, tuple(write_items))

app/core/use_cases/sync_episode.py

@@ -0,0 +1,162 @@
+"""Synchronize normalized host transcript events into the episodic provenance tables."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime, timezone
+import json
+from typing import Any
+from uuid import uuid4
+
+from app.core.entities.episodes import Episode, EpisodeEvent, EpisodeEventSource, EpisodeStatus
+from app.core.interfaces.unit_of_work import IUnitOfWork
+
+
+def sync_episode(
+    *,
+    repo_id: str,
+    host_app: str,
+    host_session_key: str,
+    thread_id: str,
+    transcript_path: str,
+    normalized_events: Sequence[dict[str, Any]],
+    uow: IUnitOfWork,
+) -> dict[str, Any]:
+    """Import one already-normalized host transcript into episodes and episode events."""
+
+    counts = _count_normalized_events(normalized_events)
+    episode = uow.episodes.get_episode_by_thread(repo_id=repo_id, thread_id=thread_id)
+    imported_count = 0
+
+    if episode is None:
+        started_at = _earliest_event_timestamp(normalized_events) or datetime.now(timezone.utc)
+        episode = Episode(
+            id=str(uuid4()),
+            repo_id=repo_id,
+            host_app=host_app,
+            thread_id=thread_id,
+            status=EpisodeStatus.ACTIVE,
+            started_at=started_at,
+            created_at=datetime.now(timezone.utc),
+        )
+        uow.episodes.create_episode(episode)
+
+    existing_keys = set(uow.episodes.list_event_keys(episode_id=episode.id))
+    next_seq = uow.episodes.next_event_seq(episode_id=episode.id)
+    for normalized_event in normalized_events:
+        host_event_key = str(normalized_event["host_event_key"])
+        if host_event_key in existing_keys:
+            continue
+        created_at = _parse_timestamp(str(normalized_event["occurred_at"]))
+        source = EpisodeEventSource(str(normalized_event["source"]))
+        uow.episodes.append_event(
+            EpisodeEvent(
+                id=str(uuid4()),
+                episode_id=episode.id,
+                seq=next_seq,
+                host_event_key=host_event_key,
+                source=source,
+                content=json.dumps(normalized_event),
+                created_at=created_at,
+            )
+        )
+        existing_keys.add(host_event_key)
+        next_seq += 1
+        imported_count += 1
+
+    return {
+        "episode_id": episode.id,
+        "thread_id": thread_id,
+        "imported_event_count": imported_count,
+        "transcript_path": transcript_path,
+        "total_event_count": counts["total_event_count"],
+        "user_event_count": counts["user_event_count"],
+        "assistant_event_count": counts["assistant_event_count"],
+        "tool_event_count": counts["tool_event_count"],
+        "system_event_count": counts["system_event_count"],
+        "tool_type_counts": counts["tool_type_counts"],
+    }
+
+
+def sync_episode_from_host(
+    *,
+    repo_id: str,
+    host_app: str,
+    host_session_key: str,
+    uow: IUnitOfWork,
+    search_roots,
+    last_known_path=None,
+) -> dict[str, Any]:
+    """Backward-compatible host sync wrapper used by existing callers."""
+
+    from app.periphery.episodes.normalization import normalize_host_transcript
+    from app.periphery.episodes.source_discovery import resolve_host_transcript_source
+
+    transcript_path = resolve_host_transcript_source(
+        host_app=host_app,
+        host_session_key=host_session_key,
+        search_roots=search_roots,
+        last_known_path=last_known_path,
+    )
+    normalized_events = normalize_host_transcript(
+        host_app=host_app,
+        host_session_key=host_session_key,
+        transcript_path=transcript_path,
+    )
+    return sync_episode(
+        repo_id=repo_id,
+        host_app=host_app,
+        host_session_key=host_session_key,
+        thread_id=f"{host_app}:{host_session_key}",
+        transcript_path=str(transcript_path),
+        normalized_events=normalized_events,
+        uow=uow,
+    )
+
+
+def _parse_timestamp(value: str) -> datetime:
+    """Parse one host timestamp into a timezone-aware datetime."""
+
+    if not value:
+        return datetime.now(timezone.utc)
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _earliest_event_timestamp(events: Sequence[dict[str, Any]]) -> datetime | None:
+    """Return the earliest normalized event timestamp if any exist."""
+
+    timestamps = [
+        _parse_timestamp(str(event["occurred_at"]))
+        for event in events
+        if event.get("occurred_at")
+    ]
+    if not timestamps:
+        return None
+    return min(timestamps)
+
+
+def _count_normalized_events(events: Sequence[dict[str, Any]]) -> dict[str, Any]:
+    """Compute telemetry-friendly source and tool-type counts from normalized events."""
+
+    tool_type_counts: dict[str, int] = {}
+    counts = {
+        "total_event_count": len(events),
+        "user_event_count": 0,
+        "assistant_event_count": 0,
+        "tool_event_count": 0,
+        "system_event_count": 0,
+        "tool_type_counts": tool_type_counts,
+    }
+    for event in events:
+        source = str(event.get("source") or "")
+        if source == "user":
+            counts["user_event_count"] += 1
+        elif source == "assistant":
+            counts["assistant_event_count"] += 1
+        elif source == "tool":
+            counts["tool_event_count"] += 1
+            tool_name = str(event.get("tool_name") or "unknown_tool")
+            tool_type_counts[tool_name] = tool_type_counts.get(tool_name, 0) + 1
+        elif source == "system":
+            counts["system_event_count"] += 1
+    return counts

app/core/use_cases/update_memory.py

@@ -0,0 +1,40 @@
+"""This module defines the update-shellbrain use-case orchestration entry point."""
+
+from app.core.contracts.requests import MemoryBatchUpdateRequest, MemoryUpdateRequest
+from app.core.contracts.responses import OperationResult
+from app.core.interfaces.unit_of_work import IUnitOfWork
+from app.core.policies.update_policy.pipeline import apply_update_plan, build_update_plan
+
+
+def execute_update_memory(request: MemoryUpdateRequest | MemoryBatchUpdateRequest, uow: IUnitOfWork) -> OperationResult:
+    """This function orchestrates update flow for an already-validated request."""
+
+    if isinstance(request, MemoryBatchUpdateRequest):
+        plan: list[dict[str, object]] = []
+        updated_memory_ids: list[str] = []
+        for item in request.updates:
+            plan.extend(
+                build_update_plan(
+                    {
+                        "repo_id": request.repo_id,
+                        "memory_id": item.memory_id,
+                        "update": item.update.model_dump(mode="python"),
+                    }
+                )
+            )
+            updated_memory_ids.append(item.memory_id)
+        apply_update_plan(plan, uow)
+        problem_id = request.updates[0].update.problem_id
+        return OperationResult(
+            status="ok",
+            data={
+                "problem_id": problem_id,
+                "updated_memory_ids": updated_memory_ids,
+                "applied_count": len(request.updates),
+                "planned_side_effects": plan,
+            },
+        )
+
+    plan = build_update_plan(request.model_dump(mode="python"))
+    apply_update_plan(plan, uow)
+    return OperationResult(status="ok", data={"memory_id": request.memory_id, "planned_side_effects": plan})

app/migrations/__init__.py

@@ -0,0 +1 @@
+"""This package contains Alembic migration configuration and revisions."""

app/migrations/env.py

@@ -0,0 +1,65 @@
+"""This module defines the Alembic environment for online and offline PostgreSQL migrations."""
+
+from __future__ import annotations
+
+import os
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from app.periphery.db.models.registry import target_metadata
+
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+configured_url = config.get_main_option("sqlalchemy.url")
+if not configured_url:
+    admin_dsn = os.getenv("SHELLBRAIN_DB_ADMIN_DSN")
+    app_dsn = os.getenv("SHELLBRAIN_DB_DSN")
+    if admin_dsn:
+        config.set_main_option("sqlalchemy.url", admin_dsn)
+    elif app_dsn:
+        config.set_main_option("sqlalchemy.url", app_dsn)
+
+
+def run_migrations_offline() -> None:
+    """This function runs migrations in offline mode using URL-only context."""
+
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        compare_type=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """This function runs migrations in online mode using an engine connection."""
+
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+        future=True,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()