🧠 NexusMind

    ╔══════════════════════════════════════╗
    ║                                      ║
    ║           🧠 NexusMind 🧠            ║
    ║                                      ║
    ║     Intelligent Scientific           ║
    ║     Reasoning through                ║
    ║     Graph-of-Thoughts                ║
    ║                                      ║
    ╚══════════════════════════════════════╝

Intelligent Scientific Reasoning through Graph-of-Thoughts

🚀 Next-Generation AI Reasoning Framework for Scientific Research

Leveraging graph structures to transform how AI systems approach scientific reasoning

🔍 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

🔄 Multi-Dimensional Confidence	🧠 Graph-Based Knowledge	🔌 MCP Integration	⚡ FastAPI Backend
🐳 Docker Deployment	🧩 Modular Design	⚙️ Configuration Management	🔒 Type Safety
🌐 Interdisciplinary Bridge Nodes	🔗 Hyperedge Support	📊 Statistical Power Analysis	🎯 Impact Estimation

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

Python 3.13+	FastAPI	NetworkX	Docker
Pytest	Pydantic	Poetry	Uvicorn

📂 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:
```
poetry install
```
This creates a virtual environment and installs all necessary packages specified in pyproject.toml.
Activate the virtual environment:
```
poetry shell
```

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

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

🧪
Testing

🔍
Type Checking

✨
Linting

📊
Coverage

poetry run pytest

poetry run pytest -v

poetry run mypy src/

pyright src/

poetry run ruff check .

poetry run ruff format .

poetry run pytest --cov=src

coverage html

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

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

Built with ❤️ for the scientific research community

NexusMind - Advancing scientific reasoning through intelligent graph structures

🧠 NexusMind

    ╔══════════════════════════════════════╗
    ║                                      ║
    ║           🧠 NexusMind 🧠            ║
    ║                                      ║
    ║     Intelligent Scientific           ║
    ║     Reasoning through                ║
    ║     Graph-of-Thoughts                ║
    ║                                      ║
    ╚══════════════════════════════════════╝

Intelligent Scientific Reasoning through Graph-of-Thoughts

🚀 Next-Generation AI Reasoning Framework for Scientific Research

Leveraging graph structures to transform how AI systems approach scientific reasoning

🔍 Overview

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

🔄 Multi-Dimensional Confidence	🧠 Graph-Based Knowledge	🔌 MCP Integration	⚡ FastAPI Backend
🐳 Docker Deployment	🧩 Modular Design	⚙️ Configuration Management	🔒 Type Safety
🌐 Interdisciplinary Bridge Nodes	🔗 Hyperedge Support	📊 Statistical Power Analysis	🎯 Impact Estimation

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

Python 3.13+	FastAPI	NetworkX	Docker
Pytest	Pydantic	Poetry	Uvicorn

📂 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:
```
poetry install
```
This creates a virtual environment and installs all necessary packages specified in pyproject.toml.
Activate the virtual environment:
```
poetry shell
```

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

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

🧪
Testing

🔍
Type Checking

✨
Linting

📊
Coverage

poetry run pytest

poetry run pytest -v

poetry run mypy src/

pyright src/

poetry run ruff check .

poetry run ruff format .

poetry run pytest --cov=src

coverage html

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

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

Built with ❤️ for the scientific research community

NexusMind - Advancing scientific reasoning through intelligent graph structures

NexusMind

🧠 NexusMind

Intelligent Scientific Reasoning through Graph-of-Thoughts

🔍 Overview

🌟 Key Features

8-Stage Reasoning Pipeline

Advanced Technical Capabilities

🛠️ Technology Stack

📂 Project Structure

🚀 Getting Started

Prerequisites

Installation and Setup (Local Development)

Docker Deployment

🔌 API Endpoints

Core Endpoints

Advanced Endpoints

🧪 Testing & Quality Assurance

Development Commands

Quality Metrics

🔧 Configuration

Application Settings (config/settings.yaml)

MCP Configuration (config/claude_mcp_config.json)

🤝 Contributing

Development Setup

Code Style

📚 Documentation

📄 License

🙏 Acknowledgments

🧠 NexusMind

Intelligent Scientific Reasoning through Graph-of-Thoughts

🔍 Overview

🌟 Key Features

8-Stage Reasoning Pipeline

Advanced Technical Capabilities

🛠️ Technology Stack

📂 Project Structure

🚀 Getting Started

Prerequisites

Installation and Setup (Local Development)

Docker Deployment

🔌 API Endpoints

Core Endpoints

Advanced Endpoints

🧪 Testing & Quality Assurance

Development Commands

Quality Metrics

🔧 Configuration

Application Settings (config/settings.yaml)

MCP Configuration (config/claude_mcp_config.json)

🤝 Contributing

Development Setup

Code Style

📚 Documentation

📄 License

🙏 Acknowledgments

Application Settings (`config/settings.yaml`)

MCP Configuration (`config/claude_mcp_config.json`)

Application Settings (`config/settings.yaml`)

MCP Configuration (`config/claude_mcp_config.json`)