Alicorn (Pegas): спецификация, архитектура, roadmap

.gitignore

@@ -0,0 +1,38 @@
+# Rust
+/target/
+**/target/
+Cargo.lock  # для библиотек; для бинарников можно коммитить
+
+# Базы данных
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+
+# Логи
+*.log
+logs/
+
+# Конфиги с секретами
+.env
+.env.local
+*.pem
+*.key
+
+# Кэш
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Строки
+*.strings

ARCHITECTURE.md

@@ -0,0 +1,163 @@
+# Alicorn — архитектурные решения
+
+Сводка ключевых архитектурных решений (ADR-формат). Основано на спецификации в Outline (ветка «autonom agent alikorn»).
+
+---
+
+## 1. Разделение «Модель предлагает — Runtime располагает»
+
+**Решение:** LLM (Ornith) только предлагает план в типизированном DSL. Runtime (Rust) детерминированно исполняет.
+
+**Почему:**
+- LLM на локальной модели даёт 20–150 t/s, слабый контекст, частые ошибки. Интерпретация плана внутри LLM = удвоение этих проблем.
+- Detерминированный runtime даёт скорость (без интерпретации) и точность (повторяемость).
+
+**Альтернативы:**
+- LangChain/CrewAI/AutoGen — предполагают облачную LLM (дешёвый контекст, редкие ошибки). Не подходят под локальные модели.
+- Чистый ReAct внутри LLM — «задыхается» через 5–10 шагов.
+
+**Риски:** DSL-ограниченность (модель не может делать всё что угодно, только то, что умеет runtime). Компромисс ради детерминизма.
+
+---
+
+## 2. Append-only журнал (SQLite WAL) как источник правды
+
+**Решение:** Все входы/выходы (llm.request/response, tool.call/result, anvil.check) пишутся в append-only журнал. Состояние = свёртка журнала.
+
+**Почему:**
+- Event Sourcing даёт replay «байт-в-байт».
+- Журнал = аудит и отладка.
+- Именно журнал, а не промежуточные рассуждения (экономия, приватность).
+
+**Риски:** размер журнала; нужна ротация/компрессия. FULL sync для durability (влияет на latency).
+
+---
+
+## 3. Детерминизм и replay
+
+**Решение:** Состояние = детерминированная свёртка журнала через reducer. Replay верифицируется в CI. Exactly-once через Transactional Outbox + Idempotency Key + Saga.
+
+**Почему:** локальные модели non-deterministic → без детерминированного executor'а нельзя гарантировать повторяемость.
+
+**Альтернативы:**
+- Хранение snapshot'ов состояния — дороже, сложно мержить.
+- Pure functional state — сложно интегрировать с инструментами.
+
+---
+
+## 4. Pegas Memory: PostgreSQL + pgvector + Apache AGE
+
+**Решение:** Единое хранилище — текст, векторы, граф, метаданные в Postgres.
+
+**Почему:**
+- pgvector = семантический поиск (检索增强).
+- AGE = граф связей (сущности, концепты).
+- Один движок вместо трёх БД.
+
+**Риски:** AGE (PostgreSQL extension для графов) — молодая технология, зрелость ниже, чем у Neo4j.
+
+**Альтернативы:**
+- Отдельный граф-сервер (Neo4j) — больше инфраструктуры.
+- Qdrant + отдельная graph DB — сложнее поддержка.
+
+---
+
+## 5. Anvil: экономика доверия через смарт-контракты
+
+**Решение:** Агент начинает с минимальными правами. Успешное действие → +репутация → расширение прав. Контракты: PermissionRegistry, ReputationOracle, BudgetController, CuriosityReward.
+
+**Почему:**
+- Безопасность: агент не может сразу получить все права.
+- Прозрачность: всё в блокчейне.
+- Мотивация: curiosity как reward.
+
+**Риски:** стоимость транзакций; сложность интеграции с локальным runtime.
+
+**Альтернативы:**
+- Hardcoded权限-система — проще, но не масштабируема.
+- Policy-based (OPA) — не такой «экономический».
+
+---
+
+## 6. World Model (V-JEPA 2 / Agentic-JEPA)
+
+**Решение:** Planner генерирует кандидатов → World Model предсказывает следующее состояние → агент выбирает с наивысшим сходством → верификация после выполнения.
+
+**Почему:** локальные модели плохо планируют на много шагов вперёд. World Model даёт «представление о мире» без реального действия.
+
+**Меры надёжности:**
+- Планирование на один шаг (k=1).
+- Калибровка доверия.
+
+**Риски:** V-JEPA 2 — тяжёлая модель; локальный инференс может быть bottleneck.
+
+**Альтернативы:**
+- Chain-of-Thought — проще, но без «представления о мире».
+- Реальные действия с откатом — дороже.
+
+---
+
+## 7. Pegas Core: Rust (dsh Harness)
+
+**Решение:** Ядро на Rust. Роли: Planner (Ornith 1.5 A3B), Executor (Spark-X2.5-4B), Researcher (Nanbeige4.1-3B), Decision (Clef-Flash).
+
+**Почему:**
+- Rust = скорость + безопасность памяти + детерминизм.
+- Разделение ролей = изоляция ошибок.
+
+**Альтернативы:**
+- Python (Hermes) — быстрее разработка, но медленнее и non-deterministic.
+- Go — быстрее Python, но Rust лучше для системного кода.
+
+---
+
+## 8. Observability: OTEL + ClickHouse + Grafana
+
+**Решение:** Трассировка, стоимость, качество через OpenTelemetry → ClickHouse → Grafana.
+
+**Почему:**
+- Наблюдаемость критична для автономного агента.
+- ClickHouse = аналитика больших логов.
+
+**Альтернативы:**
+- Prometheus + Loki — сложнее агрегация.
+- Локальные метрики — недостаточно для аудита.
+
+---
+
+## 9. MVP-стратегия
+
+**Решение:** MVP = ReAct-цикл (Rust) + одна LLM (Ornith) + один MCP (Knowledge) + Postgres+pgvector (без AGE) + простой UI + heartbeat.
+
+**Что НЕ в MVP:** мотивация/драйвы, Anvil, World Model, граф (AGE), мультиагентность, KTL, ClickHouse/Grafana, сложные метрики.
+
+**План:** Нед 1 — ядро+LLM+журнал; Нед 2 — MCP+база знаний; Нед 3 — UI+heartbeat; Нед 4 — отладка+GitHub.
+
+**Почему:** MVP должен доказать базовый цикл (задача → LLM → tool → ответ), а не всю архитектуру.
+
+---
+
+## 10. Связь с spark-mind (Animus)
+
+**Решение:** spark-mind = первый слой Alicorn (чаты + память). Alicorn = полная архитектура.
+
+**Почему:** spark-midal уже работает (персона, память, дашборд на :1337). Alicorn строится на этом фундаменте, но с детерминированным runtime'ом.
+
+**Риски:** spark-mind non-deterministic (Python); Alicorn должен быть переписан на Rust.
+
+---
+
+## Статус решений
+
+| # | Решение | Статус |
+|---|---------|--------|
+| 1 | Model proposes — Runtime disposes | Принято |
+| 2 | Append-only журнал | Принято |
+| 3 | Детерминизм + replay | Принято |
+| 4 | PostgreSQL + pgvector + AGE | Принято (AGE — риск зрелости) |
+| 5 | Anvil: экономика доверия | Принято (для full-версии) |
+| 6 | World Model (V-JEPA 2) | Принято (для full-версии) |
+| 7 | Rust-ядро | Принято |
+| 8 | Observability (OTEL+ClickHouse) | Принято (для full-версии) |
+| 9 | MVP-стратегия | Принято |
+| 10 | Связь с spark-mind | Принято |

