# oussemaha/llm_eval architecture

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

- Interactive diagram: https://gitdiagram.com/oussemaha/llm_eval
- Repository: https://github.com/oussemaha/llm_eval

## Overview

1. **Overall shape**
   This is a small **Python, script-based repo** rather than a multi-package application. The architecture appears centered on running an LLM evaluation or prompt-driven workflow from a command-line style entry point.

2. **Entry points**
   - `main.py` is the most likely **primary orchestrator**.
   - `a.py` looks like a secondary script or scratch/utility entry point.
   There is no sign of a web server, worker system, or multi-service deployment boundary.

3. **Core processing layer**
   - `preprocesing.py` is the main explicit processing module.
   - Based on the filename, it likely performs **input normalization, cleanup, and transformation** before prompt construction or evaluation.
   This is the main boundary between raw inputs and model-ready text.

4. **Prompt assets as a major subsystem**
   The `assets/prompts/` directory is a clear architectural component: it stores **task-specific prompt templates**.
   The presence of multiple prompt files suggests the system routes different input types to different prompting strategies.

5. **Prompt categories**
   The prompt set implies the repo handles several document or task classes:
   - `classification_prompt.txt`
   - `table_prompt.txt`
   - `lab_reports_prompt.txt`
   - `medical_images_prompt.txt`
   - `Hw_prescriptions_prompt.txt`
   - `unknown_prompt.txt`
   
   This indicates the application likely **classifies or interprets heterogeneous medical/clinical inputs** and falls back to an unknown/general prompt when the input type is unclear.

6. **Likely data flow**
   The observable flow is:
   **raw input → preprocessing → task/type selection → prompt template loading → LLM/evaluation step → output**
   The prompt assets act as the decision surface between preprocessing and downstream inference.

7. **Domain boundary**
   The naming strongly suggests a **medical or clinical text-processing domain**. If there are external model calls, they are probably abstracted behind the scripts rather than exposed as an API in this repo.

8. **Testing boundary**
   - `tests/test.py` is the only visible test file.
   - That suggests a lightweight test layer focused on validating core script behavior, prompt handling, or preprocessing logic rather than full integration testing.

9. **Repository organization**
   The repo is intentionally minimal:
   - top-level Python scripts for orchestration and preprocessing
   - static prompt templates under `assets/`
   - a small test area under `tests/`
   
   There is no evidence of separate service layers, persistence, or frontend components.

10. **What to show in an architecture diagram**
   A useful diagram would include:
   - **Script entry layer**: `main.py` and possibly `a.py`
   - **Processing layer**: `preprocesing.py`
   - **Prompt repository**: `assets/prompts/*`
   - **Test layer**: `tests/test.py`
   - **External dependency boundary**: any LLM or evaluation target, if used, sitting outside the repo

11. **Important caution**
   Because only filenames are available, the exact implementation details are not visible. The safest architectural interpretation is that this repo is a **prompt/template-driven evaluation utility**, with preprocessing and prompt selection as the main internal responsibilities.

