LCORE-776: Allow started_at and completed_at timestamps to be store in database #618

tisnik · 2025-10-03T09:48:41Z

Description

LCORE-776: Allow started_at and completed_at timestamps to be store in database

Type of change

Related Tickets & Documents

Related Issue #LCORE-776

Summary by CodeRabbit

New Features
- Conversation history now includes start and completion timestamps, providing clearer session timelines.
- API responses for chat messages expose started_at and completed_at fields.
- Timestamps are captured for both standard and streaming requests and persisted in conversation history.
Tests
- Updated unit tests to validate presence and propagation of started_at and completed_at across endpoints and caches.

coderabbitai · 2025-10-03T09:48:49Z

Walkthrough

Adds started_at and completed_at timestamps to conversation data: propagated from endpoints through utils to cache models and storage (Postgres/SQLite), exposed in conversations_v2 transformed messages, and covered by updated unit tests. SQL schemas and statements were extended; function signatures updated where necessary.

Changes

Cohort / File(s)	Summary
Endpoints timestamps plumbing `src/app/endpoints/query.py`, `src/app/endpoints/streaming_query.py`	Capture started_at at request start and completed_at after response; pass both into caching.
Message transformation `src/app/endpoints/conversations_v2.py`	Transform output now includes started_at and completed_at from entries.
Cache model `src/models/cache_entry.py`	CacheEntry adds public fields: started_at, completed_at.
Cache utils `src/utils/endpoints.py`	store_conversation_into_cache signature extended; forwards timestamps into CacheEntry.
Postgres cache schema + IO `src/cache/postgres_cache.py`	Table schema adds started_at, completed_at; SELECT/INSERT statements and mappings updated.
SQLite cache schema + IO `src/cache/sqlite_cache.py`	Table schema adds started_at, completed_at; SELECT/INSERT statements and mappings updated.
Tests: endpoints `tests/unit/app/endpoints/test_conversations_v2.py`	Expectations updated to include started_at and completed_at in transformed payload.
Tests: cache implementations `tests/unit/cache/test_noop_cache.py`, `tests/unit/cache/test_postgres_cache.py`, `tests/unit/cache/test_sqlite_cache.py`	CacheEntry constructions updated with started_at and completed_at; assertions aligned with new schema.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant API as API Endpoint
  participant LLM as LLM Provider
  participant Cache as Cache Store

  User->>API: Send query
  API->>API: started_at = now()
  API->>LLM: Request completion
  LLM-->>API: Response
  API->>API: completed_at = now()
  API->>Cache: store(query, response, started_at, completed_at, metadata)
  Cache-->>API: ack
  API-->>User: Return response + ids
  note over API,Cache: Timestamps persisted with conversation

sequenceDiagram
  autonumber
  actor User
  participant API as Streaming Endpoint
  participant LLM as Streaming Provider
  participant Cache as Cache Store

  User->>API: Start streaming query
  API->>API: started_at = now()
  API->>LLM: Initiate stream
  LLM-->>API: Stream chunks
  API-->>User: Relay chunks (loop)
  API->>API: completed_at = now() (on stream end)
  API->>Cache: store(..., started_at, completed_at)
  Cache-->>API: ack

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

LCORE-724: Endpoints for conversation cache v2 #591: Extends the same conversation caching flow; modifies transform_chat_message, store_conversation_into_cache, and endpoints to add started_at/completed_at.
LCORE-298: Conversation cache factory #567: Introduced CacheEntry and cache abstractions that this PR extends with timestamp fields.
LCORE-298: SQLite conversation cache #576: Touches SQLite cache schema/SQL; this PR builds on it by adding started_at/completed_at columns and statements.

Poem

A tick, a tock, my whiskers twitch—
I log the start, I mark the switch.
From first hello to final byte,
Two timestamps glow in moonlit night.
Hop, cache, hop—the tale is told,
Begun and done, in time-stamped gold. 🐇⏱️

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly captures the main change of enabling started_at and completed_at timestamps to be stored in the database and references the associated ticket LCORE-776, making it clear and specific for anyone reviewing the project history.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