README.md

@@ -0,0 +1,60 @@
+# Alicorn Agent (Pegas)
+
+Автономный агент-исследователь для **локальных** LLM. Рабочее имя — **Pegas**.
+
+> Alicorn = агентский runtime, спроектированный для локальных моделей, а не адаптированный под них.
+
+## Ключевой принцип: «Модель предлагает — Runtime располагает»
+
+- **LLM (Ornith)** — только предлагает план в типизированном DSL. Не мутирует состояние, не вызывает инструменты напрямую.
+- **Runtime (Rust)** — детерминированно исполняет план. Дает **скорость** (без интерпретации) и **точность** (каждое исполнение байт-в-байт из журнала).
+
+## Почему это нужно
+
+Существующие фреймворки (LangChain, CrewAI, AutoGen, Hermes) предполагают LLM = облачный API (дешёвый контекст, 200+ t/s, редкие ошибки). Локальные модели — наоборот: слабый контекст, 20–150 t/s, частые ошибки. Агент «задыхается» через 5–10 шагов.
+
+Alicorn решает это через:
+1. **Детерминированный Rust-выполнитель** — без интерпретации, скорость и воспроизводимость.
+2. **Append-only журнал (SQLite WAL)** — источник правды и replay.
+3. **Anvil** — экономика доверия (права, репутация, бюджет, любопытство) через смарт-контракты.
+4. **World Model (V-JEPA 2)** — симуляция последствий до реального действия.
+5. **Pegas Memory** — единое хранилище (Postgres + pgvector + Apache AGE).
+
+## Архитектура (7 слоёв)
+
+| # | Слой | Технология | Роль |
+|---|------|-----------|------|
+| 1 | Pegas Memory | PostgreSQL + pgvector + Apache AGE | Текст, векторы, граф, метаданные |
+| 2 | KTL | MinerU, Segnatura, gresmcp, mammoth + VLM Qwen3-VL | PDF/EPUB/Web → структурированные знания |
+| 3 | MCP-серверы | Rust (mcport/V.E.L.O.C.I.T.Y.) | Knowledge, Anvil, Tool, World Model |
+| 4 | Anvil | Solidity + Foundry | Права, репутация, бюджет, любопытство |
+| 5 | Pegas Core | Rust (dsh Harness) | Planner, Executor, Researcher, Decision |
+| 6 | World Model | V-JEPA 2 / Agentic-JEPA (wm-mcp) | Симуляция последствий |
+| 7 | Observability | OTEL + ClickHouse + Grafana | Трассировка, стоимость, качество |
+
+**Допы:** append-only журнал (SQLite WAL) = source of truth + replay; Dragonfly/Redis = кэш сессий; NATS JetStream = event bus.
+
+## Детерминизм и replay
+
+- **Append-only журнал** (SQLite WAL + FULL sync) — source of truth.
+- Пишутся входы/выходы (llm.request/response, tool.call/result, anvil.check), не промежуточные рассуждения.
+- **Event Sourcing**: состояние = детерминированная свёртка журнала через reducer.
+- Replay — **байт-в-байт**, верификация в CI.
+- Exactly-once через Transactional Outbox + Idempotency Key + Saga.
+
+## Внутренние драйвы
+
+Не on-chain: любопытство, компетентность, автономность, связность.
+
+## Связь с другими проектами
+
+- **spark-mind / «Animus»** — локальный чат-бот (персона, память, дашборд). Предок Alicorn.
+- **Outline** (docs.qw4.ru) — вики, источник спецификации.
+
+## Стек
+
+Ornith 1.5 A3B, Spark-X2.5-4B, Nanbeige4.1-3B, Clef-Flash, bge-m3 (эмбеддинги), PostgreSQL, pgvector, Apache AGE, V-JEPA 2, Rust.
+
+## Статус
+
+Архитектурная спецификация зафиксирована. MVP-код — в разработке (см. ROADMAP.md).

