Научный интеллектуальный слой

lean-ctx выходит за рамки сопоставления шаблонов. Шесть алгоритмов из теории информации, теории графов и статистической механики работают совместно, чтобы решить, что сохранить, что удалить и куда разместить - всё автоматически, всё локально, без настройки.

Эти алгоритмы составляют автономный интеллектуальный слой. Они активируются при каждом вызове ctx_read, ctx_preload и ctx_overview - вы никогда не вызываете их напрямую.

Как слои взаимодействуют

Оценка предиктивной неожиданности

Традиционные фильтры сжатия используют энтропию Шеннона по необработанным символам, что расценивает aaaa и import как одинаково предсказуемые. Предиктивная неожиданность вместо этого измеряет кросс-энтропию относительно частоты BPE-токенов - насколько каждая строка неожиданна для токенизатора LLM.

Как это работает

1. Каждая строка токенизируется с использованием o200k_base (токенизатор GPT-4o / Claude).
2. Для каждого токена закон Ципфа оценивает ожидаемую частоту на основе ранга.
3. Вычисляется кросс-энтропия: строки с частыми токенами (шаблонный код) получают низкую оценку; строки с редкими токенами (сложная логика) - высокую.
4. Строки ниже порога неожиданности являются кандидатами на удаление при агрессивном сжатии.

Пример

// Low surprise (boilerplate) - candidate for removal:
return Ok(());                    // surprise: 0.12
use std::collections::HashMap;   // surprise: 0.18

// High surprise (unique logic) - always preserved:
let decay = (-alpha * dist as f64).exp();   // surprise: 0.89
scores[j] += heat[i] * decay / degree;      // surprise: 0.94

Почему это важно

Предиктивная неожиданность удаляет на 15–30% больше шаблонного кода, чем символьная энтропия, сохраняя при этом сложную логику. Метод напрямую моделирует то, что LLM считает «информативным», поскольку использует тот же словарь BPE.

Распространение спектральной релевантности

Когда вы просите lean-ctx предзагрузить контекст для задачи, необходимо решить, какие файлы важны. Простое сопоставление по ключевым словам находит только файлы, упоминающие ваши поисковые термины. Spectral Relevance находит файлы, структурно связанные с релевантными - даже без общих ключевых слов.

Как это работает

На графе зависимостей проекта запускаются два алгоритма:

1. Диффузия тепла - Файлы-источники, соответствующие описанию задачи, получают начальное «тепло». Тепло распространяется по рёбрам импортов с экспоненциальным затуханием, моделируя поток информации через кодовую базу.
2. Центральность PageRank - Файлы, импортируемые многими другими файлами, получают более высокие оценки центральности. Это выявляет структурные узлы (например, db.ts, импортируемый 20 модулями).

Итоговая оценка релевантности объединяет оба показателя: 0.7 × heat + 0.3 × pagerank. Файлы ниже порога исключаются из предзагрузки.

Пример

Task: "fix authentication bug"

Direct matches:       auth.ts, login.ts
Heat diffusion adds:  middleware.ts (imports auth.ts)
                      session.ts (imported by auth.ts)
PageRank promotes:    db.ts (imported by 18 files - structural hub)

Result: 5 files preloaded instead of 2, covering the full blast radius.

Нулевая настройка

Граф зависимостей строится автоматически при первом использовании через load_or_build(). Не нужно выполнять ctx_graph build - всё работает само.

Распределение контекста по Больцману

После того как Spectral Relevance выбирает релевантные файлы, каждому файлу нужен бюджет токенов. Наивные подходы распределяют бюджет поровну или сортируют по релевантности. Boltzmann Allocation использует статистическую механику для оптимального распределения токенов.

Как это работает

