NexusMind

# 🧠 NexusMind <div align="center"> ``` ╔══════════════════════════════════════╗ ║ ║ ║ 🧠 NexusMind 🧠 ║ ║ ║ ║ Intelligent Scientific ║ ║ Reasoning through ║ ║ Graph-of-Thoughts ║ ║ ║ ╚══════════════════════════════════════╝ ``` #### **Intelligent Scientific Reasoning through Graph-of-Thoughts** [](https://github.com/SaptaDey/NexusMind/releases) [](https://www.python.org/downloads/) [](LICENSE) [](Dockerfile) [](https://fastapi.tiangolo.com) [](https://networkx.org) [](CHANGELOG.md) </div> <div align="center"> <p><strong>🚀 Next-Generation AI Reasoning Framework for Scientific Research</strong></p> <p><em>Leveraging graph structures to transform how AI systems approach scientific reasoning</em></p> </div> ## 🔍 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 ```mermaid 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: 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 <div align="center"> <table> <tr> <td align="center">🔄 <b>Multi-Dimensional<br>Confidence</b></td> <td align="center">🧠 <b>Graph-Based<br>Knowledge</b></td> <td align="center">🔌 <b>MCP<br>Integration</b></td> <td align="center">⚡ <b>FastAPI<br>Backend</b></td> </tr> <tr> <td align="center">🐳 <b>Docker<br>Deployment</b></td> <td align="center">🧩 <b>Modular<br>Design</b></td> <td align="center">⚙️ <b>Configuration<br>Management</b></td> <td align="center">🔒 <b>Type<br>Safety</b></td> </tr> <tr> <td align="center">🌐 <b>Interdisciplinary<br>Bridge Nodes</b></td> <td align="center">🔗 <b>Hyperedge<br>Support</b></td> <td align="center">📊 <b>Statistical<br>Power Analysis</b></td> <td align="center">🎯 <b>Impact<br>Estimation</b></td> </tr> </table> </div> **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 <div align="center"> <table> <tr> <td align="center"><img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/python/python-original.svg" width="38" height="38"/><br>Python 3.13+</td> <td align="center"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" width="38" height="38"/><br>FastAPI</td> <td align="center"><img src="https://networkx.org/documentation/stable/_static/networkx_logo.svg" width="38" height="38"/><br>NetworkX</td> <td align="center"><img src="https://raw.githubusercontent.com/devicons/devicon/master/icons/docker/docker-original.svg" width="38" height="38"/><br>Docker</td> </tr> <tr> <td align="center"><img src="https://docs.pytest.org/en/7.3.x/_static/pytest_logo_curves.svg" width="38" height="38"/><br>Pytest</td> <td align="center"><img src="https://docs.pydantic.dev/latest/img/logo-white.svg" width="38" height="38"/><br>Pydantic</td> <td align="center"><img src="https://python-poetry.org/images/logo-origami.svg" width="38" height="38"/><br>Poetry</td> <td align="center"><img src="https://raw.githubusercontent.com/tomchristie/uvicorn/master/docs/uvicorn.png" width="38" height="38"/><br>Uvicorn</td> </tr> </table> </div> ## 📂 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](https://python-poetry.org/docs/#installation)**: For dependency management - **[Docker](https://www.docker.com/get-started)** and **[Docker Compose](https://docs.docker.com/compose/install/)**: For containerized deployment ### Installation and Setup (Local Development) 1. **Clone the repository**: ```bash git clone https://github.com/SaptaDey/NexusMind.git cd NexusMind ``` 2. **Install dependencies using Poetry**: ```bash poetry install ``` This creates a virtual environment and installs all necessary packages specified in `pyproject.toml`. 3. **Activate the virtual environment**: ```bash poetry shell ``` 4. **Configure the application**: ```bash # 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): ```bash # 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**: ```bash python src/asr_got_reimagined/main.py ``` Alternatively, for more control: ```bash 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 ```mermaid 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 ``` 1. **Quick Start with Docker Compose**: ```bash # 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**: ```bash # 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**: ```bash # 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` ```json { "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` ```json { "status": "healthy", "version": "0.1.0", "timestamp": "2024-05-23T10:30:00Z" } ``` ### Advanced Endpoints - **Graph Query**: `POST /api/v1/graph/query` ```json { "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` ```json { "criteria": { "min_confidence": 0.7, "node_types": ["hypothesis", "evidence"], "include_causal_chains": true } } ``` ## 🧪 Testing & Quality Assurance <div align="center"> <table> <tr> <td align="center">🧪<br><b>Testing</b></td> <td align="center">🔍<br><b>Type Checking</b></td> <td align="center">✨<br><b>Linting</b></td> <td align="center">📊<br><b>Coverage</b></td> </tr> <tr> <td align="center"> <pre>poetry run pytest</pre> <pre>poetry run pytest -v</pre> </td> <td align="center"> <pre>poetry run mypy src/</pre> <pre>pyright src/</pre> </td> <td align="center"> <pre>poetry run ruff check .</pre> <pre>poetry run ruff format .</pre> </td> <td align="center"> <pre>poetry run pytest --cov=src</pre> <pre>coverage html</pre> </td> </tr> </table> </div> ### Development Commands ```bash # 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`) ```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`) ```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](CONTRIBUTING.md) 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](docs/api/)**: Comprehensive API reference - **[Architecture Guide](docs/architecture/)**: System design and components - **[Usage Examples](docs/examples/)**: Practical usage scenarios - **[Development Guide](docs/development/)**: Contributing and development setup ## 📄 License This project is licensed under the Apache License 2.0 - see the [LICENSE](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 --- <div align="center"> <p><strong>Built with ❤️ for the scientific research community</strong></p> <p><em>NexusMind - Advancing scientific reasoning through intelligent graph structures</em></p> </div>