Use Cases¶

Aletheia includes several pre-built use cases that demonstrate GraphRAG capabilities across different domains. Each use case provides a complete implementation including data parser, episode builder, ontology, and evaluation questions.

Available Use Cases¶

What is a Use Case?¶

A use case in Aletheia is a self-contained data domain that includes everything needed to build and evaluate a knowledge graph:

use_cases/<name>/
├── __init__.py              # Use case registration
├── parser.py                # Transform source format to entities
├── episode_builder.py       # Convert entities to rich text
├── ontology/                # Schema for graph-hybrid mode
│   └── *.ttl               # OWL/TTL ontology files
├── data/                    # Source data files
├── evaluation_questions.json # RAGAS evaluation questions
└── README.md                # Documentation

Key Components¶

Use Case Comparison¶

Terrorist Organizations¶

Domain: Counter-terrorism intelligence

Strengths: - Multi-jurisdiction analysis (US, UK, Australia) - Alias resolution and entity matching - Cross-reference analysis - FollowTheMoney data model

Best for demonstrating: - Cross-jurisdiction queries - Alias-based lookups - Organizational network tracing - Entity resolution across naming variants

Aviation Safety¶

Domain: Aviation incident investigation

Strengths: - Rich structured incident reports - Cause-and-effect relationships - Geographic and temporal analysis - ECCAIRS taxonomy support

Best for demonstrating: - Semantic search over narratives - Multi-hop relationship queries - Incident pattern analysis - Technical domain knowledge

Quick Start¶

1. Choose a Use Case¶

# List available use cases
aletheia list-use-cases

2. Build the Knowledge Graph¶

# Terrorist Organizations (FTM data)
aletheia build-knowledge-graph \
  --use-case terrorist_orgs \
  --knowledge-graph terrorist_orgs \
  --schema-mode graph-hybrid \
  --ontology-graph terrorist_orgs_ontology

# Aviation Safety (Markdown data)
aletheia build-knowledge-graph \
  --use-case aviation_safety \
  --knowledge-graph aviation_safety \
  --schema-mode graph-hybrid \
  --ontology-graph aviation_safety_ontology

3. Run Evaluation¶

# Evaluate retrieval quality
aletheia evaluate-ragas \
  --knowledge-graph <graph_name> \
  --questions use_cases/<name>/evaluation_questions_curated.json \
  --grounding-mode strict

Creating Your Own Use Case¶

To create a new use case:

1. Create directory structure:

   mkdir -p use_cases/my_case/{data,ontology}
   

2. Implement the parser (parser.py):

   from aletheia.core.parsing import BaseParser
   
   class MyParser(BaseParser):
       def parse_all(self):
           # Yield records from your data format
           for file in self.data_dir.glob("*.json"):
               yield self.parse_file(file)
   

3. Register the use case (__init__.py):

   from .parser import MyParser
   from aletheia.core.ontology import GenericOntologyLoader
   from aletheia.core.episodes import register_episode_builder
   from .episode_builder import build_episode
   
   Parser = MyParser
   Ontology = GenericOntologyLoader
   
   register_episode_builder(
       "my_case",
       build_episode,
       source_description="My data source",
   )
   

4. Add ontology (ontology/*.ttl):

5. Define entity types as OWL classes
6. Define relationships as ObjectProperties

7. Use existing ontologies like FTM when applicable

8. Create evaluation questions (evaluation_questions.json):

   {
     "questions": [
       {
         "id": "q1",
         "question": "What is X?",
         "answer": "X is..."
       }
     ]
   }
   

See the Developer Guide for detailed instructions.

Learn More¶

• Terrorist Organizations - Counter-terrorism intelligence
• Aviation Safety - Aviation incident analysis