Merge pull request #2004 from tisnik/lcore-1404-database-and-compaction-models

LCORE-1404: database and compaction models

Author: tisnik

Makefile

@@ -191,41 +191,52 @@ generate-documentation:	## Generate documentation
 doc:	## Generate documentation for developers
 	scripts/gen_doc.py
 
-docs/models:	docs/models/requests.puml docs/models/responses.puml docs/models/common.puml	## Generate documentation about models
+docs/models:	docs/models/requests.puml docs/models/responses.puml docs/models/database.puml docs/models/common.puml	## Generate documentation about models
 
-docs/models/requests.puml:
+docs/models/requests.puml: ## Generate PlantUML class diagram for requests data models
 	uv run pyreverse src/models/api/requests/ --output puml --output-directory=docs/models/
 	mv docs/models/classes.puml docs/models/requests.puml
 
-docs/models/responses.puml:
+docs/models/responses.puml: ## Generate PlantUML class diagram for responses data models
 	uv run pyreverse src/models/api/responses/ --output puml --output-directory=docs/models/
 	mv docs/models/classes.puml docs/models/responses.puml
 
-docs/models/common.puml:
+docs/models/common.puml: ## Generate PlantUML class diagram for common data models
 	uv run pyreverse src/models/common/ --output puml --output-directory=docs/models/
 	mv docs/models/classes.puml docs/models/common.puml
 
-docs/models/requests.svg:	docs/models/requests.puml
+docs/models/database.puml: ## Generate PlantUML class diagram for database data models
+	uv run pyreverse src/models/database/ --output puml --output-directory=docs/models/
+	mv docs/models/classes.puml docs/models/database.puml
+
+docs/models/requests.svg:	docs/models/requests.puml	## Generate an SVG with requests data models
 	pushd docs/models && \
 	java -jar ${PATH_TO_PLANTUML}/plantuml.jar requests.puml -tsvg && \
 	xmllint --format classes.svg > requests.svg && \
 	rm -f classes.svg && \
 	popd
 
-docs/models/responses.svg:	docs/models/responses.puml
+docs/models/responses.svg:	docs/models/responses.puml	## Generate an SVG with responses data models
 	pushd docs/models && \
 	java -jar ${PATH_TO_PLANTUML}/plantuml.jar responses.puml -tsvg && \
 	xmllint --format classes.svg > responses.svg && \
 	rm -f classes.svg && \
 	popd
 
-docs/models/common.svg:	docs/models/common.puml
+docs/models/common.svg:	docs/models/common.puml	## Generate an SVG with common data models
 	pushd docs/models && \
 	java -jar ${PATH_TO_PLANTUML}/plantuml.jar common.puml -tsvg && \
 	xmllint --format classes.svg > common.svg && \
 	rm -f classes.svg && \
 	popd
 
+docs/models/database.svg:	docs/models/database.puml	## Generate a SVG with database data models
+	pushd docs/models && \
+	java -jar ${PATH_TO_PLANTUML}/plantuml.jar database.puml -tsvg && \
+	xmllint --format classes.svg > database.svg && \
+	rm -f classes.svg && \
+	popd
+
 docs/config.puml:	src/models/config.py ## Generate PlantUML class diagram for configuration
 	uv run pyreverse src/models/config.py --output puml --output-directory=docs/
 	mv docs/classes.puml docs/config.puml

docs/models/README.md

@@ -0,0 +1,2 @@
+# Documentation for all data models used in LCore
+

docs/models/compaction.md

@@ -0,0 +1,54 @@
+# Lightspeed Core Stack
+
+
+
+## 🌍 Base URL
+
+
+| URL | Description |
+|-----|-------------|
+
+
+# 🛠️ APIs
+
+---
+
+# 📋 Components
+
+
+
+## ConversationSummary
+
+
+A single compaction-produced summary chunk.
+
+Attributes:
+    summary_text: The natural-language summary produced by the
+        summarization LLM call. Used directly as context for
+        subsequent requests (alongside any later summary chunks
+        and the buffer of recent turns kept verbatim).
+    summarized_through_turn: Running total of conversation items
+        consumed by this and all preceding summaries. Used by the
+        caller to advance the partition boundary on the next
+        compaction so the new summary only covers items that
+        have not yet been summarized.
+    token_count: Number of tokens in ``summary_text``. Tracked so
+        the recursive-resummarize fallback can decide when the
+        cumulative summary size itself approaches the context
+        limit without re-tokenizing.
+    created_at: ISO 8601 timestamp recording when this summary was
+        produced. Kept as a string (not datetime) to match the
+        cache schema convention used elsewhere in the codebase.
+    model_used: Fully-qualified model identifier used for the
+        summarization LLM call (e.g., ``"openai/gpt-4o-mini"``).
+        Preserved for audit and for diagnostics when summary
+        quality varies between models.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| summary_text | string | Natural-language summary produced by the summarization LLM call. |
+| summarized_through_turn | integer | Running total of conversation items consumed by this and all preceding summaries. |
+| token_count | integer | Number of tokens in summary_text. |
+| created_at | string | ISO 8601 timestamp recording when this summary was produced. |
+| model_used | string | Fully-qualified model identifier used for the summarization call. |

docs/models/database.puml

@@ -0,0 +1,25 @@
+@startuml classes
+set namespaceSeparator none
+class "Base" as src.models.database.base.Base {
+}
+class "UserConversation" as src.models.database.conversations.UserConversation {
+  created_at : Mapped[datetime]
+  id : Mapped[str]
+  last_message_at : Mapped[datetime]
+  last_response_id : Mapped[str]
+  last_used_model : Mapped[str]
+  last_used_provider : Mapped[str]
+  message_count : Mapped[int]
+  topic_summary : Mapped[str]
+  user_id : Mapped[str]
+}
+class "UserTurn" as src.models.database.conversations.UserTurn {
+  completed_at : Mapped[datetime]
+  conversation_id : Mapped[str]
+  model : Mapped[str]
+  provider : Mapped[str]
+  response_id : Mapped[str]
+  started_at : Mapped[datetime]
+  turn_number : Mapped[int]
+}
+@enduml