Надежные системы из ненадежных компонентов

Архитектура Partitura: Reactive Spreadsheet Blackboard

В центре системы находится Reactive Blackboard (Реактивная Доска).
В отличие от классических Blackboard-систем 80-х, где данные лежали неструктурированной кучей, наша Доска структурирована как Электронная Таблица (Spreadsheet).

Три кита:

1. Ячейки как Типизированные Контейнеры.
   Ячейка — это не просто место для текста. Это слот с жестким контрактом. Если ячейка имеет тип PythonCode, в неё физически нельзя записать Markdown или JSON с ошибкой. Это гарантирует Type Safety на уровне архитектуры.
2. Агенты как «Тяжелые Формулы».
   В Excel формула вычисляется мгновенно. В Партитуре «формула» — это Асинхронная Трансформация.
   • Вход: Значения из зависимых ячеек (Spec).
   • Процесс: Вызов LLM-агента (дорого, долго, стохастично).
   • Выход: Значение текущей ячейки (Code).
3. Реактивность.
   Система сама следит за актуальностью. Изменение Ячейки А (ТЗ) автоматически помечает зависимую Ячейку Б (Код) статусом DIRTY (Требует обновления). Человеку не нужно «перезапускать пайплайн», система сама стремится к согласованному состоянию.

Реактивная Доска

Это Источник Истины.

• Топология: Ориентированный ациклический граф (DAG), где узлы — это Ячейки.
• Ячейка: Атомарная единица состояния.
  • Value: Полезная нагрузка (артефакт).
  • Schema: Валидатор (Pydantic/JSON Schema). Ячейка отвергает невалидные данные.
  • Status: Жизненный цикл (EMPTY → DIRTY → PROCESSING → VALID / ERROR).
  • History: Иммутабельный лог изменений (Git-like).
  • Meta: Бюджет, тайминги, использованная модель.

Агентный Рантайм

Это Вычислительные мощности. Агенты здесь — это Stateless Workers (функции без памяти).

• Принцип: Агент не хранит историю общения. Вся история и контекст каждый раз загружаются из Ячеек Доски.
• Триггер: Агент просыпается только тогда, когда Ячейка переходит в статус DIRTY.
• Специализация:
  • Architect: Text → Scaffold.
  • Developer: Scaffold → Code.
  • Critic: Code + Spec → Review.

Механика Синхронизации

Это «Движок правил», который крутит цикл.

• Dependency Engine: Распространяет статус DIRTY вниз по графу при изменениях сверху.
• Budget Controller: «Финансовый директор». Блокирует выполнение агента, если исчерпан лимит токенов/денег на ячейку.
• Consistency Guard: Гарантирует, что агент читает только VALID данные из родительских ячеек.

Мы проектируем Ячейку как объект, который знает о себе всё: что в нем должно лежать, от кого это зависит и кто имеет право это менять.

На уровне кода Ячейка состоит из 4-х изолированных слоев: Контракт, Состояние, Данные, Метаданные.

from typing import Generic, TypeVar, List, Optional
from pydantic import BaseModel, Field
from datetime import datetime

T = TypeVar("T") # Тип контента (Code, Doc, Plan)

class SmartCell(BaseModel, Generic[T]):
    # --- 1. ID & TOPOLOGY (Где я в графе?) ---
    id: str = Field(..., description="Уникальный адрес, напр. 'auth.service.scaffold'")
    dependencies: List[str] = Field(default_factory=list, description="IDs ячеек, от которых я завишу")
    dependents: List[str] = Field(default_factory=list, description="IDs ячеек, которые зависят от меня")

    # --- 2. THE CONTRACT (ДНК ячейки) ---
    schema_ref: str = Field(..., description="Ссылка на Pydantic-схему или JSON Schema валидатора")
    instruction: str = Field(..., description="Промпт/Задача для агента. 'Формула' этой ячейки")
    
    # --- 3. THE STATE (Жизненный цикл) ---
    status: CellStatus = Field(default=CellStatus.VOID)
    locked: bool = False # Блокировка от записи (например, Human Override)
    
    # --- 4. THE PAYLOAD (Тело) ---
    value: Optional[T] = None # Текущий контент (код, текст)
    error: Optional[str] = None # Если валидация не прошла
    
    # --- 5. OBSERVABILITY (Черный ящик) ---
    history: List[Revision] = Field(default_factory=list) # Git-like лог изменений
    budget: float = Field(default=1.0) # Оставшийся бюджет ($)

