Installation

There are two ways to install VectorScope:

PyPI install - Quick installation with full UI (recommended for users)
Development install - For contributing or modifying VectorScope

Option 1: Install from PyPI (Recommended)

Install VectorScope with pip:

pip install vectorscope

This installs both the backend API and the frontend UI.

Running VectorScope

Start VectorScope with a single command:

vectorscope

This starts the backend API server which also serves the frontend UI. Open http://localhost:8000 in your browser to access the full VectorScope interface - no separate frontend server needed.

Command-line options:

vectorscope                  # Start at localhost:8000
vectorscope --port 9000      # Use custom port
vectorscope --host 0.0.0.0   # Listen on all interfaces
vectorscope --reload         # Auto-reload on code changes (development)
vectorscope --version        # Show version
vectorscope --help           # Show all options

Verifying the Installation

Start the server:
```
vectorscope
```
Open http://localhost:8000 in your browser
You should see the VectorScope interface with the logo and empty graph editor
Click Load Dataset and select iris to load sample data
The Iris dataset should appear as a layer node in the graph editor

If you see the interface and can load data, the installation is complete!

Checking the API:

You can also verify the API is running:

curl http://localhost:8000/health
# Should return: {"status":"healthy"}

curl http://localhost:8000/api
# Should return: {"name":"VectorScope","version":"1.2.0",...}

Option 2: Development Installation

For development or contributing to VectorScope, use a full source installation.

Prerequisites

Pixi - Python package and environment manager
Node.js 18 or later - for frontend development

Installing Pixi

On macOS/Linux:

curl -fsSL https://pixi.sh/install.sh | bash

On Windows (PowerShell):

iwr -useb https://pixi.sh/install.ps1 | iex

Installing Node.js

Download from nodejs.org or use a version manager like nvm.

Installing from Source

Clone the repository:

git clone https://github.com/cranmer/vectorscope.git
cd vectorscope

Install Python dependencies with Pixi:
```
pixi install
```
This creates a managed Python environment with all required packages.
Install frontend dependencies:
```
cd frontend
npm install
cd ..
```

Running in Development Mode

Development mode runs the backend and frontend separately, with hot-reloading:

# Terminal 1: Start the backend with auto-reload
pixi run uvicorn backend.main:app --reload --port 8000

# Terminal 2: Start the frontend dev server
cd frontend && npm run dev

Open http://localhost:5173 in your browser. The frontend dev server proxies API requests to the backend automatically.

Running Tests

# Run backend tests
pixi run pytest backend/tests

# Run with coverage
pixi run pytest backend/tests --cov=backend

Building Documentation

pixi run sphinx-build -b html docs docs/_build/html

The documentation will be in docs/_build/html/.

Troubleshooting

Port already in use:

# Find what's using the port
lsof -i :8000

# Use a different port
vectorscope --port 8001

Frontend not loading:

If you see JSON instead of the UI at http://localhost:8000, the frontend assets may not be installed correctly. Try reinstalling:

pip uninstall vectorscope
pip install vectorscope

Import errors:

Make sure you have Python 3.10 or later:

python --version
# Should be 3.10.x or higher

Missing dependencies:

pip install vectorscope[dev]  # Install with dev dependencies