src/models/cache_entry.py (1)

6-21: Update the docstring to document the new timestamp fields.

The Attributes section in the docstring doesn't include started_at and completed_at, which are now part of the model.

Apply this diff to complete the documentation:

 class CacheEntry(BaseModel):
     """Model representing a cache entry.

     Attributes:
         query: The query string
         response: The response string
         provider: Provider identification
         model: Model identification
+        started_at: ISO 8601 timestamp when processing started (UTC with Z suffix)
+        completed_at: ISO 8601 timestamp when processing completed (UTC with Z suffix)
     """

     query: str
     response: str
     provider: str
     model: str
     started_at: str
     completed_at: str

Based on coding guidelines.

src/utils/endpoints.py (1)

184-217: Update the docstring to document new parameters.

The function signature was extended to include started_at and completed_at, but the docstring lacks an Args section describing these new parameters.

As per coding guidelines, apply this diff to add complete parameter documentation:

 def store_conversation_into_cache(
     config: AppConfig,
     user_id: str,
     conversation_id: str,
     provider_id: str,
     model_id: str,
     query: str,
     response: str,
     started_at: str,
     completed_at: str,
     _skip_userid_check: bool,
     topic_summary: str | None,
 ) -> None:
-    """Store one part of conversation into conversation history cache."""
+    """Store one part of conversation into conversation history cache.
+
+    Args:
+        config: Application configuration containing cache settings.
+        user_id: User identification.
+        conversation_id: Conversation ID unique for the given user.
+        provider_id: Model provider identifier.
+        model_id: Model identifier.
+        query: User query text.
+        response: Model response text.
+        started_at: ISO 8601 timestamp when the query processing started.
+        completed_at: ISO 8601 timestamp when the query processing completed.
+        _skip_userid_check: Skip user_id validation check.
+        topic_summary: Optional topic summary for the conversation.
+    """

🧹 Nitpick comments (2)

src/app/endpoints/conversations_v2.py (1)
241-252: Update docstring to document the new fields in the return value.

The function now returns started_at and completed_at fields, but the docstring doesn't document the complete structure of the returned dictionary.

Apply this diff to enhance the docstring:
 def transform_chat_message(entry: CacheEntry) -> dict[str, Any]:
-    """Transform the message read from cache into format used by response payload."""
+    """Transform the message read from cache into format used by response payload.
+    
+    Args:
+        entry: The cache entry containing query, response, and metadata.
+        
+    Returns:
+        A dictionary containing provider, model, messages list, started_at, and completed_at.
+    """
     return {
Based on coding guidelines.
src/cache/sqlite_cache.py (1)
22-40: Optional: Fix stale documentation.

The class docstring mentions "cache_key_key" UNIQUE CONSTRAINT, btree (key) which does not exist in the actual schema (there is no key column). This is a pre-existing documentation issue unrelated to the current changes.

Consider removing these lines from the docstring:
     Indexes:
         "cache_pkey" PRIMARY KEY, btree (user_id, conversation_id, created_at)
-        "cache_key_key" UNIQUE CONSTRAINT, btree (key)
         "timestamps" btree (updated_at)
-    Access method: heap

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f72b573 and 7b71c8b.

📒 Files selected for processing (11)

src/app/endpoints/conversations_v2.py (1 hunks)
src/app/endpoints/query.py (3 hunks)
src/app/endpoints/streaming_query.py (4 hunks)
src/cache/postgres_cache.py (5 hunks)
src/cache/sqlite_cache.py (5 hunks)
src/models/cache_entry.py (1 hunks)
src/utils/endpoints.py (2 hunks)
tests/unit/app/endpoints/test_conversations_v2.py (2 hunks)
tests/unit/cache/test_noop_cache.py (1 hunks)
tests/unit/cache/test_postgres_cache.py (1 hunks)
tests/unit/cache/test_sqlite_cache.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (9)

**/*.py