# mmitaa/question_generator architecture

> Architecture diagram of the GitHub repository mmitaa/question_generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mmitaa/question_generator
- Repository: https://github.com/mmitaa/question_generator

## Overview

Это офлайн-инструмент для выявления повторяющихся правок институтов к типовому договору и подготовки рекомендаций юристу. Основной поток: пользователь запускает CLI с эталоном и договорами; тексты извлекаются и разбиваются на пункты, затем договоры сравниваются, изменения группируются в паттерны и превращаются в рекомендации, которые выводятся в Markdown и/или JSON. Claude и средства чтения PDF/DOC — необязательные интеграции. Связи отражают показанные вызовы и зависимости из индекса; несэмплированные реализации не исследовались.

Main entry points: [`contract_patterns/agent.py`](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/agent.py) (Анализатор), [`contract_patterns/cluster.py`](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/cluster.py) (Кластеризация правок), [`contract_patterns/recommend.py`](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/recommend.py) (Построение рекомендаций), [`contract_patterns/compare.py`](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/compare.py) (Сравнение договоров)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Запуск и управление"]
  node_cli["CLI<br/>[cli.py]"]
  node_main["Модульный запуск<br/>[__main__.py]"]
  node_agent["Анализатор<br/>[agent.py]"]
end

subgraph group_documents["Обработка договоров"]
  node_extract["Извлечение текста<br/>[extract.py]"]
  node_clauses["Разбор пунктов<br/>[clauses.py]"]
end

subgraph group_analysis["Анализ правок"]
  node_similarity["Метрики сходства<br/>[similarity.py]"]
  node_compare["Сравнение договоров<br/>[compare.py]"]
  node_cluster["Кластеризация правок<br/>[cluster.py]"]
  node_topics["Юридические темы<br/>[topics.py]"]
end

subgraph group_results["Рекомендации и отчёты"]
  node_recommend["Построение рекомендаций<br/>[recommend.py]"]
  node_llm["Обогащение Claude<br/>[llm.py]"]
  node_report["Markdown и JSON<br/>[report.py]"]
end

node_user(("Пользователь"))
node_claude{{"Claude API"}}
node_document_tools{{"PDF/DOC средства"}}

node_user -->|"запускает"| node_cli
node_main -->|"вызывает"| node_cli
node_cli -->|"запускает анализ"| node_agent
node_agent -->|"извлекает текст"| node_extract
node_agent -->|"разбирает документы"| node_clauses
node_agent -->|"строит векторизатор"| node_similarity
node_agent -->|"сравнивает версии"| node_compare
node_agent -->|"группирует правки"| node_cluster
node_agent -->|"строит рекомендации"| node_recommend
node_compare -->|"сопоставляет пункты"| node_clauses
node_compare -->|"считает сходство"| node_similarity
node_cluster -->|"токенизирует правки"| node_clauses
node_cluster -->|"группирует изменения"| node_compare
node_cluster -->|"сравнивает тексты"| node_similarity
node_cluster -->|"определяет темы"| node_topics
node_recommend -->|"обрабатывает паттерны"| node_cluster
node_recommend -->|"использует типы правок"| node_compare
node_recommend -->|"называет паттерны"| node_topics
node_cli -->|"формирует отчёт"| node_report
node_report -->|"читает документы"| node_clauses
node_report -->|"читает изменения"| node_compare
node_report -->|"читает рекомендации"| node_recommend
node_cli -->|"опционально обогащает"| node_llm
node_llm -->|"дополняет формулировки"| node_recommend
node_llm -->|"запрашивает пояснения"| node_claude
node_extract -.->|"опционально читает PDF/DOC"| node_document_tools

