shellbrain 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,99 @@
+"""This module defines relational repository operations for shellbrain aggregates."""
+
+from datetime import datetime, timezone
+from typing import Sequence
+
+from sqlalchemy import select, update
+from sqlalchemy.dialects.postgresql import insert
+
+from app.core.entities.memory import Memory, MemoryKind, MemoryScope
+from app.core.interfaces.repos import IMemoriesRepo
+from app.periphery.db.models.memories import memories, memory_embeddings
+
+
+class MemoriesRepo(IMemoriesRepo):
+    """This class provides relational persistence operations for memories."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for repository operations."""
+
+        self._session = session
+
+    def create(self, memory: Memory) -> None:
+        """This method persists a shellbrain record into relational storage."""
+
+        self._session.execute(
+            memories.insert().values(
+                id=memory.id,
+                repo_id=memory.repo_id,
+                scope=memory.scope.value,
+                kind=memory.kind.value,
+                text=memory.text,
+                created_at=datetime.now(timezone.utc),
+                archived=memory.archived,
+            )
+        )
+
+    def get(self, memory_id: str) -> Memory | None:
+        """This method loads a shellbrain record by identifier."""
+
+        row = self._session.execute(select(memories).where(memories.c.id == memory_id)).mappings().first()
+        if row is None:
+            return None
+        return self._to_memory(row)
+
+    def list_by_ids(self, ids: Sequence[str]) -> Sequence[Memory]:
+        """This method loads visible shellbrain records in the caller's identifier order."""
+
+        unique_ids = list(dict.fromkeys(str(memory_id) for memory_id in ids))
+        if not unique_ids:
+            return []
+        rows = self._session.execute(select(memories).where(memories.c.id.in_(unique_ids))).mappings().all()
+        memories_by_id = {
+            str(row["id"]): self._to_memory(row)
+            for row in rows
+        }
+        return [memories_by_id[memory_id] for memory_id in unique_ids if memory_id in memories_by_id]
+
+    def _to_memory(self, row) -> Memory:
+        """Convert one relational row into the canonical shellbrain entity."""
+
+        return Memory(
+            id=row["id"],
+            repo_id=row["repo_id"],
+            scope=MemoryScope(row["scope"]),
+            kind=MemoryKind(row["kind"]),
+            text=row["text"],
+            archived=row["archived"],
+        )
+
+    def set_archived(self, *, memory_id: str, archived: bool) -> bool:
+        """This method updates the archived state for a shellbrain and returns whether a row changed."""
+
+        result = self._session.execute(
+            update(memories).where(memories.c.id == memory_id).values(archived=archived)
+        )
+        return bool(result.rowcount)
+
+    def upsert_embedding(self, *, memory_id: str, model: str, vector: Sequence[float]) -> None:
+        """This method inserts or updates the embedding vector for the target memory."""
+
+        self._session.execute(
+            insert(memory_embeddings)
+            .values(
+                memory_id=memory_id,
+                model=model,
+                dim=len(vector),
+                vector=list(vector),
+                created_at=datetime.now(timezone.utc),
+            )
+            .on_conflict_do_update(
+                index_elements=["memory_id"],
+                set_={
+                    "model": model,
+                    "dim": len(vector),
+                    "vector": list(vector),
+                    "created_at": datetime.now(timezone.utc),
+                },
+            )
+        )

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

