Criminal Sentence Calculation
Relevant source files
The following files were used as context for generating this wiki page:
Criminal Sentence Calculation is a system that estimates potential legal penalties based on messages analyzed for violations of the Russian Criminal Code (UK RF). It parses natural language punishment descriptions provided by AI models and aggregates them into numerical values representing years of imprisonment or life sentences.
The system integrates with the broader Criminal Code Analysis module to provide users and administrators with a quantitative measure of "legal risk" associated with chat history.
Architecture and Data Flow
The calculation process begins after a message is identified as a violation. The AI provider generates a CriminalAnalysisResult containing specific articles and their corresponding punishment descriptions. The CriminalCodeAnalyzerDO persists these results, which are later processed by the MessageFormatter and sentence-calculator utility for display in statistics.
Calculation Logic Flow
The system extracts maximum prison terms from strings such as "лишение свободы на срок до 15 лет" (imprisonment for up to 15 years) or "пожизненное лишение свободы" (life imprisonment). It specifically ignores non-prison penalties like fines or community service.
Sources: [src/features/criminal/sentence-calculator.ts](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/features/criminal/sentence-calculator.ts), [tests/criminal-sentence-calculator.test.ts:10-40](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/tests/criminal-sentence-calculator.test.ts#L10-L40)
Key Components
Sentence Calculator Utility
The core logic resides in sentence-calculator.ts. It uses regular expressions to identify prison terms and life sentence markers within the punishment field of a violation.
calculateSentenceFromPunishment(text: string): Parses a single punishment string.calculateSentenceFromViolationCount(violation: ViolationCount): Multiplies parsed terms by the number of times a user committed a specific violation.calculateSentenceFromViolationCounts(violations: ViolationCount[]): Sums the total years and life sentences across multiple different articles.
Sources: [src/features/criminal/sentence-calculator.ts](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/features/criminal/sentence-calculator.ts), [src/core/message-formatter.ts:182-200](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/core/message-formatter.ts#L182-L200)
Data Structures
The following structures define the inputs and outputs of the calculation system:
| Interface | Field | Type | Description |
|---|---|---|---|
SentenceTotal | totalYears | number | Total accumulated years of imprisonment. |
SentenceTotal | lifeSentences | number | Total count of life sentences. |
CriminalViolation | punishment | string | The raw text description of the penalty from the AI. |
ViolationCount | count | number | Frequency of a specific violation. |
Sources: [src/core/providers/ai-provider.ts:46-59](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/core/providers/ai-provider.ts#L46-L59), [src/features/criminal/sentence-calculator.ts](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/features/criminal/sentence-calculator.ts)
Integration with Statistics
The MessageFormatter class uses the calculator to enhance user and chat-wide reports. When displaying stats via commands like /my_criminal or /criminal_stats, the formatter includes a "Total Sentenced" (Итого напиздел) line.
In the formatUserStats and formatPeriodStats methods, the system generates specific lines for sentence totals. If a sentence cannot be parsed from the provided text, it returns "срок не распознан" (term not recognized).
Sources: [src/core/message-formatter.ts:182-192](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/core/message-formatter.ts#L182-L192), [src/features/stats/stats.ts:1050-1070](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/features/stats/stats.ts#L1050-L1070), [tests/criminal-sentence-calculator.test.ts:55-60](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/tests/criminal-sentence-calculator.test.ts#L55-L60)
Persistence and Storage
Violations and their associated punishments are stored in the Cloudflare D1 database. The criminal_violations table includes the punishment string and numerical severity.
Database Schema for Violations
| Field | Type | Description |
|---|---|---|
article | TEXT | The UK RF article number. |
punishment | TEXT | Raw text of the legal penalty. |
severity | INTEGER | Scale of 1-10 used for risk level calculation. |
violation_ts | INTEGER | Timestamp of the message. |
Sources: [src/durable-objects/criminal-code-analyzer-do.ts:1450-1480](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/durable-objects/criminal-code-analyzer-do.ts#L1450-L1480)
Summary of Calculation Behavior
- Maximum Term Preference: If a range is provided (e.g., "from 8 to 15 years"), the system selects the maximum value.
- Life Sentences: These are tracked as a separate integer count rather than a year value.
- Exclusions: Fines (штраф), compulsory labor (обязательные работы), and restriction of liberty (ограничение свободы) are ignored to ensure the "sentence" reflects only actual imprisonment.
- Aggregation: Personal totals sum the maximum penalty of every recorded violation instance for that user.
Sources: [src/features/criminal/sentence-calculator.ts](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/src/features/criminal/sentence-calculator.ts), [tests/criminal-sentence-calculator.test.ts:41-50](https://github.com/thesunwave/telegram_history_bot/blob/8ceb4acbbc11bb32f48d5786c6ae612021aef78d/tests/criminal-sentence-calculator.test.ts#L41-L50)
The Criminal Sentence Calculation system provides a gamified yet technically grounded view of potential legal consequences by converting qualitative AI-generated legal references into quantitative metrics. It relies on strict regex parsing of Russian legal terminology to maintain accuracy across different AI providers.