refactor(storage): split MessageStore into :message-log-api
ci / JVM build + tests (push) Successful in 6m15s
ci / JVM build + tests (push) Successful in 6m15s
Выделяет append-only message log в отдельный KMP-модуль.
Цель — разделить ДВЕ сущности по своей природе:
:message-log-api — append-only audit log (User/Assistant/ToolCall/
ToolResult/Error). Никаких update, только insert + read.
Это иммутабельная история диалога.
:working-memory-api — mutable runtime context (compact, summary, WM order).
Live state. Compaction-логика.
Раньше оба жили в :message-store-api, что:
- смешивало контракты: append-only audit vs mutable runtime;
- делало невозможным лёгкого клиента который читает только audit log
без WM-runtime зависимости;
- затрудняло compaction-логике жить в одном модуле с audit-записью.
Миграция:
- В :message-log-api переехали: Content, MessageRecord, MessageStore,
MessageContext (с MessageOrigin), MessageEvent, TokenStats, TurnTokens,
helpers (encode/decodeBodyPayload, MessageBodyPayload, BodyDecoded).
Пакет pw.binom.agentik.messageLog.
- В :message-store-api остались: ConversationStore, ConversationRecord,
ReflectionStore, Ids, legacy events.EventStore (paginated replay).
Пакет pw.binom.agentik.messageStore.
- :working-memory-api: обновил deps (api → :message-log-api для Content/MessageContext).
- 23 consumer-файла обновлены (FQN renames).
- storage-sqlite/ksqlite: убраны недостижимые ветки Summary/System
(эти synthetic records живут ТОЛЬКО в :working-memory-api, не попадают
в audit log :message-log-api).
Файлы:
+ :message-log-api (5 файлов, ~280 строк)
- :message-store-api (5 файлов, ~430 строк)
~ 23 файла обновлены
Совместимость схем не меняется. Все 5 storage impl'ов (3 backend × 5 store)
работают на тех же таблицах.
This commit is contained in:
@@ -1,29 +0,0 @@
|
||||
package pw.binom.agentik.messageStore
|
||||
|
||||
import kotlinx.serialization.SerialName
|
||||
import kotlinx.serialization.Serializable
|
||||
|
||||
/**
|
||||
* Часть контента сообщения на уровне хранилища.
|
||||
*
|
||||
* Намеренно НЕ зависит от [pw.binom.agentik.proto.Content] — маппинг
|
||||
* `:proto.Content ↔ Content` живёт в `Mapping.kt`. Структурно типы
|
||||
* идентичны, но даёт возможность заменить transport-протокол без миграции
|
||||
* таблиц.
|
||||
*
|
||||
* Image сериализуется в JSON через base64 (стандарт для kotlinx-serialization).
|
||||
*/
|
||||
@Serializable
|
||||
sealed interface Content {
|
||||
@Serializable
|
||||
@SerialName("text")
|
||||
data class Text(val body: String) : Content
|
||||
|
||||
@Serializable
|
||||
@SerialName("image")
|
||||
data class Image(val data: ByteArray, val mime: String) : Content {
|
||||
override fun equals(other: Any?): Boolean =
|
||||
this === other || (other is Image && mime == other.mime && data.contentEquals(other.data))
|
||||
override fun hashCode(): Int = 31 * mime.hashCode() + data.contentHashCode()
|
||||
}
|
||||
}
|
||||
-40
@@ -1,40 +0,0 @@
|
||||
package pw.binom.agentik.messageStore
|
||||
|
||||
import kotlinx.serialization.SerialName
|
||||
import kotlinx.serialization.Serializable
|
||||
import kotlinx.serialization.json.JsonElement
|
||||
|
||||
/**
|
||||
* Контекст инициации хода (кто/что и почему).
|
||||
*
|
||||
* Дубликат типа из `:proto` (`pw.binom.agentik.proto.MessageContext`):
|
||||
* живёт в `:storage-core` чтобы не тащить `:proto` в слой хранения данных.
|
||||
* Маппинг между ними — в `MessageRecord.toProto()` / `ProtoMessage.toStorage()`.
|
||||
*
|
||||
* Используется:
|
||||
* - в `MessageRecord.UserMessage.context` — фиксируется в audit log;
|
||||
* - в `WorkingMemoryEntry.User.context` — попадает в LLM-нагрузку
|
||||
* как префикс к user-тексту (для не-USER origin'ов).
|
||||
*
|
||||
* Сериализация в `payload_json` (SQLite) — через kotlinx-serialization,
|
||||
* формат snake_case для enum origin.
|
||||
*/
|
||||
@Serializable
|
||||
enum class MessageOrigin {
|
||||
@SerialName("user")
|
||||
USER,
|
||||
|
||||
@SerialName("system")
|
||||
SYSTEM,
|
||||
|
||||
@SerialName("event")
|
||||
EVENT,
|
||||
}
|
||||
|
||||
@Serializable
|
||||
data class MessageContext(
|
||||
val origin: MessageOrigin,
|
||||
val description: String? = null,
|
||||
val sourceId: String? = null,
|
||||
val metadata: JsonElement? = null,
|
||||
)
|
||||
-144
@@ -1,144 +0,0 @@
|
||||
package pw.binom.agentik.messageStore
|
||||
|
||||
import kotlinx.serialization.SerialName
|
||||
import kotlinx.serialization.Serializable
|
||||
import kotlin.time.Instant
|
||||
|
||||
/**
|
||||
* Token usage одного assistant turn'а: сколько токенов модель обработала
|
||||
* на входе (system + history + tools + user message) и сколько сгенерировала
|
||||
* (assistant text + tool calls + tool results, всё что LiteConversation
|
||||
* добавила к истории за этот turn).
|
||||
*
|
||||
* `input` — снимок [LiteConversation.tokenCount] перед первым send() в turn'е
|
||||
* (после подготовки user-сообщения). `output` — дельта после завершения turn'а
|
||||
* (включая все tool loop итерации).
|
||||
*
|
||||
* Persisted в `message.payload_json` — никаких schema-миграций при добавлении
|
||||
* полей. Optional: `null` для исторических сообщений или для бэкендов, не
|
||||
* отдающих tokenCount (например off-line embedded LLM без контекст-счётчика).
|
||||
*/
|
||||
@Serializable
|
||||
data class TurnTokens(
|
||||
val input: Int,
|
||||
val output: Int,
|
||||
) {
|
||||
val total: Int get() = input + output
|
||||
init {
|
||||
require(input >= 0) { "input tokens must be non-negative, got $input" }
|
||||
require(output >= 0) { "output tokens must be non-negative, got $output" }
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Запись в таблице `message` (append-only audit) и `working_memory` (mutable view).
|
||||
*
|
||||
* Использует sealed-иерархию: подтипы `User`/`Assistant`/`ToolCall`/`ToolResult`
|
||||
* живут и там, и там. `Summary`/`System` — только в `working_memory`
|
||||
* (синтетические строки, созданные при суммаризации или как system-prompt).
|
||||
*
|
||||
* Все подтипы несут [id] (UUID, стабильный между лайв-стримом Event и историей),
|
||||
* [conversationId] и [createdAt].
|
||||
*
|
||||
* Поля, специфичные для подтипа, сериализуются в JSON в `payload_json`
|
||||
* колонке SQLite — это даёт гибкость без миграций при добавлении полей.
|
||||
*/
|
||||
@Serializable
|
||||
sealed interface MessageRecord {
|
||||
|
||||
val id: String
|
||||
val conversationId: String
|
||||
val createdAt: Instant
|
||||
|
||||
/** Подтип сообщения с телом из [Content]. */
|
||||
@Serializable
|
||||
sealed interface Body : MessageRecord {
|
||||
val content: List<Content>
|
||||
}
|
||||
|
||||
@Serializable
|
||||
@SerialName("user")
|
||||
data class UserMessage(
|
||||
override val id: String,
|
||||
override val conversationId: String,
|
||||
override val content: List<Content>,
|
||||
override val createdAt: Instant,
|
||||
/**
|
||||
* Контекст инициации хода: кто/что вызвал этот turn. `null` —
|
||||
* обычное user-сообщение. См. [MessageContext].
|
||||
*
|
||||
* Persisted через `payload_json` SQLite (см. `Payload.kt`).
|
||||
*/
|
||||
val context: MessageContext? = null,
|
||||
) : Body
|
||||
|
||||
@Serializable
|
||||
@SerialName("assistant")
|
||||
data class AssistantMessage(
|
||||
override val id: String,
|
||||
override val conversationId: String,
|
||||
override val content: List<Content>,
|
||||
override val createdAt: Instant,
|
||||
/**
|
||||
* Token usage этого turn'а: сколько input+output токенов обработала
|
||||
* модель. Заполняется в [ChatConversation.runTurn] через
|
||||
* `LiteConversation.tokenCount()` (до/после send).
|
||||
*/
|
||||
val tokens: TurnTokens? = null,
|
||||
) : Body
|
||||
|
||||
@Serializable
|
||||
@SerialName("tool_call")
|
||||
data class ToolCall(
|
||||
override val id: String,
|
||||
override val conversationId: String,
|
||||
val toolName: String,
|
||||
val toolTitle: String?,
|
||||
val toolArgsJson: String,
|
||||
override val createdAt: Instant,
|
||||
) : MessageRecord
|
||||
|
||||
@Serializable
|
||||
@SerialName("tool_result")
|
||||
data class ToolResult(
|
||||
override val id: String,
|
||||
override val conversationId: String,
|
||||
val toolCallId: String,
|
||||
val result: String?,
|
||||
override val createdAt: Instant,
|
||||
) : MessageRecord
|
||||
|
||||
/**
|
||||
* Терминальная запись провалившегося хода. Только audit log
|
||||
* (в working_memory не пишется — модель не должна видеть ошибки прошлых ходов).
|
||||
*/
|
||||
@Serializable
|
||||
@SerialName("error")
|
||||
data class Error(
|
||||
override val id: String,
|
||||
override val conversationId: String,
|
||||
val message: String,
|
||||
val code: String?,
|
||||
override val createdAt: Instant,
|
||||
) : MessageRecord
|
||||
|
||||
/** Синтетическое: суммаризация старого контекста. Только в working_memory. */
|
||||
@Serializable
|
||||
@SerialName("summary")
|
||||
data class Summary(
|
||||
override val id: String,
|
||||
override val conversationId: String,
|
||||
val text: String,
|
||||
override val createdAt: Instant,
|
||||
) : MessageRecord
|
||||
|
||||
/** Синтетическое: system-prompt, введённый при создании диалога. Только в working_memory. */
|
||||
@Serializable
|
||||
@SerialName("system")
|
||||
data class System(
|
||||
override val id: String,
|
||||
override val conversationId: String,
|
||||
val text: String,
|
||||
override val createdAt: Instant,
|
||||
) : MessageRecord
|
||||
}
|
||||
@@ -1,56 +0,0 @@
|
||||
package pw.binom.agentik.messageStore
|
||||
|
||||
import kotlinx.coroutines.flow.Flow
|
||||
import kotlin.time.Instant
|
||||
|
||||
/**
|
||||
* Суммарная статистика токенов диалога — aggregate по всем assistant-сообщениям
|
||||
* в audit log. Делит input/output и считает число assistant-ходов.
|
||||
*
|
||||
* Используется:
|
||||
* - В startup banner'е агента (см. `Main.kt` → "conversation stats").
|
||||
* - На HTTP фасаде `/agentik/conversations/{id}/stats` (если будет endpoint).
|
||||
* - В клиентских дашбордах для оценки cost.
|
||||
*/
|
||||
data class TokenStats(
|
||||
val turns: Int,
|
||||
val inputTokens: Long,
|
||||
val outputTokens: Long,
|
||||
) {
|
||||
val totalTokens: Long get() = inputTokens + outputTokens
|
||||
}
|
||||
|
||||
/**
|
||||
* Append-only audit log сообщений (`message` table).
|
||||
*
|
||||
* Только `insert` и чтение. Никаких обновлений, никакого удаления (кроме
|
||||
* каскадного удаления вместе с [ConversationStore.delete]).
|
||||
*/
|
||||
interface MessageStore : AutoCloseable {
|
||||
|
||||
/** Добавить запись в audit log. `conversationId` берётся из [MessageRecord.conversationId]. */
|
||||
suspend fun append(record: MessageRecord)
|
||||
|
||||
/**
|
||||
* Страница audit-сообщений диалога после [after] (UTC), отсортированная
|
||||
* по `createdAt ASC`. Для первоначальной загрузки передай `Instant.DISTANT_PAST`.
|
||||
*/
|
||||
suspend fun list(conversationId: String, after: Instant, offset: Int, limit: Int): List<MessageRecord>
|
||||
|
||||
/** Все сообщения диалога, отсортированные по `createdAt ASC` (для rebuild working memory). */
|
||||
suspend fun listAll(conversationId: String): List<MessageRecord>
|
||||
|
||||
/** Лайв-стрим новых сообщений (для SSE-подписчиков). По умолчанию — пустой. */
|
||||
fun events(): Flow<MessageEvent> = kotlinx.coroutines.flow.emptyFlow()
|
||||
|
||||
/**
|
||||
* Суммарная token-статистика по диалогу: input/output/turns. Один проход
|
||||
* по всем assistant-сообщениям. Дёшево (на практике < 1мс на SQLite).
|
||||
*/
|
||||
suspend fun tokenStats(conversationId: String): TokenStats
|
||||
}
|
||||
|
||||
sealed interface MessageEvent {
|
||||
val conversationId: String
|
||||
data class Appended(override val conversationId: String, val record: MessageRecord) : MessageEvent
|
||||
}
|
||||
@@ -1,79 +0,0 @@
|
||||
package pw.binom.agentik.messageStore
|
||||
|
||||
import kotlinx.serialization.SerialName
|
||||
import kotlinx.serialization.Serializable
|
||||
import kotlinx.serialization.builtins.ListSerializer
|
||||
import kotlinx.serialization.json.Json
|
||||
|
||||
/**
|
||||
* JSON-формат для тел user/assistant сообщений: список [Content], опционально
|
||||
* с [MessageContext] (для user — кто инициировал ход) и [TurnTokens]
|
||||
* (для assistant — сколько токенов стоил этот turn).
|
||||
*
|
||||
* Encoded-формат:
|
||||
* ```
|
||||
* {"content": [ ...Content ], "context": {...MessageContext?}, "tokens": {...TurnTokens?}}
|
||||
* ```
|
||||
*
|
||||
* Backward compat: при чтении старых строк, где payload был просто
|
||||
* `[ ... ]` (без обёртки), парсер падает на wrapper-формат и fallback'ит
|
||||
* к `ListSerializer<Content>` — такие строки возвращаются с `context = null`,
|
||||
* `tokens = null`.
|
||||
*/
|
||||
private val bodyJson = Json {
|
||||
ignoreUnknownKeys = true
|
||||
encodeDefaults = true
|
||||
explicitNulls = false
|
||||
}
|
||||
|
||||
@Serializable
|
||||
data class MessageBodyPayload(
|
||||
val content: List<Content>,
|
||||
@SerialName("context")
|
||||
val context: MessageContext? = null,
|
||||
/**
|
||||
* Token usage для assistant (input + output). `null` для user-сообщений,
|
||||
* для исторических assistant-сообщений без метрики и для бэкендов без
|
||||
* tokenCount() (off-line модели).
|
||||
*/
|
||||
val tokens: TurnTokens? = null,
|
||||
)
|
||||
|
||||
/**
|
||||
* Сериализует тело user (или assistant) сообщения в JSON-строку для
|
||||
* `payload_json` SQLite. Для user может нести [context] — кто инициировал ход;
|
||||
* для assistant может нести [tokens] — token usage этого turn'а.
|
||||
*/
|
||||
fun encodeBodyPayload(
|
||||
content: List<Content>,
|
||||
context: MessageContext? = null,
|
||||
tokens: TurnTokens? = null,
|
||||
): String = bodyJson.encodeToString(
|
||||
MessageBodyPayload.serializer(),
|
||||
MessageBodyPayload(content = content, context = context, tokens = tokens),
|
||||
)
|
||||
|
||||
/**
|
||||
* Десериализует тело сообщения: возвращает тройку `(content, context, tokens)`.
|
||||
* Контекст и токены — null если:
|
||||
* - поля отсутствуют в новом формате;
|
||||
* - payload в старом plain-array формате (миграция не нужна — fallback).
|
||||
*/
|
||||
fun decodeBodyPayload(json: String): BodyDecoded = readPayload(json)
|
||||
|
||||
data class BodyDecoded(
|
||||
val content: List<Content>,
|
||||
val context: MessageContext?,
|
||||
val tokens: TurnTokens? = null,
|
||||
)
|
||||
|
||||
private fun readPayload(json: String): BodyDecoded {
|
||||
return try {
|
||||
val p = bodyJson.decodeFromString(MessageBodyPayload.serializer(), json)
|
||||
BodyDecoded(p.content, p.context, p.tokens)
|
||||
} catch (e: kotlinx.serialization.SerializationException) {
|
||||
// Старый формат: голый JSON-массив Content, без обёртки.
|
||||
val arr = bodyJson.decodeFromString(ListSerializer(Content.serializer()), json)
|
||||
BodyDecoded(arr, null, null)
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user