ChatSEEK: Knowledge Graph Query & Submission System

A production-ready tool for querying NExtSEEK biosampling knowledge graphs and automating GEO submissions to NCBI.

Overview

ChatSEEK combines two powerful capabilities:

1. GraphRAG Query System: Fast, transparent natural language queries against Neo4j biosampling knowledge graphs
2. GEO Submission Automation: Zero-friction NCBI GEO submissions with intelligent field mapping

Key Features

🔍 GraphRAG Query System

• Natural Language Processing: Ask questions in plain English
• Entity Extraction: Automatic identification of studies, assays, samples, UIDs
• Fast Queries: 1-2 second response time (vs 30-45 sec with agents)
• Two Query Approaches:
  • Text2Cypher: Structured relationship traversal for provenance and study navigation
  • VectorCypher: Semantic similarity search for protocol and phenotype discovery
• Transparent: See the generated Cypher queries and understand results

📊 GEO Submission System

• Automated Submissions: Generate pre-filled NCBI GEO Excel forms
• Schema Discovery: Automatically introspects your graph properties
• Intelligent Mapping: Claude-validated field suggestions (no hallucination)
• Template System: Built-in templates for RNA-seq, ChIP-seq, and custom data types
• Submission Tracking: Track submission state in Neo4j

Architecture

Natural Language Query
↓
Entity Extraction (Claude)
↓
Query Builder (Cypher templates)
↓
Neo4j Execution (1-2 seconds)
↓
Formatted Results
---OR---
Choose GEO Template
↓
Extract Subgraph (Cypher)
↓
Discover Schema (properties)
↓
Map Fields (Claude validates)
↓
Generate Excel (pre-filled)
↓
User Reviews & Submits

Quick Start

Installation

# Core dependencies
pip install neo4j neo4j-graphrag anthropic python-dotenv openpyxl sentence-transformers
# Optional: OpenAI for embeddings/LLM
pip install openai

Environment Setup

Create .env:

NEO4J_URI=neo4j://localhost:7687NEO4J_USERNAME=neo4jNEO4J_PASSWORD=your_passwordANTHROPIC_API_KEY=your_key_here

GraphRAG Queries

fromchatseekimportQueryEnginefromneo4jimportGraphDatabasedriver=GraphDatabase.driver("neo4j://localhost:7687", auth=("neo4j", "password"))
engine=QueryEngine(driver)
# Ask questions in natural languageresult=engine.query(
"In the GBM Study, find samples from NHP with UID NHP12345",
verbose=True
)
print(result["formatted_results"])

GEO Submissions

fromgeo_submission_systemimportsubmit_to_geo# One line to generate pre-filled GEO submissionsubmit_to_geo(
study_id="YourStudyID",
template_name="rna-seq-v1",
output_path="your_submission.xlsx"
)

Run Examples

# GraphRAG examples
python examples/query_examples.py
# GEO submission examples
python examples/geo_examples.py
# Quickstart example
python examples/quickstart.py

Data Model

NExtSEEK (the platform) encodes:

• Sample Provenance: Parent → Child relationships via HAS_PARENT and ASSAYED_TO
• Assay Workflow: Sample → Assay → Study → Investigation
• Analysis Chain: Multi-step transformations from raw samples to models
• Type Encoding: *_ prefix naming (SEQ_Sample, NHP_Sample, etc.)

Supported Query Types

Intent	Example
find_samples	"In GBM Study, find samples from NHP NHP12345"
list_outputs	"Show samples from RNA Sequencing assay"
show_provenance	"Show full provenance for analysis A_001"
show_relationships	"What are parent-child relationships for sample S001?"
filter_by_assay	"What samples were inputs to immunophenotyping?"

GEO Templates

Built-in templates:

• RNA-seq: RNA sequencing expression data
• ChIP-seq: Chromatin immunoprecipitation sequencing
• SNP Array: Genotype/copy number data
• Proteomics: Mass spectrometry proteomics (example)
• Custom: Create your own for any data type

Documentation

Core Documentation

• README.md (this file) - Main project documentation
• QUICKSTART.md - Step-by-step getting started guide
• IMPLEMENTATION_STATUS.md - Current project status (single source of truth)
• TESTING_STATUS.md - Comprehensive testing documentation
• ROADMAP.md - Future development plans
• VECTOR_SEARCH_GUIDE.md - Advanced vector search capabilities

User Guides

• docs/guides/DEMO_HIGHLIGHTS.md - Demo script and tuning parameters

Archived Research & Design Documentation

• docs/archive/prototypes/ - Original working prototypes (superseded by production code)
• docs/archive/design_notes/ - Design documentation and analysis
• docs/archive/ - Historical status reports and outdated documentation
• presentations/ - Project presentation materials (PowerPoint)

