ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Реализовать component registry

1. Цель задачи

Создать реестр компонентов (component registry) для управления версиями промптов, инструментов и конфигураций AI-пайплайнов. Решение должно обеспечить централизованное хранение, версионирование и возможность отката к предыдущим версиям компонентов без простоя системы. Ключевой результат работоспособный registry, интегрированный с CI/CD, позволяющий откатить любой компонент к предыдущей версии командой git revert или API-запросом.

2. Исходные данные

Если нет реального проекта — симулируем:

1. Создать новый Git-репозиторий
2. Сгенерировать 5 версий промпта (например, изменения в системном сообщении)
3. Создать 3 версии инструмента (разные реализации поиска)
4. Создать 3 конфига (разные параметры top_k, model)
5. Описать структуру registry в YAML/JSON

3. Технологический стек

4. Этапы выполнения

Этап 1: Проектирование схемы registry (1 час)

Действия

1. Определить типы компонентов: prompt, tool, config
2. Спроектировать схему записей для каждого типа:

# Пример записи для промпта
component:
  id: prompt-sys-intent-1
  type: prompt
  name: system_intent_v1
  version: 1.0.2
  hash: sha256:abc123
  content: "You are a helpful assistant..."
  created_at: 2025-04-01T10:00:00Z
  created_by: user1
  tags: ["production", "v1.0"]
  parent_version: 1.0.1

3. Выбрать формат хранения registry: YAML-файл в репозитории (registry.yaml) или SQLite БД (registry.db)
4. Описать API (CRUD):
   • POST /register
   • GET /versions/{component_id}
   • POST /rollback/{component_id}/{version}
   • GET /diff?from=1.0.1&to=1.0.2

Ожидаемый результат этапа Документ со схемой данных и API (OpenAPI spec или описание).

Этап 2: Реализация CLI и логики версионирования (2-3 часа)

Действия

1. Реализовать функцию register(component_type, content, metadata)
   • Вычислить хеш содержимого (SHA256)
   • Создать или обновить запись в registry
   • Автоматически инкрементировать версию (semver minor)
2. Реализовать list_versions(component_id)
   • Вернуть все версии с датами и хешами
3. Реализовать rollback(component_id, target_version)
   • Скопировать содержимое целевой версии как текущую
   • Создать новую запись с обновлением parent
   • Гарантировать, что откат сам версионируется
4. CLI интерфейс (click):

@click.group()
def cli(): pass

@cli.command()
@click.option('--type', required=True)
@click.option('--file', required=True)
def register(type, file):
    # чтение файла, регистрация
    pass

@cli.command()
@click.argument('component_id')
def versions(component_id):
    # вывод списка версий
    pass

@cli.command()
@click.argument('component_id')
@click.argument('version')
def rollback(component_id, version):
    # откат
    pass

5. Написать юнит-тесты для функций register, rollback, list_versions.

Ожидаемый результат этапа Рабочий CLI, который может регистрировать, просматривать и откатывать компоненты.

Этап 3: Интеграция с Git и CI/CD (2 часа)

Действия

1. Добавить pre-commit hook (опционально):
   • При коммите изменений в папке components/ автоматически вызывать cli register
   • Или как часть CI: GitHub Action на push
2. Создать GitHub Action workflow .github/workflows/registry.yml:

name: Component Registry
on:
  push:
    paths:
      - 'components/**'
jobs:
  register:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install click pyyaml
      - run: python -m cli register --type prompt --file components/prompts/system.yaml

3. Добавить команду validate — проверяет корректность структуры файла (Pydantic schema).
4. Реализовать автоматическую генерацию diff при pull request (comment с изменениями).

Ожидаемый результат этапа При каждом изменении компонента в репозитории автоматически регистрируется новая версия.

Этап 4: Реализация API (2 часа)

Действия

1. Создать FastAPI приложение с эндпоинтами:
   • GET /api/v1/registry/{component_id} — последняя версия
   • GET /api/v1/registry/{component_id}/versions — все версии
   • POST /api/v1/registry/{component_id}/rollback — откат
   • POST /api/v1/registry/register — регистрация
2. Добавить аутентификацию (API key простой).
3. Добавить swagger docs (встроено в FastAPI).
4. Протестировать curl запросы.

Ожидаемый результат этапа Рабочее API, доступное для интеграции с пайплайнами.

Этап 5: Тестирование отката и документирование (1 час)

Действия

1. Симулировать сценарий
   • Зарегистрировать версию 1.0.0 промпта
   • Обновить и зарегистрировать 1.0.1 (с ошибкой)
   • Выполнить rollback to 1.0.0
   • Проверить, что текущая версия содержит контент 1.0.0
2. Проверить, что откат не удаляет историю — версия 1.0.1 остаётся доступной
3. Написать README с инструкцией по использованию CLI и API.
4. Добавить пример отката в README:

# После обнаружения проблемы
python registry_cli.py rollback prompt-main 1.0.0
# Результат: создана версия 1.0.2, содержимое совпадает с 1.0.0

Ожидаемый результат этапа Документация, тесты, подтверждённая возможность отката.

5. Критерии приемки (Definition of Done)

• Registry хранит историю изменений для каждого компонента (промпт, инструмент, конфиг)
• Возможность зарегистрировать новую версию через CLI одной командой
• Возможность откатить любой компонент к предыдущей любой версии
• Откат создаёт новую запись в истории (не перезаписывает)
• Интеграция с CI/CD — автоматическая регистрация при push изменений
• REST API с документацией (OpenAPI)
• Юнит-тесты покрывают не менее 80% функций регистрации и отката
• README с инструкцией по установке и использованию
• Возможность просмотреть diff между любыми двумя версиями (через git diff)
• Все компоненты имеют уникальный ID и валидную схему

6. Ожидаемый результат

Основной артефакт Git-репозиторий с кодом:

• src/registry.py — логика registry
• src/cli.py — CLI интерфейс
• src/api.py — FastAPI приложение
• components/ — примеры компонентов
• registry.yaml или registry.db — файл registry
• .github/workflows/registry.yml — CI пайплайн
• tests/test_registry.py — юнит-тесты
• README.md — документация

Дополнительные результаты

• Возможность использовать registry в других пайплайнах (HTTP-вызовы)
• Демонстрация rollback на примере

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание: Для первого выполнения задачи заложите 12 часов (непредвиденные сложности).

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я спроектировал схему registry с учётом типов (prompt, tool, config) и версий
• Я реализовал CLI с командами register, versions, rollback
• Я проверил, что после rollback содержимое файла соответствует целевой версии
• Я добавил CI/CD: при изменении в components/ регистрируется новая версия
• Я написал README с примерами использования и инструкцией по развёртыванию