А. Контракт

Это то, что делает Ячейку не принимающей «мусор».

• schema_ref: Это ссылка на валидатор. Если Ячейка предназначена для Python-кода, здесь ссылка на парсер, который проверит синтаксис (AST) и наличие типов. Если это JSON-конфиг — здесь JSON Schema.
• Механика: Агент-Исполнитель не может записать данные в value, если они не проходят проверку schema_ref. Система отбросит попытку записи (Exception) и понизит репутацию агента.

Б. Конечный автомат (машина состояний)

Ячейка живет своей жизнью. Вот её состояния (CellStatus):

1. VOID (Пусто): Ячейка создана, но данных нет.
2. DIRTY (Грязно):
   • Либо изменилась зависимость (апстрим).
   • Либо Критик отверг текущее значение.
   • Сигнал: «Нужен Агент!».
3. LOCKED (В работе): Агент взял задачу. Ячейка заблокирована для других (мьютекс), чтобы избежать гонки.
4. PENDING_REVIEW (На проверке): Агент записал значение, схема прошла первичную валидацию. Ждем Критика.
5. STABLE (Стабильно): Критик одобрил. Значение считается «Истиной». Это состояние триггерит зависимые ячейки (Downstream).
6. FROZEN (Заморожено): Вмешался Человек. Агентам запрещено трогать эту ячейку, даже если зависимости изменились. (Важно для фиксации архитектуры).

В. История

Мы не перезаписываем данные. Мы дописываем версию. Объект Revision хранит:

• timestamp
• author_agent_id (Кто писал: Claude, DeepSeek или User Alex).
• diff (Что изменилось).
• reasoning_trace (Критически важно!): Ссылка на лог "мыслей" агента. Почему он решил написать именно этот код?
• cost: Сколько токенов сожгла эта итерация.

Как Ячейка реагирует на изменения? Это логика электронной таблицы.

1. Человек меняете ячейку Spec (ТЗ).
2. Ячейка Spec переходит в STABLE.
3. Она посылает сигнал invalidate() всем своим dependents.
4. Ячейка Scaffold (зависимая) получает сигнал.
   • Проверяет: «Я FROZEN?». Нет.
   • Переходит в статус DIRTY.
   • Сбрасывает value (опционально, или оставляет как контекст для diff).
5. Система видит DIRTY ячейку и выставляет ордер на биржу агентов.

Вложенность

Ячейка может содержать в value... ссылку на другую Партитуру (Sub-Graph).

• У вас есть ячейка AuthModule.
• Для верхнего уровня — это просто черный ящик, который должен принимать Login и отдавать Token.
• Но если «провалиться» внутрь, то AuthModule — это отдельный граф из 5 ячеек (UserDB, JWTService, RateLimiter и т.д.).

Зачем это нужно? Это позволяет использовать разные модели на разных уровнях зума.

• Верхний уровень (Архитектура) рисует Claude Opus 4.5.
• Внутренний уровень (Реализация методов) заполняет дешевый Gemini 3 Flash или Claude Haiku 4.5 или Qwen3 Coder.
• Система не грузит контекст целиком. Она подгружает только тот уровень абстракции (тот "Лист" в Экселе), который сейчас пересчитывается.

Критик — это агент-валидатор. Его задача — не допустить, чтобы энтропия (грязный код) просочилась вниз по графу зависимостей.

1. Объект «Вердикт»

Критик не просто меняет статус ячейки. Он производит структурированный артефакт.

