ss-tools/semantic_protocol.md

Протокол GRACE-Py: Семантическая Разметка для AI-Агентов на Python

Версия: 2.2 (Hybrid)

I. Философия и Основные Принципы

Этот протокол является единственным источником истины для правил семантического обогащения кода. Его цель — превратить процесс разработки с LLM-агентами из непредсказуемого "диалога" в управляемую инженерную дисциплину.

• Аксиома 1: Код Вторичен. Первична его семантическая модель (графы, контракты, якоря).
• Аксиома 2: Когерентность Абсолютна. Все артефакты (ТЗ, граф, контракты, код) должны быть на 100% семантически согласованы.
• Аксиома 3: Архитектура GPT — Закон. Протокол построен на фундаментальных принципах работы трансформеров (Causal Attention, KV Cache, Sparse Attention).

II. Структура Файла (.py)

Каждый Python-файл ДОЛЖЕН иметь четкую, машиночитаемую структуру, обрамленную якорями.

# <GRACE_MODULE id="my_module" name="my_module.py">
#   @SEMANTICS: domain, usecase, data_processing
#   @PURPOSE: Этот модуль отвечает за обработку пользовательских данных.
#   @DEPENDS_ON: utils_module -> Использует утилиты для валидации.

# <IMPORTS>
import os
from typing import List
# </IMPORTS>

# --- Начало кода модуля ---

# ... (классы, функции, константы) ...

# --- Конец кода модуля ---

# </GRACE_MODULE id="my_module">

III. Компоненты Разметки (Детализация GRACE-Py)

A. Anchors (Якоря): Навигация и Консолидация

1. Назначение: Якоря — это основной инструмент для управления вниманием ИИ, создания семантических каналов и обеспечения надежной навигации в больших кодовых базах (Sparse Attention).
2. Синтаксис: Используются парные комментарии в псевдо-XML формате.
   • Открывающий: # <ANCHOR id="[уникальный_id]" type="[тип_из_таксономии]">
   • Закрывающий (Обязателен!): # </ANCHOR id="[уникальный_id]">
3. "Якорь-Аккумулятор": Закрывающий якорь консолидирует всю семантику блока (контракт + код), создавая мощный вектор для RAG-систем.
4. Семантические Каналы: id якоря ДОЛЖЕН совпадать с именем сущности для создания устойчивой семантической связи.
5. Таксономия Типов (type): Module, Class, Interface, Object, DataClass, SealedInterface, EnumClass, Function, UseCase, ViewModel, Repository.

C. Contracts (Контракты): Тактические Спецификации

1. Назначение: Предоставление ИИ точных инструкций для генерации и валидации кода.
2. Расположение: Контракт всегда располагается внутри открывающего якоря, ДО декларации кода (def или class).
3. Синтаксис: JSDoc-подобный стиль с @tag для лаконичности и читаемости.

   # <ANCHOR id="process_data" type="Function">
   #   @PURPOSE: Валидирует и обрабатывает входящие данные пользователя.
   #   @SPEC_LINK: tz-req-005
   #   @PRE: `raw_data` не должен быть пустым.
   #   @POST: Возвращаемый словарь содержит ключ 'is_valid'.
   #   @PARAM: raw_data: Dict[str, any] - Сырые данные от пользователя.
   #   @RETURN: Dict[str, any] - Обработанные и валидированные данные.
   #   @TEST: input='{"user_id": 123}', expected_output='{"is_valid": True}'
   #   @THROW: ValueError - Если 'user_id' отсутствует.
   #   @RELATION: CALLS -> validate_user_id
   #   @CONSTRAINT: Не использовать внешние сетевые вызовы.
   

4. Реализация в Коде: Предусловия и постусловия, описанные в контракте, ДОЛЖНЫ быть реализованы в коде с использованием assert, require()/check() или явных if...raise.

G. Graph (Граф Знаний)

1. Назначение: Описание высокоуровневых зависимостей между сущностями.
2. Реализация: Граф определяется тегами @RELATION внутри GRACE блока (якоря). Это создает распределенный граф, который легко парсить.
   • Синтаксис: @<PREDICATE>: <object_id> -> [опциональное описание]
   • Таксономия Предикатов (<PREDICATE>): DEPENDS_ON, CALLS, CREATES_INSTANCE_OF, INHERITS_FROM, IMPLEMENTS, READS_FROM, WRITES_TO, DISPATCHES_EVENT, OBSERVES.

E. Evaluation (Логирование)

1. Назначение: Декларация belief state агента и обеспечение трассируемости для отладки.
2. Формат: logger.level(f"[ANCHOR_ID][STATE] Сообщение")
   • ANCHOR_ID: id якоря, в котором находится лог.
   • STATE: Текущее состояние логики (например, Entry, Validation, Exit, CoherenceCheckFailed).
3. Пример: logger.debug(f"[process_data][Validation] Проверка raw_data...")

IV. Запреты и Ограничения

1. Запрет на Обычные Комментарии: Комментарии в стиле // или /* */ ЗАПРЕЩЕНЫ. Вся мета-информация должна быть в структурированных GRACE блоках.
   • Исключение: # [AI_NOTE]: ... для прямых указаний агенту в конкретной точке кода.

V. Полный Пример Разметки Функции (GRACE-Py 2.2)

# <ANCHOR id="process_data" type="Function">
#   @PURPOSE: Валидирует и обрабатывает входящие данные пользователя.
#   @SPEC_LINK: tz-req-005
#   @PRE: `raw_data` не должен быть пустым.
#   @PARAM: raw_data: Dict[str, any] - Сырые данные от пользователя.
#   @RETURN: Dict[str, any] - Обработанные и валидированные данные.
#   @TEST: input='{}', expected_exception='AssertionError'
#   @RELATION: CALLS -> some_helper_function
def process_data(raw_data: dict) -> dict:
    """
    Docstring для стандартных инструментов Python.
    Не является источником истины для ИИ-агентов.
    """
    logger.debug(f"[process_data][Entry] Начало обработки данных.")
    
    # Реализация контракта
    assert raw_data, "Precondition failed: raw_data must not be empty."
    
    # ... Основная логика ...
    processed_data = {"is_valid": True}
    processed_data.update(raw_data)
    
    logger.info(f"[process_data][CoherenceCheck:Passed] Код соответствует контракту.")
    logger.debug(f"[process_data][Exit] Завершение обработки.")
    
    return processed_data
# </ANCHOR id="process_data">