@@ -0,0 +1,202 @@
+"""This module defines SQL-backed read-path visibility and explicit expansion queries."""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from sqlalchemy import literal, or_, select, union_all
+
+from app.core.interfaces.repos import IReadPolicyRepo
+from app.periphery.db.models.associations import association_edges
+from app.periphery.db.models.experiences import fact_updates, problem_attempts
+from app.periphery.db.models.memories import memories
+
+
+class ReadPolicyRepo(IReadPolicyRepo):
+    """This class provides visibility-gated read-path expansion queries."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for read-path queries."""
+
+        self._session = session
+
+    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."""
+
+        attempt_stmt = (
+            select(problem_attempts.c.attempt_id.label("memory_id"), literal("problem_attempt").label("expansion_type"))
+            .select_from(problem_attempts.join(memories, memories.c.id == problem_attempts.c.attempt_id))
+            .where(
+                problem_attempts.c.problem_id == anchor_memory_id,
+                *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
+            )
+        )
+        problem_stmt = (
+            select(problem_attempts.c.problem_id.label("memory_id"), literal("problem_attempt").label("expansion_type"))
+            .select_from(problem_attempts.join(memories, memories.c.id == problem_attempts.c.problem_id))
+            .where(
+                problem_attempts.c.attempt_id == anchor_memory_id,
+                *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
+            )
+        )
+        union_stmt = union_all(attempt_stmt, problem_stmt).subquery()
+        stmt = (
+            select(union_stmt.c.memory_id, union_stmt.c.expansion_type)
+            .distinct()
+            .order_by(union_stmt.c.memory_id.asc())
+        )
+        return list(self._session.execute(stmt).mappings().all())
+
+    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."""
+
+        old_stmt = (
+            select(fact_updates.c.old_fact_id.label("memory_id"), literal("fact_update").label("expansion_type"))
+            .select_from(fact_updates.join(memories, memories.c.id == fact_updates.c.old_fact_id))
+            .where(
+                or_(
+                    fact_updates.c.change_id == anchor_memory_id,
+                    fact_updates.c.new_fact_id == anchor_memory_id,
+                ),
+                *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
+            )
+        )
+        change_stmt = (
+            select(fact_updates.c.change_id.label("memory_id"), literal("fact_update").label("expansion_type"))
+            .select_from(fact_updates.join(memories, memories.c.id == fact_updates.c.change_id))
+            .where(
+                or_(
+                    fact_updates.c.old_fact_id == anchor_memory_id,
+                    fact_updates.c.new_fact_id == anchor_memory_id,
+                ),
+                *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
+            )
+        )
+        new_stmt = (
+            select(fact_updates.c.new_fact_id.label("memory_id"), literal("fact_update").label("expansion_type"))
+            .select_from(fact_updates.join(memories, memories.c.id == fact_updates.c.new_fact_id))
+            .where(
+                or_(
+                    fact_updates.c.old_fact_id == anchor_memory_id,
+                    fact_updates.c.change_id == anchor_memory_id,
+                ),
+                *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
+            )
+        )
+        union_stmt = union_all(old_stmt, change_stmt, new_stmt).subquery()
+        stmt = (
+            select(union_stmt.c.memory_id, union_stmt.c.expansion_type)
+            .where(union_stmt.c.memory_id != anchor_memory_id)
+            .distinct()
+            .order_by(union_stmt.c.memory_id.asc())
+        )
+        return list(self._session.execute(stmt).mappings().all())
+
+    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."""
+
+        from_stmt = (
+            select(
+                association_edges.c.to_memory_id.label("memory_id"),
+                association_edges.c.relation_type,
+                association_edges.c.strength,
+                literal("association").label("expansion_type"),
+            )
+            .select_from(association_edges.join(memories, memories.c.id == association_edges.c.to_memory_id))
+            .where(
+                association_edges.c.repo_id == repo_id,
+                association_edges.c.from_memory_id == anchor_memory_id,
+                association_edges.c.state != "deprecated",
+                association_edges.c.strength >= min_strength,
+                *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
+            )
+        )
+        reverse_associated_stmt = (
+            select(
+                association_edges.c.from_memory_id.label("memory_id"),
+                association_edges.c.relation_type,
+                association_edges.c.strength,
+                literal("association").label("expansion_type"),
+            )
+            .select_from(association_edges.join(memories, memories.c.id == association_edges.c.from_memory_id))
+            .where(
+                association_edges.c.repo_id == repo_id,
+                association_edges.c.to_memory_id == anchor_memory_id,
+                association_edges.c.relation_type == "associated_with",
+                association_edges.c.state != "deprecated",
+                association_edges.c.strength >= min_strength,
+                *self._visibility_filters(repo_id=repo_id, include_global=include_global, kinds=kinds),
+            )
+        )
+        union_stmt = union_all(from_stmt, reverse_associated_stmt).subquery()
+        stmt = (
+            select(
+                union_stmt.c.memory_id,
+                union_stmt.c.relation_type,
+                union_stmt.c.strength,
+                union_stmt.c.expansion_type,
+            )
+            .where(union_stmt.c.memory_id != anchor_memory_id)
+            .order_by(union_stmt.c.strength.desc(), union_stmt.c.memory_id.asc(), union_stmt.c.relation_type.asc())
+        )
+        rows = self._session.execute(stmt).mappings().all()
+        best_by_memory_id: dict[str, dict[str, Any]] = {}
+        for row in rows:
+            memory_id = str(row["memory_id"])
+            strength = float(row["strength"])
+            relation_type = str(row["relation_type"])
+            current = best_by_memory_id.get(memory_id)
+            if current is None or strength > float(current["strength"]) or (
+                strength == float(current["strength"]) and relation_type < str(current["relation_type"])
+            ):
+                best_by_memory_id[memory_id] = {
+                    "memory_id": memory_id,
+                    "relation_type": relation_type,
+                    "strength": strength,
+                    "expansion_type": str(row["expansion_type"]),
+                }
+        return sorted(
+            best_by_memory_id.values(),
+            key=lambda item: (-float(item["strength"]), str(item["memory_id"]), str(item["relation_type"])),
+        )
+
+    def _visibility_filters(
+        self,
+        *,
+        repo_id: str,
+        include_global: bool,
+        kinds: Sequence[str] | None,
+    ) -> list[Any]:
+        """Build the visibility filters used by read-path queries."""
+
+        scope_values = ["repo", "global"] if include_global else ["repo"]
+        filters: list[Any] = [
+            memories.c.repo_id == repo_id,
+            memories.c.archived.is_(False),
+            memories.c.scope.in_(scope_values),
+        ]
+        if kinds:
+            filters.append(memories.c.kind.in_(list(kinds)))
+        return filters

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

@@ -0,0 +1,161 @@
+"""Relational repository for low-overhead telemetry persistence."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from datetime import datetime, timezone
+
+from sqlalchemy import delete, func, select, update
+
+from app.core.entities.guidance import PendingUtilityCandidate
+from app.core.entities.telemetry import (
+    EpisodeSyncRunRecord,
+    EpisodeSyncToolTypeRecord,
+    OperationInvocationRecord,
+    ReadResultItemRecord,
+    ReadSummaryRecord,
+    WriteEffectItemRecord,
+    WriteSummaryRecord,
+)
+from app.periphery.db.models.memories import memories
+from app.core.interfaces.repos import ITelemetryRepo
+from app.periphery.db.models.telemetry import (
+    episode_sync_runs,
+    episode_sync_tool_types,
+    operation_invocations,
+    read_invocation_summaries,
+    read_result_items,
+    write_effect_items,
+    write_invocation_summaries,
+)
+from app.periphery.db.models.utility import utility_observations
+
+
+class TelemetryRepo(ITelemetryRepo):
+    """Append-heavy relational persistence for operational telemetry."""
+
+    def __init__(self, session) -> None:
+        """Store the active session used to persist telemetry rows."""
+
+        self._session = session
+
+    def insert_operation_invocation(self, record: OperationInvocationRecord) -> None:
+        """Append one parent invocation row."""
+
+        self._session.execute(operation_invocations.insert().values(**asdict(record)))
+
+    def insert_read_summary(
+        self,
+        summary: ReadSummaryRecord,
+        items: tuple[ReadResultItemRecord, ...] | list[ReadResultItemRecord],
+    ) -> None:
+        """Replace one read summary row and its ordered result items."""
+
+        invocation_id = summary.invocation_id
+        self._session.execute(delete(read_result_items).where(read_result_items.c.invocation_id == invocation_id))
+        self._session.execute(
+            delete(read_invocation_summaries).where(read_invocation_summaries.c.invocation_id == invocation_id)
+        )
+        self._session.execute(read_invocation_summaries.insert().values(**asdict(summary)))
+        if items:
+            self._session.execute(read_result_items.insert(), [asdict(item) for item in items])
+
+    def insert_write_summary(
+        self,
+        summary: WriteSummaryRecord,
+        items: tuple[WriteEffectItemRecord, ...] | list[WriteEffectItemRecord],
+    ) -> None:
+        """Replace one write summary row and its ordered effect items."""
+
+        invocation_id = summary.invocation_id
+        self._session.execute(delete(write_effect_items).where(write_effect_items.c.invocation_id == invocation_id))
+        self._session.execute(
+            delete(write_invocation_summaries).where(write_invocation_summaries.c.invocation_id == invocation_id)
+        )
+        self._session.execute(write_invocation_summaries.insert().values(**asdict(summary)))
+        if items:
+            self._session.execute(write_effect_items.insert(), [asdict(item) for item in items])
+
+    def insert_episode_sync_run(
+        self,
+        run: EpisodeSyncRunRecord,
+        tool_types: tuple[EpisodeSyncToolTypeRecord, ...] | list[EpisodeSyncToolTypeRecord],
+    ) -> None:
+        """Append one sync-run row and its per-tool counts."""
+
+        self._session.execute(episode_sync_runs.insert().values(**asdict(run)))
+        if tool_types:
+            self._session.execute(episode_sync_tool_types.insert(), [asdict(item) for item in tool_types])
+
+    def update_operation_polling(self, invocation_id: str, *, attempted: bool, started: bool) -> None:
+        """Patch poller-start bookkeeping on an existing invocation row."""
+
+        self._session.execute(
+            update(operation_invocations)
+            .where(operation_invocations.c.id == invocation_id)
+            .values(
+                poller_start_attempted=attempted,
+                poller_started=started,
+            )
+        )
+
+    def list_pending_utility_candidates(
+        self,
+        *,
+        repo_id: str,
+        caller_id: str,
+        problem_id: str,
+        since_iso: str,
+    ) -> list[PendingUtilityCandidate]:
+        """Return retrieved memories that still lack a utility vote for one problem."""
+
+        stmt = (
+            select(
+                read_result_items.c.memory_id,
+                func.max(read_result_items.c.kind).label("kind"),
+                func.count().label("retrieval_count"),
+                func.max(operation_invocations.c.created_at).label("last_seen_at"),
+            )
+            .select_from(
+                read_result_items.join(
+                    operation_invocations,
+                    operation_invocations.c.id == read_result_items.c.invocation_id,
+                )
+                .join(memories, memories.c.id == read_result_items.c.memory_id)
+                .outerjoin(
+                    utility_observations,
+                    (utility_observations.c.memory_id == read_result_items.c.memory_id)
+                    & (utility_observations.c.problem_id == problem_id),
+                )
+            )
+            .where(
+                operation_invocations.c.repo_id == repo_id,
+                operation_invocations.c.command == "read",
+                operation_invocations.c.outcome == "ok",
+                operation_invocations.c.selected_thread_id == caller_id,
+                operation_invocations.c.created_at >= _parse_iso(since_iso),
+                read_result_items.c.memory_id != problem_id,
+                utility_observations.c.id.is_(None),
+            )
+            .group_by(read_result_items.c.memory_id)
+            .order_by(func.count().desc(), func.max(operation_invocations.c.created_at).desc())
+        )
+        rows = self._session.execute(stmt).mappings().all()
+        return [
+            PendingUtilityCandidate(
+                memory_id=str(row["memory_id"]),
+                kind=str(row["kind"]),
+                retrieval_count=int(row["retrieval_count"]),
+                last_seen_at=row["last_seen_at"].isoformat(),
+            )
+            for row in rows
+        ]
+
+
+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/periphery/db/repos/relational/utility_repo.py

