Генерация с бизнес-правилами¶

English · Русский

Для чего это нужно¶

Задайте правила YAML/JSON, когда одной схемы недостаточно: например amount=quantity*unit_price, порядок дат или обязательное поле. Детерминированный код применяет и проверяет правила; текстовое обещание AI не заменяет правило.

Что получится в результате¶

Две синтетические таблицы и business_validation_report.json.

Предварительные требования¶

Установлен Python 3.11+ и пакет проекта. Терминал открыт в корне репозитория agent-paranoid-android; виртуальное окружение активно. Входы — только вымышленные файлы из репозитория. Папка назначения новая; есть права чтения входов и записи результата. Для команд ниже используйте macOS/Linux; в PowerShell вводите каждую команду одной строкой без \. Для этого сценария достаточно базового пакета.

Пошаговое выполнение¶

Шаг 1. Изучите правила примера¶

Что сделать: Откройте rules.yaml; проверьте ссылки на таблицы и поля.

Где выполнить: Редактор, examples/relational_csv/rules.yaml.

Команда или пример:

examples/relational_csv/rules.yaml

Что должно произойти: Видны структурированные правила вымышленного домена.

Как проверить: Имена совпадают с CSV и будущим spec; чувствительных литералов нет.

Если не получилось: Не переносите правила с реальными ID, адресами или секретами. Формула — ограниченная арифметика, не Python.

Шаг 2. Выполните связанный пример¶

Что сделать: Запустите профиль → spec → generate с правилами → validate.

Где выполнить: macOS/Linux, корень checkout.

Команда или пример:

bash examples/relational_csv/run.sh out/ru-rules

Что должно произойти: Созданы customers.csv, orders.csv, validation_report.json, business_validation_report.json и manifest.

Как проверить: Команды завершаются успешно; manifest содержит business_validation.

Если не получилось: При противоречии правил и spec исправьте имена и требования; не удаляйте проверки ради успешного отчёта.

Шаг 3. Проверьте бизнес-отчёт¶

Что сделать: Проверьте valid без печати строк.

Где выполнить: Корень checkout.

Команда или пример:

python -c "import json; from pathlib import Path; r=json.loads(Path('out/ru-rules/generated/business_validation_report.json').read_text()); assert r['valid'] is True; print('business rules: ok')"

Что должно произойти: Правила выполнены.

Как проверить: Код 0.

Если не получилось: При нарушении прочитайте счётчики правил; обычный schema valid не означает успешные business rules.

Проверка результата¶

Сверьте rule fingerprint и счётчики в manifest с выбранным файлом. Нужные бизнес-инварианты должны быть явно представлены и проверены. Отсутствующее правило не проверяется автоматически.

Типичные ошибки¶

Ошибка	Причина	Решение
Неизвестный тип/поле правила	Опечатка или неподдерживаемая конструкция	Сопоставьте правило с spec и справочником правил.
Превышен work budget	Слишком много строк × правил	Уменьшите тест; меняйте лимиты только после оценки ресурсов.

Переносимость и смысл правил в 1.6.0¶

DatasetSpec.business_rules переносит правила между Python, CLI, MCP, agent workspace и всеми форматами. infer-spec --business-rules сохраняет их в spec; generate, validate и export-postgres-sql также принимают отдельный --business-rules. Повторная валидация проверяет данные и не присваивает значения заново.

У формул mode: assign по умолчанию задаёт результат; mode: check только проверяет. Отчёт содержит application и assigned_row_count: зелёный результат после присваивания не доказывает независимую верность бизнес-гипотезы. Поддерживаются явные equals: null / not_equals: null и числовые включительные gte/lte. DECIMAL-формулы и aggregate mappings используют точную арифметику с однократным HALF_UP округлением в scale целевого поля. Подробности: контракт правил 1.6.

Категории и ограничения¶

Поддерживаются field rules (required, allowed values, bounds), conditional required/allowed values, temporal ordering, formula, foreign key, aggregate formula и weighted scenario. Не все агрегатные правила могут создавать отрицательные данные: count с field: "*" — только проверка, поскольку изменение числа строк нарушило бы форму набора.

Пример контролируемых нарушений, проверенный существующими документационными тестами:

test-data-agent generate examples/negative_cases/dataset_spec.yaml --seed 1300 --mode mixed --invalid-ratio 0.5 --format json --business-rules examples/negative_cases/business_rules.yaml --output out/ru-negative

При намеренных нарушениях команда 1.6.0 возвращает exit code 1, хотя набор и validation evidence сохранены. Это ожидаемое поведение данного negative-примера. Держите такой набор отдельно. Успех отрицательного сценария — совпадение ожидаемых и наблюдаемых нарушений (expectations_met=true, ноль unexpected и missing expected), а не отсутствие нарушений. Режим negative и mixed не разрешает PII. Точные поля правил и примеры всех категорий описаны в существующем руководстве.

Следующий шаг¶

Валидация.

Условные формулы и синтетическая EAV-модель¶

Формула в режиме assign или check принимает необязательное условие when. При ложном условии выражение не вычисляется, значение не меняется, строка считается пропущенной. Отчёт отдельно возвращает eligible_row_count, evaluated_row_count и skipped_row_count; пропуск не считается успехом. Правила без when сохраняют прежние отпечатки и поведение. equals: null выбирает пустое или отсутствующее значение; числовой диапазон его не выбирает. Неизвестное в DatasetSpec поле условия отклоняется до генерации.

Поле условия нельзя изменять другими построчными правилами. Несколько формул назначения одного поля разрешены для доказуемо непересекающихся equals или in_values по одному полю. Пересечение, диапазон или недоказанная совместимость отклоняются. Проверки чувствительных литералов, точная арифметика DECIMAL, общий лимит работы и срок выполнения остаются обязательными.

Исполняемый пример EAV использует заранее заданные синтетические атрибуты ratio и total, независимые идентификаторы и две условные формулы. Одна запись содержит один атрибут и одно значение. Отсутствие наблюдения отличается от пустого значения. Уникальность пары сущность/атрибут нужно объявить отдельно; пример допускает повторение. Преобразование исходных строк, сохранение ключей и разрешение дубликатов источника этим примером не выполняются.