1. Каждый файл имеет оценку релевантности E_i от Spectral Relevance.
2. Параметр температуры β определяется задачей: конкретные задачи ("исправить баг авторизации в login.ts") дают низкую температуру (резкое распределение в пользу топ-файлов); широкие задачи ("отрефакторить кодовую базу") дают высокую температуру (равномерное распределение).
3. Бюджеты токенов следуют распределению Больцмана: budgeti = total × (eβ·Ei / Σ eβ·Ej)
4. Применяются минимальные и максимальные бюджеты (128–4096 токенов на файл), а режим сжатия (full, map, signatures) выбирается на основе выделенного бюджета.

Пример

Task: "fix the JWT validation in auth middleware"
Task specificity: 0.85 (specific) → β = 4.2

File            | Relevance | Budget | Mode
auth.ts         |      0.92 |  3,200 | full
middleware.ts   |      0.78 |  1,800 | full
session.ts      |      0.45 |    420 | map
db.ts           |      0.31 |    180 | signatures
routes.ts       |      0.22 |    128 | signatures
                                ─────
Total:                         5,728 tokens (within 8,000 budget)

Reciprocal Rank Fusion (RRF) Cache Eviction

lean-ctx uses Reciprocal Rank Fusion for cache eviction decisions, replacing the earlier Boltzmann-inspired weighted scoring. RRF handles incomparable signals (time in seconds, frequency as counts, size in tokens) without arbitrary weight tuning.

Formula: RRF(d) = Σ 1/(K + ranki(d)) - entries with the lowest fused score are evicted first. This produces monotonically correct ordering regardless of signal magnitude differences.

Семантическая разбивка с мостами внимания

LLM страдают от проблемы «Потерянное в середине»: информация в начале и конце контекста получает больше внимания, чем содержимое в середине. Семантическая разбивка перестраивает вывод для минимизации потери информации.

Как это работает

1. Обнаружение блоков - Строки исходного кода группируются в семантические блоки (функции, типы, импорты, свободная логика) на основе эвристик границ AST.
2. Упорядочивание по релевантности - Блоки, соответствующие текущей задаче, перемещаются наверх (позиция высокого внимания). Остальные блоки упорядочиваются по приоритету типа.
3. Мосты внимания - Между блоками lean-ctx вставляет минимальные маркеры-мосты (---), чтобы LLM распознавала структурные границы.
4. Хвостовые якоря - Последние 2–3 строки блока с наивысшим приоритетом повторяются в самом конце вывода, используя эффект недавности для критически важной информации.

Пример

// Without chunking (flat output):
import { db } from '../pages/docs/db';
import { hash } from '../pages/docs/crypto';
const MAX_RETRIES = 3;
export function createUser(...) { ... }
export function validateToken(...) { ... }    ← lost in the middle
export function deleteUser(...) { ... }

// With semantic chunking (task: "fix token validation"):
export function validateToken(...) { ... }    ← promoted to top
---
export function createUser(...) { ... }
export function deleteUser(...) { ... }
---
import { db } from '../pages/docs/db';
const MAX_RETRIES = 3;
---
// anchor: validateToken signature                ← tail anchor

MMR-дедупликация

Когда в контекст загружается несколько файлов, они часто содержат дублирующиеся импорты, общий шаблонный код или очень похожие паттерны. Maximum Marginal Relevance (MMR) устраняет эту избыточность, сохраняя уникальную информацию.

Как это работает

1. Для каждой строки вычисляется биграммное сходство Жаккара со всеми ранее отобранными строками ("набор покрытия").
2. Оценка MMR балансирует между релевантностью и избыточностью: MMR(l) = λ × relevance(l) - (1 - λ) × max_similarity(l, selected)
3. Строки с MMR < 0 подавляются - они добавляют больше избыточности, чем информации. Параметр λ по умолчанию равен 0.7 (в пользу релевантности над разнообразием).

Влияние

При типичной предзагрузке нескольких файлов MMR удаляет 10–25% избыточного контента - в основном общие импорты и повторяющиеся шаблоны утилит.

BPE-оптимизация токенов

