RagQL-Nav (Retrieval Augmented Generation with Query Language Navigation) is a multi-agent framework that bridges the gap between natural language queries and complex clinical trial data analysis. It intelligently routes queries between SQL and Neo4j databases, provides dual-system validation, and generates transparent decision trees for regulatory compliance.

• Intelligent Query Routing: Automatically determines whether SQL or Neo4j is optimal for each query component
• Dual-System Validation: Cross-validates results between database systems for enhanced accuracy
• Decision Tree Visualization: Provides transparent audit trails for regulatory compliance
• ADaM Standards Compliance: Built specifically for Clinical Data Interchange Standards Consortium (CDISC) ADaM datasets
• Multi-Agent Architecture: Leverages LangGraph for orchestrated query processing
• Performance Optimization: Includes caching, parallelization, and selective validation

Based on experimental evaluation with synthetic clinical trial data:

• 91% accuracy on complex queries (12% improvement over single-system approaches)
• Automatic resolution of 85% of discrepancies between systems
• Transparent audit trails with decision tree documentation
• Optimized performance for complex multi-domain queries

Natural Language Query
         ↓
   Query Decomposition
         ↓
   Intelligent Router ──→ SQL Database (PostgreSQL)
         ↓                      ↓
   Dual Validation ←──── Neo4j Database
         ↓
   Decision Tree Generator
         ↓
   Final Result + Audit Trail

ragql_nav_project/
├── ragql_nav/                 # Main application package
│   ├── core/                  # Core RagQL-Nav components
│   │   ├── decomposer.py      # Query decomposition engine
│   │   ├── router.py          # Intelligent query router
│   │   ├── validator.py       # Dual-query validation
│   │   └── decision_tree.py   # Decision tree generator
│   ├── database/              # Database management
│   │   ├── connections.py     # DB connection managers
│   │   ├── schema_manager.py  # Schema setup and management
│   │   └── data_loader.py     # Data loading utilities
│   ├── agents/                # Agent clients
│   ├── graph/                 # LangGraph workflow
│   └── __main__.py           # CLI entry point
├── servers/                   # Agent servers
├── data/                      # Synthetic datasets
├── evaluation/                # Evaluation framework
├── config/                    # Configuration
└── docs/                      # Documentation

• Python 3.8+
• PostgreSQL 13+
• Neo4j 5.0+
• DeepSeek API key (or compatible LLM provider)

1. Clone the repository:

   git clone https://github.com/yanmingyu92/ragql-nav.git
   cd ragql-nav

2. Run the setup script:

   python setup.py

   This will:

   • Check system dependencies
   • Create a virtual environment
   • Install Python packages
   • Set up configuration files
   • Create necessary directories

3. Configure environment:

   cp .env.example .env
   # Edit .env with your actual configuration

4. Set up databases:

   # Start PostgreSQL and Neo4j services
   # Then run:
   python -m ragql_nav.database.setup

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run a query
python -m ragql_nav "What is the incidence of severe neutropenia in patients who received the study drug for at least 14 days?"

# Run with checkpointing enabled
python -m ragql_nav "Calculate the mean change from baseline for hemoglobin in the active treatment group" --checkpoint

# Specify a custom thread ID
python -m ragql_nav "List all Grade 3 or higher adverse events" --thread-id my-analysis-001

RagQL-Nav supports various types of clinical data queries:

python -m ragql_nav "How many subjects were randomized to the placebo arm?"
python -m ragql_nav "What is the distribution of subjects by sex?"

python -m ragql_nav "What is the average age of subjects who experienced a serious adverse event?"
python -m ragql_nav "Calculate the mean change from baseline for hemoglobin in the active treatment group"

python -m ragql_nav "Identify subjects who experienced Grade 2+ neutropenia followed by a fever within 7 days while actively receiving the study drug"
python -m ragql_nav "What is the incidence rate of major adverse cardiac events adjusted for total exposure time in each treatment arm?"

Key configuration options in .env:

# LLM Configuration
GRAPHRAG_API_KEY=your_deepseek_api_key
BASE_URL=https://api.deepseek.com
LLM_MODEL_NAME=deepseek-chat

# Database Configuration
DB_HOST=localhost
DB_USER=ragql_user
DB_PASSWORD=your_password
DB_NAME=ragql_nav_clinical

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password

# Performance Settings
MAX_PARALLEL_QUERIES=4
QUERY_TIMEOUT_SECONDS=300
ENABLE_QUERY_CACHE=true

The intelligent router uses weighted features to determine optimal database selection:

