🧠 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
graph TD
A[🌱 Stage 1: Initialization] --> B[🧩 Stage 2: Decomposition]
B --> C[🔬 Stage 3: Hypothesis/Planning]
C --> D[📊 Stage 4: Evidence Integration]
D --> E[✂️ Stage 5: Pruning/Merging]
E --> F[🔍 Stage 6: Subgraph Extraction]
F --> G[📝 Stage 7: Composition]
G --> H[🤔 Stage 8: Reflection]
A1[Create root node<br/>Set initial confidence<br/>Define graph structure] --> A
B1[Break into dimensions<br/>Identify components<br/>Create dimensional nodes] --> B
C1[Generate hypotheses<br/>Create reasoning strategy<br/>Set falsification criteria] --> C
D1[Gather evidence<br/>Link to hypotheses<br/>Update confidence scores] --> D
E1[Remove low-value elements<br/>Consolidate similar nodes<br/>Optimize structure] --> E
F1[Identify relevant portions<br/>Focus on high-value paths<br/>Create targeted subgraphs] --> F
G1[Synthesize findings<br/>Create coherent insights<br/>Generate comprehensive answer] --> G
H1[Evaluate reasoning quality<br/>Identify improvements<br/>Final confidence assessment] --> H
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#ffebee
style F fill:#f1f8e9
style G fill:#e3f2fd
style H fill:#fce4ec
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
Alternatively, for more control:
uvicorn asr_got_reimagined.main:app --reload --host 0.0.0.0 --port 8000
The API will be available at http://localhost:8000.
Docker Deployment
graph TB
subgraph "Development Environment"
A[👨💻 Developer] --> B[🐳 Docker Compose]
end
subgraph "Container Orchestration"
B --> C[📦 NexusMind Container]
B --> D[📊 Monitoring Container]
B --> E[🗄️ Database Container]
end
subgraph "NexusMind Application"
C --> F[⚡ FastAPI Server]
F --> G[🧠 ASR-GoT Engine]
F --> H[🔌 MCP Protocol]
end
subgraph "External Integrations"
H --> I[🤖 Claude Desktop]
H --> J[🔗 Other AI Clients]
end
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style F fill:#fff3e0
style G fill:#ffebee
style H fill:#f1f8e9
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
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