AI-powered deep literary analysis and interactive visualization of Shota Rustaveli's 12th-century Georgian epic poem.
This project uses GPT-4.1-mini with structured outputs to perform comprehensive analysis of all 65 chapters of Vepkhistkaosani, then presents the results as an interactive dark-themed web visualization with Chart.js and D3.js.
The Python backend performs 7 types of analysis:
| Analysis | Method | Description |
|---|---|---|
| Structural | Pure Python | Strophe/line/word counts per chapter |
| Lexical | Pure Python | Word frequency, hapax legomena, vocabulary richness |
| Per-Chapter | LLM (65 calls) | Themes, emotions, tension, characters, colors, geography, poetic devices |
| Character Profiles | LLM | Big Five personality traits, relationships, signature quotes |
| Symbol System | LLM | Animal, celestial, natural, color symbolism with philosophical mapping |
| Intertextual | LLM | Biblical, Neoplatonic, Sufi, Persian literary connections |
| Meta-Analysis | LLM | Narrative arc, thematic evolution, literary significance |
All results are merged into a single output/stats.json (1.3MB) that powers the web visualization.
data.txt ──> parser.py ──> Poem object
│
┌──────────┼──────────┐
│ │ │
structural.py lexical.py LLM analyzers
(pure Python) (pure Python) │
│ │ ┌──────┼──────────────┐
│ │ │ │ │
│ │ chapter character symbol
│ │ analyzer profiler analyzer
│ │ │ │ │
│ │ │ intertextual meta_analyzer
│ │ │ │ │
└──────────┴─────┴──────┴──────────────┘
│
merger.py ──> output/stats.json
git clone https://github.com/shoti/vefxistkaosani.git
cd vefxistkaosani
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # Add your OpenAI API key
python -m src.main~$2–3 USD for a full run with GPT-4.1-mini. Cached responses are stored in output/raw/ — re-running skips completed analyses.
Key settings in src/config.py (overridable via .env):
| Setting | Default | Description |
|---|---|---|
model |
gpt-4.1-mini |
OpenAI model |
temperature |
0.0 |
Deterministic output |
seed |
42 |
Reproducibility seed |
batch_size |
5 |
Concurrent API calls |
skip_cached |
True |
Reuse cached responses |
Interactive dark-themed visualization built with vanilla JavaScript (ES modules), Chart.js 4, and D3.js 7.
- Hero — Poem stats with floating Georgian letter background
- Emotional Arc — 10 emotions tracked across 65 chapters (line chart)
- Characters — Character profiles, heatmap, relationship network (D3 force), Big Five radar
- Tears & Drama — Crying, fainting, dramatic events (bar chart)
- Dialogue & Narration — Speaker analysis with frequency bars
- Color Palette — Color mentions with bubble visualization
- Poetic Craftsmanship — Rhyme/meter quality + rhetorical devices
- Narrative Tension — Tension curve with climax annotation
- Nature Imagery — Celestial, flora, fauna, elements (stacked area)
- Poem Architecture — Strophe counts + lexical diversity per chapter
- Geography — Mentioned places with leaderboard bars
The web visualization is a static site — just serve the web/ directory:
cd web
python -m http.server 8000
# Open http://localhost:8000The visualization reads web/output/stats.json. This file is pre-generated by the Python pipeline.
├── data.txt # Source poem text (~65 chapters)
├── requirements.txt # Python dependencies
├── .env.example # Environment template
├── src/ # Python analysis pipeline
│ ├── main.py # Pipeline orchestrator
│ ├── config.py # Settings (pydantic-settings)
│ ├── parser.py # Poem parser (Line/Strophe/Chapter)
│ ├── models.py # Pydantic v2 data models
│ ├── utils.py # Georgian text helpers
│ ├── merger.py # Result aggregation
│ ├── llm/
│ │ ├── client.py # Async OpenAI client with retry & cost tracking
│ │ ├── prompts.py # Prompt template loader
│ │ └── response_cache.py # File-based response cache
│ └── analyzers/
│ ├── structural.py # Strophe/line/word counts
│ ├── lexical.py # Word frequency & richness
│ ├── chapter_analyzer.py # Per-chapter LLM analysis
│ ├── character_profiler.py # Character psychological profiles
│ ├── symbol_analyzer.py # Symbol & metaphor system
│ ├── intertextual.py # Cross-text references
│ └── meta_analyzer.py # Narrative arc & themes
├── prompts/ # LLM prompt templates
├── tests/ # Unit tests
├── docs/ # Data schema documentation
├── web/ # Frontend visualization
│ ├── index.html
│ ├── assets/ # Favicon, preview image
│ ├── css/ # Dark theme stylesheets
│ ├── js/
│ │ ├── app.js # Main orchestrator
│ │ ├── i18n.js # Internationalization
│ │ ├── charts/ # Chart.js visualizations
│ │ ├── sections/ # Dynamic content modules
│ │ └── utils/ # Animations, theme, helpers
│ └── output/
│ └── stats.json # Analysis data (consumed by web)
└── output/ # Pipeline output (gitignored)
├── stats.json
└── raw/ # Cached API responses
- All API responses cached in
output/raw/with full metadata - Prompt templates versioned in
prompts/with SHA-256 hashing - Deterministic settings:
temperature=0.0,seed=42
pip install pytest
pytest tests/ -v| Layer | Technology |
|---|---|
| Analysis | Python 3.9+, OpenAI API, Pydantic v2 |
| Charts | Chart.js 4, D3.js 7 |
| Frontend | Vanilla JavaScript (ES modules) |
| Styling | CSS custom properties, dark theme |
Shota Mtvarelishvili — mtvarelishvili.com
This project is for educational and research purposes. The poem text (Vepkhistkaosani) is in the public domain.