acid-engine 0.2.0

Contract-Driven Data Control Layer

cat << 'EOF' > README.md

AcidEngine — Contract-Driven Data Control Layer

Контрактно-ориентированная платформа для Data Engineering.
Описывайте правила, структуру и жизненный цикл данных в декларативном стиле. AcidEngine автоматически обеспечивает их соблюдение, сгенерирует код, тесты и отчёты.

---

Быстрый пример

Создайте файл спецификации orders.ae:

spec_version "1.0"

project "Orders Validation"
version "1.0"

INPUT:
    source orders
    source customers

OUTPUT:
    source validated_orders

IMPLEMENTATION:
    stage validate:
        input orders
        output validated_orders
        use contract
        schema:
            order_id is integer
            price is float
            quantity is integer
        require:
            price > 0
            quantity between 1 and 100
        join customers with orders by customer_email
        enrich phone from customers.phone

Запустите валидацию через CLI или Python:

$ acid run orders.ae --input orders.csv
Stage: validate
PASS: 150, FAIL: 12, SKIPPED: 3

---

Ключевые возможности

Возможность	Описание
Field Contracts	Типы, диапазоны, regex, choices, 8 встроенных пресетов (Email, Url, UUID…)
Cross‑Field Rules	Бизнес-правила, связывающие поля (age >= 18 if ...)
QualityGate	4 режима обработки: strict, recovery, audit, quarantine
Explain Engine	Читаемый отчёт (Markdown, HTML) с топом ошибок и примерами
Pipeline Generator	Автоматическая генерация Python-пайплайна прямо из контракта
AI Guard	Валидация и фильтрация ответов LLM через контракт
LangChain Plugin	Нативный компонент AcidOutputGuard для LangChain-пайплайнов
YAML Support	Бесшовный импорт и экспорт контрактов
Derived Fields	Объявление и расчет вычисляемых полей внутри контракта
Join & Enrich	Описание связей и обогащения между источниками данных
Contract Testing	Автоматическая генерация готовых pytest-тестов для данных
HTML Reports	Визуальные профессиональные отчёты в один клик

---

Быстрый старт

1. Установите пакет:

   pip install acid-engine
   

2. Запустите пайплайн:

   acid run my_pipeline.ae --input data.csv
   

---

Документация и ссылки

• Архитектура проекта
• Дорожная карта (Roadmap)
• Демо-скрипты и примеры

---

Статус проекта

• ✅ v1.0 (Стабилен): Ядро полностью готово к пилотным внедрениям в production.
• 🔄 В разработке: Polars adapter, Contract Registry, Audit Trail.

---

Автор и лицензия

© 2025 Alexey Rodkin. Распространяется под лицензией Apache 2.0. Подробности в файле LICENSE. EOF

cat << 'EOF' > ROADMAP.md

AcidEngine Roadmap

v1.0 (Текущая версия) — Стабильное ядро

• Field Contracts: Типы, диапазоны, regex, пресеты.
• Container Contracts: Проверки на уникальность (unique), упорядоченность (ordered), неизменяемость (frozen).
• Cross‑Field Validation: Кросс-полевая валидация и условная логика.
• QualityGate: Режимы strict, recovery, audit, quarantine.
• Explain Engine: Генерация понятных отчетов в Markdown и HTML.
• YAML Support: Экспорт/импорт декларативных спецификаций.
• Pipeline Generator: Конвертация контрактов в исполняемый Python-код.
• Pandas Integration & CSV Loader: Базовый движок для работы с табличными данными.
• AI Guard & LangChain Plugin: Инструменты контроля качества для LLM-агентов.
• Join & Enrich & Derived Fields: Трансформация данных на уровне контракта.
• Contract Testing: Автогенерация тестовых сценариев для pytest.
• AcidLogger: Структурированное JSON-логирование для интеграции с SIEM/ELK.

v1.1 (Ближайшие планы) — Расширение экосистемы

• Polars Integration: Поддержка высокопроизвого движка Polars для больших датасетов.
• JSON Schema / Pydantic export: Генерация стандартных схем данных из .ae-файлов.
• Contract Diff: Утилита для сравнения двух версий контрактов.
• Excel Export: Выгрузка отчетов Explain Engine в формат .xlsx.

v1.5 (В проектировании) — Жизненный цикл контрактов

• Full Pipeline Generation: Полная сборка сложных направленных графов (DAG) из контрактов.
• Contract Versioning: Систематизация версий и обратная совместимость схем.
• Soft Contracts: Уровни строгости правил (INFO, WARNING, ERROR).
• Contract Fingerprint: Хеширование состояния контракта для контроля целостности данных.

v2.0 (Перспектива) — Enterprise & Стриминг

• Rust Runtime: Перенос критического движка валидации на Rust для максимальной скорости.
• Kafka / Spark Streaming Plugins: Валидация потоковых данных «на лету».
• Marketplace of Contracts: Публичный и приватный хаб готовых контрактов (Data Presets).
• Enterprise Features: Интеграция SSO, RBAC (ролевая модель) и сквозной аудит (Audit Trail). EOF

cat << 'EOF' > ARCHITECTURE.md

AcidEngine — Architecture Overview

Базовый принцип

Контракт является единственным источником истины (Single Source of Truth).
Все правила, ограничения, типы данных и связи хранятся исключительно в файле контракта (.ae / .yaml). Никакая другая сущность, компонент рантайма или сторонний сервис не должны содержать собственную копию правил. Изменения в контракте автоматически каскадируются на код, тесты и аналитику.

---

Основные компоненты

1. Парсер (Lark)

Отвечает за чтение текстовых файлов спецификации .ae и построение абстрактного синтаксического дерева (AST). Грамматика описывает декларативные блоки:

• INPUT: / OUTPUT: / IMPLEMENTATION: — макроструктура пайплайна.
• stage, input, output, use, schema, require — контекст исполнения и логические блоки.
• join, enrich, derive — правила трансформации.
• Набор операторов валидации: is, >, >=, <, <=, !=, between.

2. Рантайм (StageRunner)

Оркестратор жизненного цикла данных на конкретном этапе пайплайна. Выполняет следующие шаги:

1. Загружает сырые данные из источников.
2. Применяет трансформации (join / enrich / derive).
3. Конструирует объект Contract на основе AST.
4. Пропускает данные через движок валидации (Field Validation & QualityGate).
5. Агрегирует метрики для формирования финального отчета.

3. Генераторы (Группа расширений)

• HTMLReporter: Отвечает за компиляцию результатов валидации в интерактивные HTML/Markdown бизнес-отчеты.
• ContractTestGenerator: Анализирует ограничения контракта и автоматически создаёт тестовые люксы (свиты) для pytest, снижая рутину написания тестов.
• AcidLogger: Обеспечивает стандартизированный вывод логов в формате JSON.

---

Поток данных (Data Flow)

[ .ae contract file ] 
        │
        ▼
   Parser (Lark) ──► Builds AST
        │
        ▼
   StageRunner   ──► 1. Join & Enrich Data
        │            2. Compute Derived Fields
        │            3. Validate (Field / QualityGate)
        ▼
[ Executive Output ] ──► (Validated Data, Error Tables)
        │
        ├──► HTMLReporter        ──► [ Interactive HTML/MD Reports ]
        └──► ContractTestGen     ──► [ Automated pytest Files ]