# vilsonkhchoian/promting_project_iad architecture

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

- Interactive diagram: https://gitdiagram.com/vilsonkhchoian/promting_project_iad
- Repository: https://github.com/vilsonkhchoian/promting_project_iad

## Overview

#### Purpose
Essay Checker Bot is a Telegram workflow for evaluating English exam essays against HSE-style criteria. A student submits an essay task and essay text; the system asks GigaChat for a 0–10 score plus feedback. Core runtime logic is in `bot.py`; provider and prompt settings are centralized in `config.py`.

#### Runtime Entry Point
`bot.py` is the executable application boundary. It receives Telegram updates, manages the multi-message checking interaction, invokes the LLM, and returns the generated assessment. `/start` begins a new evaluation and `/cancel` clears an in-progress one.

Paths: `bot.py`, `config.py`

#### Conversation-State Pipeline
The bot implements a sequential collection flow:
1. User starts a session.
2. Bot receives and retains the essay assignment.
3. Bot receives the essay body, including long responses.
4. The combined task/essay payload is submitted for evaluation.
5. The resulting score and comments are delivered back through Telegram.

This stateful chat boundary separates untrusted user input from the model request construction.

Paths: `bot.py`

#### Prompted Evaluation Layer
Evaluation behavior is driven by a prompt template and model-generation parameters: endpoint URLs, model selection, temperature, maximum tokens, and credentials. The intended rubric covers task response, cohesion, vocabulary/register, and grammar. Prompt design includes an injection-resistant variant and was empirically compared before being used in the bot.

Paths: `config.py`, `Промпты.pdf`, `bot.py`

#### External-Service Boundaries
Telegram is the inbound/outbound messaging transport; its bot token is configured outside application logic. GigaChat is the production inference provider, accessed through configured API endpoints and API credentials. The application depends on network availability and provider response formatting when producing a user-visible grade.

Paths: `bot.py`, `config.py`, `requirements.txt`

#### Offline Model and Prompt Evaluation
The notebook is the experimentation and validation environment rather than the serving path. It runs essay checks against GigaChat and OpenRouter-accessed models, retries poor responses, and calculates evaluation metrics. Its findings are persisted as spreadsheets: detailed per-essay/model/prompt results and aggregate ranking metrics such as MAE, RMSE, Spearman, and QWK.

Paths: `essay_prompt_project.ipynb`, `model_scores.xlsx`, `metrics_summary.xlsx`

#### Supporting Project Artifacts
Project documentation records the chosen criteria, candidate models, prompt variants, experimentation methodology, metrics, and prompt-injection considerations. These artifacts define the quality-governance context for future changes to the prompt or underlying model, but are not application runtime dependencies.

Paths: `Проект ПЗАД.pdf`, `Промпты.pdf`, `README.md`

Main entry points: [`essay_prompt_project.ipynb`](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/essay_prompt_project.ipynb) (Experiment notebook), [`bot.py`](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py) (Bot application), [`config.py`](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/config.py) (Provider and prompt settings), [`model_scores.xlsx`](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/model_scores.xlsx) (Detailed model scores)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Telegram Runtime"]
  node_student(("Student<br/>user"))
  node_bot["Bot application<br/>Python entry point<br/>[bot.py]"]
  node_session["Conversation state<br/>collection pipeline<br/>[bot.py]"]
  node_request["Evaluation request<br/>prompt payload<br/>[bot.py]"]
  node_config["Provider and prompt settings<br/>configuration module<br/>[config.py]"]
  node_assessment["Score and feedback<br/>generated assessment<br/>[bot.py]"]
  node_dependencies["Runtime dependencies<br/>package manifest<br/>[requirements.txt]"]
end

subgraph group_evaluation["Offline Evaluation"]
  node_notebook["Experiment notebook<br/>offline evaluation"]
  node_model_scores["Detailed model scores<br/>results spreadsheet<br/>[model_scores.xlsx]"]
  node_metrics["Ranking metrics<br/>metrics spreadsheet"]
end

subgraph group_external["External Services"]
  node_telegram{{"Telegram<br/>messaging transport"}}
  node_gigachat{{"GigaChat<br/>inference provider"}}
  node_openrouter{{"OpenRouter models<br/>inference provider"}}
end

subgraph group_artifacts["Quality Artifacts"]
  node_prompt_doc["Prompt variants<br/>prompt documentation<br/>[Промпты.pdf]"]
  node_project_doc["Project methodology<br/>project documentation<br/>[Проект ПЗАД.pdf]"]
  node_readme["Project README<br/>documentation<br/>[README.md]"]
end