click node_cli "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/cli.py"
click node_main "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/__main__.py"
click node_agent "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/agent.py"
click node_extract "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/extract.py"
click node_clauses "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/clauses.py"
click node_similarity "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/similarity.py"
click node_compare "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/compare.py"
click node_cluster "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/cluster.py"
click node_topics "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/topics.py"
click node_recommend "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/recommend.py"
click node_llm "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/llm.py"
click node_report "https://github.com/mmitaa/question_generator/blob/main/contract_patterns/report.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_main,node_agent toneBlue
class node_extract,node_clauses toneAmber
class node_similarity,node_compare,node_cluster,node_topics,node_claude toneMint
class node_recommend,node_llm,node_report toneRose
class node_user,node_document_tools toneIndigo
```

## Components

### Запуск и управление

- [CLI](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/cli.py): `contract_patterns/cli.py`
- [Модульный запуск](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/__main__.py): `contract_patterns/__main__.py`
- [Анализатор](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/agent.py): `contract_patterns/agent.py`

### Обработка договоров

- [Извлечение текста](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/extract.py): `contract_patterns/extract.py`
- [Разбор пунктов](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/clauses.py): `contract_patterns/clauses.py`

### Анализ правок

- [Метрики сходства](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/similarity.py): `contract_patterns/similarity.py`
- [Сравнение договоров](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/compare.py): `contract_patterns/compare.py`
- [Кластеризация правок](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/cluster.py): `contract_patterns/cluster.py`
- [Юридические темы](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/topics.py): `contract_patterns/topics.py`

### Рекомендации и отчёты

- [Построение рекомендаций](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/recommend.py): `contract_patterns/recommend.py`
- [Обогащение Claude](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/llm.py): `contract_patterns/llm.py`
- [Markdown и JSON](https://github.com/mmitaa/question_generator/blob/main/contract_patterns/report.py): `contract_patterns/report.py`

### Other components

- **Пользователь**
- **Claude API**
- **PDF/DOC средства**

## Connections

- Пользователь → CLI: запускает (evidence: `contract_patterns/cli.py`)
- Модульный запуск → CLI: вызывает (evidence: `contract_patterns/__main__.py`)
- CLI → Анализатор: запускает анализ (evidence: `contract_patterns/cli.py`)
- Анализатор → Извлечение текста: извлекает текст (evidence: `contract_patterns/agent.py`)
- Анализатор → Разбор пунктов: разбирает документы (evidence: `contract_patterns/agent.py`)
- Анализатор → Метрики сходства: строит векторизатор (evidence: `contract_patterns/agent.py`)
- Анализатор → Сравнение договоров: сравнивает версии (evidence: `contract_patterns/agent.py`)
- Анализатор → Кластеризация правок: группирует правки (evidence: `contract_patterns/agent.py`)
- Анализатор → Построение рекомендаций: строит рекомендации (evidence: `contract_patterns/agent.py`)
- Сравнение договоров → Разбор пунктов: сопоставляет пункты (evidence: `contract_patterns/compare.py`)
- Сравнение договоров → Метрики сходства: считает сходство (evidence: `contract_patterns/compare.py`)
- Кластеризация правок → Разбор пунктов: токенизирует правки (evidence: `contract_patterns/cluster.py`)
- Кластеризация правок → Сравнение договоров: группирует изменения (evidence: `contract_patterns/cluster.py`)
- Кластеризация правок → Метрики сходства: сравнивает тексты (evidence: `contract_patterns/cluster.py`)
- Кластеризация правок → Юридические темы: определяет темы (evidence: `contract_patterns/cluster.py`)
- Построение рекомендаций → Кластеризация правок: обрабатывает паттерны (evidence: `contract_patterns/recommend.py`)
- Построение рекомендаций → Сравнение договоров: использует типы правок (evidence: `contract_patterns/recommend.py`)
- Построение рекомендаций → Юридические темы: называет паттерны (evidence: `contract_patterns/recommend.py`)
- CLI → Markdown и JSON: формирует отчёт (evidence: `contract_patterns/cli.py`)
- Markdown и JSON → Разбор пунктов: читает документы (evidence: `contract_patterns/report.py`)
- Markdown и JSON → Сравнение договоров: читает изменения (evidence: `contract_patterns/report.py`)
- Markdown и JSON → Построение рекомендаций: читает рекомендации (evidence: `contract_patterns/report.py`)
- CLI → Обогащение Claude: опционально обогащает (evidence: `contract_patterns/cli.py`)
- Обогащение Claude → Построение рекомендаций: дополняет формулировки (evidence: `contract_patterns/llm.py`)
- Обогащение Claude → Claude API: запрашивает пояснения (evidence: `contract_patterns/llm.py`)
- Извлечение текста → PDF/DOC средства: опционально читает PDF/DOC (evidence: `contract_patterns/extract.py`)
