5.7 KiB
Build System
Source: Home · ../GETTING_STARTED.md · ../CONTRIBUTING.md
This page documents the build-system surfaces of the Sovereign Research Stack
that supplement the Lean toolchain described in GETTING_STARTED.md. Content
here is the wiki-level companion to the top-level setup docs and to the
VSCode tasks and npm scripts committed under the repository root.
Python Environment Management
The repository pins a single Python version for all Python-based harnesses (swarm scripts, CAD tooling, DeepSeek review adapters, etc.) so that deterministic re-runs and AI-assisted review receipts remain reproducible.
| Surface | Value | Source |
|---|---|---|
| Python version | 3.11.15 |
.python-version |
| Installer | uv (Astral) |
VSCode task Install Python 3.11.15, npm script install-python |
| Interpreter path | Platform-local uv path printed by uv python find 3.11.15 |
User-level VSCode setting or selected interpreter |
The repository intentionally does not commit python.defaultInterpreterPath.
That VSCode setting is absolute-path based and is therefore not portable across
Linux, macOS, Windows, or users with a non-default XDG_DATA_HOME. If you want
VSCode to pin an interpreter, set it in your user-level settings after running
uv python find 3.11.15. The per-OS uv install roots are typically:
| Platform | uv-managed CPython 3.11.15 path (example) |
|---|---|
| Linux | /home/<user>/.local/share/uv/python/cpython-3.11-linux-x86_64-gnu/bin/python3.11 |
| macOS | /Users/<user>/.local/share/uv/python/cpython-3.11-macos-aarch64-none/bin/python3.11 |
| Windows | C:\\Users\\<user>\\AppData\\Roaming\\uv\\python\\cpython-3.11-windows-x86_64-none\\python.exe |
Run uv python find 3.11.15 after installing the interpreter to print the
exact path for your platform.
Why a pinned .python-version
build123dandOCP(the CAD stack used by5-Applications/text-to-cad/) publish wheels for CPython 3.11 only.- DeepSeek review receipts (see DeepSeek-Review-Process) record SHA-256 hashes of prompts and answers; differing Python runtimes can change tokenizer output and break receipt reproducibility for downstream review continuation.
- The Lean toolchain is independent of Python, but every Python harness must agree on a single interpreter so that artifacts produced by one stage (e.g. equation-forest extraction) can be re-validated by another stage (e.g. metaprobe replay) without environment drift.
UV integration
uv is used as the installer for the pinned interpreter. The repository does
not bundle a pyproject.toml at the root — uv is invoked only to install
the interpreter itself, and per-application virtual environments are created
from that interpreter.
# Install the pinned interpreter (idempotent)
uv python install 3.11.15
# Equivalent npm shortcut from the repo root
npm run install-python
VSCode integration
.vscode/settings.json avoids committing a workspace-level
python.defaultInterpreterPath. Open the repository in VSCode after the
interpreter is installed, then select the interpreter reported by
uv python find 3.11.15 if the Python extension does not discover it
automatically. The portable source of truth is .python-version plus the
root install task/script, not an absolute path from one machine.
Installation flow
# 1. Install uv itself (one-time, see https://docs.astral.sh/uv/)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Install the pinned interpreter
uv python install 3.11.15 # or: npm run install-python
# 3. (CAD only) Create the text-to-cad venv
npm run setup-cad-env # see [[Text-to-CAD-Environment]]
# 4. (CAD only) Verify the CAD venv resolves build123d and OCP
npm run verify-cad
NPM Script Surface (repo root package.json)
The repository root package.json exposes a small set of orchestration scripts
that wrap the VSCode tasks so that they are available outside the editor (CI,
remote shells, headless installs).
| Script | Wraps | Purpose |
|---|---|---|
npm run install-python |
uv python install 3.11.15 |
Install the pinned interpreter via uv |
npm run setup-cad-env |
python3.11 -m venv + pip install -r requirements-cad.txt in 5-Applications/text-to-cad/ |
Create the text-to-cad virtual environment |
npm run verify-cad |
import build123d; import OCP in the text-to-cad venv |
Validate that the CAD dependencies are importable |
See Text-to-CAD-Environment for the CAD-specific workflow these scripts support.
VSCode Tasks (.vscode/tasks.json)
The same three operations are exposed as VSCode tasks so they can be invoked
from the command palette (Tasks: Run Task) without leaving the editor.
| Task label | Equivalent npm script | Notes |
|---|---|---|
Install Python 3.11.15 |
npm run install-python |
Runs uv python install 3.11.15 from the workspace root |
Setup CAD Environment |
npm run setup-cad-env |
Creates 5-Applications/text-to-cad/.venv and installs requirements-cad.txt |
Verify CAD Dependencies |
npm run verify-cad |
Runs ./.venv/bin/python -c "import build123d; import OCP; print('CAD dependencies OK')" from the text-to-cad directory |
Tasks present output in a shared panel so the install logs are persisted across re-runs.
Related
- Text-to-CAD-Environment — CAD-specific environment, requirements, and
the agent contract that consumes
5-Applications/text-to-cad/.venv. - DeepSeek-Review-Process — receipt schema and review workflow that depends on the pinned Python interpreter for prompt-hash reproducibility.
GETTING_STARTED.md— Lean toolchain installation and end-to-end build walkthrough for the Lean core.