node_student -->|"sends task and essay"| node_telegram
node_telegram -->|"delivers updates"| node_bot
node_bot -->|"collects sequential inputs"| node_session
node_session -->|"task + essay"| node_request
node_config -->|"supplies rubric prompt"| node_request
node_request -->|"submits evaluation"| node_gigachat
node_config -->|"endpoint, model, credentials"| node_gigachat
node_gigachat -->|"returns generated grade"| node_assessment
node_assessment -->|"formats response"| node_bot
node_bot -->|"sends assessment"| node_telegram
node_telegram -->|"delivers feedback"| node_student
node_dependencies -.->|"provides runtime libraries"| node_bot
node_notebook -->|"evaluates prompts"| node_gigachat
node_notebook -->|"compares models"| node_openrouter
node_notebook -->|"writes detailed results"| node_model_scores
node_notebook -->|"writes aggregate metrics"| node_metrics
node_prompt_doc -.->|"candidate prompts"| node_notebook
node_model_scores -->|"aggregated into rankings"| node_metrics
node_project_doc -.->|"defines evaluation methodology"| node_notebook
node_readme -.->|"project context"| node_project_doc

click node_bot "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py"
click node_session "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py"
click node_request "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py"
click node_config "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/config.py"
click node_assessment "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py"
click node_notebook "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/essay_prompt_project.ipynb"
click node_model_scores "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/model_scores.xlsx"
click node_metrics "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/metrics_summary.xlsx"
click node_prompt_doc "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/%D0%9F%D1%80%D0%BE%D0%BC%D0%BF%D1%82%D1%8B.pdf"
click node_project_doc "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/%D0%9F%D1%80%D0%BE%D0%B5%D0%BA%D1%82%20%D0%9F%D0%97%D0%90%D0%94.pdf"
click node_readme "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/README.md"
click node_dependencies "https://github.com/vilsonkhchoian/promting_project_iad/blob/main/requirements.txt"

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_student,node_bot,node_session,node_request,node_config,node_assessment,node_dependencies toneBlue
class node_notebook,node_model_scores,node_metrics toneAmber
class node_telegram,node_gigachat,node_openrouter toneMint
class node_prompt_doc,node_project_doc,node_readme toneRose
```

## Components

### Telegram Runtime

Production essay-checking workflow.

- **Student**: user
- [Bot application](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py): Python entry point · Manages commands, state, LLM calls, and replies. · `bot.py`
- [Conversation state](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py): collection pipeline · Retains assignment then essay body before evaluation. · `bot.py`
- [Evaluation request](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py): prompt payload · Combines the task and essay as model input. · `bot.py`
- [Provider and prompt settings](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/config.py): configuration module · Defines rubric prompt, model parameters, endpoints, and credentials. · `config.py`
- [Score and feedback](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/bot.py): generated assessment · 0–10 grade with rubric-based comments. · `bot.py`
- [Runtime dependencies](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/requirements.txt): package manifest · Declares Telegram and provider client dependencies. · `requirements.txt`

### Offline Evaluation

Prompt and model validation workflow.

- [Experiment notebook](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/essay_prompt_project.ipynb): offline evaluation · Compares prompts and models, retries responses, and calculates metrics. · `essay_prompt_project.ipynb`
- [Detailed model scores](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/model_scores.xlsx): results spreadsheet · Per-essay, model, and prompt outcomes. · `model_scores.xlsx`
- [Ranking metrics](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/metrics_summary.xlsx): metrics spreadsheet · MAE, RMSE, Spearman, and QWK summaries. · `metrics_summary.xlsx`

### External Services

- **Telegram**: messaging transport · Inbound and outbound chat transport.
- **GigaChat**: inference provider · Production scoring and feedback provider.
- **OpenRouter models**: inference provider · Alternative models evaluated offline.

### Quality Artifacts

- [Prompt variants](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/%D0%9F%D1%80%D0%BE%D0%BC%D0%BF%D1%82%D1%8B.pdf): prompt documentation · Includes injection-resistant prompt designs. · `Промпты.pdf`
- [Project methodology](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/%D0%9F%D1%80%D0%BE%D0%B5%D0%BA%D1%82%20%D0%9F%D0%97%D0%90%D0%94.pdf): project documentation · Records criteria, models, methodology, and governance. · `Проект ПЗАД.pdf`
- [Project README](https://github.com/vilsonkhchoian/promting_project_iad/blob/main/README.md): documentation · `README.md`

## Connections

- Student → Telegram: sends task and essay
- Telegram → Bot application: delivers updates
- Bot application → Conversation state: collects sequential inputs
- Conversation state → Evaluation request: task + essay
- Provider and prompt settings → Evaluation request: supplies rubric prompt
- Evaluation request → GigaChat: submits evaluation
- Provider and prompt settings → GigaChat: endpoint, model, credentials
- GigaChat → Score and feedback: returns generated grade
- Score and feedback → Bot application: formats response
- Bot application → Telegram: sends assessment
- Telegram → Student: delivers feedback
- Runtime dependencies → Bot application: provides runtime libraries
- Experiment notebook → GigaChat: evaluates prompts
- Experiment notebook → OpenRouter models: compares models
- Experiment notebook → Detailed model scores: writes detailed results
- Experiment notebook → Ranking metrics: writes aggregate metrics
- Prompt variants → Experiment notebook: candidate prompts
- Detailed model scores → Ranking metrics: aggregated into rankings
- Project methodology → Experiment notebook: defines evaluation methodology
- Project README → Project methodology: project context