class ReviewVerdict(BaseModel):
    # --- 1. Решение ---
    status: Literal["APPROVED", "REJECTED", "BLOCKING_ISSUE"]
    
    # --- 2. Детализация ---
    # Критик должен указать, ГДЕ ошибка и В ЧЕМ она.
    issues: List[Issue] = Field(..., description="Список дефектов")
    
    # --- 3. Навигация ---
    guidance: str = Field(..., description="Инструкция для Исполнителя: что именно исправить.")
    
    # --- 4. Метрики ---
    compliance_score: float = Field(..., ge=0, le=1.0) # Насколько соответствует ТЗ

Механика Взаимодействия

Взаимодействие между Исполнителем и Критиком происходит асинхронно через Ячейку. Это не чат. Это редактирование документа с комментариями.

1. Commit (Попытка 1):
   • DeveloperAgent записывает код в Cell.value.
   • Статус ячейки -> PENDING_REVIEW.
2. Review (Анализ):
   • Система видит статус PENDING_REVIEW и будит CriticAgent.
   • Входные данные Критика: Spec (Истина), Candidate (Текущий код), History (Предыдущие ошибки).
   • Критик находит логическую ошибку (например, "нет проверки токена").
3. Reject (Отказ):
   • Критик создает объект ReviewVerdict (Статус: REJECTED).
   • Система записывает этот вердикт в Историю Ячейки (Cell.history).
   • Ключевой момент: Статус ячейки меняется на DIRTY.
4. Feedback Injection (Обратная связь):
   • Система снова видит DIRTY. Она снова зовет DeveloperAgent.
   • НО! В этот раз Контекст (Промпт) собирается иначе.

Алгоритм пересборки Контекста

Система видит, что это не первая попытка, и собирает для Исполнителя «Пакет исправления»:

# SYSTEM PROMPT FOR DEVELOPER (ATTEMPT 2)

Твоя задача: Написать реализацию для [Spec ID].

ВАЖНО: Это ПОВТОРНАЯ попытка. Твой прошлый код был отклонен.

--- КОНТЕКСТ ПРОШЛОЙ ПОПЫТКИ ---
Твой код: [Ссылка на Hash v1]
Вердикт Критика:
❌ ОШИБКА: Отсутствует валидация JWT токена.
СОВЕТ: Используй библиотеку PyJWT и добавь декоратор @verify_token.

--- ЗАДАЧА ---
Перепиши код, ИСПРАВИВ указанные ошибки. Не ломай то, что работало.

Результат: Исполнитель не генерирует с нуля. Он делает Self-Correction на основе четкого сигнала.

3. Уровни Критики

Чтобы не жечь дорогие токены на пропущенные запятые, Критик устроен слоисто.

• Уровень 1: Синтаксический (Linter / Static Analysis)
  • Агент: Ruff, MyPy, Prettier.
  • Логика: Если Линтер падает, код даже не доходит до LLM-Критика. Ячейка сразу становится DIRTY.
• Уровень 2: Семантический (LLM Critic)
  • Агент: Claude 4.5 Sonnet.
  • Логика: Сравнивает Spec vs Implementation. Ловит логические ошибки и галлюцинации.
• Уровень 3: Тестовый (Execution Critic)
  • Агент: PyTest Runner.
  • Логика: Запускает код в песочнице. Если тесты падают -> REJECTED.

Замыкание петли: Budget & Circuit Breaker

Самый большой риск такой системы — бесплодное зацикливание. В Ячейку встроен механизм «Предохранитель» (Circuit Breaker).

def governance_loop(cell):
    if cell.retry_count > MAX_RETRIES (например, 5):
        cell.status = "FATAL_ERROR"
        cell.error = "Агенты не смогли договориться. Требуется человек."
        notify_human(cell.id)
        return

    if cell.budget_spent > cell.budget_limit:
        cell.status = "BANKRUPT"
        return

