eleutheria 1.0.0

Ancient Philosophy Knowledge Graph - CLI Tools

https://free-will.app

A FAIR-compliant knowledge graph for ancient philosophical debates on free will, fate, and moral responsibility (6th c. BCE - 6th c. CE)

Quick Start

# Install CLI
pip install eleutheria

# Clone and configure
git clone https://github.com/romain-girardi-eng/EleutherIA.git
cd EleutherIA
cp .env.example .env
# Add your API key(s) to .env

# Start all services
eleutheria run

Access: http://localhost (frontend) | http://localhost:8000/docs (API)

CLI Commands

eleutheria run              # Start all services (Docker)
eleutheria run -p full      # Start with monitoring (Prometheus + Grafana)
eleutheria stop             # Stop all services
eleutheria logs             # View logs
eleutheria dev -s backend   # Development mode (no Docker)
eleutheria dev -s frontend

eleutheria test all         # Run all tests
eleutheria test database    # Test specific package
eleutheria lint             # Check code quality
eleutheria lint --fix       # Auto-fix issues
eleutheria quality          # Full quality check

eleutheria info             # Show project stats
eleutheria --help           # All commands

The Three Systems

Package	Install	Purpose
database/	pip install eleutheria-database	Ancient Greek/Latin texts corpus (189 works, 17k passages)
kg/	pip install eleutheria-kg	Knowledge graph framework (2,193 nodes, 8,616 edges)
graphrag/	pip install eleutheria-graphrag	Graph-based RAG for scholarly Q&A

Install only what you need. Each package works independently.

Features

• Dual-layer structure: Primary layer (ancient sources) + secondary layer (modern scholarship)
• Hybrid search: Full-text + lemmatic + semantic search with RRF fusion
• GraphRAG: 5-stage RAG pipeline with citation grounding to ancient passages
• Lemmatization: Token-level analysis of Ancient Greek and Latin texts
• Interactive visualization: Cosmograph GPU-accelerated graph exploration

Documentation

Full documentation is available in the docs/ folder:

• Quick Start - Get running in 5 minutes
• Architecture - System design and components
• API Reference - REST API documentation
• Data Dictionary - Database schema reference
• Development Setup - Contributing guide

Tech Stack

• Backend: FastAPI + Python 3.11+ + PostgreSQL + Qdrant
• Frontend: React 19 + TypeScript + Vite + Tailwind CSS + Cosmograph
• LLM: Gemini 3 (primary) + Kimi K2.5 Thinking (extended reasoning)
• Deployment: Docker Compose

Statistics

Metric	Count
Knowledge graph nodes	2,193
Knowledge graph edges	8,616
Ancient works	189
Passages	16,968
Node types	15
Relation types	32

Citation

@software{girardi2025eleutheria,
  author       = {Girardi, Romain},
  title        = {EleutherIA: A FAIR-Compliant Knowledge Graph for Ancient Philosophy on Free Will},
  year         = 2025,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.17379490},
  url          = {https://doi.org/10.5281/zenodo.17379490}
}

License

CC BY 4.0 - See LICENSE

Links

• Full Documentation
• Dataset (Zenodo)
• Contributing