Metadata-Version: 2.4
Name: semanticscout
Version: 3.4.2
Summary: A language-aware semantic code search MCP server with intelligent filtering and 9.3x better dependency analysis
Author-email: Psynosaur <psynosaur@gmail.com>
Maintainer-email: Psynosaur <psynosaur@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Psynosaur/SemanticScout
Project-URL: Repository, https://github.com/Psynosaur/SemanticScout.git
Project-URL: Issues, https://github.com/Psynosaur/SemanticScout/issues
Project-URL: Documentation, https://github.com/Psynosaur/SemanticScout#readme
Keywords: mcp,context-engine,code-search,vector-database,ai-agents,semantic-search,ollama,chromadb
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: chromadb>=0.4.0
Requires-Dist: openai>=1.0.0
Requires-Dist: tree-sitter<0.22,>=0.20.0
Requires-Dist: tree-sitter-languages>=1.10.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pathspec>=0.11.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: networkx>=3.2.1
Requires-Dist: psutil>=5.9.0
Requires-Dist: sentence-transformers>=2.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Provides-Extra: fast
Requires-Dist: sentence-transformers>=2.2.0; extra == "fast"
Provides-Extra: gpu
Requires-Dist: torch>=2.0.0; extra == "gpu"
Requires-Dist: torchvision>=0.15.0; extra == "gpu"
Requires-Dist: torchaudio>=2.0.0; extra == "gpu"
Dynamic: license-file

# SemanticScout

A language-aware semantic code search MCP server with intelligent filtering and enhanced dependency analysis.

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GPU Support](https://img.shields.io/badge/GPU-CUDA%20Accelerated-green.svg)](https://pytorch.org/get-started/locally/)

## 🚀 Features

- **🧠 Semantic Search**: Natural language understanding of code functionality
- **🔍 Symbol Resolution**: Precise function/class/variable lookup with AST parsing
- **📊 Dependency Tracking**: Advanced dependency graph analysis (9.3x better than v3.1.4)
- **🎯 Context Expansion**: Intelligent code context retrieval with multiple expansion levels
- **⚡ GPU Acceleration**: 5-10x faster embedding generation with CUDA support
- **🔧 Language Support**: Python, JavaScript, TypeScript, Java, C#, Go, Rust, and more
- **🎛️ Query Intent Tracking**: Meta-learning system for search optimization
- **🚀 High Performance**: Optimized indexing with parallel processing

## 📋 Prerequisites

- **Python 3.12 or higher** (required)
- 4GB+ RAM recommended
- SSD storage for best performance
- **Optional**: NVIDIA GPU with CUDA support for 5-10x acceleration
- **Optional**: Ollama with `nomic-embed-text` model (alternative embedding provider)

## 🛠️ Installation

### Python 3.12 Setup

**macOS (Homebrew)**:
```bash
brew install python@3.12
```

**Windows**:
- Download from [python.org](https://www.python.org/downloads/windows/)
- Or use winget: `winget install Python.Python.3.12`

**Linux (Ubuntu/Debian)**:
```bash
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-pip
```

**Linux (CentOS/RHEL/Fedora)**:
```bash
sudo dnf install python3.12 python3.12-pip
```

### SemanticScout Installation

1. **Install SemanticScout**:
   ```bash
   # Basic installation (uses sentence-transformers by default)
   pip install semanticscout

   # With GPU support (recommended for 5-10x performance boost)
   pip install semanticscout[gpu]
   ```

2. **Verify Installation**:
   ```bash
   python -c "import semanticscout; print('✅ SemanticScout installed')"
   ```

3. **Optional: Install Ollama** (alternative embedding provider):
   ```bash
   # Download from https://ollama.ai
   ollama pull nomic-embed-text
   ```

### 🎮 GPU Support (Recommended for Performance)

SemanticScout uses **sentence-transformers by default** and supports GPU acceleration for 5-10x faster embedding generation.

**Two ways to enable GPU support:**

**Option 1: Install with GPU extras (easiest)**:
```bash
pip install semanticscout[gpu]
```

**Option 2: Manual PyTorch GPU installation**:
```bash
# For CUDA 12.4 (recommended)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# For CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```

**Verify GPU Support**:
```bash
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU devices: {torch.cuda.device_count()}')"
```

**Performance Comparison**:
- **CPU**: ~100-200 embeddings/second
- **GPU**: ~1000-2000 embeddings/second (RTX 3090/4090)
- **Large codebases**: 5-10x faster indexing
- **Auto-detection**: GPU used automatically if available, graceful CPU fallback

## ⚙️ Configuration

Configure SemanticScout in your MCP client (e.g., Claude Desktop's `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "semanticscout": {
      "command": "uvx",
      "args": ["--python", "3.12", "semanticscout@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "sentence-transformers",
        "DEVICE_PREFERENCE": "auto",
        "GPU_BATCH_SIZE": "64",
        "SEMANTICSCOUT_ENABLE_ENHANCEMENTS": "true"
      }
    }
  }
}
```

**For Ollama (alternative embedding provider)**:
```json
{
  "mcpServers": {
    "semanticscout": {
      "command": "uvx",
      "args": ["--python", "3.12", "semanticscout@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "nomic-embed-text"
      }
    }
  }
}
```

### GPU Configuration Options

```bash
# Auto-detect GPU (default)
DEVICE_PREFERENCE=auto

# Force GPU usage
DEVICE_PREFERENCE=cuda

# Force CPU usage
DEVICE_PREFERENCE=cpu

# Customize batch sizes
GPU_BATCH_SIZE=128
CPU_BATCH_SIZE=32

# Enable GPU memory monitoring
GPU_MEMORY_MONITORING=true
```

## 🚀 Quick Start

1. **Index your codebase**:
   ```bash
   # Index current directory
   index_codebase()
   
   # Index specific path
   index_codebase(path="/path/to/your/project")
   ```

2. **Search your code**:
   ```bash
   # Natural language search
   search_code("authentication functions", collection_name="your_project")
   
   # Find specific symbols
   find_symbol("UserController", collection_name="your_project")
   ```

3. **Check GPU status**:
   ```bash
   get_gpu_status()
   ```

## 📚 Documentation

- [User Guide](docs/USER_GUIDE.md) - Complete usage guide
- [API Reference](docs/API_REFERENCE.md) - Detailed API documentation
- [Configuration](docs/CONFIGURATION.md) - Advanced configuration options
- [Performance Tuning](docs/PERFORMANCE_TUNING.md) - Optimization tips
- [Architecture](docs/ARCHITECTURE.md) - Technical architecture details

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [FastMCP](https://github.com/pydantic/fastmcp) framework
- Powered by [ChromaDB](https://www.trychroma.com/) vector database
- Uses [tree-sitter](https://tree-sitter.github.io/) for AST parsing
- GPU acceleration via [PyTorch](https://pytorch.org/)
- Embeddings by [Ollama](https://ollama.ai/) and [sentence-transformers](https://www.sbert.net/)

---

**Made with ❤️ for developers who want smarter code search**