После отбора и упорядочивания всего контента финальный проход оптимизирует текст под BPE-токенизатор LLM. Небольшие изменения форматирования могут значительно сократить количество токенов без изменения семантики.

Правила оптимизации

Как это работает

Каждое правило - это простая строковая замена, применяемая построчно после всех остальных этапов сжатия. Правила выведены из анализа границ BPE-токенов - они нацелены на паттерны, где токенизатор создаёт избыточное количество токенов для семантически эквивалентного текста.

Влияние

BPE-оптимизация обычно экономит дополнительные 3–8% токенов на уже сжатом выводе. Экономия накапливается по файлам и наиболее значительна для многословных языков (TypeScript, Java, C#).

Проверка эффекта

Запустите lean-ctx benchmark run в вашем проекте, чтобы измерить совокупный эффект всех шести алгоритмов. Отчёт бенчмарка показывает экономию токенов по каждому файлу, оценки сохранения (AST, идентификаторы, строки) и общие коэффициенты сжатия.

$ lean-ctx benchmark run
──────────────────────────────────────────
BENCHMARK - /Users/you/project
──────────────────────────────────────────
Files:       143
Total:       285,401 → 42,810 tokens (85% reduction)
Avg/file:    1,997 → 300 tokens

Preservation:
  AST:         98.2%
  Identifiers: 97.4%
  Lines:       96.1%

Mode breakdown:
  full:        68% of files
  map:         22% of files
  signatures:   8% of files
  aggressive:   2% of files

Структурированное распознавание намерений

lean-ctx классифицирует каждое взаимодействие в StructuredIntent - слотовое представление, содержащее тип задачи, уверенность, целевые файлы, область, подсказку языка, срочность и глагол действия. Это управляет всеми последующими решениями: какой режим сжатия использовать, как маршрутизировать контекст и что приоритизировать.

Распознаются 9 типов задач: Explore, Generate, FixBug, Refactor, Test, Review, Config, Deploy и Document. Каждый тип запускает разные стратегии сжатия и маршрутизации контекста.

IntentScope варьируется от SingleFile через MultiFile и CrossModule до ProjectWide - определяя, насколько широко собирается контекст.

Как это работает

Сжатие адаптируется по намерению: задачи FixBug приоритизируют строки ошибок и тестовые файлы через фильтр Information Bottleneck, задачи Explore используют лёгкую очистку для сохранения структуры, а задачи Generate фокусируются на сигнатурах и типах.

Автоматический селектор режима ctx_read использует активный тип задачи для уточнения решения - выбирая режим task для исправления ошибок в больших файлах, режим map для исследования и режим signatures для задач документирования.

Пример

Query: "fix the NaN bug in entropy.rs"

StructuredIntent:
  task_type:    FixBug (confidence: 0.95)
  targets:      ["entropy.rs"]
  scope:        SingleFile
  language:     Rust
  urgency:      0.8
  action_verb:  "fix"

→ Compression: Information Bottleneck filter (error lines boosted)
→ Mode:        task (error-focused extraction)
→ Suggestions: tests/entropy_test.rs (deficit detection)

Архитектура конвейера контекста

Конвейер контекста обрабатывает информацию через шесть отдельных слоёв: Input → Intent → Relevance → Compression → Translation → Delivery. Каждый слой имеет определённые контракты (типы ввода/вывода) и генерирует метрики.

Как это работает

Input → Intent → Relevance → Compression → Terse Engine → Delivery
  │        │          │            │              │              │
  │        │          │            │              │              └─ Final output to LLM
  │        │          │            │              └─ 4-layer terse pipeline (see below)
  │        │          │            └─ AST-aware compression per intent
  │        │          └─ Graph heat + relevance scoring
  │        └─ StructuredIntent classification
  └─ Raw file content / shell output

Метрики по слоям отслеживают входные токены, выходные токены, степень сжатия и время обработки. В совокупности за сессию они показывают, где происходит наибольшая экономия и какие слои являются узкими местами.

4-Layer Terse Engine

The terse engine applies four composable compression layers, controlled by compression_level (Off / Lite / Standard / Max). Each layer is independently verified by Lean4 proofs (TerseQuality, TerseEngine — part of 82 total theorems).

Реестр контекста и управление давлением

ContextLedger отслеживает каждый файл, отправленный ИИ: путь, режим сжатия, исходные токены, отправленные токены и метку времени. Он рассчитывает использование контекстного окна и давление в реальном времени.

Как это работает

Три уровня давления: None (менее 70% использования), Compress (70–90%) и Evict (более 90%). На каждом уровне система предпринимает разные действия - понижая режимы сжатия для менее релевантных файлов или предлагая вытеснение.

Пример

Context Window: 128,000 tokens
Loaded: 89,600 tokens (70% utilization)
Pressure: None → safe

After loading 3 more files:
Loaded: 115,200 tokens (90% utilization)
Pressure: Compress → downgrade non-target files

Re-Injection Plan:
  utils.rs:    full → signatures  (save 2,400 tokens)
  helpers.rs:  full → map         (save 1,800 tokens)
  config.rs:   full → signatures  (save 1,200 tokens)
  Protected:   auth.rs, login.ts  (target files)

Обнаружение дефицита контекста выявляет недостающую информацию: если задача исправления ошибки нацелена на auth.rs, но тестовый файл не загружен, система предлагает tests/auth_test.rs. Для задач конфигурации рекомендует Cargo.toml, .env или Dockerfile.

Умная реинъекция генерирует план освобождения бюджета контекста путём понижения нецелевых файлов (напр. переключение с режима full на signatures) при защите файлов, критичных для текущего намерения.

Мульти-агентный интеллект

Когда несколько ИИ-агентов сотрудничают (напр. кодер и ревьюер), lean-ctx обеспечивает структурированные передачи, глубину контекста на основе ролей и межагентный обмен знаниями.

Как это работает

HandoffPackage объединяет текущий реестр сессии, структурированное намерение и снимок контекста в единую передаваемую единицу - чтобы принимающий агент начинал с полным ситуационным осознанием, а не с чистого листа.

Распознаются семь ролей агентов: Coder, Reviewer, Planner, Explorer, Debugger, Tester и Orchestrator. Каждый получает адаптированную ContextDepthConfig - Кодер получает больше полных чтений файлов, Ревьюер больше сигнатур, Исследователь более широкий контекст графа.

Пример

Agent "coder-1" (role: Coder):
  max_files_full: 8
  preferred_mode: full
  context_budget: 80%

Agent "reviewer-1" (role: Reviewer):
  max_files_full: 3
  preferred_mode: signatures
  context_budget: 60%

Shared Knowledge:
  K:discovery:auth_bug = "null check missing in line 42"
  K:decision:fix_approach = "add Option<T> wrapper"
  → reviewer-1 inherits these facts without re-reading files

Межагентный обмен знаниями позволяет агентам обмениваться структурированными фактами (напр. "discovery:auth_bug=отсутствует проверка null в строке 42") через общий блокнот. Новые агенты наследуют релевантные знания без необходимости их повторного обнаружения.

Community Detection (Louvain)

The core::community module clusters files by their dependency graph using the Louvain algorithm. This groups tightly-coupled files into communities, enabling more intelligent context selection — files in the same community as your target are prioritized for preloading and receive higher relevance scores during task-driven reads.

Code Smell Detection

The ctx_smells tool detects long functions, deep nesting, and high cyclomatic complexity using the core::smells module. Detected smells are scored with graph-enriched weighting — files with high PageRank or many dependents receive amplified smell scores, surfacing maintenance hotspots that have the widest blast radius across the codebase.

См. также

• Автономные интеллектуальные инструменты - инструменты, использующие эти алгоритмы
• Движок tree-sitter - парсинг AST для 18 языков
• Конфигурация - настройка пороговых значений и параметров автономии
• Benchmark - измерение вашей экономии