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

**Версия: 2.2 (Hybrid)**

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

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

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

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

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

```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` для лаконичности и читаемости.
    ```python
    # <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)**

```python
# <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">
```