• SQL Weights: [0.40, 0.10, 0.35, 0.05, 0.10] (tabular, relationship, aggregation, path, hierarchical)
• Neo4j Weights: [0.15, 0.35, 0.10, 0.25, 0.15]

These can be adjusted in config/settings.py based on your specific use case.

RagQL-Nav includes a comprehensive evaluation framework with:

• 150 test queries across three complexity levels
• Synthetic ADaM datasets for reproducible testing
• Multiple evaluation metrics: accuracy, system agreement, execution time
• Automated benchmarking against baseline approaches

Run the evaluation:

python -m ragql_nav.evaluation.run_benchmark

• ADSL: Subject-Level Analysis Dataset
• ADAE: Adverse Events Analysis Dataset
• ADCM: Concomitant Medications Analysis Dataset
• ADEG: ECG Analysis Dataset
• ADLB: Laboratory Test Results Analysis Dataset
• ADVS: Vital Signs Analysis Dataset
• ADTTE: Time-to-Event Analysis Dataset
• ADEFF: Efficacy Analysis Dataset

• Nodes: :Subject, :AdverseEvent, :LabTest, :Medication, :Treatment
• Relationships: :EXPERIENCED, :HAS_LAB_RESULT, :TOOK_MEDICATION, :FOLLOWS
• Temporal relationships for sequence analysis
• Hierarchical structures for medical coding systems

Every query generates a decision tree showing:

• Original query decomposition
• Routing decisions and rationale
• Execution results from each system
• Validation outcomes
• Final result selection

Example output files:

• decision_tree_[thread_id].json: Structured decision data
• decision_tree_[thread_id].md: Mermaid diagram for visualization

Add custom SQL/Cypher templates in ragql_nav/templates/:

# SQL template example
ADVERSE_EVENT_INCIDENCE = """
SELECT
    arm,
    COUNT(DISTINCT usubjid) as subjects_with_ae,
    COUNT(DISTINCT usubjid) * 100.0 / (
        SELECT COUNT(DISTINCT usubjid)
        FROM adsl
        WHERE arm = ae.arm
    ) as incidence_rate
FROM adae ae
WHERE aesev = %(severity)s
GROUP BY arm;
"""

Enable performance features:

# Enable caching
export ENABLE_QUERY_CACHE=true

# Increase parallel execution
export MAX_PARALLEL_QUERIES=8

# Adjust validation thresholds
export VALIDATOR_NUMERIC_THRESHOLD=0.01

Enable comprehensive audit logging:

export ENABLE_AUDIT_LOG=true
export AUDIT_LOG_FILE=ragql_nav_audit.log

# Install development dependencies
pip install -r requirements-dev.txt

# Run unit tests
pytest tests/

# Run integration tests
pytest tests/integration/

# Run evaluation benchmarks
python -m ragql_nav.evaluation.run_benchmark

# Format code
black ragql_nav/

# Lint code
flake8 ragql_nav/

# Type checking
mypy ragql_nav/

1. Query Templates: Add to ragql_nav/templates/
2. Router Features: Extend ragql_nav/core/router.py
3. Validation Logic: Modify ragql_nav/core/validator.py
4. Database Schemas: Update ragql_nav/database/schema_manager.py

• Installation Guide
• Configuration Reference
• API Documentation
• Database Schema Guide
• Query Template Guide
• Evaluation Framework

We welcome contributions! Please see our Contributing Guide for details.

# Clone the repository
git clone https://github.com/yanmingyu92/ragql-nav.git
cd ragql-nav

# Create development environment
python -m venv venv-dev
source venv-dev/bin/activate

# Install development dependencies
pip install -r requirements-dev.txt
pip install -e .

# Run tests
pytest

This project is licensed under the MIT License - see the LICENSE file for details.

If you use RagQL-Nav in your research, please cite:

@article{ragql_nav_2024,
  title={Comparing SQL and Graph Database Query Methods for Answering Clinical Trial Questions with LLM-Powered Pipelines},
  author={[Author Name]},
  journal={[Journal Name]},
  year={2024},
  url={https://github.com/yanmingyu92/ragql-nav}
}

• CDISC for ADaM standards
• LangChain and LangGraph communities
• Neo4j and PostgreSQL communities
• Clinical research community for domain expertise

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Project Wiki

• Real-world clinical data validation
• Additional LLM provider support
• Enhanced visualization dashboard
• REST API interface

• Machine learning-based router optimization
• Support for additional database systems
• Advanced statistical analysis templates
• Regulatory compliance certification

Built with ❤️ for the clinical research community