Стратегия эскалации (пример): Попытки 1-2: быстрые модели → Попытка 3: умные модели (Sonnet/Opus) → Попытка 5: человек.

Вложенность

Если Ячейка содержит Sub-Graph (вложенную Партитуру), то Критик работает на уровне интерфейса этого графа. Внутренние агенты могут спорить внутри AuthModule, а внешний Критик проверяет только результат.

Движок — это бесконечный цикл, который следит за появлением грязных Ячеек и пытается их стабилизировать.

В основе лежит DAG (Directed Acyclic Graph) — Направленный Ациклический Граф зависимостей. Но в отличие от Airflow, этот граф динамический.

Когда вы (Человек) меняете ячейку Spec (ТЗ):

1. Движок проходит вниз по графу.
2. Он помечает всех прямых и косвенных потомков (Scaffold, Code, Tests) статусом DIRTY (или CASCADE_PENDING).
3. Важно: Он не запускает пересчет всего сразу. Он просто маркирует территорию как "устаревшую".

Агент может менять граф в процессе работы.

• Сценарий: Агент-Архитектор видит, что Spec слишком сложный.
• Действие: Он не просто пишет код. Он создает новые ячейки (Sub-Module A, Sub-Module B) и линкует их в граф.
• Движок на лету перестраивает зависимости без перезагрузки.

Биржа Задач

Движок не вызывает агентов напрямую (agent.run()).

1. Очередь задач:
   Движок собирает все ячейки со статусом DIRTY.
   • Task #101: Обновить Scaffold (High Priority, так как блокирует остальных).
   • Task #102: Обновить Readme (Low Priority).
2. Диспетчер:
   Cмотрит на пул свободных Агентов (воркеров).
   • Есть свободный слот для Claude Opus? -> Отдаем ему Task #101.
   • Все слоты заняты? -> Задача висит в Pending.

Цикл Реактора

Вот псевдокод ядра системы.

async def reactor_loop(graph: ScoreBoard):
    while True:
        # 1. Сбор событий (кто изменился?)
        changes = graph.get_state_changes()
        
        # 2. Волна инвалидации
        if changes:
            graph.propagate_dirty_status(changes)

        # 3. Планирование (Какие ячейки готовы к работе?)
        # Ячейка готова, если она DIRTY, но все её родители STABLE.
        runnable_cells = graph.get_runnable_cells()

        # 4. Диспетчеризация (Назначаем агентов)
        for cell in runnable_cells:
            if budget_controller.can_afford(cell):
                # Асинхронный запуск в фоне
                asyncio.create_task(spawn_agent(cell))
            else:
                log.warning("Budget freeze for cell", cell.id)

        # 5. Сбор урожая (Обработка завершенных)
        # Если агент закончил, проверяем статус (STABLE / REJECTED)
        # и обновляем граф.
        
        await asyncio.sleep(0.1)

Механизмы защиты

Движок — это единственный компонент, который имеет право убить агента.

Движок хранит хеши состояний графа. Если граф пришел в состояние A -> B -> A -> B (Агент 1 правит, Агент 2 отменяет правку, Агент 1 снова правит), Движок:

1. Замечает осцилляцию.
2. Ставит обе ячейки в статус CONFLICT.
3. Зовет Человека (или Арбитра).

Когда Движок готовит задачу для Агента, он делает стряхивание дерева.

• Агенту, который пишет метод login(), не нужно знать про модуль Billing.
• Движок вырезает из графа только релевантные зависимые узлы и подает их в контекст.

Это экономит токены и повышает точность (меньше шума).

Резюме: Как это работает вместе

1. Вы (Человек) меняете одну строчку в Спецификации.
2. Движок видит изменение, делает Invalidate для 50 зависимых файлов.
3. Движок видит, что 5 файлов (верхний уровень) готовы к пересчету.
4. Движок нанимает 5 Архитекторов.
5. Архитекторы обновляют Скаффолды.
6. Движок видит, что Скаффолды стали STABLE. Открывается фронт работ для 20 Кодеров.
7. Движок запускает рой Кодеров.
8. ... через 5 минут ...
9. Движок сообщает: «Проект пересобран. Все тесты зеленые».