@@ -0,0 +1,30 @@
+"""This module defines relational repository operations for utility feedback entries."""
+
+from datetime import datetime, timezone
+
+from app.core.entities.utility import UtilityObservation
+from app.core.interfaces.repos import IUtilityRepo
+from app.periphery.db.models.utility import utility_observations
+
+
+class UtilityRepo(IUtilityRepo):
+    """This class provides persistence operations for utility observations."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for repository operations."""
+
+        self._session = session
+
+    def append_observation(self, observation: UtilityObservation) -> None:
+        """This method appends a utility observation row."""
+
+        self._session.execute(
+            utility_observations.insert().values(
+                id=observation.id,
+                memory_id=observation.memory_id,
+                problem_id=observation.problem_id,
+                vote=observation.vote,
+                rationale=observation.rationale,
+                created_at=datetime.now(timezone.utc),
+            )
+        )

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

@@ -0,0 +1 @@
+"""This package contains semantic retrieval repository classes."""

app/periphery/db/repos/semantic/keyword_retrieval_repo.py

@@ -0,0 +1,63 @@
+"""This module defines keyword-lane retrieval operations backed by app-side BM25."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Sequence
+
+from sqlalchemy import select
+
+from app.core.policies.read_policy.bm25 import BM25Document, admit_scored_documents, score_documents
+from app.core.policies.read_policy.lexical_query import build_lexical_query, normalize_lexical_text
+from app.core.interfaces.repos import IKeywordRetrievalRepo
+from app.periphery.db.models.memories import memories
+
+
+class KeywordRetrievalRepo(IKeywordRetrievalRepo):
+    """This class provides lexical retrieval candidates from app-side BM25 scoring."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for keyword retrieval operations."""
+
+        self._session = session
+
+    def query_keyword(
+        self,
+        *,
+        repo_id: str,
+        mode: Literal["ambient", "targeted"],
+        include_global: bool,
+        query_text: str,
+        kinds: Sequence[str] | None,
+        limit: int,
+    ) -> Sequence[dict[str, Any]]:
+        """This method returns keyword candidates and lexical ranking scores."""
+
+        lexical_query = build_lexical_query(query_text)
+        if not lexical_query.terms:
+            return []
+
+        scope_values = ["repo", "global"] if include_global else ["repo"]
+        stmt = (
+            select(
+                memories.c.id.label("memory_id"),
+                memories.c.text,
+            )
+            .where(
+                memories.c.repo_id == repo_id,
+                memories.c.archived.is_(False),
+                memories.c.scope.in_(scope_values),
+            )
+            .order_by(memories.c.id.asc())
+        )
+        if kinds:
+            stmt = stmt.where(memories.c.kind.in_(list(kinds)))
+
+        documents = [
+            BM25Document(
+                memory_id=str(row["memory_id"]),
+                terms=normalize_lexical_text(str(row["text"])).terms_for(lexical_query),
+            )
+            for row in self._session.execute(stmt).mappings().all()
+        ]
+        scored_documents = score_documents(lexical_query.terms, documents)
+        return admit_scored_documents(scored_documents, mode=mode)[:limit]

