Skip to content
BranchesTags

Repository files navigation

Ouroboros: E2E процесс контроля соблюдения стандартов

Платформа автоматизации контроля нормативных требований с помощью Ouroboros/GigaAgent. Эксперт отправляет стандарт по почте, система выделяет проверяемые требования, запрашивает недостающие корпоративные данные, создаёт и проверяет SQL, формирует удобный Excel с отклонениями и закрывает сценарий только после повторной проверки исправленной полной таблицы.

Проблема

Нормативные требования часто превращаются в ручные проверки: эксперт читает документ, выясняет структуру данных, формулирует SQL, собирает отклонения и ведёт долгую переписку с ДЗО. В результате теряется связь между исходным требованием, решением человека, версией данных и итогом повторной проверки.

Возможности

  • принимает PDF, DOCX, TXT или MD через почтовый шлюз;
  • создаёт структурированные карточки требований;
  • проводит экспертное согласование каждого содержательного этапа;
  • сопоставляет потребность с каталогом допустимых полных таблиц;
  • принимает CSV/XLSX и хранит версии полученных данных;
  • генерирует один SELECT только для чтения на сценарий и проверяет его в песочнице;
  • собирает все отклонения одного subject_ref в один XLSX;
  • добавляет в XLSX поля «Статус ответа ДЗО» и «Комментарий ДЗО»;
  • принимает исправление только после повторного запуска того же SELECT и результата в ноль строк;
  • сохраняет задачи, gates, audit events и решения восстановления после ошибок.

Ключевая роль Ouroboros / GigaAgent

Ouroboros выполняет семантическую работу с помощью пяти независимых навыков:

  1. standards_orchestrator выбирает следующий допустимый маршрут;
  2. standards_requirements_factory выделяет требования из документа;
  3. standards_data_factory определяет нужную логическую таблицу;
  4. standards_script_factory формирует контрольный SQL;
  5. standards_monitoring_factory интерпретирует результат и готовит отклонения.

Шестой навык, standards_mail_gateway, обеспечивает почтовый вход и запускает детерминированное Python-ядро. Фабрики не вызывают друг друга напрямую и не могут самостоятельно переписать состояние процесса.

Команда также проводила цикл эволюции Ouroboros и использовала его результаты при доработке решения. В репозитории есть воспроизводимый второй режим для контролируемого запуска этой эволюции и независимого бенчмарка; он не подменяет навык автоматически и не выдаёт результат, затронувший только память, за успешную эволюцию.

Архитектура

flowchart LR
    A[Эксперт] --> B[Mail Gateway]
    B --> C[Фабрика требований]
    C --> D[Согласование]
    D --> E[Фабрика данных]
    E --> F{Таблица доступна?}
    F -->|Нет| G[Запрос полной таблицы у ДЗО]
    F -->|Да| H[Фабрика скриптов]
    G --> H
    H --> I[SQL sandbox и согласование]
    I --> J[Фабрика мониторинга]
    J --> K[XLSX с отклонениями]
    K --> L[Исправленная полная таблица]
    L --> M[Повторный SELECT]
    M -->|0 строк| N[Сценарий закрыт]
Loading

Подробности: архитектура и границы ответственности.

Пример на закупках

В examples/procurement/ опубликованы:

  • обезличенный закупочный стандарт;
  • первоначальная и две исправленные версии полной таблицы;
  • четыре согласованных SQL;
  • два XLSX с отклонениями;
  • два результата повторной проверки;
  • обезличенные ответы фабрик и audit-трасса.

Закупочный маршрут выполняется через Ouroboros и почтовый шлюз; HR и учёт используют единый процесс контроля и соответствующие каталоги данных.

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

python3 -m venv .venv
./.venv/bin/python -m pip install -e '.[dev]'
./.venv/bin/python -m pytest -q
./.venv/bin/python -m ruff check .
./.venv/bin/python scripts/build_skill_bundles.py
./.venv/bin/python scripts/verify_skill_bundles.py --root dist/skills

Проверенная среда: macOS, Python 3.10+ и Ouroboros 6.64.4. Установка навыков выполняется вручную после создания резервной копии: инструкция по установке.

Модели и восстановление после ошибок

  • обычные задачи: DeepSeek V4 Flash;
  • повторная генерация скрипта и решение сложного recovery: DeepSeek V4 Pro;
  • polling почты: 15 секунд;
  • максимальная конкуренция: 3;
  • не больше двух автоматических попыток восстановления;
  • Task Result Review: off, при этом проверка устанавливаемых навыков остаётся обязательным.

Неудачная попытка сохраняется. Оркестратор может повторить фабрику, вернуть процесс на допустимый предыдущий этап или выбрать manual_review. Переходы вне графа блокирует детерминированный validator.

Все значения: настройки Ouroboros.

Observability и Langfuse

