File size: 3,003 Bytes
e547dfd | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 | # 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.
|