team-work-ai-Teyu

Powered by: Teyu Slava1111 discocat

(Была Student 2 у Slava1111)

Описание выполненной работы

В этом репозитории реализован небольшой аналитический сервис для обработки статического снимка метаданных GitHub‑репозиториев и предоставления статистики через Django REST API. Работа выполнена в несколько этапов:

• Анализ спецификации (
  codex.md
  ): были зафиксированы жёсткие ограничения (без ML, только агрегации и простая интерполяция, строгая схема входных данных, ISO 8601 даты, кэширование детерминированных результатов, обязательные поля
  data
  /
  meta
  и
  data_freshness
  в ответах).
• Проектирование структуры модуля: основная логика была вынесена в отдельный модуль
  solution.py
  , чтобы один и тот же код можно было использовать и как обычную Python‑библиотеку (в аналитических пайплайнах), и как часть Django/DRF‑приложения.
• Реализация аналитики: с помощью
  pandas
  реализованы функции для:
  • расчёта трендов по звёздам за период (месяц/квартал),
  • агрегирования статистики по языкам программирования,
  • оценки «здоровья» отдельного репозитория по активности, свежести и популярности.
• Интеграция с Django REST API: поверх аналитических функций добавлены классы‑представления DRF, реализующие эндпоинты
  /trending
  ,
  /languages
  ,
  /health/{repo_name}
  с обработкой ошибок и граничных случаев.
• Демонстрация и артефакты (
  demo/
  ): создана минимальная, но показательная конфигурация данных и скрипт, подтверждающие работоспособность и соответствие спецификации.

Структура репозитория

• codex.md
  
  Оригинальная спецификация системы: описание входных данных, ограничений, формата ответов и бизнес‑логики для эндпоинтов
  /trending
  ,
  /languages
  и
  /health/{repo_name}
  .

• solution.py
  
  Основной модуль проекта, включающий:
  • Загрузка и валидация данных:
    • load_repositories_from_csv
      ,
      load_repositories_from_json
      — функции чтения CSV/JSON со строгой проверкой схемы (обязательные поля, числовые типы, ISO 8601‑даты).
    • register_dataset
      — регистрация набора данных и установка метки актуальности (
      data_freshness
      ), а также сброс кэша.
  • Аналитические функции:
    • compute_trending_repositories(time_period, language=None, limit=10)
      — логика
      /trending
      : относительный прирост звёзд за указанный период (месяц/квартал) с аппроксимацией через линейную интерполяцию по времени существования репозитория.
    • compute_language_stats()
      — логика
      /languages
      : группировка по
      language
      , средние значения звёзд и медианный рост, формирование списка
      trending_languages
      .
    • compute_repo_health(repo_name)
      — логика
      /health/{repo_name}
      : вычисление показателей активности, свежести, популярности, итогового
      health_score
      и статуса.
  • Кэширование:
    • внутренний словарь
      _CACHE
      , где ключ зависит от версии данных (
      data_freshness
      ) и параметров запроса, а значения — готовые JSON‑совместимые структуры; это позволяет не пересчитывать детерминированные запросы.
  • Django REST API:
    • TrendingView
      ,
      LanguagesView
      ,
      HealthView
      — классы
      APIView
      , которые вызывают соответствующие аналитические функции, формируют ответы строго в формате
      { "data": ..., "meta": ... }
      и корректно обрабатывают ошибки (неверные параметры, отсутствие датасета, отсутствующий репозиторий).
  • Визуализация:
    • plot_top_languages_by_stars
      — вспомогательная функция для построения bar‑чарта по среднему количеству звёзд на язык (использует
      matplotlib
      , если он установлен).

• demo/
  
  Папка с артефактами, демонстрирующими, как использовать модуль:
  • sample_data.csv
    — небольшой статический снимок репозиториев по требуемой схеме (одна строка на репозиторий, все даты в ISO 8601, UTC).
  • example_responses.json
    — примерные JSON‑ответы для основных запросов, иллюстрирующие структуру
    data
    и
    meta
    , а также наличие
    data_freshness
    во всех случаях.

Как использовать написанный код

• Внутри Python‑скриптов / ноутбуков:

  • импортировать функции из
    solution.py
    ,
  • загрузить и зарегистрировать датасет,
  • вызывать аналитические функции напрямую (они не зависят от Django).

• В составе Django‑приложения:

  • добавить
    TrendingView
    ,
    LanguagesView
    ,
    HealthView
    в
    urls.py
    ,
  • позаботиться о том, чтобы
    register_dataset
    был вызван при старте приложения (или периодически, при обновлении данных),
  • использовать стандартный стек Django REST Framework для аутентификации/логирования/ограничения доступа при необходимости.

Таким образом, репозиторий содержит не только реализацию бизнес‑логики строго по спецификации, но и наглядные артефакты, демонстрирующие, как этот код применять на практике как в скриптовом режиме, так и через HTTP‑API.