Installation¶

Prerequisites¶

Python 3.10 or higher
CUDA-capable GPU (recommended) or CPU
8GB+ RAM

Install from PyPI¶

The recommended way to install COSMIC:

# Install core package
pip install cosmic-chunker

# Install with all optional dependencies (recommended)
pip install cosmic-chunker[all]

# Install spaCy model for coreference resolution
python -m spacy download en_core_web_trf

Installation Options¶

Option	Command	Description
Core	`pip install cosmic-chunker`	Basic installation
All	`pip install cosmic-chunker[all]`	Includes dev and benchmark dependencies
Dev	`pip install cosmic-chunker[dev]`	Testing and linting tools
Benchmark	`pip install cosmic-chunker[benchmark]`	Benchmarking dependencies

Install from Source¶

For development or to get the latest changes:

# Clone the repository
git clone https://github.com/manceps/cosmic.git
cd cosmic

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

# Install with all dependencies
pip install -e ".[all]"

# Install spaCy model
python -m spacy download en_core_web_trf

Docker Installation¶

# Build container
docker build -t cosmic:latest .

# Run with GPU support
docker run --gpus all -v $(pwd):/workspace cosmic:latest

Verify Installation¶

# Check version
cosmic info

# Run a quick test
cosmic chunk --help

Optional: Ollama Setup¶

For local LLM verification without API costs:

Install Ollama from ollama.com/download
Pull a model:
```
ollama pull gemma3
```

Use with COSMIC:

cosmic chunk document.txt --strategy full --ollama auto

Troubleshooting¶

CUDA Not Found¶

If you don't have a GPU, COSMIC will automatically use CPU. To explicitly set:

export COSMIC_EMBEDDING_DEVICE=cpu

spaCy Model Download Fails¶

Try downloading directly:

python -m spacy download en_core_web_sm  # Smaller alternative

Memory Issues¶

Reduce batch size or use CPU:

export COSMIC_EMBEDDING_DEVICE=cpu

See Troubleshooting for more solutions.