Metadata-Version: 2.4
Name: spikeagent
Version: 1.0.0
Summary: AI-powered assistant for spike sorting and neural data analysis
Author: SpikeAgent Contributors
License: MIT
Project-URL: Homepage, https://github.com/arnaumarin/SpikeAgent
Project-URL: Documentation, https://github.com/arnaumarin/SpikeAgent/tree/main/docs
Project-URL: Repository, https://github.com/arnaumarin/SpikeAgent
Project-URL: Issues, https://github.com/arnaumarin/SpikeAgent/issues
Keywords: neuroscience,spike-sorting,ai,electrophysiology,neural-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: streamlit>=1.43.2
Requires-Dist: streamlit-audiorec>=0.1.3
Requires-Dist: audio-recorder-streamlit>=0.0.8
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: langchain>=0.3.20
Requires-Dist: langchain-core>=0.3.67
Requires-Dist: langchain-anthropic>=0.3.10
Requires-Dist: langchain-openai>=0.3.11
Requires-Dist: langchain-google-genai>=2.1.1
Requires-Dist: langchain-community>=0.3.19
Requires-Dist: langchain-experimental>=0.3.4
Requires-Dist: langchain-text-splitters>=0.3.6
Requires-Dist: langgraph>=0.3.8
Requires-Dist: langgraph-checkpoint>=2.0.19
Requires-Dist: langgraph-prebuilt>=0.1.2
Requires-Dist: langgraph-sdk>=0.1.56
Requires-Dist: langsmith<0.4,>=0.3.45
Requires-Dist: anthropic>=0.49.0
Requires-Dist: openai>=1.68.2
Requires-Dist: google-ai-generativelanguage>=0.6.18
Requires-Dist: google-api-core>=2.24.2
Requires-Dist: google-auth>=2.38.0
Requires-Dist: googleapis-common-protos>=1.69.2
Requires-Dist: spikeinterface>=0.102.3
Requires-Dist: spikeextractors>=0.9.11
Requires-Dist: probeinterface>=0.2.26
Requires-Dist: sortingview>=0.14.1
Requires-Dist: kilosort>=4.0.21
Requires-Dist: mountainsort4>=1.0.6
Requires-Dist: mountainsort5
Requires-Dist: herdingspikes>=0.4.6
Requires-Dist: numpy>=1.26.4
Requires-Dist: pandas>=2.2.3
Requires-Dist: scipy>=1.15.2
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: h5py>=3.13.0
Requires-Dist: zarr>=2.18.7
Requires-Dist: matplotlib>=3.10.1
Requires-Dist: plotly>=6.0.1
Requires-Dist: plotly-express>=0.4.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: bokeh>=3.6.3
Requires-Dist: altair>=4.2.2
Requires-Dist: dash>=3.0.0
Requires-Dist: dash-core-components>=2.0.0
Requires-Dist: dash-html-components>=2.0.0
Requires-Dist: dash-table>=5.0.0
Requires-Dist: pydeck>=0.9.1
Requires-Dist: kaleido
Requires-Dist: pillow>=11.1.0
Requires-Dist: rich>=14.0.0
Requires-Dist: contourpy>=1.3.1
Requires-Dist: cycler>=0.12.1
Requires-Dist: fonttools>=4.56.0
Requires-Dist: kiwisolver>=1.4.8
Requires-Dist: pydantic>=2.10.6
Requires-Dist: pydantic-settings>=2.8.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: requests
Requires-Dist: filetype>=1.2.0
Requires-Dist: nest-asyncio
Requires-Dist: PyYAML
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: aiohappyeyeballs>=2.6.1
Requires-Dist: aiohttp>=3.11.13
Requires-Dist: aiosignal>=1.3.2
Requires-Dist: anyio
Requires-Dist: async-lru
Requires-Dist: httpx
Requires-Dist: httpx-sse>=0.4.0
Requires-Dist: httpcore
Requires-Dist: h11
Requires-Dist: h2
Requires-Dist: hpack
Requires-Dist: hyperframe
Requires-Dist: frozenlist>=1.5.0
Requires-Dist: multidict>=6.1.0
Requires-Dist: yarl>=1.18.3
Requires-Dist: sniffio
Requires-Dist: idna
Requires-Dist: uvicorn>=0.34.0
Requires-Dist: starlette>=0.46.1
Requires-Dist: neo>=0.14.1
Requires-Dist: quantities>=0.16.1
Requires-Dist: hdmf>=4.1.0
Requires-Dist: pynwb>=3.0.0
Requires-Dist: elephant>=1.1.1
Requires-Dist: MEArec>=1.9.2
Requires-Dist: MEAutility>=1.5.3
Requires-Dist: LFPy>=2.3.5
Requires-Dist: LFPykit>=0.5.1
Requires-Dist: NEURON>=8.2.6
Requires-Dist: isosplit5>=0.2.2
Requires-Dist: mtscomp>=1.0.2
Requires-Dist: jupyter
Requires-Dist: jupyterlab
Requires-Dist: jupyterlab-server
Requires-Dist: jupyterlab-widgets
Requires-Dist: jupyter-server
Requires-Dist: jupyter-server-terminals
Requires-Dist: jupyter-client
Requires-Dist: jupyter-core
Requires-Dist: jupyter-console
Requires-Dist: jupyter-events
Requires-Dist: jupyter-lsp
Requires-Dist: jupyterlab-pygments
Requires-Dist: ipython
Requires-Dist: ipykernel
Requires-Dist: ipywidgets
Requires-Dist: notebook
Requires-Dist: notebook-shim
Requires-Dist: nbconvert
Requires-Dist: nbformat
Requires-Dist: nbclient
Requires-Dist: matplotlib-inline
Requires-Dist: traitlets
Requires-Dist: prompt-toolkit
Requires-Dist: Pygments
Requires-Dist: widgetsnbextension
Requires-Dist: jedi
Requires-Dist: parso
Requires-Dist: pexpect
Requires-Dist: pickleshare
Requires-Dist: decorator
Requires-Dist: executing
Requires-Dist: stack-data
Requires-Dist: pure-eval
Requires-Dist: asttokens
Requires-Dist: terminado
Requires-Dist: Send2Trash
Requires-Dist: prometheus-client
Requires-Dist: accelerate>=1.10.0
Requires-Dist: transformers>=4.51.3
Requires-Dist: transformers-stream-generator>=0.0.5
Requires-Dist: huggingface-hub>=0.30.2
Requires-Dist: safetensors>=0.5.3
Requires-Dist: tokenizers>=0.21.1
Requires-Dist: tiktoken>=0.9.0
Requires-Dist: sentencepiece>=0.2.0
Requires-Dist: transformer-lens>=2.16.1
Requires-Dist: wandb>=0.21.1
Requires-Dist: tensorboard>=2.19.0
Requires-Dist: tensorboard-data-server>=0.7.2
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=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.0.0; extra == "dev"