UI для Партитуры — это гибрид IDE, BI-дашборда и Стратегической игры. Человек здесь — не собеседник. Человек — Наблюдатель и Арбитр. Интерфейс должен решать главную проблему: Снижение когнитивной нагрузки при наблюдении за роем.

Основной экран: Топологическая Карта (The Graph View).

В центре экрана — Живой Граф Зависимостей (DAG).

• Визуализация: Ячейки соединены стрелками зависимостей.
• Цветовое кодирование (Светофор):
  • Зеленый: STABLE (Все тесты прошли).
  • Красный: ERROR / REJECTED (Требуется внимание).
  • Желтый: DIRTY (Ожидает пересчета).
  • Пульсирующий Синий: PROCESSING (Агент прямо сейчас пишет код).
• Семантический Зум:
  • Zoom Out: Вы видите квадраты микросервисов («Auth», «Billing»).
  • Zoom In: Квадрат распадается на файлы/классы.
  • Deep Zoom: Вы видите конкретные методы внутри класса.

Волна изменений бежит по графу. Вы поменяли ТЗ слева — и видите, как желтая волна DIRTY накрывает зависимые модули справа.

Инспектор Ячейки

Когда вы кликаете на узел графа, справа выезжает панель Детального просмотра. Это не просто редактор кода.

А. Вкладка "Content" (Код + Контракт)

• Сверху: Pydantic Schema / Interface (Неизменяемая часть, написанная Архитектором).
• Снизу: Monaco Editor (VS Code) с текущим значением value.
• Кнопка «God Mode»: Вы можете вручную отредактировать код. Как только вы начинаете печатать, статус ячейки меняется на 🔒 FROZEN (User Lock). Агенты больше не смеют трогать этот файл, пока вы не снимете замок.

Б. Вкладка "Reasoning" (Мысли Агента)

Здесь мы видим почему ИИ написал этот код.

• Не сырой лог, а Структурированный Трейс:
  1. 🎯 Цель: "Реализовать метод login".
  2. ⚠️ Риски: "Нужно проверить SQL-инъекции".
  3. 📝 План: "Импортирую SQLAlchemy..."
  4. ❌ Ошибка (попытка 1): "Syntax Error".
  5. ✅ Фикс (попытка 2): "Исправлено".

В. Вкладка "Reviews" (Вердикт Критика)

Здесь лежит отчет от CriticAgent.

• Красная плашка: "REJECTED".
• Список претензий:
  • [High] Не используется соль для хеширования пароля.
  • [Low] Нет докстринга.

Лента Событий

Внизу экрана (как терминал в VS Code) бежит лента событий в реальном времени.

Если нажать на строчку лога, Граф автоматически фокусируется на соответствующей ячейке.

Панель Управления

Сверху — приборная панель состояния системы.

1. Бюджет: "$45.20 / $100.00". (Если деньги кончаются, полоска краснеет).
2. Нагрузка: "Active Agents: 12 / 50".
3. Кнопка «PANIC BUTTON» (Большая красная):

Как выглядит работа с таким UI:

1. Вы открываете Топологическую Карту. Видите, что модуль Reporting горит красным .
2. Кликаете на него. В Инспекторе видите вердикт Критика: "Агент зациклился, 5 попыток провалено".
3. Открываете вкладку Reasoning. Видите, что агент пытается использовать библиотеку, которая устарела.
4. Вы нажимаете «Edit Scaffold».
5. Дописываете в комментарий к коду: # HINT: Используй библиотеку Pandas v2.2.
6. Снимаете статус ERROR, ставите DIRTY.
7. Система видит: "О, человек дал подсказку".
8. Запускает агента заново.
9. Вы видите, как ячейка стала (Processing), потом (Stable).

Вы не писали код. Вы подтолкнули застрявшего робота.