ROADMAP.md

@@ -0,0 +1,60 @@
+# Alicorn — Roadmap
+
+## Фаза 0: Спецификация (завершена)
+- [x] Изучение концепций и архитектуры в Outline (ветка «autonom agent alikorn»)
+- [x] Фиксация в Gitea (README + ARCHITECTURE.md)
+
+## Фаза 1: MVP (1 месяц)
+
+### Неделя 1 — Ядро + LLM + журнал
+- [ ] Rust-проект (Cargo), ReAct-цикл: задача → LLM → tool → ответ
+- [ ] Приёмник LLM (Ornith 1.5 A3B через llama.cpp / Ollama API)
+- [ ] Append-only журнал (SQLite WAL)
+- [ ] Типизированный DSL-план
+
+### Неделя 2 — MCP + база знаний
+- [ ] Один MCP-сервер (Knowledge: search + get_entity)
+- [ ] Postgres + pgvector (без AGE)
+- [ ] Интеграция журнала с MCP
+
+### Неделя 3 — UI + heartbeat
+- [ ] Простой UI (список задач, статус)
+- [ ] Heartbeat по cron
+- [ ] Базовая статистика
+
+### Неделя 4 — Отладка + GitHub
+- [ ] Replay-верификация
+- [ ] Exactly-once (Idempotency + Saga)
+- [ ] Документация, первый публичный коммит
+
+## Фаза 2: Полная версия (1 год)
+
+### Q1 — Anvil
+- [ ] Smart-контракты (PermissionRegistry, ReputationOracle, BudgetController, CuriosityReward)
+- [ ] Экономика доверия (права → репутация → расширение)
+- [ ] Foundry-тесты
+
+### Q2 — World Model
+- [ ] V-JEPA 2 / Agentic-JEPA интеграция
+- [ ] Предсказание состояний (k=1)
+- [ ] Калибровка доверия
+
+### Q3 — Расширение ролей
+- [ ] Executor (Spark-X2.5-4B)
+- [ ] Researcher (Nanbeige4.1-3B)
+- [ ] Decision (Clef-Flash)
+
+### Q4 — Наблюдаемость + KTL
+- [ ] OTEL + ClickHouse + Grafana
+- [ ] Knowledge Translation Layer (MinerU, Segnatura, VLM)
+- [ ] Apache AGE (граф)
+
+## Критические риски
+
+| Риск | Вероятность | Влияние | Митигация |
+|------|------------|---------|-----------|
+| V-JEPA 2 bottleneck (локальный инференс) | Средняя | Высокое | Кэш, квантизация |
+| AGE зрелость | Средняя | Среднее | Резервный Neo4j |
+| Размер журнала | Высокая | Среднее | Ротация, компрессия |
+| Non-determinism LLM | Высокая | Высокое | Detерминированный executor + replay |
+| Стоимость Anvil транзакций | Низкая | Среднее | L2 / batch |