System Requirements

• Neo4j: 5.18.1+ (Community or Enterprise)
• Python: 3.8+
• LLM: Claude (Anthropic) or GPT-4 (OpenAI)
• Embeddings: SentenceTransformers (local/free) or OpenAI (cloud/paid)

Use Cases

Research Labs

• Query knowledge graphs without learning Cypher
• Rapidly explore sample provenance and assay relationships
• Submit datasets to NCBI in minutes instead of hours

Biobanks

• Track sample lineage across processing steps
• Discover similar samples by phenotype or protocol
• Automate data sharing with public repositories

Data Scientists

• Fast semantic search for relevant samples
• Transparent query building for reproducibility
• Integration-ready Python API

Key Advantages

GraphRAG System

✅ Fast: 1-2 seconds (not 30-45 sec with agents) ✅ Transparent: See the exact Cypher query generated ✅ Reliable: Template-based queries prevent hallucination ✅ Debuggable: If wrong, see exactly why

GEO Submission System

✅ Time-saving: Minutes instead of hours of form-filling ✅ Pre-filled: Actual data from your graph ✅ User control: Review and edit in Excel before submission ✅ Trackable: Submission state persisted in Neo4j

Tuning & Configuration

Query Engine Parameters

Entity Extraction (chatseek/graphrag/entity_extractor.py)

• Add domain-specific examples to LLM prompt for better extraction
• Customize entity types: study, sample, assay, analysis, UID
• Adjust confidence thresholds for entity detection

Query Builder (chatseek/graphrag/query_builder.py)

# Provenance depth (default: 10 levels)ASSAYED_TO*1..10# Increase for deeper lineage, decrease for speed# Study name matchingWHEREtoLower(study.name) CONTAINStoLower('GBM') # Flexible (default)WHEREtoLower(study.name) =toLower('GBM') # Exact match

Verbose Mode

result=engine.query("Find samples...", verbose=True)
# Shows: entity extraction → query building → execution → results

GEO Submission Parameters

Subgraph Extraction (chatseek/geo/extractor.py)

subgraph, success=extractor.extract(
query,
params={'study_id': 'GBM'},
limit=1000# Max records to fetch (adjust for large studies)
)

Field Mapping Confidence (chatseek/geo/mapper.py)

• LLM suggests property → GEO field mappings
• Adjust prompt for more conservative/aggressive mapping
• Review non-null counts to validate data coverage

Performance Tuning

Component	Typical Latency	Tuning Options
Entity Extraction	500-800ms	Cache common queries, reduce examples
Query Execution	100-500ms	Add Neo4j indexes, limit result size
GEO Field Mapping	2-3s	Cache schema introspection

Advanced: Vector Search

See VECTOR_SEARCH_GUIDE.md for adding semantic search capabilities:

Benefits:

• Fuzzy sample type matching ("permeability" → PERM_Analysis)
• Synonym handling ("gene expression" → SCXP_Analysis + SEQ_Sample)
• User-friendly (no need to know exact label names)

Quick Overview:

1. Create semantic descriptions for sample types
2. Generate embeddings (OpenAI/local model)
3. Store in Neo4j vector index
4. Query-time: embed search → find similar types → enhance Cypher

Trade-offs:

• Setup: Write sample type descriptions
• Latency: +100-200ms per query
• Accuracy: May return false positives

Presentation Materials

• presentations/NExtSEEK_GraphRAG_Demo.pptx - Professional 11-slide presentation demonstrating capabilities

Testing

Run Tests

# Run all tests
python3 -m pytest tests/ -v -o addopts=""# Run with coverage
python3 -m pytest tests/ --cov=chatseek --cov-report=html --cov-report=term
# Run specific test file
python3 -m pytest tests/unit/test_llm.py -v -o addopts=""

Test Status

Current: 179/179 tests passing (100% pass rate) ✅

• ✅ 179 total tests (33 UID parser, 21 CLI, 14 database, 11 LLM, 100+ GraphRAG/GEO)
• ✅ 86% code coverage (691/807 lines)
• ✅ All core functionality fully tested and working

See TESTING_STATUS.md for detailed test status and IMPLEMENTATION_STATUS.md for overall progress.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Start:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

Adding GEO Templates: See docs/guides/CUSTOM_TEMPLATE_GUIDE.md for template creation guide.

License

ChatSEEK is released under the MIT License.

Support

For questions or issues:

1. Check documentation in claude_docs/
2. Review runnable examples
3. Open an issue on GitHub

Acknowledgments

Built on:

• Neo4j GraphRAG Python
• Anthropic Claude
• Neo4j Database

---

Status: Production-ready Version: 1.0.0 Last Updated: 2026-01-23 Test Coverage: 86% (179/179 tests passing - 100% pass rate)