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 | Визуальные профессиональные отчёты в один клик |
Быстрый старт
-
Установите пакет:
pip install acid-engine
-
Запустите пайплайн:
acid run my_pipeline.ae --input data.csv
Документация и ссылки
Статус проекта
- ✅ 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)
Оркестратор жизненного цикла данных на конкретном этапе пайплайна. Выполняет следующие шаги:
- Загружает сырые данные из источников.
- Применяет трансформации (
join/enrich/derive). - Конструирует объект
Contractна основе AST. - Пропускает данные через движок валидации (
Field Validation&QualityGate). - Агрегирует метрики для формирования финального отчета.
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 ]
Metadata
Release files for acid-engine 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| acid_engine-0.2.0.tar.gz | 31.8 kB | Without provenance | Details for acid_engine-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| acid_engine-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for acid_engine-0.2.0-py3-none-any.whl |
Total release size: 63.3 kB
Release files / acid_engine-0.2.0.tar.gz
| Download URL | acid_engine-0.2.0.tar.gz |
|---|---|
| Size | 31.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc1367cc95bd42b009f530b017ace44edf1329a2093b1be4811256cc887e8ec8
|
|
BLAKE2b-256 checksum How to use checksums |
f5268e6a739debe684436a2367cdecacf25ee4f8eac56c695ec4890df5a8ad6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / acid_engine-0.2.0-py3-none-any.whl
| Download URL | acid_engine-0.2.0-py3-none-any.whl |
|---|---|
| Size | 31.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b4d35097fc861fd7b2b64e61ed07dbdbb57c4cdde0f57a0e6fd57cfb9c779674
|
|
BLAKE2b-256 checksum How to use checksums |
f884b65ca29220388a7b01e16c82053d5dd56c724b5bff1e77390c9e58694424
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for acid-engine 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.