### Install Project Packages

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Installs all project packages in editable mode using the 'make install' command. Alternatively, packages can be installed individually by navigating to their respective directories and using pip or npm.

```bash
make install

# Or individually:
# Database package
cd database && pip install -e ".[dev]"

# KG package
cd kg && pip install -e ".[dev]"

# GraphRAG package
cd graphrag && pip install -e ".[dev,llm]"

# Frontend
cd frontend && npm install
```

--------------------------------

### Manually Start Development Services

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Manually starts the PostgreSQL and Qdrant databases using Docker, followed by the backend API and frontend development server. This option is useful if Docker Compose is not preferred or available.

```bash
# Start PostgreSQL and Qdrant:
docker run -d -p 5432:5432 \
  -e POSTGRES_USER=eleutheria \
  -e POSTGRES_PASSWORD=eleutheria \
  -e POSTGRES_DB=eleutheria \
  postgres:16-alpine

docker run -d -p 6333:6333 qdrant/qdrant

# Start backend:
cd graphrag
uvicorn eleutheria_graphrag.api:router --reload --port 8000

# Start frontend:
cd frontend
npm run dev
```

--------------------------------

### Start Development Services with Docker

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Starts the development services using Docker Compose, which is the recommended method. This command brings up all necessary services like databases and backend applications in detached mode.

```bash
make dev
# Or: docker compose -f deploy/docker/docker-compose.dev.yml up -d
```

--------------------------------

### Install and Set Up Pre-commit Hooks

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Installs the 'pre-commit' package and sets up the Git pre-commit hooks for the project. These hooks automatically run checks like linting and secret detection before each commit.

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Copies the example environment file and prompts the user to edit it with necessary API keys. This step is crucial for configuring external service integrations.

```bash
cp .env.example .env
# Edit .env with your API keys
```

--------------------------------

### Install and Run EleutherIA CLI

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/README.md

This snippet shows how to install the EleutherIA command-line interface using pip, clone the repository, configure environment variables, and start all services using Docker. It's the primary method for getting the system up and running.

```bash
# 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
```

--------------------------------

### Start EleutherIA Services with Docker Compose

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/guides/QUICK_START.md

Starts the EleutherIA services using either the 'make run' command or Docker Compose. This command brings up all necessary containers for the application to function.

```bash
make run
# Or:
docker compose -f deploy/docker/docker-compose.yml up -d
```

--------------------------------

### Troubleshoot Port Conflicts

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Provides commands to check which processes are using specific ports, which is useful for resolving port conflicts when starting development services. Examples are given for PostgreSQL, Qdrant, backend, and frontend ports.

```bash
# Check what's using ports
lsof -i :5432  # PostgreSQL
lsof -i :6333  # Qdrant
lsof -i :8000  # Backend
lsof -i :5173  # Frontend
```

--------------------------------

### Configure EleutherIA Environment Variables

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/guides/QUICK_START.md

Copies the example environment file and instructs the user to edit it, specifically to add LLM API keys (Gemini, Kimi, or OpenRouter). This step is crucial for enabling the application's AI functionalities.

```bash
cp .env.example .env
# Edit .env and add at least one API key:
# GEMINI_API_KEY=your-key-here
# MOONSHOT_API_KEY=your-key-here
# OPENROUTER_API_KEY=your-key-here
```

--------------------------------

### Install EleutherIA Python Packages

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/guides/QUICK_START.md

Installs individual EleutherIA Python packages using pip. This allows developers to use EleutherIA's functionalities within their Python projects.

```bash
pip install eleutheria-database
pip install eleutheria-kg
pip install eleutheria-graphrag[llm]
```

--------------------------------

### Clone EleutherIA Repository

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/guides/QUICK_START.md

Clones the EleutherIA repository from GitHub and navigates into the project directory. This is the first step in setting up the project locally.

```bash
git clone https://github.com/romain-girardi-eng/EleutherIA.git
cd EleutherIA
```

--------------------------------

### Query GraphRAG (Streaming) Example (Bash)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

An example using curl to make a GET request to the streaming GraphRAG query endpoint. It shows how to pass the question parameter in the URL and retrieve the SSE stream.