Каждый вызов семантической фабрики создаёт структурированную трассировку: process_id, имя фабрики, локальный идентификатор задачи, модельный профиль, статус и длительность. Тексты документов, письма, запросы к модели и её ответы в телеметрию не передаются. Без настройки Langfuse наблюдаемость не влияет на работу процесса.

Для Langfuse:

./.venv/bin/python -m pip install -e '.[dev,observability]'
export LANGFUSE_PUBLIC_KEY='...'
export LANGFUSE_SECRET_KEY='...'
# при self-hosted инсталляции также LANGFUSE_BASE_URL='https://...'

Локальный стек Langfuse (PostgreSQL, ClickHouse, Redis, MinIO) и контейнер с инструментами проекта: Docker Compose.

Защита от инъекций в запросы

Тексты стандартов, вложений и писем считаются недоверенными данными. Перед каждым вызовом фабрики защитный модуль нормализует Unicode, включая невидимые символы, и блокирует явные попытки переопределить инструкции, роль системы или извлечь секреты; задача переводится в контур manual_review. Менее однозначные сигналы фиксируются только как счётчик в наблюдаемости, без записи текста источника. Данные отделены от контракта фабрики в INPUT_JSON, а семантические задачи не имеют доступа к файловой системе, сети или инструментам записи.

Режим самоэволюции и бенчмарка

Встроенный набор входных данных для бенчмарка позволяет запустить три кейса проверки без внешних путей. Сначала выполняется baseline без доступа к expected_outputs, затем обучающие кейсы, native evolution и blind-проверка. Автоматически создаётся только brief для native evolution: изменённый навык можно принять лишь после проверки жизненного цикла и зафиксированного статуса absorbed.

PACK=/Users/ilyamikheev/Downloads/requirements_self_evolution_full_evidence_pack_2026-07-19

./.venv/bin/python -m ouroboros_mail_agent.evolution evolution-plan \
  --baseline-skill "$PACK/01_identity_and_skills/starting_skill.md" \
  --learning-note "$PACK/05_feedback_loops/hr/01_learning_hr_feedback_notes.md" \
  --learning-note "$PACK/05_feedback_loops/procurement/02_learning_procurement_feedback_notes.md" \
  --output runtime/evolution/native-evolution-brief.md

# Встроенные независимые кейсы запускаются по умолчанию; contracts появляются
# после scripts/build_skill_bundles.py.
./.venv/bin/python -m ouroboros_mail_agent.evolution benchmark-run \
  --base-url http://127.0.0.1:8765 \
  --contract-dir dist/skills/standards_mail_gateway/factory_contracts \
  --output-dir runtime/evolution/raw-benchmark

# После прогона трёх независимых кейсов и ручной оценки 0/1/2 по rubric:
./.venv/bin/python -m ouroboros_mail_agent.evolution benchmark \
  --scores runtime/evolution/expert-scores.json \
  --output-dir runtime/evolution/benchmark

expert-scores.json — массив объектов {"case_id":"case_01","scores":[...12 значений 0..2...],"evidence":[...]}. Команда формирует отдельную карточку оценки для каждого кейса и final_score_summary.csv; сохраняйте результаты прогона до открытия эталонных ответов.

Метрики качества evidence pack (19.07.2026)

Стандарт До После Дельта
HR methodology 17/24 20/24 +3
Procurement policy 15/24 22/24 +7
Debt management (blind) 19/24 22/24 +3

Рубрика содержит 12 критериев: полнота, точность, атомарность, traceability источника, applicability/exclusions, сроки и роли, честная проверяемость, сценарий контроля, корректность цифрового следа, его частичность, связь с корпусом и готовность к экспертной проверке.

Полный набор результатов, экспертной обратной связи, diff навыка и scorecards: Эволюция фабрики требований.

Проверенные результаты

Репозиторий содержит модульные, интеграционные и E2E-проверки, а также проверку пакетов навыков. Текущие результаты и ссылки на доказательства находятся в статусе acceptance и матрице проверок.

Форматы входов и выходов

  • нормативные документы: PDF с текстовым слоем, DOCX, TXT, MD;
  • данные: CSV UTF-8 и XLSX;
  • до 10 MB на вложение и до 100 000 строк таблицы;
  • первая строка — точные заголовки согласованной полной таблицы;
  • company_inn и company_name обязательны и идут первыми;
  • результат отклонений — один XLSX на subject_ref.

Для сканированных PDF требуется предварительный OCR.

Архитектура данных

SQLite используется для состояния процесса, аудита, версий данных и локального изолированного SQL-sandbox.

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

Презентация и видео подаются отдельно и намеренно не хранятся в репозитории.

Лицензия

Код проекта распространяется по лицензии MIT.

About

Ouroboros Demo: E2E процесс контроля соблюдения стандартов

Topics

gigaagenthackathonhuman-in-the-loopouroborospythonsql

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages