# Getting started

This guide starts with routing code that does not need AWS, an API key, a model download, or a desktop build. Use Python 3.11+ and Git.

## 1. Clone and create an environment

```bash
git clone https://github.com/SNAPKITTYWEST/sovereign-engine-v2.git
cd sovereign-engine-v2
python -m venv .venv
```

Activate it using your shell:

```powershell
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
```

```bash
# Linux/macOS
source .venv/bin/activate
```

If activation is unavailable, invoke `.venv\Scripts\python.exe` on Windows or `.venv/bin/python` on POSIX instead of `python`. Check the selected environment:

```bash
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip install numpy scipy pytest hypothesis
```

These four packages support the independent research router. They are not the full engine dependencies.

## 2. Run the reference tests

```bash
cd research/sparse-routing
python -m pytest tests/ -q
cd ../..
```

The recorded run passed 57 tests. See [validation](VALIDATION.md) for scope. A missing `sparse_routing` import usually means the command was run from the wrong directory.

## 3. Collect benchmark results

From the repository root:

```bash
python scripts/benchmark_sparse_routing.py --trials 10 --output docs/benchmarks/sparse-routing-local.json
```

The command prints timing summaries and writes individual trials and environment metadata. It compares structural outputs with the original fixture and permits a `1e-12` route-cost tolerance. It does not overwrite the historical experiment file. See the [benchmark explanation](../README.md#benchmarks).

## 4. Try the engine routing API

Follow the asynchronous expert example in [Routing](ROUTING.md). Unlike the research experiment, it exercises `src.routing.RoutingPipeline`. Both are provider-free, but they solve different routing problems.

## 5. Choose an integration

- [Tools](TOOLS.md): a small registered function with schema validation.
- [Machine runtime](MACHINE_CODE.md): a stack program with a known arithmetic result.
- [Ollama](LOCAL_TRAINING_OLLAMA.md): direct model inference against a running local service.
- [IDE](IDE.md): Windows native client or Electron desktop sources.

For the larger Python engine, install the repository requirements in a separate environment if you want to avoid adding the ML stack to this small test environment:

```bash
python -m pip install -r requirements.txt
```

The root runner selects Bedrock. It is not the recommended first success path: synchronous expert callbacks and agent/continuity interface mismatches remain in the current wiring. See [deployment readiness](PRODUCTION_HARDENING.md) before trying full orchestration. Installing the package alone does not install every runtime dependency.

## When something fails

Capture the command, current directory, Python executable/version, and traceback. Use [Testing and troubleshooting](TESTING.md) to distinguish environment failures from known integration gaps.