```bash
curl -N "http://localhost:8000/api/graphrag/query/stream?question=What%20is%20fate"
```

--------------------------------

### Run All Project Tests

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Executes all unit and integration tests for the project using the 'make test' command. This verifies the functionality of different components.

```bash
make test
```

--------------------------------

### Install EleutherIA Python Packages

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/examples/README.md

Installs the necessary EleutherIA Python packages for database, knowledge graph, and graphrag functionalities. The graphrag package includes optional LLM support.

```python
pip install eleutheria-database eleutheria-kg eleutheria-graphrag[llm]
```

--------------------------------

### Run Basic Python Query Example

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/examples/README.md

Executes a basic query example using the EleutherIA Python packages. This demonstrates how to interact with the EleutherIA functionalities through Python.

```python
python examples/python/basic_query.py
```

--------------------------------

### Get Knowledge Graph Node Neighbors Example (Bash)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

Example using curl to retrieve neighbors of the 'chrysippus' node up to a depth of 2.

```bash
curl "http://localhost:8000/api/kg/nodes/chrysippus/neighbors?depth=2"
```

--------------------------------

### List Knowledge Graph Nodes Example (Bash)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

Example using curl to list Person nodes belonging to the Stoic school from the knowledge graph.

```bash
curl "http://localhost:8000/api/kg/nodes?node_type=Person&school=Stoic"
```

--------------------------------

### Connect and Query Ancient Works with EleutherIA Python Packages

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/guides/QUICK_START.md

Demonstrates how to connect to the EleutherIA database and fetch ancient works based on specific criteria using Python. It requires the 'eleutheria-database' package.

```python
from eleutheria_database import DatabaseService

# Connect
db = DatabaseService()
await db.connect()

# Query ancient works
works = await db.fetch("""
    SELECT title, author FROM free_will.ancient_works
    WHERE school = 'Stoic' LIMIT 10
""")
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Executes all project tests and generates a code coverage report using the 'make test-coverage' command. This helps identify areas of the codebase that are not adequately tested.

```bash
make test-coverage
```

--------------------------------

### Install EleutherIA Packages

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/README.md

This table outlines the core packages for EleutherIA, including their installation commands via pip and their primary purpose. Users can install specific packages based on their needs, as each package functions independently.

```bash
pip install eleutheria-database
pip install eleutheria-kg
pip install eleutheria-graphrag
```

--------------------------------

### Troubleshoot Database Connection

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Offers commands to test the PostgreSQL connection and to reset the database using Docker Compose. This helps in diagnosing and resolving issues related to database connectivity.

```bash
# Test PostgreSQL
psql -h localhost -U eleutheria -d eleutheria

# Reset database
docker compose -f deploy/docker/docker-compose.dev.yml down -v
docker compose -f deploy/docker/docker-compose.dev.yml up -d
```

--------------------------------

### Install EleutherIA Packages (Bash)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/INDEX.md

Installs the three core packages of the EleutherIA project using pip. Each package can be installed independently.

```bash
pip install eleutheria-database   # Ancient texts corpus
pip install eleutheria-kg         # Knowledge graph framework
pip install eleutheria-graphrag   # Graph-based RAG
```

--------------------------------

### VS Code IDE Settings

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Provides recommended VS Code extensions and settings for Python development within the EleutherIA project. This includes configuring the Python interpreter, type checking mode, and formatter.

```json
{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}
```

--------------------------------

### Troubleshoot Import Errors

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Provides instructions to reinstall packages in editable mode to resolve import errors. This is often necessary after making changes to the project structure or dependencies.

```bash
# Reinstall packages in editable mode
pip install -e database/
pip install -e kg/
pip install -e graphrag/
```

--------------------------------

### Install eleutheria-database Package

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/database/README.md

Installs the eleutheria-database package using pip. Includes options for development dependencies and FastAPI integration.

```bash
pip install eleutheria-database

```

```bash
pip install eleutheria-database[dev]

```

```bash
pip install eleutheria-database[api]

