Installation

Install Archeo-Cluster and set up your Python environment.

Prerequisites

Before installing Archeo-Cluster, make sure you have:

• Python 3.11 or later — Archeo-Cluster requires Python 3.11+. Check your version with python --version.
• uv — The recommended package manager for Archeo-Cluster. Install it from docs.astral.sh/uv.

uv handles virtual environment creation and dependency locking automatically. You do not need to create a virtual environment manually.

Install Archeo-Cluster

1. Clone the repository

   git clone https://github.com/keviingarciah/archeo-cluster.git
   cd archeo-cluster
   
2. Install dependencies

   Run uv sync to install all dependencies into an isolated virtual environment:

   uv sync
   

   uv reads pyproject.toml and installs all required packages including NumPy, OpenCV, pandas, scikit-learn, matplotlib, and Typer.

3. Verify the installation

   Confirm the CLI is available using either of these commands:

   run-cli

   ./run-cli --help
   

   You should see the Archeo-Cluster help output listing available commands: detect, cluster, analyze, pipeline, and sessions.

Dev install

If you plan to contribute or run the test suite, install the development dependencies:

uv sync --extra dev

This adds pytest, ruff, mypy, pre-commit, and type stubs to your environment. Then set up the pre-commit hooks:

uv run pre-commit install

Pre-commit hooks run ruff formatting and linting checks automatically on every commit.

Running make commands

The project includes a Makefile with common development tasks:

Command	Description
make install	Install dependencies with uv sync --extra dev
make test	Run the full test suite with pytest
make lint	Run ruff and mypy on src/ and tests/
make format	Format and auto-fix code with ruff
make check	Run lint and test together

# Run tests
make test

# Lint and type-check
make lint

# Format code
make format

# Run all checks
make check

Use make check before opening a pull request to run both linting and the test suite in one step.

Troubleshooting

If ./run-cli fails with a permission error, make the script executable: chmod +x run-cli

If uv is not found, install it following the uv installation guide and ensure it is on your PATH.

If you see import errors for cv2 or other packages, confirm you are running commands with uv run or that your shell has activated the uv-managed virtual environment.