feat(storage): implement unified persistence layer with database models and repositories

backend/packages/storage/store/repositories/contracts/__init__.py

@@ -0,0 +1,35 @@
+from store.repositories.contracts.feedback import (
+    Feedback,
+    FeedbackCreate,
+    FeedbackRepositoryProtocol,
+)
+from store.repositories.contracts.run import (
+    Run,
+    RunCreate,
+    RunRepositoryProtocol,
+)
+from store.repositories.contracts.run_event import (
+    RunEvent,
+    RunEventCreate,
+    RunEventRepositoryProtocol,
+)
+from store.repositories.contracts.thread_meta import (
+    ThreadMeta,
+    ThreadMetaCreate,
+    ThreadMetaRepositoryProtocol,
+)
+
+__all__ = [
+    "Feedback",
+    "FeedbackCreate",
+    "FeedbackRepositoryProtocol",
+    "Run",
+    "RunCreate",
+    "RunEvent",
+    "RunEventCreate",
+    "RunEventRepositoryProtocol",
+    "RunRepositoryProtocol",
+    "ThreadMeta",
+    "ThreadMetaCreate",
+    "ThreadMetaRepositoryProtocol",
+]

backend/packages/storage/store/repositories/contracts/feedback.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Protocol
+
+from pydantic import BaseModel, ConfigDict
+
+
+class FeedbackCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    feedback_id: str
+    run_id: str
+    thread_id: str
+    rating: int
+    user_id: str | None = None
+    message_id: str | None = None
+    comment: str | None = None
+
+
+class Feedback(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    feedback_id: str
+    run_id: str
+    thread_id: str
+    rating: int
+    user_id: str | None
+    message_id: str | None
+    comment: str | None
+    created_time: datetime
+
+
+class FeedbackRepositoryProtocol(Protocol):
+    async def create_feedback(self, data: FeedbackCreate) -> Feedback: ...
+    async def get_feedback(self, feedback_id: str) -> Feedback | None: ...
+    async def list_feedback_by_run(self, run_id: str) -> list[Feedback]: ...
+    async def list_feedback_by_thread(self, thread_id: str) -> list[Feedback]: ...
+    async def delete_feedback(self, feedback_id: str) -> bool: ...

backend/packages/storage/store/repositories/contracts/run.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RunCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    run_id: str
+    thread_id: str
+    assistant_id: str | None = None
+    user_id: str | None = None
+    status: str = "pending"
+    model_name: str | None = None
+    multitask_strategy: str = "reject"
+    follow_up_to_run_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    kwargs: dict[str, Any] = Field(default_factory=dict)
+
+
+class Run(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    run_id: str
+    thread_id: str
+    assistant_id: str | None
+    user_id: str | None
+    status: str
+    model_name: str | None
+    multitask_strategy: str
+    error: str | None
+    follow_up_to_run_id: str | None
+    metadata: dict[str, Any]
+    kwargs: dict[str, Any]
+    total_input_tokens: int
+    total_output_tokens: int
+    total_tokens: int
+    llm_call_count: int
+    lead_agent_tokens: int
+    subagent_tokens: int
+    middleware_tokens: int
+    message_count: int
+    first_human_message: str | None
+    last_ai_message: str | None
+    created_time: datetime
+    updated_time: datetime | None
+
+
+class RunRepositoryProtocol(Protocol):
+    async def create_run(self, data: RunCreate) -> Run: ...
+    async def get_run(self, run_id: str) -> Run | None: ...
+    async def list_runs_by_thread(self, thread_id: str, *, limit: int = 50, offset: int = 0) -> list[Run]: ...
+    async def update_run_status(self, run_id: str, status: str, *, error: str | None = None) -> None: ...
+    async def delete_run(self, run_id: str) -> None: ...
+    async def update_run_completion(
+        self,
+        run_id: str,
+        *,
+        status: str,
+        total_input_tokens: int = 0,
+        total_output_tokens: int = 0,
+        total_tokens: int = 0,
+        llm_call_count: int = 0,
+        lead_agent_tokens: int = 0,
+        subagent_tokens: int = 0,
+        middleware_tokens: int = 0,
+        message_count: int = 0,
+        first_human_message: str | None = None,
+        last_ai_message: str | None = None,
+        error: str | None = None,
+    ) -> None: ...

backend/packages/storage/store/repositories/contracts/run_event.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RunEventCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    thread_id: str
+    run_id: str
+    event_type: str
+    category: str
+    content: str | dict[str, Any] = ""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime | None = None
+
+
+class RunEvent(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    thread_id: str
+    run_id: str
+    event_type: str
+    category: str
+    content: str | dict[str, Any]
+    metadata: dict[str, Any]
+    seq: int
+    created_at: datetime
+
+
+class RunEventRepositoryProtocol(Protocol):
+    async def append_batch(self, events: list[RunEventCreate]) -> list[RunEvent]: ...
+
+    async def list_messages(
+        self,
+        thread_id: str,
+        *,
+        limit: int = 50,
+        before_seq: int | None = None,
+        after_seq: int | None = None,
+    ) -> list[RunEvent]: ...
+
+    async def list_events(
+        self,
+        thread_id: str,
+        run_id: str,
+        *,
+        event_types: list[str] | None = None,
+        limit: int = 500,
+    ) -> list[RunEvent]: ...
+
+    async def list_messages_by_run(
+        self,
+        thread_id: str,
+        run_id: str,
+        *,
+        limit: int = 50,
+        before_seq: int | None = None,
+        after_seq: int | None = None,
+    ) -> list[RunEvent]: ...
+
+    async def count_messages(self, thread_id: str) -> int: ...
+
+    async def delete_by_thread(self, thread_id: str) -> int: ...
+
+    async def delete_by_run(self, thread_id: str, run_id: str) -> int: ...

backend/packages/storage/store/repositories/contracts/thread_meta.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ThreadMetaCreate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    thread_id: str
+    assistant_id: str | None = None
+    user_id: str | None = None
+    display_name: str | None = None
+    status: str = "idle"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ThreadMeta(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    thread_id: str
+    assistant_id: str | None
+    user_id: str | None
+    display_name: str | None
+    status: str
+    metadata: dict[str, Any]
+    created_time: datetime
+    updated_time: datetime | None
+
+
+class ThreadMetaRepositoryProtocol(Protocol):
+    async def create_thread_meta(self, data: ThreadMetaCreate) -> ThreadMeta: ...
+
+    async def get_thread_meta(self, thread_id: str) -> ThreadMeta | None: ...
+
+    async def update_thread_meta(
+        self,
+        thread_id: str,
+        *,
+        display_name: str | None = None,
+        status: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None: ...
+
+    async def delete_thread(self, thread_id: str) -> None: ...
+
+    async def search_threads(
+        self,
+        *,
+        metadata: dict[str, Any] | None = None,
+        status: str | None = None,
+        user_id: str | None = None,
+        assistant_id: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[ThreadMeta]: ...