```

--------------------------------

### Run Tests for Individual Packages

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Runs tests specifically for individual packages within the EleutherIA project, such as database, kg, or graphrag. This allows for targeted testing during development.

```bash
make test-database
make test-kg
make test-graphrag
```

--------------------------------

### Rate Limit Headers Example

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

Example HTTP headers indicating the current status of API rate limits. These headers help clients manage their request frequency to avoid exceeding limits.

```http
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1706644800
```

--------------------------------

### Install eleutheria-kg Package

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/kg/README.md

Installs the core eleutheria-kg Python package using pip. Additional dependencies for community detection or FastAPI integration can be installed using optional extras.

```bash
pip install eleutheria-kg

```

```bash
pip install eleutheria-kg[community]

```

```bash
pip install eleutheria-kg[api]

```

--------------------------------

### Query GraphRAG (Non-Streaming) Example (Bash)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

An example using curl to send a POST request to the non-streaming GraphRAG query endpoint. It demonstrates how to structure the request body with a question and other parameters like semantic_k, graph_depth, and include_passages.

```bash
curl -X POST "http://localhost:8000/api/graphrag/query" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What did the Stoics believe about fate and moral responsibility?",
    "semantic_k": 15,
    "graph_depth": 2,
    "include_passages": true
  }'
```

--------------------------------

### Search Passages Example (Bash)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

Example of how to use curl to search for passages related to 'εἱμαρμένη' in Greek, with a limit of 20 results.

```bash
curl "http://localhost:8000/api/search?q=εἱμαρμένη&language=grc&limit=20"
```

--------------------------------

### Install eleutheria-graphrag Package

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/graphrag/README.md

Installs the core eleutheria-graphrag package using pip. Additional dependencies for LLM providers or FastAPI integration can be installed using optional extras.

```bash
pip install eleutheria-graphrag
```

```bash
pip install eleutheria-graphrag[llm]
```

```bash
pip install eleutheria-graphrag[api]
```

--------------------------------

### GraphRAG Streaming Client Example (JavaScript)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

A JavaScript example demonstrating how to consume the Server-Sent Events (SSE) stream from the GraphRAG query endpoint. It uses the EventSource API to handle incoming messages, process data, and close the connection when '[DONE]' is received.

```javascript
const eventSource = new EventSource(
  '/api/graphrag/query/stream?question=What%20is%20fate'
);

eventSource.onmessage = (event) => {
  if (event.data === '[DONE]') {
    eventSource.close();
  } else if (event.data.startsWith('[ERROR]')) {
    console.error(event.data);
    eventSource.close();
  } else {
    process.stdout.write(event.data);
  }
};
```

--------------------------------

### Quick Start: Analyze Knowledge Graph with Python

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/kg/README.md

Demonstrates how to use the eleutheria-kg library to connect to services, load knowledge graph data, and perform analysis such as calculating statistics, detecting communities, and finding centrality. It also shows how to perform semantic search using Qdrant.

```python
from eleutheria_kg import KGAnalytics, QdrantService
from eleutheria_database import DatabaseService

# Connect to services
db = DatabaseService()
qdrant = QdrantService()
await db.connect()
await qdrant.connect()

# Load knowledge graph
kg_data = await load_kg_from_database(db)

# Analyze graph
analytics = KGAnalytics(kg_data)

# Get node statistics
stats = analytics.get_statistics()
print(f"Nodes: {stats['total_nodes']}, Edges: {stats['total_edges']}")

# Find communities
communities = analytics.detect_communities(algorithm="leiden")

# Calculate centrality
centrality = analytics.calculate_centrality(metric="betweenness")

# Semantic search
results = await qdrant.search_nodes(query_embedding, limit=10)

```

--------------------------------

### Quick Start: Initialize and Query GraphRAG Service

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/graphrag/README.md

Demonstrates how to initialize the GraphRAGService by connecting to database and Qdrant services, loading the knowledge graph, and performing a query. It shows how to retrieve both the answer and its sources.

```python
from eleutheria_graphrag import GraphRAGService
from eleutheria_database import DatabaseService
from eleutheria_kg import QdrantService

# Connect services
db = DatabaseService()
qdrant = QdrantService()
await db.connect()
await qdrant.connect()

