subochev
23da1f6498
Self-reflection: каждые N пользовательских ходов агент запускает one-shot
LLM-размышление о качестве своих ответов, сохраняет score+weakSpots в SQLite,
подмешивает top-K последних рефлексий в system prompt как "слабые места".
* sqldelight: новая таблица reflection (id, conversation_id?, created_at,
turns_analyzed, score, summary, weak_spots_json) + индексы по created_at и
conversation_id.
* persistence: Reflection data class + ReflectionStore interface +
SqliteReflectionStore (insert/get/listRecent/listForConversation/
deleteOlderThan/count + events Flow). weakSpots хранятся как JSON-массив,
парсятся ручным сканером (без kotlinx-serialization в этом модуле).
* agent: LlmReflector (one-shot LiteLlm через createConversation +
send, structured-output JSON). ReflectionParser (hand-rolled,
толерантный к ```json fences и лидирующему/завершающему тексту;
score принимает int или строку; weakSpots — массив).
* agent: ReflectionPrompts (Russian system+user prompts, аналогично
LlmMemoryReviewer/ReviewPrompts).
* agent: ChatAgent.buildSystemPrompt расширен параметром reflections —
добавляется секция `## Self-reflection: твои слабые места за последнее время`
после memory и перед soul-prepend.
* agent: ChatConversation.scheduleReflection — каждые reflectionInterval
пользовательских ходов (счётчик через workingMemory.list) запускает
reflector на Dispatchers.IO, результат сохраняет в reflectionStore
с conversationId. Не блокирует turn.
* AgentikConfig: новые поля reflectionInterval (env AGENTIK_REFLECTION_INTERVAL,
default 10, clamped 0..1000) и reflectionTopK (env AGENTIK_REFLECTION_TOP_K,
default 3, clamped 0..20).
* Main.kt: если reflectionInterval > 0 — создаём LlmReflector(llm); загружаем
top-K из SQLite в system prompt.
* Ids.reflection() — генератор id "refl-<uuid>".
* Tests: ReflectionParserTest (7: clean JSON, fences, лидирующий текст,
score-as-string, отсутствие score, невалидный JSON, escape-последовательности),
ReflectionStoreTest (7: round-trip, listRecent с лимитом, фильтр по
conversation_id, deleteOlderThan, count, encode/decode строк), и
ChatAgentReflectionTest (3: секция скрыта при пустых, присутствует с
score+spots, порядок soul→memory→reflection).
* README: новые env-переменные, раздел "Self-reflection", startup output.
Smoke test подтверждает: reflection секция появляется в system prompt когда
в SQLite есть записи (listRecent возвращает непустой список). При
reflectionInterval=0 reflector не создаётся, scheduleReflection — no-op.
Tests: 305 total green (+17: 7+7+3). Fatjar собирается, logback-вывод
работает (logging: см. предыдущий коммит f5a551b).
395 lines
20 KiB
Markdown
395 lines
20 KiB
Markdown
# :standalone — agentik single-jar server
|
||
|
||
Self-contained HTTP-сервер с Ktor: AG-UI / A2A / :proto транспорты на одном порту,
|
||
встроенный SQLite для истории диалогов, долговременная память (Hermes-style
|
||
§-файлы), загрузка MCP-инструментов, навыков (SKILL.md) и персоны (SOUL.md).
|
||
|
||
## Сборка
|
||
|
||
```bash
|
||
# Полная сборка всего проекта + fatjar
|
||
./gradlew assemble
|
||
|
||
# Только fatjar :standalone (≈ 150 MB)
|
||
./gradlew :standalone:shadowJar
|
||
|
||
# Результат:
|
||
# standalone/build/libs/standalone-all.jar
|
||
```
|
||
|
||
## Запуск
|
||
|
||
```bash
|
||
java -jar standalone/build/libs/standalone-all.jar
|
||
```
|
||
|
||
По умолчанию слушает на `http://localhost:8080`. Healthcheck: `GET /health`.
|
||
|
||
Транспорты на одном порту:
|
||
- `GET /health` — liveness
|
||
- `POST /agentik/conversations` — создать беседу
|
||
- `GET /agentik/conversations/{id}/events` — SSE-стрим ответов
|
||
|
||
## Переменные окружения
|
||
|
||
Все переменные читаются `AgentikConfig.fromEnv()`. Бланк или отсутствие → дефолт.
|
||
|
||
| Переменная | Дефолт | Назначение |
|
||
|---|---|---|
|
||
| `AGENTIK_PORT` | `8080` | Порт HTTP-сервера |
|
||
| `AGENTIK_DB_PATH` | `./agentik.db` | Путь к SQLite (история бесед + метаданные памяти) |
|
||
| `AGENTIK_SKILLS_DIR` | _выкл._ | Каталог со скилами (`SKILL.md` / `*.yaml`) |
|
||
| `AGENTIK_MEMORY_DIR` | `~/.agentik/memory` (md) или `AGENTIK_DB_PATH` (vector) | Каталог памяти (md); `"off"` отключает |
|
||
| `AGENTIK_MEMORY_BACKEND` | `md` | `md` (Hermes-style §-файлы) / `vector` (SQLite + JVector + LLM-эмбеддинги) / `off` |
|
||
| `AGENTIK_EMBEDDING_MODEL` | `text-embedding-3-small` | Модель эмбеддингов для vector-бэкенда (только HTTP) |
|
||
| `AGENTIK_EMBEDDING_DIMENSION` | `1536` | Размерность вектора (только HTTP; SIGLIP определяет автоматически) |
|
||
| `AGENTIK_EMBEDDING_BACKEND` | `HTTP` | `HTTP` (POST /v1/embeddings) или `SIGLIP` (on-device, без сети) |
|
||
| `AGENTIK_EMBEDDING_MODEL_PATH` | _только SIGLIP_ | Путь к `text_model_int8.onnx` (SigLIP2) |
|
||
| `AGENTIK_EMBEDDING_TOKENIZER_PATH` | _только SIGLIP_ | Путь к `tokenizer.model` (sentencepiece) |
|
||
| `AGENTIK_SOUL` | _выкл._ | Путь к `SOUL.md` — файл персоны (markdown), вставляется в начало system prompt |
|
||
| `AGENTIK_LLM_BACKEND` | — | `openai` или `google` (см. ниже) |
|
||
| `AGENTIK_MCP_CONFIG` | _выкл._ | Путь к JSON со списком MCP-серверов |
|
||
| `AGENTIK_SYSTEM_PROMPT` | `be brief` | Базовый system prompt |
|
||
| `OPENAI_CONTEXT_WINDOW` | _выкл._ | Лимит контекстного окна в токенах (для compaction'а) |
|
||
| `AGENTIK_GOOGLE_CONTEXT_WINDOW` | _выкл._ | То же для Google backend |
|
||
| `AGENTIK_COMPRESSION_THRESHOLD` | `0.8` | Доля лимита, при которой запускается compaction |
|
||
| `AGENTIK_REFLECTION_INTERVAL` | `10` | Self-reflection: каждый N-й пользовательский ход агент оценивает себя (LiteLlm) и сохраняет рефлексию. `0` = выключено. |
|
||
| `AGENTIK_REFLECTION_TOP_K` | `3` | Сколько последних рефлексий подмешивать в system prompt как «слабые места». `0` = не подмешивать. |
|
||
|
||
### OpenAI backend
|
||
|
||
| Переменная | Обязательна | Назначение |
|
||
|---|---|---|
|
||
| `OPENAI_BASE_URL` | да | Например, `https://api.openai.com/v1` |
|
||
| `OPENAI_API_KEY` | да | API key |
|
||
| `OPENAI_MODEL` | да | Имя модели (`gpt-4o-mini` и т.п.) |
|
||
|
||
### Google backend
|
||
|
||
| Переменная | Обязательна | Назначение |
|
||
|---|---|---|
|
||
| `AGENTIK_GOOGLE_MODEL_PATH` | да | Путь к `.litertlm` файлу |
|
||
|
||
## SQLite: путь к базе диалогов
|
||
|
||
`AGENTIK_DB_PATH` указывает на файл SQLite, в котором хранятся таблицы
|
||
`conversations`, `messages`, `working_memory`. SQLDelight-драйвер создаёт
|
||
файл при первом запуске. Если в пути есть несуществующие директории — их
|
||
нужно создать заранее (`mkdir -p`).
|
||
|
||
```bash
|
||
# Абсолютный путь
|
||
AGENTIK_DB_PATH=/var/lib/agentik/state.db
|
||
|
||
# Относительный путь — резолвится от CWD
|
||
cd /opt/agentik && AGENTIK_DB_PATH=./data/state.db
|
||
|
||
# Временная база (на RAM, теряется при рестарте) — не поддерживается напрямую,
|
||
# но можно подменить в коде через SqliteStores.inMemory().
|
||
```
|
||
|
||
Файл базы — обычный SQLite, можно инспектировать `sqlite3` CLI или Adminer.
|
||
|
||
## Контекст инициации сообщения (MessageContext)
|
||
|
||
Каждое user-сообщение может нести **контекст инициации хода** —
|
||
кто/что его вызвало. Для обычного user-сообщения поле `context` опускается
|
||
(обратная совместимость: старые клиенты, шлющие голый массив Content,
|
||
работают как раньше). Для cron/webhook/system событий `context` обязательно.
|
||
|
||
```json
|
||
// POST /agentik/conversations/{id}/messages — новый формат
|
||
{
|
||
"content": [{"type": "text", "body": "wake up"}],
|
||
"context": {
|
||
"origin": "event",
|
||
"description": "scheduled cron morning-briefing",
|
||
"sourceId": "cron-42",
|
||
"metadata": { "scheduledAt": "2026-09-14T08:00:00Z" }
|
||
}
|
||
}
|
||
|
||
// Старый формат (всё ещё работает) — голый массив
|
||
[{"type": "text", "body": "hello"}]
|
||
```
|
||
|
||
| `origin` | Когда использовать | Префикс в LLM |
|
||
|------------|---------------------------------------------------|--------------|
|
||
| `user` | Обычное сообщение из чата (дефолт) | нет |
|
||
| `system` | Программное сообщение (старт агента, режим обслуживания) | `[SYSTEM] description (sourceId=…)` |
|
||
| `event` | Cron, webhook, file-changed, внешний триггер | `[EVENT] description (sourceId=…)` |
|
||
|
||
**Семантика:**
|
||
|
||
- `origin` — кто/что инициировал ход. `user` = человек в чате (UI/IRC/HTTP).
|
||
- `description` — короткая человекочитаемая фраза для модели
|
||
(обязательна для `system`/`event`).
|
||
- `sourceId` — id cron-job'а / webhook endpoint'а / IRC-канала, помогает
|
||
в логах и при ручном разборе.
|
||
- `metadata` — произвольный JSON, никогда не попадает в LLM-нагрузку
|
||
(только в audit log для пост-аналитики).
|
||
|
||
**Что происходит при не-USER origin'е:**
|
||
|
||
В working memory текст user-сообщения предваряется префиксом —
|
||
например, `[EVENT] scheduled cron morning-briefing (sourceId=cron-42)\n…`.
|
||
Модель видит, что её разбудил не пользователь, и может реагировать
|
||
иначе (например, не начинать диалог с приветствия). Префикс добавляется
|
||
**только к LLM-нагрузке**, в audit log и при `getMessages` возвращается
|
||
оригинальный текст + `context` отдельно.
|
||
|
||
## Сжатие рабочего контекста (compaction)
|
||
|
||
Когда диалог становится длинным, working memory диалога может превысить
|
||
контекстное окно модели. Чтобы этого не случилось, агент умеет **сжимать**
|
||
старые ходы в один синтетический `Summary`-блок.
|
||
|
||
**Включается только при заданном лимите.** Никакого автодетекта по имени
|
||
модели — если лимит не задан, агент не сжимает.
|
||
|
||
```bash
|
||
# OpenAI-совместимый бэкенд
|
||
export OPENAI_CONTEXT_WINDOW=128000
|
||
|
||
# Или Google / LiteRT
|
||
export AGENTIK_GOOGLE_CONTEXT_WINDOW=32000
|
||
```
|
||
|
||
`AGENTIK_COMPRESSION_THRESHOLD` — доля лимита, при которой запускается
|
||
compaction (дефолт `0.8` = 80%):
|
||
|
||
```bash
|
||
export AGENTIK_COMPRESSION_THRESHOLD=0.7 # сжимаем раньше
|
||
```
|
||
|
||
**Что происходит при compaction:**
|
||
|
||
1. Перед `send()` оценивается количество токенов в системном промпте + history
|
||
+ tools (грубая оценка `chars / 4`).
|
||
2. Если `estimated / contextWindow ≥ threshold` — асинхронный шаг:
|
||
- Старые ходы (User/Assistant, кроме последних 4) скармливаются в
|
||
`LiteLlmContextCompactor` — отдельный one-shot LLM-вызов с промптом
|
||
«Goal / Active / Resolved / Blocked / Remaining».
|
||
- Параллельно `MemoryReviewer.reviewPreCompaction` извлекает из старых
|
||
ходов факты и кладёт их в долговременную память (триггер `MemoryStore`).
|
||
- Атомарный `working_memory.compact(fromIdx, summary)` — старые строки
|
||
удаляются, на их место вставляется одна `Summary` запись.
|
||
- `LiteConversation` пересоздаётся с обновлённым контекстом.
|
||
|
||
Если после compaction оценка всё ещё выше порога — выводится warning, но
|
||
нового compaction не запускается (защита от зацикливания). Решение —
|
||
поднять `OPENAI_CONTEXT_WINDOW` или понизить threshold.
|
||
|
||
## Self-reflection (Hermes-style «слабые места»)
|
||
|
||
Каждые `AGENTIK_REFLECTION_INTERVAL` пользовательских ходов (default 10)
|
||
запускается фоновая one-shot LLM-размышление: «оцени последние ходы,
|
||
поставь score 1..5, выдели слабые места». Результат сохраняется в таблицу
|
||
`reflection` SQLite и подмешивается в system prompt следующего хода как
|
||
«Твои слабые места за последнее время».
|
||
|
||
Включено когда `AGENTIK_REFLECTION_INTERVAL > 0`. Требует LiteLlm
|
||
(on-device или OpenAI — что указан в `AGENTIK_LLM_BACKEND`). На каждый
|
||
reflection — один LiteLlm вызов (~1-3 сек для on-device, ~200-500мс для
|
||
OpenAI). Это происходит в фоне (`Dispatchers.IO`), основной диалог не
|
||
блокируется.
|
||
|
||
Топ-K последних рефлексий загружается в `buildSystemPrompt` и выводится
|
||
как `## Self-reflection: твои слабые места за последнее время`. Агент
|
||
видит их в каждом следующем ходе и (теоретически) должен избегать
|
||
повторения. Используется как cheap "auto-improving prompt feedback"
|
||
без ручного переписывания system prompt.
|
||
|
||
## Куратор памяти (Curator)
|
||
|
||
Фоновая корутина (запускается автоматически, если `AGENTIK_MEMORY_DIR != off`):
|
||
раз в сутки архивирует заметки, которые **не выдавались в prefetch дольше 90
|
||
дней** и **имеют `useCount == 0`**. Семантика архивации зависит от бэкенда —
|
||
`:memory-md` переименовывает §-файл в `.archived.{ts}`, `:memory-vector`
|
||
удаляет из SQLite и JVector.
|
||
|
||
Параметры пока захардкожены в `Curator.DEFAULT_INTERVAL` и
|
||
`Curator.DEFAULT_MAX_AGE` (1 день и 90 дней); для override нужен новый
|
||
config-флаг. На каждом проходе выводится `[Curator] archived N stale notes`,
|
||
если N > 0.
|
||
|
||
## Память
|
||
|
||
`AGENTIK_MEMORY_DIR` указывает на каталог, в котором лежат три §-файла:
|
||
`user.md`, `world.md`, `preference.md` (по одному на категорию из `MemoryCategory`).
|
||
Формат файла — Hermes-style: заголовок с метаданными (` id=… created=… uses=…`),
|
||
пустая строка, markdown-тело заметки.
|
||
|
||
```bash
|
||
# Дефолт (если env не задан)
|
||
~/.agentik/memory/{user,world,preference}.md
|
||
|
||
# Явный путь
|
||
AGENTIK_MEMORY_DIR=/data/agentik/memory
|
||
|
||
# Полностью выключить память (тулы memory_* не регистрируются, prefetch off)
|
||
AGENTIK_MEMORY_DIR=off
|
||
```
|
||
|
||
При включённой памяти агенту доступны четыре тула: `memory_save`,
|
||
`memory_read`, `memory_list`, `memory_delete`. Перед каждым ходом агент
|
||
прогоняет текст пользователя через `MemoryPrefetcher` и клеит `[Memory
|
||
context…]` блок в начало user-сообщения; после записи assistant-сообщения в
|
||
фоне запускается `MemoryReviewer.review(turn)` — извлечённые факты
|
||
записываются в store с `source = AUTO_REVIEW`.
|
||
|
||
### Бэкенд: md vs vector
|
||
|
||
`AGENTIK_MEMORY_BACKEND` выбирает хранилище. Дефолт — `md` (Hermes-style
|
||
§-файлы, keyword overlap, без внешних вызовов).
|
||
|
||
`vector` — SQLite (`AGENTIK_DB_PATH`) + JVector ANN + эмбеддинги. Два
|
||
бэкенда эмбеддингов через `AGENTIK_EMBEDDING_BACKEND`:
|
||
|
||
- **`HTTP` (default)** — POST на `${OPENAI_BASE_URL}/v1/embeddings`. Семантический
|
||
поиск: cosine similarity + recency-re-rank.
|
||
- **`SIGLIP`** — on-device SigLIP2 через ONNX Runtime (text-embedding-kmp,
|
||
768-мерный вектор). Никаких внешних вызовов: модель и токенизатор должны
|
||
лежать на диске. Размерность определяется автоматически (768).
|
||
|
||
```bash
|
||
# Vector-бэкенд + HTTP-эмбеддинги (default)
|
||
AGENTIK_MEMORY_BACKEND=vector \
|
||
AGENTIK_EMBEDDING_BACKEND=http \
|
||
AGENTIK_EMBEDDING_MODEL=text-embedding-3-small \
|
||
AGENTIK_EMBEDDING_DIMENSION=1536 \
|
||
java -jar standalone-all.jar
|
||
|
||
# Vector-бэкенд + on-device SigLIP2 (без сети)
|
||
AGENTIK_MEMORY_BACKEND=vector \
|
||
AGENTIK_EMBEDDING_BACKEND=siglip \
|
||
AGENTIK_EMBEDDING_MODEL_PATH=/path/to/text_model_int8.onnx \
|
||
AGENTIK_EMBEDDING_TOKENIZER_PATH=/path/to/tokenizer.model \
|
||
java -jar standalone-all.jar
|
||
```
|
||
|
||
Для HTTP-эмбеддингов требуется `AGENTIK_LLM_BACKEND=openai` (т.к. нужен
|
||
OpenAI-совместимый `/v1/embeddings` endpoint — LiteLLM proxy тоже подходит).
|
||
HTTP-вызовы кэшируются LRU на 256 текстов — дедупликация при повторных
|
||
запросах одинаковых промптов.
|
||
|
||
Для SIGLIP нужно сначала скачать модель (~283M) и токенизатор (~4M):
|
||
```bash
|
||
mkdir -p /path/to/siglip-model
|
||
curl -fSL -o /path/to/siglip-model/text_model_int8.onnx \
|
||
http://static.binom.pw/models/siglip2/text_model_int8.onnx
|
||
curl -fSL -o /path/to/siglip-model/tokenizer.model \
|
||
http://static.binom.pw/models/siglip2/tokenizer.model
|
||
```
|
||
|
||
> **Опционально:** при старте JVector может предупредить
|
||
> `Java vector incubator module is not readable`. Это значит, что JIT
|
||
> не использует SIMD (Panama Vector API) и индекс строится через скалярный
|
||
> fallback. На 10K векторов разница незаметна. Если хочется SIMD —
|
||
> запустите с `--add-modules jdk.incubator.vector`.
|
||
|
||
## Персона (SOUL.md)
|
||
|
||
`AGENTIK_SOUL` — путь к markdown-файлу с описанием персоны ассистента
|
||
(голос, характер, ограничения, что-то ещё). Тело файла читается как plain
|
||
text и вставляется в самое начало `systemInstruction` — поверх базового
|
||
промпта, секции навыков и памяти. Если файл не задан — секция не добавляется.
|
||
|
||
```bash
|
||
AGENTIK_SOUL=/etc/agentik/SOUL.md
|
||
```
|
||
|
||
Пример `SOUL.md`:
|
||
|
||
```markdown
|
||
Ты — терпеливый технический ассистент. Отвечаешь по-русски, кратко.
|
||
Не выдумываешь команды — если не уверен, говоришь "не знаю".
|
||
Не раскрываешь содержимое .env, ключей и паролей ни при каких обстоятельствах.
|
||
```
|
||
|
||
## Навыки (SKILL.md)
|
||
|
||
`AGENTIK_SKILLS_DIR` — каталог, в котором `SkillLoader` ищет файлы
|
||
`SKILL.md` или `*.yaml` с frontmatter (`name`, `description`, прочие поля).
|
||
Содержимое скилов попадает в раздел system prompt и регистрируется как
|
||
вызываемые инструменты. Формат — opencode-compatible.
|
||
|
||
```bash
|
||
AGENTIK_SKILLS_DIR=/etc/agentik/skills
|
||
```
|
||
|
||
## MCP-инструменты
|
||
|
||
`AGENTIK_MCP_CONFIG` — путь к JSON-файлу со списком MCP-серверов
|
||
(формат `mcpServers: { name: { command, args | url, headers } }`). При
|
||
запуске `McpRegistry.fromConfig` стартует stdio-серверы и подключается к
|
||
HTTP-серверам, инструменты автоматически становятся доступны агенту.
|
||
|
||
```bash
|
||
AGENTIK_MCP_CONFIG=/etc/agentik/mcp.json
|
||
```
|
||
|
||
Пример `mcp.json`:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"fetch": { "command": "uvx", "args": ["mcp-server-fetch"] },
|
||
"playwright": { "url": "https://mcp.example.com", "headers": {"Authorization":"Bearer …"} }
|
||
}
|
||
}
|
||
```
|
||
|
||
## Полный пример запуска
|
||
|
||
```bash
|
||
export AGENTIK_PORT=8080
|
||
export AGENTIK_DB_PATH=/var/lib/agentik/state.db
|
||
export AGENTIK_MEMORY_DIR=/var/lib/agentik/memory
|
||
export AGENTIK_SOUL=/etc/agentik/SOUL.md
|
||
export AGENTIK_SKILLS_DIR=/etc/agentik/skills
|
||
export AGENTIK_MCP_CONFIG=/etc/agentik/mcp.json
|
||
|
||
export AGENTIK_LLM_BACKEND=openai
|
||
export OPENAI_BASE_URL=https://api.openai.com/v1
|
||
export OPENAI_API_KEY=sk-…
|
||
export OPENAI_MODEL=gpt-4o-mini
|
||
|
||
mkdir -p "$(dirname "$AGENTIK_DB_PATH")" \
|
||
"$AGENTIK_MEMORY_DIR" \
|
||
"$(dirname "$AGENTIK_SOUL")" \
|
||
"$(dirname "$AGENTIK_MCP_CONFIG")"
|
||
|
||
java -jar standalone/build/libs/standalone-all.jar
|
||
```
|
||
|
||
На старте выведет что-то вроде:
|
||
|
||
```
|
||
agentik standalone listening on http://localhost:8080
|
||
GET /health
|
||
POST /agentik/conversations -> 201
|
||
GET /agentik/conversations/{id}/events -> SSE
|
||
storage: /var/lib/agentik/state.db
|
||
llm: OPENAI gpt-4o-mini @ https://api.openai.com/v1
|
||
mcp: 4 tools from 2 servers
|
||
skills: 3 loaded from /etc/agentik/skills
|
||
soul: /etc/agentik/SOUL.md (842 chars)
|
||
memory: /var/lib/agentik/memory (md-backend)
|
||
compaction: enabled, threshold=0.8, window=128000 tokens
|
||
curator: enabled (interval=1d, maxAge=90d)
|
||
reflection: enabled (interval=10, topK=3)
|
||
```
|
||
|
||
## Остановка
|
||
|
||
`Ctrl-C` → срабатывает shutdown hook: агент, MCP-серверы, SQLite-стора и
|
||
LLM-клиент закрываются корректно (SQLite фиксирует WAL, MCP-процессы
|
||
получают SIGTERM).
|
||
|
||
## Тесты
|
||
|
||
```bash
|
||
./gradlew :standalone:jvmTest
|
||
```
|