Skip to content

Installation Guide

Get Citation Compass up and running on your system.

Prerequisites

Before installing, ensure you have:

  • Python 3.8+ installed on your system
  • Neo4j database (local or cloud instance)
  • Git for cloning the repository
  • pip for package management

Recommended Setup

We recommend using a virtual environment to isolate dependencies and avoid conflicts with other Python projects.

Installation Options

Choose the installation method that best fits your needs:

# Clone the repository
git clone https://github.com/dagny099/citation-compass.git
cd citation-compass

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

# Clone the repository
git clone https://github.com/dagny099/citation-compass.git
cd citation-compass

# Install base dependencies only
pip install -e .

# Add optional feature sets as needed
pip install -e ".[ml]"        # Machine learning features
pip install -e ".[analytics]" # Advanced analytics
pip install -e ".[viz]"       # Visualization tools
pip install -e ".[web]"       # Streamlit interface
pip install -e ".[dev]"       # Development tools

# Clone the repository
git clone https://github.com/dagny099/citation-compass.git
cd citation-compass

# Build and run with Docker Compose
docker-compose up -d

Virtual Environment Setup

Important

Always use a virtual environment to avoid dependency conflicts:

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

# Install the platform
pip install -e ".[all]"

Verify Installation

Test your installation to ensure everything is working correctly:

# Test basic imports
python -c "
from src.database.connection import Neo4jConnection
from src.services.analytics_service import get_analytics_service
print('✅ Basic installation successful')
"

# Run all tests to verify functionality  
python -m pytest tests/ -v

# Verify Streamlit works
streamlit --version

Next Steps

After installation, proceed to:

  1. Configuration → - Set up your environment variables
  2. Environment Setup → - Configure Neo4j and validate setup
  3. Quick Start → - Run your first analysis

Troubleshooting

Common Installation Issues

ImportError: No module named 'src'

This usually means the package wasn't installed in editable mode. Make sure to use: 

pip install -e ".[all]"
Note the -e flag for editable installation.

Neo4j connection errors

Neo4j connection issues are usually configuration problems. See Configuration Guide for database setup.

PyTorch installation issues

If you encounter PyTorch installation problems: 

# Install PyTorch separately first
pip install torch torchvision torchaudio
# Then install the platform
pip install -e ".[all]"

Permission denied errors

On some systems you may need to use --user flag: 

pip install --user -e ".[all]"

Getting Help

If you encounter issues:

  1. Check the installation steps above carefully
  2. Search existing GitHub Issues
  3. Join our community discussions
  4. Create an issue on GitHub

System Requirements

Minimum Requirements

  • CPU: 2+ cores
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 2GB for installation, additional space for data
  • Python: 3.8, 3.9, 3.10, or 3.11
  • CPU: 4+ cores with good single-thread performance
  • RAM: 16GB+ for large citation networks
  • Storage: SSD recommended, 10GB+ free space
  • GPU: CUDA-compatible GPU for ML training (optional)

Supported Operating Systems

  • macOS: 10.15+ (Catalina and later)
  • Linux: Ubuntu 18.04+, CentOS 7+, other modern distributions
  • Windows: Windows 10+ (Windows Subsystem for Linux recommended)