# Initialize GraphRAG
graphrag = GraphRAGService(db, qdrant)
await graphrag.load_kg()

# Ask a question
result = await graphrag.query(
    "What did the Stoics believe about fate and free will?"
)

print(result["answer"])
print(f"Sources: {result['citations']}")
```

--------------------------------

### Quick Start: Connect and Fetch Data with Python

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/database/README.md

Demonstrates how to connect to the database, fetch ancient works by language, and retrieve passages authored by a specific person using SQL queries. Requires the `eleutheria_database` library.

```python
from eleutheria_database import DatabaseService

# Connect to database
db = DatabaseService()
await db.connect()

# Fetch ancient works
works = await db.fetch("""
    SELECT work_id, title, author, language
    FROM free_will.ancient_works
    WHERE language = 'grc'
    LIMIT 10
""")

# Fetch passages with CTS URN
passages = await db.fetch("""
    SELECT p.passage_id, p.text_content, p.cts_urn, w.title
    FROM free_will.passages p
    JOIN free_will.ancient_works w ON p.work_id = w.work_id
    WHERE w.author = 'Chrysippus'
""")

# Clean up
await db.close()

```

--------------------------------

### EleutherIA CLI: Quick Access Commands

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/README.md

Provides convenient commands for quick access to the EleutherIA web interface, documentation, and interactive shell.

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

--------------------------------

### Stop EleutherIA Services with Docker Compose

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/guides/QUICK_START.md

Stops the running EleutherIA services using either the 'make stop' command or Docker Compose. This command shuts down all containers associated with the EleutherIA application.

```bash
make stop
# Or:
docker compose -f deploy/docker/docker-compose.yml down
```

--------------------------------

### Run Code Quality Checks

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Performs code linting using Ruff to check for style and potential errors. The 'make lint' command runs checks on all packages, or specific directories can be targeted.

```bash
make lint
# Or: ruff check database/src kg/src graphrag/src
```

--------------------------------

### Docker Compose Deployment and CLI Usage

Source: https://context7.com/romain-girardi-eng/eleutheria/llms.txt

Instructions for deploying the EleutherIA stack using Docker Compose, including cloning the repository, configuring environment variables, and managing services with the CLI. It outlines commands for starting, stopping, checking status, and cleaning up the deployment.

```bash
# Clone repository
git clone https://github.com/romain-girardi-eng/EleutherIA.git
cd EleutherIA

# Configure environment
cp .env.example .env
# Edit .env to add API keys:
# GEMINI_API_KEY=your-key-here
# MOONSHOT_API_KEY=your-key-here  (optional, for thinking mode)

# Start all services
docker compose -f deploy/docker/docker-compose.yml up -d

# Or use the CLI
eleutheria run

# Start with monitoring (Prometheus + Grafana)
eleutheria run -p full

# Check status
eleutheria status

# View logs
docker compose -f deploy/docker/docker-compose.yml logs -f backend

# Stop services
eleutheria stop

# Clean up (removes all data volumes)
eleutheria clean

```

--------------------------------

### Run All Code Quality Checks

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Executes all defined code quality checks, including linting, auto-fixing, and type checking, using the 'make quality' command. This ensures the codebase adheres to project standards.

```bash
make quality
```

--------------------------------

### Automatically Fix Code Quality Issues

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Automatically fixes code quality issues and formats code using Ruff. The 'make fix' command applies fixes, or specific Ruff commands can be used for checking and formatting.

```bash
make fix
# Or: ruff check --fix ... && ruff format ...
```

--------------------------------

### Configure Qdrant and Embedding Settings

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/kg/README.md

Sets environment variables for configuring the connection to a Qdrant instance and specifying the embedding dimensions for semantic search.

```bash
QDRANT_HOST=localhost
QDRANT_HTTP_PORT=6333
QDRANT_API_KEY=  # For Qdrant Cloud
EMBEDDING_DIMENSIONS=3072

