🧠 NexusMind
╔══════════════════════════════════════╗
║ ║
║ 🧠 NexusMind 🧠 ║
║ ║
║ Intelligent Scientific ║
║ Reasoning through ║
║ Graph-of-Thoughts ║
║ ║
╚══════════════════════════════════════╝
Intelligent Scientific Reasoning through Graph-of-Thoughts
🔍 Overview
NexusMind leverages graph structures to perform sophisticated scientific reasoning. It implements the Model Context Protocol (MCP) to integrate with AI applications like Claude Desktop, providing an Advanced Scientific Reasoning Graph-of-Thoughts (ASR-GoT) framework designed for complex research tasks.
Key highlights:
- Process complex scientific queries using graph-based reasoning
- Dynamic confidence scoring with multi-dimensional evaluations
- Built with modern Python and FastAPI for high performance
- Dockerized for easy deployment
- Modular design for extensibility and customization
- Integration with Claude Desktop via MCP protocol
🌟 Key Features
8-Stage Reasoning Pipeline
The core reasoning process follows a sophisticated 8-stage pipeline:
- 🌱 Initialization
- Creates root node from query with multi-dimensional confidence vector
- Establishes initial graph structure with proper metadata
- Sets baseline confidence across empirical, theoretical, methodological, and consensus dimensions
- 🧩 Decomposition
- Breaks query into key dimensions: Scope, Objectives, Constraints, Data Needs, Use Cases
- Identifies potential biases and knowledge gaps from the outset
- Creates dimensional nodes with initial confidence assessments
- 🔬 Hypothesis/Planning
- Generates 3-5 hypotheses per dimension with explicit falsification criteria
- Creates detailed execution plans for each hypothesis
- Tags with disciplinary provenance and impact estimates
- 📊 Evidence Integration
- Iteratively selects hypotheses based on confidence-to-cost ratio and impact
- Gathers and links evidence using typed edges (causal, temporal, correlative)
- Updates confidence vectors using Bayesian methods with statistical power assessment
- ✂️ Pruning/Merging
- Removes nodes with low confidence and impact scores
- Consolidates semantically similar nodes
- Optimizes graph structure while preserving critical relationships
- 🔍 Subgraph Extraction
- Identifies high-value subgraphs based on multiple criteria
- Focuses on nodes with high confidence and impact scores
- Extracts patterns relevant to the original query
- 📝 Composition
- Synthesizes findings into coherent narrative
- Annotates claims with node IDs and edge types
- Provides comprehensive answers with proper citations
- 🤔 Reflection
- Performs comprehensive quality audit
- Evaluates coverage, bias detection, and methodological rigor
- Provides final confidence assessment and improvement recommendations
Advanced Technical Capabilities
Core Features:
- 🧠 Graph Knowledge Representation: Uses
networkx to model complex relationships with hyperedges and multi-layer networks - 🔄 Dynamic Confidence Vectors: Four-dimensional confidence assessment (empirical support, theoretical basis, methodological rigor, consensus alignment)
- 🌐 Interdisciplinary Bridge Nodes: Automatically connects insights across different research domains
- 🔗 Advanced Edge Types: Supports causal, temporal, correlative, and custom relationship types
- 📊 Statistical Rigor: Integrated power analysis and effect size estimation
- 🎯 Impact-Driven Prioritization: Focuses on high-impact research directions
- 🔌 MCP Server: Seamless Claude Desktop integration with Model Context Protocol
- ⚡ High-Performance API: Modern FastAPI implementation with async support
🛠️ Technology Stack
📂 Project Structure
NexusMind/
├── 📁 config/ # Configuration files
│ ├── settings.yaml # Application settings
│ ├── claude_mcp_config.json # Claude MCP integration config
│ └── logging.yaml # Logging configuration
│
├── 📁 src/asr_got_reimagined/ # Main source code
│ ├── 📁 api/ # API layer
│ │ ├── 📁 routes/ # API route definitions
│ │ │ ├── mcp.py # MCP protocol endpoints
│ │ │ ├── health.py # Health check endpoints
│ │ │ └── graph.py # Graph query endpoints
│ │ ├── schemas.py # API request/response schemas
│ │ └── middleware.py # API middleware
│ │
│ ├── 📁 domain/ # Core business logic
│ │ ├── 📁 models/ # Domain models
│ │ │ ├── common.py # Common types and enums
│ │ │ ├── graph_elements.py # Node, Edge, Hyperedge models
│ │ │ ├── graph_state.py # Graph state management
│ │ │ ├── confidence.py # Confidence vector models
│ │ │ └── metadata.py # Metadata schemas
│ │ │
│ │ ├── 📁 services/ # Business services
│ │ │ ├── got_processor.py # Main GoT processing service
│ │ │ ├── evidence_service.py # Evidence gathering and assessment
│ │ │ ├── confidence_service.py # Confidence calculation service
│ │ │ ├── graph_service.py # Graph manipulation service
│ │ │ └── mcp_service.py # MCP protocol service
│ │ │
│ │ ├── 📁 stages/ # 8-Stage pipeline implementation
│ │ │ ├── base_stage.py # Abstract base stage
│ │ │ ├── stage_1_initialization.py # Stage 1: Graph initialization
│ │ │ ├── stage_2_decomposition.py # Stage 2: Query decomposition
│ │ │ ├── stage_3_hypothesis.py # Stage 3: Hypothesis generation
│ │ │ ├── stage_4_evidence.py # Stage 4: Evidence integration
│ │ │ ├── stage_5_pruning.py # Stage 5: Pruning and merging
│ │ │ ├── stage_6_extraction.py # Stage 6: Subgraph extraction
│ │ │ ├── stage_7_composition.py # Stage 7: Answer composition
│ │ │ └── stage_8_reflection.py # Stage 8: Quality reflection
│ │ │
│ │ └── 📁 utils/ # Utility functions
│ │ ├── graph_utils.py # Graph manipulation utilities
│ │ ├── confidence_utils.py # Confidence calculation utilities
│ │ ├── statistical_utils.py # Statistical analysis utilities
│ │ ├── bias_detection.py # Bias detection algorithms
│ │ └── temporal_analysis.py # Temporal pattern analysis
│ │
│ ├── 📁 infrastructure/ # Infrastructure layer
│ │ ├── 📁 database/ # Database integration
│ │ ├── 📁 cache/ # Caching layer
│ │ └── 📁 external/ # External service integrations
│ │
│ ├── main.py # Application entry point
│ └── app_setup.py # Application setup and configuration
│
├── 📁 tests/ # Test suite
│ ├── 📁 unit/ # Unit tests
│ │ ├── 📁 stages/ # Stage-specific tests
│ │ ├── 📁 services/ # Service tests
│ │ └── 📁 models/ # Model tests
│ ├── 📁 integration/ # Integration tests
│ └── 📁 fixtures/ # Test fixtures and data
│
├── 📁 scripts/ # Utility scripts
│ ├── setup_dev.py # Development setup
│ ├── add_type_hints.py # Type hint utilities
│ └── deployment/ # Deployment scripts
│
├── 📁 docs/ # Documentation
│ ├── api/ # API documentation
│ ├── architecture/ # Architecture diagrams
│ └── examples/ # Usage examples
│
├── 📁 static/ # Static assets
│ └── nexusmind-logo.png # Application logo
│
├── 📄 Docker Files & Config
├── Dockerfile # Docker container definition
├── docker-compose.yml # Multi-container setup
├── .dockerignore # Docker ignore patterns
│
├── 📄 Configuration Files
├── pyproject.toml # Python project configuration
├── poetry.lock # Dependency lock file
├── mypy.ini # Type checking configuration
├── pyrightconfig.json # Python type checker config
├── .pre-commit-config.yaml # Pre-commit hooks
├── .gitignore # Git ignore patterns
│
└── 📄 Documentation
├── README.md # This file
├── CHANGELOG.md # Version history
├── LICENSE # Apache 2.0 license
└── CONTRIBUTING.md # Contribution guidelines
🚀 Getting Started
Prerequisites
- Python 3.13+ (Docker image uses Python 3.13.3-slim-bookworm)
- Poetry: For dependency management
- Docker and Docker Compose: For containerized deployment
Installation and Setup (Local Development)
- Clone the repository:
git clone https://github.com/SaptaDey/NexusMind.git
cd NexusMind
- Install dependencies using Poetry:This creates a virtual environment and installs all necessary packages specified in
pyproject.toml. - Activate the virtual environment:
- Configure the application:
# Copy example configuration
cp config/settings.example.yaml config/settings.yaml
# Edit configuration as needed
vim config/settings.yaml
- Set up environment variables (optional):
# Create .env file for sensitive configuration
echo "LOG_LEVEL=DEBUG" > .env
echo "API_HOST=0.0.0.0" >> .env
echo "API_PORT=8000" >> .env
- Run the development server:
python src/asr_got_reimagined/main.py
uvicorn asr_got_reimagined.main:app --reload --host 0.0.0.0 --port 8000
http://localhost:8000.
Docker Deployment
- Quick Start with Docker Compose:
# Build and run all services
docker-compose up --build
# For detached mode (background)
docker-compose up --build -d
# View logs
docker-compose logs -f nexusmind
- Individual Docker Container:
# Build the image
docker build -t nexusmind:latest .
# Run the container
docker run -p 8000:8000 -v $(pwd)/config:/app/config nexusmind:latest
- Production Deployment:
# Use production compose file
docker-compose -f docker-compose.prod.yml up --build -d
- Access the Services:
- API Documentation:
http://localhost:8000/docs - Health Check:
http://localhost:8000/health - MCP Endpoint:
http://localhost:8000/mcp
🔌 API Endpoints
Core Endpoints
- MCP Protocol:
POST /mcp{
"method": "process_query",
"params": {
"query": "Analyze the relationship between microbiome diversity and cancer progression",
"confidence_threshold": 0.7,
"max_stages": 8
}
}
- Health Check:
GET /health{
"status": "healthy",
"version": "0.1.0",
"timestamp": "2024-05-23T10:30:00Z"
}
Advanced Endpoints
- Graph Query:
POST /api/v1/graph/query{
"query": "Research question or hypothesis",
"parameters": {
"disciplines": ["immunology", "oncology"],
"confidence_threshold": 0.6,
"include_temporal_analysis": true,
"enable_bias_detection": true
}
}
- Graph State:
GET /api/v1/graph/{session_id}- Retrieve current state of a reasoning graph
- Includes confidence scores, node relationships, and metadata
- Analytics:
GET /api/v1/analytics/{session_id}- Get comprehensive metrics about the reasoning process
- Includes performance stats, confidence trends, and quality measures
- Subgraph Extraction:
POST /api/v1/graph/{session_id}/extract{
"criteria": {
"min_confidence": 0.7,
"node_types": ["hypothesis", "evidence"],
"include_causal_chains": true
}
}
🧪 Testing & Quality Assurance
Development Commands
# Run full test suite with coverage
poetry run pytest --cov=src --cov-report=html --cov-report=term
# Run specific test categories
poetry run pytest tests/unit/stages/ # Stage-specific tests
poetry run pytest tests/integration/ # Integration tests
poetry run pytest -k "test_confidence" # Tests matching pattern
# Type checking and linting
poetry run mypy src/ --strict # Strict type checking
poetry run ruff check . --fix # Auto-fix linting issues
poetry run ruff format . # Format code
# Pre-commit hooks (recommended)
poetry run pre-commit install # Install hooks
poetry run pre-commit run --all-files # Run all hooks
Quality Metrics
- Type Safety:
- Fully typed codebase with strict mypy configuration
- Configured with
mypy.ini and pyrightconfig.json - Fix logger type issues:
python scripts/add_type_hints.py
- Code Quality:
- 95%+ test coverage target
- Automated formatting with Ruff
- Pre-commit hooks for consistent code quality
- Comprehensive integration tests for the 8-stage pipeline
🔧 Configuration
Application Settings (config/settings.yaml)
# Core application settings
app:
name: "NexusMind"
version: "0.1.0"
debug: false
log_level: "INFO"
# API configuration
api:
host: "0.0.0.0"
port: 8000
cors_origins: ["*"]
# ASR-GoT Framework settings
asr_got:
max_stages: 8
default_confidence_threshold: 0.6
enable_bias_detection: true
enable_temporal_analysis: true
max_hypotheses_per_dimension: 5
# Graph settings
graph:
max_nodes: 10000
enable_hyperedges: true
enable_multi_layer: true
temporal_decay_factor: 0.1
MCP Configuration (config/claude_mcp_config.json)
{
"name": "nexusmind",
"description": "Advanced Scientific Reasoning with Graph-of-Thoughts",
"version": "0.1.0",
"endpoints": {
"mcp": "http://localhost:8000/mcp"
},
"capabilities": [
"scientific_reasoning",
"graph_analysis",
"confidence_assessment",
"bias_detection"
]
}
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Development Setup
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Install development dependencies:
poetry install --with dev - Make your changes and add tests
- Run the test suite:
poetry run pytest - Submit a pull request
Code Style
- Follow PEP 8 style guidelines
- Use type hints for all functions and methods
- Write comprehensive docstrings
- Maintain test coverage above 95%
📚 Documentation
📄 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
🙏 Acknowledgments
- NetworkX community for graph analysis capabilities
- FastAPI team for the excellent web framework
- Pydantic for robust data validation
- The scientific research community for inspiration and feedback