🧠 NexusMind

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:

1. 🌱 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

2. 🧩 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

3. 🔬 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

4. 📊 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

5. ✂️ Pruning/Merging

   • Removes nodes with low confidence and impact scores

   • Consolidates semantically similar nodes

   • Optimizes graph structure while preserving critical relationships

6. 🔍 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

7. 📝 Composition

   • Synthesizes findings into coherent narrative

   • Annotates claims with node IDs and edge types

   • Provides comprehensive answers with proper citations

8. 🤔 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

🚀 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)

1. Clone the repository:

   git clone https://github.com/SaptaDey/NexusMind.git cd NexusMind

2. Install dependencies using Poetry:

   poetry install

   This creates a virtual environment and installs all necessary packages specified in pyproject.toml.

3. Activate the virtual environment:

   poetry shell

4. Configure the application:

   # Copy example configuration cp config/settings.example.yaml config/settings.yaml # Edit configuration as needed vim config/settings.yaml

5. 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

6. 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

1. 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

2. 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

3. Production Deployment:

   # Use production compose file docker-compose -f docker-compose.prod.yml up --build -d

4. 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

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)

MCP Configuration (config/claude_mcp_config.json)

🤝 Contributing

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

Development Setup

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Install development dependencies: poetry install --with dev

4. Make your changes and add tests

5. Run the test suite: poetry run pytest

6. 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

• API Documentation: Comprehensive API reference

• Architecture Guide: System design and components

• Usage Examples: Practical usage scenarios

• Development Guide: Contributing and development setup

📄 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