```

--------------------------------

### Perform Type Checking

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/development/SETUP.md

Executes type checking across the project using MyPy to ensure type consistency and catch potential type-related errors. The 'make typecheck' command runs checks on all packages, or specific directories can be targeted.

```bash
make typecheck
# Or: mypy database/src kg/src graphrag/src
```

--------------------------------

### Get Timeline Nodes by Period (HTTP)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

Retrieves nodes from the knowledge graph, grouped by historical periods. This endpoint is useful for visualizing historical timelines and understanding the distribution of entities over time. It returns a JSON array where each object represents a period with its start and end years and associated nodes.

```http
GET /kg/timeline
```

--------------------------------

### Python SDK LLM Service Integration

Source: https://context7.com/romain-girardi-eng/eleutheria/llms.txt

Demonstrates how to use the LLMService from the Python SDK to interact with multiple LLM providers like Gemini, Kimi, and OpenRouter. It covers configuration, non-streaming and streaming generation, and extended reasoning modes, including fallback and rate limiting.

```python
import asyncio
import os

async def main():
    # Configure at least one API key
    os.environ["GEMINI_API_KEY"] = "your-gemini-key"
    # os.environ["MOONSHOT_API_KEY"] = "your-kimi-key"  # For thinking mode
    # os.environ["OPENROUTER_API_KEY"] = "your-openrouter-key"  # Fallback

    from eleutheria_graphrag.services.llm_service import LLMService, ModelProvider

    # Initialize with preferred provider
    llm = LLMService(
        preferred_provider=ModelProvider.GEMINI,
        timeout=120.0,
        enable_rate_limiting=True
    )

    print(f"Available providers: {[p.value for p in llm.available_providers]}")

    # Non-streaming generation
    response = await llm.generate(
        prompt="Explain the Stoic concept of fate in 2 sentences.",
        system_prompt="You are a scholar of ancient philosophy.",
        temperature=0.7,
        max_tokens=200
    )
    print(f"Response: {response}")

    # Streaming generation
    print("\nStreaming response:")
    async for chunk in llm.stream(
        prompt="What is the atomic swerve?",
        temperature=0.7,
        max_tokens=300
    ):
        print(chunk, end="", flush=True)
    print()

    # Extended reasoning mode (uses Kimi K2.5 Thinking)
    if ModelProvider.KIMI in llm.available_providers:
        response = await llm.generate(
            prompt="Compare Stoic and Epicurean views on determinism.",
            thinking_mode=True,  # Uses Kimi K2.5 for extended reasoning
            max_tokens=1000
        )
        print(f"\nThinking mode response: {response}")

    await llm.close()

asyncio.run(main())

```

--------------------------------

### List Passages for a Work via EleutherIA API (Bash)

Source: https://context7.com/romain-girardi-eng/eleutheria/llms.txt

Illustrates how to use `curl` to retrieve passages for a specific work from the EleutherIA API. It shows an example of fetching passages with pagination and includes the structure of the response, detailing passage ID, text content, morphological analysis, and citation information. It also shows how to get a specific passage by its ID.

```bash
# Get passages from a work
curl "http://localhost:8000/api/works/550e8400-e29b-41d4-a716-446655440000/passages?book=3&limit=50"

# Response:
# [
#   {
#     "passage_id": "660e8400-e29b-41d4-a716-446655440001",
#     "work_id": "550e8400-e29b-41d4-a716-446655440000",
#     "canonical_ref": "3.191",
#     "cts_urn": "urn:cts:greekLit:tlg0546.tlg001:3.191",
#     "book": "3",
#     "section": "191",
#     "sequence_number": 191,
#     "text_content": "τὸ ἐφ' ἡμῖν ἐστιν ὃ δι' ἡμῶν γίνεται...",
#     "char_length": 245,
#     "word_count": 42,
#     "morphology": {
#       "lemmas": [
#         {"f": "τὸ", "l": "ὁ", "p": "DET", "m": {"case": "nom", "number": "sg"}},
#         {"f": "ἐφ'", "l": "ἐπί", "p": "ADP"}
#       ]
#     },
#     "previous_passage_id": "660e8400...",
#     "next_passage_id": "660e8400..."
#   }
# ]