app/periphery/db/repos/semantic/semantic_retrieval_repo.py

@@ -0,0 +1,111 @@
+"""This module defines semantic-lane retrieval operations over stored shellbrain embeddings."""
+
+from math import sqrt
+from typing import Any, Sequence
+
+from sqlalchemy import select
+
+from app.core.interfaces.repos import ISemanticRetrievalRepo
+from app.periphery.db.models.memories import memories, memory_embeddings
+
+
+class SemanticRetrievalRepo(ISemanticRetrievalRepo):
+    """This class provides semantic retrieval candidates from embedding similarity."""
+
+    def __init__(self, session) -> None:
+        """This method stores the active DB session for semantic retrieval operations."""
+
+        self._session = session
+
+    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 candidates and similarity scores."""
+
+        if not query_vector:
+            return []
+
+        scored: list[dict[str, Any]] = []
+        for row in self._visible_embedding_rows(repo_id=repo_id, include_global=include_global, kinds=kinds):
+            score = _cosine_similarity(list(query_vector), row["vector"])
+            if score <= 0.0:
+                continue
+            scored.append({"memory_id": row["memory_id"], "score": score})
+        scored.sort(key=lambda item: (-float(item["score"]), str(item["memory_id"])))
+        return scored[:limit]
+
+    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."""
+
+        visible_rows = self._visible_embedding_rows(repo_id=repo_id, include_global=include_global, kinds=kinds)
+        anchor_vector = next((row["vector"] for row in visible_rows if row["memory_id"] == anchor_memory_id), None)
+        if anchor_vector is None:
+            return []
+
+        scored: list[dict[str, Any]] = []
+        for row in visible_rows:
+            if row["memory_id"] == anchor_memory_id:
+                continue
+            score = _cosine_similarity(anchor_vector, row["vector"])
+            if score <= 0.0:
+                continue
+            scored.append({"memory_id": row["memory_id"], "score": score})
+        scored.sort(key=lambda item: (-float(item["score"]), str(item["memory_id"])))
+        if limit is None:
+            return scored
+        return scored[:limit]
+
+    def _visible_embedding_rows(self, *, repo_id: str, include_global: bool, kinds: Sequence[str] | None) -> list[dict[str, Any]]:
+        """Load visible embedded memories eligible for semantic retrieval."""
+
+        scope_values = ["repo", "global"] if include_global else ["repo"]
+        stmt = (
+            select(
+                memories.c.id.label("memory_id"),
+                memory_embeddings.c.vector,
+            )
+            .select_from(memories.join(memory_embeddings, memory_embeddings.c.memory_id == memories.c.id))
+            .where(
+                memories.c.repo_id == repo_id,
+                memories.c.archived.is_(False),
+                memories.c.scope.in_(scope_values),
+            )
+        )
+        if kinds:
+            stmt = stmt.where(memories.c.kind.in_(list(kinds)))
+
+        rows = self._session.execute(stmt).mappings().all()
+        return [
+            {
+                "memory_id": str(row["memory_id"]),
+                "vector": [float(value) for value in row["vector"]],
+            }
+            for row in rows
+        ]
+
+
+def _cosine_similarity(left: list[float], right: list[float]) -> float:
+    """Compute cosine similarity for semantic retrieval ranking and gating."""
+
+    if len(left) != len(right):
+        return 0.0
+    left_norm = sqrt(sum(value * value for value in left))
+    right_norm = sqrt(sum(value * value for value in right))
+    if left_norm == 0 or right_norm == 0:
+        return 0.0
+    dot = sum(left_value * right_value for left_value, right_value in zip(left, right, strict=True))
+    return dot / (left_norm * right_norm)

app/periphery/db/session.py

@@ -0,0 +1,10 @@
+"""This module defines SQLAlchemy session-factory helpers for repository execution."""
+
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session, sessionmaker
+
+
+def get_session_factory(engine: Engine) -> sessionmaker[Session]:
+    """This function creates a reusable session factory bound to an engine."""
+
+    return sessionmaker(bind=engine, future=True, expire_on_commit=False)