<p align="center">
  <img src="docs/spikeagent_logo.png" alt="SpikeAgent Logo" width="300" style="display:block; margin:auto; background:#fff; box-shadow:0 2px 12px rgba(0,0,0,0.1)">
</p>

<!--
If the logo image does not appear above this line, make sure the file exists at:
docs/img/spikeagent_logo.png
-->

[![GitHub stars](https://img.shields.io/github/stars/SpikeAgent/SpikeAgent)](https://github.com/LiuLab-Bioelectronics-Harvard/SpikeAgent/stargazers)

# SpikeAgent

**An AI-powered assistant for spike sorting and neural data analysis**

SpikeAgent is a web-based AI assistant designed to help neuroscience laboratories analyze neural electrophysiology data. It provides an intuitive interface for spike sorting workflows, data curation, and neural data analysis, powered by state-of-the-art language models (OpenAI, Anthropic, and Google's Gemini).

## What is SpikeAgent?

SpikeAgent automates and streamlines the spike sorting pipeline, from raw neural recordings to curated spike trains. It leverages AI to assist with:

- **Spike sorting**: Automated detection and classification of action potentials
- **Data curation**: AI-assisted quality control and unit validation
- **Visual analysis**: Vision-language models for analyzing spike sorting outputs
- **Workflow guidance**: Interactive assistance throughout the analysis pipeline

The tool integrates with [SpikeInterface](https://github.com/SpikeInterface/spikeinterface), a unified framework for spike sorting, providing a seamless experience for analyzing neural data from various recording systems.

## Quick Start (5 Minutes)

### What You Need

1. **Docker** - Make sure Docker Desktop is installed and running (for Docker installation)
   - OR **Python 3.11+** (for pip installation)
2. **One API Key** - Choose one of these:
   - [OpenAI API Key](https://platform.openai.com/api-keys) - OR -
   - [Anthropic API Key](https://console.anthropic.com/) - OR -
   - [Google API Key](https://makersuite.google.com/app/apikey)

That's it! You only need one API key to get started.

### Installation Options

SpikeAgent offers three ways to install and run:

#### Option 1: Pip Installation (Recommended for Development)

```bash
# Install from PyPI
pip install spikeagent

# Or install from source
git clone https://github.com/arnaumarin/SpikeAgent.git
cd SpikeAgent
pip install -e .

# Run the application
spikeagent
# or
python -m spikeagent.app.main
```

#### Option 2: Docker (Recommended for Production)

SpikeAgent offers two ways to run with Docker:

- **CPU Version** - Works on any computer, easiest to set up
- **GPU Version** - For systems with NVIDIA GPUs (needed for some spike sorters like Kilosort4)

#### Using Pre-built CPU Image (Easiest Method)

**Step 1: Create a `.env` file**

Create a file named `.env` in your working directory with your API keys. You need **at least one** of these:

```bash
# Create the .env file
touch .env
```

Then add your API keys to the `.env` file. Here are examples:

**Example 1: Using OpenAI (Standard)**
```bash
OPENAI_API_KEY=sk-your-actual-key-here
```

**Example 2: Using OpenAI (Custom/Institutional Endpoint)**
```bash
OPENAI_API_KEY=your_institution_key_here
OPENAI_API_BASE=https://your-institution-endpoint.com/v1
```

**Example 3: Using Anthropic**
```bash
ANTHROPIC_API_KEY=sk-ant-your-actual-key-here
```

**Example 4: Using Google/Gemini**
```bash
GOOGLE_API_KEY=your-google-api-key-here
```

**You only need ONE of these options** - choose the provider you prefer!

**Important Notes:**
- You only need **one** API key (OpenAI, Anthropic, or Google) - choose whichever you prefer
- If using a custom or institutional OpenAI endpoint, include both `OPENAI_API_KEY` and `OPENAI_API_BASE`
- If using standard OpenAI, you only need `OPENAI_API_KEY` (no `OPENAI_API_BASE` needed)
- The `.env` file should be in the same directory where you run the Docker commands

**Step 2: Run SpikeAgent**

**Option A: Using the automated script (Easiest):**

```bash
# Run without volume mounts (if you don't need to access local data)
./run-spikeagent.sh

# Run with volume mounts (to access your data directories)
./run-spikeagent.sh /path/to/your/data /path/to/results
```

**Volume Mounts (Optional but Recommended):**

If you need SpikeAgent to access your local data files, you should mount your data directories when running the script:

```bash
# Mount a single data directory
./run-spikeagent.sh /path/to/your/raw/data

# Mount multiple directories (e.g., raw data and results folder)
./run-spikeagent.sh /path/to/raw/data /path/to/processed/results

# Mount relative paths (automatically converted to absolute)
./run-spikeagent.sh ./data ./results
```

**Why mount volumes?**
- SpikeAgent needs access to your raw electrophysiology data files
- You may want to save processed results to a specific location
- Config files (YAML) and other data should be accessible to the container

**What paths should you mount?**
- **Raw data directory**: Where your experimental data files are stored (e.g., `.rhd`, SpikeGLX files, etc.)
- **Results/output directory**: Where you want processed data and results saved
- **Config directory**: If you have YAML configuration files (optional)

The script will:
- Pull the latest image from GitHub
- Mount your specified directories (if provided)
- Start the container
- Wait for the application to be ready
- Open your browser automatically

**Option B: Manual Docker commands:**

```bash
# Pull the latest CPU image
docker pull ghcr.io/arnaumarin/spikeagent-cpu:latest

# Run without volume mounts
docker run --rm -p 8501:8501 --env-file .env ghcr.io/arnaumarin/spikeagent-cpu:latest

# Run with volume mounts (to access your data)
docker run --rm -p 8501:8501 --env-file .env \
  -v /path/to/your/data:/path/to/your/data \
  -v /path/to/results:/path/to/results \
  ghcr.io/arnaumarin/spikeagent-cpu:latest
```

**Step 3: Access the application**

Once the container is running, open your browser and go to:
```
http://localhost:8501
```

That's it! You're ready to use SpikeAgent.

**GPU Version (Build Locally):**

The GPU version is not yet available as a pre-built package. You need to build it locally:

```bash
# Build the GPU image
docker build -f dockerfiles/Dockerfile.gpu -t spikeagent:gpu .

# Create a .env file with your API keys, then run the container
docker run --rm --gpus all -p 8501:8501 --env-file .env spikeagent:gpu
```

**Adding Volume Mounts After Startup:**

If you need to access a data path that wasn't mounted when you started the container:

```bash
# Add mounts to existing container (preserves existing mounts)
./run-spikeagent.sh --add /path/to/new/data

# You can add multiple paths at once
./run-spikeagent.sh --add /path/to/data1 /path/to/data2

# Or restart with new mounts only (replaces existing mounts)
./run-spikeagent.sh --restart /path/to/data
```

The `--add` option will:
- Stop the current container
- Preserve all existing volume mounts
- Add your new paths
- Restart the container

**Note:** Docker containers cannot mount new volumes at runtime - a restart is required. The app UI will show you the exact command to run if it detects an unmounted path.

**Troubleshooting:**

- **Port already in use?** Make sure port 8501 is free, or stop any existing containers: `docker stop spikeagent`
- **Can't pull image?** The image is public, so no authentication needed. If you have issues, make sure Docker is running.
- **ARM64/Apple Silicon (M1/M2/M3 Mac)?** If you get "no matching manifest for linux/arm64" error, the run script will automatically detect this and build the image locally for you. The first build may take 10-20 minutes. Once multi-arch images are available, this will no longer be necessary.
- **Path not accessible in app?** If you see a warning about a path not being found, use `./restart-spikeagent-with-mounts.sh /path/to/data` to add it. The app will show you the exact command to use.
- **API connection errors?** Double-check your `.env` file has the correct API keys and is in the same directory as your Docker command.

## Open Source Neural Data

You can test SpikeAgent with open datasets such as [Neuropixels 2.0 chronic recordings in mice](https://doi.org/10.5522/04/24411841.v1) and [AutoSort flexible electrode recordings](https://github.com/LiuLab-Bioelectronics-Harvard/AutoSort).

## Tutorials

The repository includes Jupyter notebook tutorials to help you get started:

- **`tutorials/vlm_noise_rejection_tutorial.ipynb`**: Tutorial on using Vision Language Models (VLM) for AI-assisted spike curation
  - Classifying units as "Good" or "Bad" based on visual features
  - Using waveforms, autocorrelograms, and spike locations for quality control
  - Applying curation to filter out noise units

- **`tutorials/vlm_merge_simple_tutorial.ipynb`**: Tutorial on using VLM for merge analysis
  - Finding potential merge candidates automatically
  - Analyzing visual features using AI (crosscorrelograms, amplitude plots, PCA clustering)
  - Making merge decisions based on AI analysis
  - Applying merges to consolidate units from the same neuron

## Project Structure

```
spikeagent/
├── src/spikeagent/                      # Main source code package
│   ├── app/                            # Application code
│   └── curation/                       # Curation and VLM analysis tools
├── dockerfiles/                        # Docker configuration files
│   ├── Dockerfile.cpu                  # CPU Docker image
│   └── Dockerfile.gpu                  # GPU Docker image
├── docs/                               # Documentation
│   └── img/                            # Documentation images
├── tutorials/                         # Jupyter notebook tutorials
│   ├── vlm_merge_simple_tutorial.ipynb # VLM merge analysis tutorial
│   └── vlm_noise_rejection_tutorial.ipynb # VLM curation tutorial
└── tests/                              # Test suite
```

## Documentation

Comprehensive documentation is available in the [`docs/`](docs/) directory:

- **[Installation Guide](docs/installation.md)**: Detailed setup and installation instructions
- **[User Guide](docs/user-guide.md)**: How to use SpikeAgent for spike sorting and curation
- **[API Reference](docs/api-reference.md)**: Programmatic API documentation

## Getting Help

For detailed setup instructions, troubleshooting, and usage information:
- Review the [Installation Guide](docs/installation.md)
- Check the [User Guide](docs/user-guide.md) for workflows
- Explore the Jupyter notebook tutorials in `tutorials/`
- Ensure your `.env` file contains the required API keys

## Citation

If you find SpikeAgent useful for your work, please cite:

**SpikeAgent**:
Lin, Z., Marin-Llobet, A., Baek, J., He, Y., Lee, J., Wang, W., ... & Liu, J. (2025). Spike sorting AI agent. Preprint at bioRxiv: https://doi.org/10.1101/2025.02.11.637754

**SpikeInterface**:
Buccino, A. P., Hurwitz, C. L., Garcia, S., Magland, J., Siegle, J. H., Hurwitz, R., & Hennig, M. H. (2020). SpikeInterface, a unified framework for spike sorting. Elife, 9, e61834.