# Get a specific passage by ID
curl "http://localhost:8000/api/passages/660e8400-e29b-41d4-a716-446655440001"
```

--------------------------------

### Configure LLM Providers and Vector Database

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/graphrag/README.md

Sets up environment variables to configure the preferred LLM provider (Kimi, OpenRouter, or Gemini) and their respective API keys. It also includes settings for connecting to a Qdrant vector database.

```bash
# LLM Providers (at least one required)
LLM_PREFERRED_PROVIDER=kimi  # kimi, openrouter, or gemini
MOONSHOT_API_KEY=your-key    # For Kimi K2
OPENROUTER_API_KEY=your-key  # For OpenRouter
GEMINI_API_KEY=your-key      # For Gemini

# Vector DB
QDRANT_HOST=localhost
QDRANT_HTTP_PORT=6333
```

--------------------------------

### Python SDK Database Service - Querying Ancient Works

Source: https://context7.com/romain-girardi-eng/eleutheria/llms.txt

An asynchronous Python example using the `eleutheria-database` package to connect to a PostgreSQL database. It demonstrates querying ancient works by school and performing full-text searches on passages.

```python
import asyncio
import os

async def main():
    # Configure environment
    os.environ.setdefault("POSTGRES_HOST", "localhost")
    os.environ.setdefault("POSTGRES_USER", "eleutheria")
    os.environ.setdefault("POSTGRES_PASSWORD", "eleutheria")
    os.environ.setdefault("POSTGRES_DB", "eleutheria")

    from eleutheria_database import DatabaseService

    # Connect to database
    db = DatabaseService()
    await db.connect()
    print("Connected to PostgreSQL")

    # Query ancient works by school
    works = await db.fetch("""
        SELECT title, author, language, period
        FROM free_will.ancient_works
        WHERE school = 'Stoic'
        LIMIT 5
    """)
    for work in works:
        print(f"  - {work['title']} by {work['author']} ({work['period']})")

    # Full-text search for passages
    passages = await db.fetch("""
        SELECT
            p.text_content,
            w.title,
            w.author,
            ts_rank(to_tsvector('simple', p.text_content),
                    plainto_tsquery('simple', 'fate')) as rank
        FROM free_will.passages p
        JOIN free_will.ancient_works w ON p.work_id = w.work_id
        WHERE to_tsvector('simple', p.text_content) @@ plainto_tsquery('simple', 'fate')
        ORDER BY rank DESC
        LIMIT 3
    """)
    for p in passages:
        print(f"  - {p['author']}, {p['title']}: {p['text_content'][:100]}...")

    # Get KG statistics
    stats = await db.fetchrow("""
        SELECT
            (SELECT COUNT(*) FROM free_will.kg_nodes) as nodes,
            (SELECT COUNT(*) FROM free_will.kg_edges) as edges
    """)
    print(f"Nodes: {stats['nodes']}, Edges: {stats['edges']}")

    await db.close()

asyncio.run(main())

```

--------------------------------

### EleutherIA CLI: Development and Quality Commands

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/README.md

This snippet covers commands relevant to the development and maintenance of the EleutherIA project. It includes running tests, linting code with auto-fixing capabilities, and performing comprehensive quality checks.

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

--------------------------------

### Configure Eleutheria Database Connection via Environment Variables

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/database/README.md

Lists the environment variables required to configure the connection to the PostgreSQL database for the Eleutheria project. Includes host, port, database name, user, password, and connection pool size settings.

```bash
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=eleutheria
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secret
DB_POOL_MIN_SIZE=5
DB_POOL_MAX_SIZE=15

```

--------------------------------

### Validation Error Example (422)

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/docs/reference/API.md

An example of a JSON response when a request fails validation, typically indicated by a 422 Unprocessable Entity status code. It details the specific validation rule that was violated, the location of the invalid data, and the input that caused the error.

```json
{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["body", "question"],
      "msg": "String should have at least 3 characters",
      "input": "hi"
    }
  ]
}
```

--------------------------------

### EleutherIA CLI: Service Management Commands

Source: https://github.com/romain-girardi-eng/eleutheria/blob/main/README.md

This section details commands for managing EleutherIA services. It covers starting, stopping, checking status, and diagnosing issues with the system, including options for running with monitoring tools like Prometheus and Grafana.

```bash
# 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
```