eleutheria 1.1.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

# Services
eleutheria run              # Start all services (Docker)
eleutheria run -p full      # With monitoring (Prometheus + Grafana)
eleutheria stop             # Stop services
eleutheria status           # Check service health
eleutheria doctor           # Diagnose issues

# Search & Query
eleutheria search "Stoic fate"           # Search knowledge graph
eleutheria ask "What is free will?"      # Ask with GraphRAG
eleutheria ask -t "Complex question"     # Extended reasoning mode

# Explore Data
eleutheria stats            # Database statistics
eleutheria philosophers     # List philosophers
eleutheria concepts         # List concepts
eleutheria works -l grc     # List works by language

# Export/Import
eleutheria export kg        # Export knowledge graph
eleutheria export passages  # Export passages

# Development
eleutheria test all         # Run all tests
eleutheria lint --fix       # Lint + auto-fix
eleutheria quality          # Full quality check

# Quick Access
eleutheria web              # Open free-will.app
eleutheria docs             # Open documentation
eleutheria shell            # Interactive mode

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