Getting Started Installation Environment Setup

Getting Started: Installation & Environment Setup

This page provides a technical guide for setting up the Claude Sleuth development environment. It covers the installation of core and modular dependency groups, the structure of the Python project, and the use of the specialized CLI entry points for managing investigations.

Prerequisites & Environment Creation

Claude Sleuth requires Python 3.10 or higher. The project is designed to be installed in an editable state to allow for rapid development of investigative scripts and templates.

Local Setup Steps

1. Clone the repository:

   git clone https://github.com/elb-pr/claude-sleuth.git
   cd claude-sleuth

2. Initialize a Virtual Environment: It is recommended to use a virtual environment to isolate the 50+ investigative packages.

   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Install Core Dependencies: The core installation provides essential HTTP, data handling, and utility libraries.

   pip install -e .

Project Structure & Dependency Management

The project uses pyproject.toml as the primary configuration for builds and dependencies. It defines three main CLI entry points used throughout the investigation lifecycle:

CLI Command	Source Script	Purpose
sleuth-setup	scripts.setup:main	Modular dependency installation
sleuth-task	scripts.task_runner:main	Investigation state machine and gatekeeper
sleuth-template	scripts.template_builder:main	Workspace assembly from Markdown templates

Dependency Groups

Dependencies are categorized into functional modules. This allows users to install only the tools necessary for a specific phase (e.g., geo for spatial analysis or network for infrastructure investigation).

Core Dependencies (Always Installed):

• requests, httpx, aiohttp: Network communication.
• pandas, numpy: Data processing.
• rich, tqdm: CLI visualization and progress tracking.
• beautifulsoup4, lxml: HTML/XML parsing.

Modular Installation with setup.py

The setup.py script (invoked via sleuth-setup) manages these groups. It provides a more granular interface than standard pip for managing the toolkit's 13 distinct modules.

# List all available modules and their descriptions
sleuth-setup --list

# Install specific modules for a corporate investigation
sleuth-setup --modules core,corporate,sanctions,documents

# Perform a dry-run to see what would be installed
sleuth-setup --dry-run

Installation Data Flow

The following diagram illustrates how the setup utilities interact with the Python environment and the pyproject.toml configuration.

Setup Logic Flow: From CLI to Environment

graph TD
    subgraph "CLI Space"
        A["sleuth-setup --modules"] --> B["setup.py:main()"]
    end

    subgraph "Code Entity Space"
        B --> C["MODULES dictionary"]
        C --> D["get_all_packages()"]
        D --> E["install() function"]
    end

    subgraph "System Execution"
        E --> F["subprocess.run(['pip', 'install', ...])"]
        F --> G["Python Site-Packages"]
    end

    style A stroke-width:2px
    style G stroke-width:2px

Loading

Initializing the Investigation

Once the environment is set up, the investigation is managed via the sleuth-task (Task Runner). The Task Runner acts as a hard gate between investigation phases, ensuring that dependencies are met and state is preserved.

The First Task

To start an investigation, the user interacts with task_runner.py.

1. Check Status: sleuth-task status shows the current phase and task.
2. Next Task: sleuth-task next advances the investigation and triggers template_builder.py to generate the necessary Markdown files for the current step.

Automated Dependency Checks

When moving between tasks, the task_runner.py can automatically invoke setup.py if a specific task requires an uninstalled module (e.g., transitioning to a Geolocation task will trigger the geo module installation).

Intelligence Cycle Initialization

graph LR
    subgraph "Natural Language Space (Investigation)"
        Step1["Define Operational Goals"]
        Step2["STEEPLES Assessment"]
    end

    subgraph "Code Entity Space (Automation)"
        Runner["task_runner.py"]
        TBuilder["template_builder.py"]
        TIndex["template-index.json"]
        
        Runner -- "triggers" --> TBuilder
        TBuilder -- "queries" --> TIndex
        TBuilder -- "outputs" --> MD["Phase 1 Templates (.md)"]
    end

    Step1 --> Runner
    Step2 --> Runner

Loading

Continuous Integration & Verification

The repository includes a CI suite in .github/workflows/ci.yml that performs "Smoke Tests" on every push to main or pull request. These tests verify:

1. Script Executability: Ensures sleuth-task, sleuth-template, and sleuth-setup can run --help or --list commands.
2. Dependency Imports: Verifies that core libraries like pandas, httpx, and rich are correctly mapped and importable in Python 3.10, 3.11, and 3.12 environments.

To run these checks locally:

# Verify script entry points
sleuth-task --help
sleuth-template --help
sleuth-setup --list

# Verify imports
python -c "import requests; import pandas; import rich; print('OK')"

---