Main entry points: [`assets/prompts`](https://github.com/oussemaha/llm_eval/tree/main/assets/prompts) (Prompt set), [`main.py`](https://github.com/oussemaha/llm_eval/blob/main/main.py) (main.py), [`preprocesing.py`](https://github.com/oussemaha/llm_eval/blob/main/preprocesing.py) (preprocesing.py), [`tests/test.py`](https://github.com/oussemaha/llm_eval/blob/main/tests/test.py) (tests/test.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scripts["Scripts"]
  node_main_py["main.py<br/>orchestrator<br/>[main.py]"]
  node_a_py["a.py<br/>utility script<br/>[a.py]"]
end

subgraph group_processing["Processing"]
  node_preprocesing_py["preprocesing.py<br/>preprocessing<br/>[preprocesing.py]"]
end

subgraph group_prompts["Prompts"]
  node_prompts_dir["Prompt set<br/>prompt assets"]
  node_classification_prompt["Classification<br/>prompt template"]
  node_table_prompt["Table<br/>prompt template<br/>[table_prompt.txt]"]
  node_lab_reports_prompt["Lab reports<br/>prompt template"]
  node_medical_images_prompt["Medical images<br/>prompt template"]
  node_hw_prescriptions_prompt["Prescriptions<br/>prompt template"]
  node_unknown_prompt["Unknown<br/>prompt template<br/>[unknown_prompt.txt]"]
end

subgraph group_tests["Tests"]
  node_tests_py["tests/test.py<br/>[test.py]"]
end

node_external_llm(("LLM / evaluator<br/>external dependency"))

node_main_py -->|"prepares input"| node_preprocesing_py
node_main_py -->|"loads prompts"| node_prompts_dir
node_main_py -->|"invokes"| node_external_llm
node_a_py -.->|"reuses"| node_preprocesing_py
node_preprocesing_py -->|"routes to"| node_prompts_dir
node_prompts_dir -->|"contains"| node_classification_prompt
node_prompts_dir -->|"contains"| node_table_prompt
node_prompts_dir -->|"contains"| node_lab_reports_prompt
node_prompts_dir -->|"contains"| node_medical_images_prompt
node_prompts_dir -->|"contains"| node_hw_prescriptions_prompt
node_prompts_dir -->|"contains"| node_unknown_prompt
node_tests_py -.->|"validates"| node_main_py
node_tests_py -.->|"validates"| node_preprocesing_py
node_tests_py -.->|"checks"| node_prompts_dir

click node_main_py "https://github.com/oussemaha/llm_eval/blob/main/main.py"
click node_a_py "https://github.com/oussemaha/llm_eval/blob/main/a.py"
click node_preprocesing_py "https://github.com/oussemaha/llm_eval/blob/main/preprocesing.py"
click node_prompts_dir "https://github.com/oussemaha/llm_eval/tree/main/assets/prompts"
click node_classification_prompt "https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/classification_prompt.txt"
click node_table_prompt "https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/table_prompt.txt"
click node_lab_reports_prompt "https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/lab_reports_prompt.txt"
click node_medical_images_prompt "https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/medical_images_prompt.txt"
click node_hw_prescriptions_prompt "https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/Hw_prescriptions_prompt.txt"
click node_unknown_prompt "https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/unknown_prompt.txt"
click node_tests_py "https://github.com/oussemaha/llm_eval/blob/main/tests/test.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_main_py,node_a_py toneBlue
class node_preprocesing_py toneAmber
class node_prompts_dir,node_classification_prompt,node_table_prompt,node_lab_reports_prompt,node_medical_images_prompt,node_hw_prescriptions_prompt,node_unknown_prompt toneMint
class node_tests_py toneRose
class node_external_llm toneNeutral
```

## Components

### Scripts

Command-line entry points and orchestration scripts

- [main.py](https://github.com/oussemaha/llm_eval/blob/main/main.py): orchestrator · Primary script that drives the workflow · `main.py`
- [a.py](https://github.com/oussemaha/llm_eval/blob/main/a.py): utility script · Secondary script or scratch entry point · `a.py`

### Processing

Input normalization and preparation

- [preprocesing.py](https://github.com/oussemaha/llm_eval/blob/main/preprocesing.py): preprocessing · Transforms raw inputs into model-ready form · `preprocesing.py`

### Prompts

Prompt template assets and task variants

- [Prompt set](https://github.com/oussemaha/llm_eval/tree/main/assets/prompts): prompt assets · Task-specific prompt templates used by the workflow · `assets/prompts`
- [Classification](https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/classification_prompt.txt): prompt template · Prompt for classification-oriented inputs · `assets/prompts/classification_prompt.txt`
- [Table](https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/table_prompt.txt): prompt template · Prompt for tabular inputs · `assets/prompts/table_prompt.txt`
- [Lab reports](https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/lab_reports_prompt.txt): prompt template · Prompt for laboratory report inputs · `assets/prompts/lab_reports_prompt.txt`
- [Medical images](https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/medical_images_prompt.txt): prompt template · Prompt for medical image-related inputs · `assets/prompts/medical_images_prompt.txt`
- [Prescriptions](https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/Hw_prescriptions_prompt.txt): prompt template · Prompt for prescription-like inputs · `assets/prompts/Hw_prescriptions_prompt.txt`
- [Unknown](https://github.com/oussemaha/llm_eval/blob/main/assets/prompts/unknown_prompt.txt): prompt template · Fallback prompt when input type is unclear · `assets/prompts/unknown_prompt.txt`

### Tests

Lightweight validation surface

- [tests/test.py](https://github.com/oussemaha/llm_eval/blob/main/tests/test.py): test · Basic test coverage for core script and prompt behavior · `tests/test.py`

### Other components

- **LLM / evaluator**: external dependency · Downstream model or evaluation target outside the repository

## Connections

- main.py → preprocesing.py: prepares input · Main workflow uses preprocessing before prompt construction
- main.py → Prompt set: loads prompts · Main workflow selects from the prompt asset set
- main.py → LLM / evaluator: invokes · Main workflow sends prepared prompts to an external model or evaluator
- a.py → preprocesing.py: reuses · Secondary script likely shares preprocessing logic
- preprocesing.py → Prompt set: routes to · Preprocessed content is matched to a prompt category
- Prompt set → Classification: contains · Prompt asset bundle includes the classification template
- Prompt set → Table: contains · Prompt asset bundle includes the table template
- Prompt set → Lab reports: contains · Prompt asset bundle includes the lab report template
- Prompt set → Medical images: contains · Prompt asset bundle includes the medical images template
- Prompt set → Prescriptions: contains · Prompt asset bundle includes the prescription template
- Prompt set → Unknown: contains · Prompt asset bundle includes the fallback template
- tests/test.py → main.py: validates · Tests likely exercise the main entry flow
- tests/test.py → preprocesing.py: validates · Tests likely cover preprocessing behavior
- tests/test.py → Prompt set: checks · Tests may verify prompt selection or loading
