# geisteswille/aicorpusx-python architecture

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

- Interactive diagram: https://gitdiagram.com/geisteswille/aicorpusx-python
- Repository: https://github.com/geisteswille/aicorpusx-python

## Overview

aicorpusx is a Python translation library for text, structured rows, and CSV/XLSX corpora. Callers use its public API for in-memory translation or the resumable `trans()` file workflow; that workflow prepares translation tasks, schedules concurrent provider requests, and writes translated results. Supporting branches cover glossary constraints, file/row I/O, resumable checkpoints, and progress display. The excerpts show the scheduler and several integrations, but omit portions of `_core.py`; unverified runtime calls are therefore not asserted as solid edges.

Main entry points: [`src/aicorpusx/_core.py`](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.py) (Translation workflows), [`src/aicorpusx/__init__.py`](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/__init__.py) (Package API), [`src/aicorpusx/_providers.py`](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_providers.py) (Provider adapter), [`src/aicorpusx/_io.py`](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_io.py) (Row I/O API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public interfaces"]
  node_public_api["Package API<br/>[__init__.py]"]
  node_translation_engine["Translation workflows<br/>[_core.py]"]
end

subgraph group_translation["Translation runtime"]
  node_scheduler["Concurrent scheduler<br/>[_core.py]"]
  node_provider["Provider adapter<br/>[_providers.py]"]
  node_glossary["Glossary matching<br/>[_glossary.py]"]
end

subgraph group_data["Corpus data"]
  node_table_adapters["Table adapters<br/>[_tables.py]"]
  node_row_io["Row I/O API<br/>[_io.py]"]
end

subgraph group_support["Runtime support"]
  node_progress["Progress reporting<br/>[_progress.py]"]
  node_json_checkpoint[("JSON checkpoint<br/>[_core.py]")]
  node_sqlite_checkpoint[("SQLite checkpoint<br/>[_core.py]")]
end

node_caller(("Python caller"))
node_source_files["CSV/XLSX corpus"]
node_provider_service["Chat-completions service"]

node_caller -->|"calls"| node_public_api
node_public_api -->|"exports"| node_translation_engine
node_translation_engine -->|"schedules tasks"| node_scheduler
node_scheduler -.->|"requests translation"| node_provider
node_provider -->|"sends requests"| node_provider_service
node_translation_engine -->|"loads terms"| node_glossary
node_translation_engine -.->|"uses tables"| node_table_adapters
node_row_io -->|"reads and writes"| node_table_adapters
node_caller -->|"calls"| node_row_io
node_source_files -.->|"provides corpus"| node_translation_engine
node_translation_engine -.->|"writes results"| node_source_files
node_translation_engine -->|"persists state"| node_json_checkpoint
node_translation_engine -->|"persists state"| node_sqlite_checkpoint
node_scheduler -->|"reports progress"| node_progress

click node_public_api "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/__init__.py"
click node_translation_engine "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.py"
click node_scheduler "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.py"
click node_provider "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_providers.py"
click node_glossary "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_glossary.py"
click node_progress "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_progress.py"
click node_table_adapters "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_tables.py"
click node_row_io "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_io.py"
click node_json_checkpoint "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.py"
click node_sqlite_checkpoint "https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.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_public_api,node_translation_engine toneBlue
class node_scheduler,node_provider,node_glossary toneAmber
class node_table_adapters,node_row_io toneMint
class node_progress,node_json_checkpoint,node_sqlite_checkpoint toneRose
class node_caller,node_source_files,node_provider_service toneIndigo
```

## Components

### Public interfaces

- [Package API](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/__init__.py): `src/aicorpusx/__init__.py`
- [Translation workflows](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.py): `src/aicorpusx/_core.py`

### Translation runtime

- [Concurrent scheduler](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.py): `src/aicorpusx/_core.py`
- [Provider adapter](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_providers.py): `src/aicorpusx/_providers.py`
- [Glossary matching](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_glossary.py): `src/aicorpusx/_glossary.py`

### Corpus data

- [Table adapters](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_tables.py): `src/aicorpusx/_tables.py`
- [Row I/O API](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_io.py): `src/aicorpusx/_io.py`

### Runtime support

- [Progress reporting](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_progress.py): `src/aicorpusx/_progress.py`
- [JSON checkpoint](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.py): `src/aicorpusx/_core.py`
- [SQLite checkpoint](https://github.com/geisteswille/aicorpusx-python/blob/main/src/aicorpusx/_core.py): `src/aicorpusx/_core.py`

### Other components

- **Python caller**
- **CSV/XLSX corpus**
- **Chat-completions service**

## Connections

- Python caller → Package API: calls (evidence: `README.md`)
- Package API → Translation workflows: exports (evidence: `src/aicorpusx/__init__.py`)
- Translation workflows → Concurrent scheduler: schedules tasks (evidence: `src/aicorpusx/_core.py`)
- Concurrent scheduler → Provider adapter: requests translation (evidence: `src/aicorpusx/_core.py`)
- Provider adapter → Chat-completions service: sends requests (evidence: `src/aicorpusx/_providers.py`)
- Translation workflows → Glossary matching: loads terms (evidence: `src/aicorpusx/_core.py`)
- Translation workflows → Table adapters: uses tables (evidence: `src/aicorpusx/_core.py`)
- Row I/O API → Table adapters: reads and writes (evidence: `src/aicorpusx/_io.py`)
- Python caller → Row I/O API: calls (evidence: `README.md`)
- CSV/XLSX corpus → Translation workflows: provides corpus
- Translation workflows → CSV/XLSX corpus: writes results
- Translation workflows → JSON checkpoint: persists state (evidence: `src/aicorpusx/_core.py`)
- Translation workflows → SQLite checkpoint: persists state (evidence: `src/aicorpusx/_core.py`)
- Concurrent scheduler → Progress reporting: reports progress (evidence: `src/aicorpusx/_core.py`)
