diff --git a/.vscode/settings.json b/.vscode/settings.json index 68b3ccd1..bf17cb7e 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,6 +1,5 @@ { - "cmake.sourceDirectory": "/home/allaun/Documents/Research Stack/2-Search-Space/simulations/heat-2D", - "python.defaultInterpreterPath": "/home/allaun/.local/share/uv/python/cpython-3.11-linux-x86_64-gnu/bin/python3.11", + "cmake.sourceDirectory": "${workspaceFolder}/2-Search-Space/simulations/heat-2D", "files.watcherExclude": { "**/.git/objects/**": true, "**/.git/subtree-cache/**": true, diff --git a/6-Documentation/wiki/Build-System.md b/6-Documentation/wiki/Build-System.md new file mode 100644 index 00000000..d5f3f072 --- /dev/null +++ b/6-Documentation/wiki/Build-System.md @@ -0,0 +1,133 @@ +# Build System + +> **Source:** [[Home|Wiki Home]] · [[../GETTING_STARTED.md|Getting Started]] · [[../CONTRIBUTING.md|Contributing]] + +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//.local/share/uv/python/cpython-3.11-linux-x86_64-gnu/bin/python3.11` | +| macOS | `/Users//.local/share/uv/python/cpython-3.11-macos-aarch64-none/bin/python3.11` | +| Windows | `C:\\Users\\\\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` + +- `build123d` and `OCP` (the CAD stack used by `5-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. + +```bash +# 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 + +```bash +# 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. diff --git a/6-Documentation/wiki/DeepSeek-Review-Process.md b/6-Documentation/wiki/DeepSeek-Review-Process.md new file mode 100644 index 00000000..441a9170 --- /dev/null +++ b/6-Documentation/wiki/DeepSeek-Review-Process.md @@ -0,0 +1,189 @@ +# DeepSeek Review Process + +> **Source:** [[Home|Wiki Home]] · `5-Applications/tools-scripts/llm/deepseek_review_adapter.py` · `shared-data/artifacts/deepseek_review/` + +The Research Stack incorporates DeepSeek AI models for formal mathematical +review and validation of canonical specifications, Lean kernels, and +statistical-interpretation receipts. This page documents the wiki-level view +of the review pipeline, the receipt schema, and the canonical example +(prime-gap entropy collapse) shipped under +`shared-data/artifacts/deepseek_review/`. + +--- + +## AI-Assisted Mathematical Review + +DeepSeek review receipts provide reproducibility and integrity tracking for +AI-assisted mathematical validation. Each review run emits a paired +`.md` answer file and a `.receipt.json` sidecar that records the exact model, +endpoint, token usage, and SHA-256 hashes needed to re-validate the review +without re-running the model. + +### Review Artifacts + +| Path | Purpose | +|---|---| +| `shared-data/artifacts/deepseek_review/` | Root for all review answers and receipt sidecars | +| `*_deepseek-v3.2_*.md` | Primary review answer (markdown, model-authored) | +| `*_deepseek-v3.2_*.receipt.json` | Receipt for the primary review (schema `ollama_deepseek_review_receipt_v1`) | +| `*_deepseek-v4-flash_continuation_*.md` | Continuation answer when the primary review was truncated | +| `*_deepseek-v4-flash_continuation_*.receipt.json` | Receipt for the continuation (schema `ollama_deepseek_review_continuation_receipt_v1`) | + +Receipt filenames are aligned with their answer files by sharing the same +`__` stem. + +### Receipt Schema + +Both receipt schemas are versioned JSON records that track every field needed +to re-derive the review independently of the model server. + +| Field | Type | Notes | +|---|---|---| +| `schema` | string | `ollama_deepseek_review_receipt_v1` (primary) or `ollama_deepseek_review_continuation_receipt_v1` (continuation) | +| `created_at` | ISO-8601 timestamp | UTC time at which the review was produced | +| `model` | string | Model identifier (e.g. `deepseek-v3.2`, `deepseek-v4-flash`) | +| `endpoint` | URL | API endpoint that served the review (e.g. `https://ollama.com/v1/chat/completions`) | +| `prompt_sha256` | `sha256:` | SHA-256 of the exact serialized prompt body sent to the endpoint | +| `answer_sha256` | `sha256:` | SHA-256 of the answer payload written to `answer_path` | +| `usage.prompt_tokens` | int | Tokens consumed by the prompt as reported by the endpoint | +| `usage.completion_tokens` | int | Tokens produced by the model | +| `usage.total_tokens` | int | Sum of the two above (recorded for cross-checks) | +| `context_files` | string[] | Repo-relative paths to every file that participated in the review prompt context (primary receipt only; continuation consumers reconstruct this through `previous_answer_path` and the primary receipt) | +| `answer_path` | string | Repo-relative path to the answer markdown | +| `previous_answer_path` | string | Repo-relative path to the answer being continued (continuation receipt only) | +| `message_keys` | string[] | Field names returned alongside `content` by the continuation endpoint (e.g. `role`, `content`, `reasoning`) (continuation receipt only) | + +Receipts are committed alongside the answers so that any future agent can: + +1. Verify integrity by recomputing the SHA-256 of `answer_path` and comparing + to `answer_sha256`. +2. Reconstruct the prompt by joining the listed `context_files` against the + commit at which the receipt was authored. +3. Audit token usage and cost without re-querying the endpoint. + +### Reconstructing context for continuations + +Continuation receipts intentionally omit `context_files` — a continuation +inherits the prompt context of the primary review it extends. Consumers should +not treat the missing field as lost context; they reconstruct it through the +previous answer and primary receipt. To reconstruct the full context for a +continuation answer: + +1. Read `previous_answer_path` from the continuation receipt. +2. Locate the sibling primary receipt by replacing the `.md` suffix on + `previous_answer_path` with `.receipt.json` (the primary receipt and its + answer share a stem). +3. Read `context_files` from that primary receipt and treat it as the + continuation's effective context bundle. +4. The continuation prompt body itself is the primary answer at + `previous_answer_path` plus any continuation directive recorded in the + continuation answer's preamble; `prompt_sha256` on the continuation + receipt covers that combined body. + +### Review Process + +Reviews are executed as a two-stage pipeline: + +1. **Primary analysis** with `deepseek-v3.2` against a curated prompt that + bundles the canonical spec, statistical receipts, and Lean kernels for the + topic under review. +2. **Continuation** with `deepseek-v4-flash` when the primary review is + truncated by the per-completion token cap. The continuation receipt + references the primary answer via `previous_answer_path` and inherits the + review topic via filename stem. + +Every review answer is structured to include: + +- A **YES/NO verdict table** answering the specific review questions posed + in the prompt. +- An **arithmetic recheck** that recomputes every numeric claim in the + reviewed material against the canonical specification. +- A **statistical interpretation** section that classifies thresholds as + `CANONICAL`, `HEURISTIC`, or `DETERMINISTIC WINDOW FEATURE`, and flags + null-model mismatches. +- A **failure mode analysis** that enumerates the conditions under which the + reviewed method would emit false positives or false negatives. +- A **canonical spec patches** block of explicit warnings to copy verbatim + into the reviewed specification. + +### Example Review: Prime Gap Entropy Collapse + +The canonical example shipped with the initial DeepSeek review tracking is +the prime-gap entropy-collapse analysis: + +| Artifact | Path | +|---|---| +| Primary answer | `shared-data/artifacts/deepseek_review/prime_gap_entropy_collapse_deepseek_deepseek-v3.2_20260512T033551Z.md` | +| Primary receipt | `shared-data/artifacts/deepseek_review/prime_gap_entropy_collapse_deepseek_deepseek-v3.2_20260512T033551Z.receipt.json` | +| Continuation answer | `shared-data/artifacts/deepseek_review/prime_gap_entropy_collapse_deepseek_deepseek-v4-flash_continuation_20260512T033849Z.md` | +| Continuation receipt | `shared-data/artifacts/deepseek_review/prime_gap_entropy_collapse_deepseek_deepseek-v4-flash_continuation_20260512T033849Z.receipt.json` | + +Context files cited by the primary receipt: + +- `6-Documentation/docs/distilled/ArithmeticSpec_Corrected_2026-05-11.md` +- `shared-data/data/stack_solidification/prime_gap_k21_rerun_receipt_2026-05-11.md` +- `0-Core-Formalism/lean/Semantics/Semantics/HCMMR/Kernels/EntropyCollapseDetector.lean` + +The review covers: + +- **Arithmetic verification** of the canonical spec (crossing counts, `D₂`, + `σ_q`, Kendall SD, and exact tail probabilities at `W=8`). +- **Statistical interpretation** of threshold selection — confirming `K=7` + as non-selective (94.57% FPR under random-permutation null) and `K=21` as a + heuristic ~5% FPR calibration (strict `>21`: 3.05%, inclusive `>=21`: 5.43%). +- **Failure mode analysis** for the random-permutation null model when + applied to prime gaps (ties, non-uniform marginal distribution, local + dependence make the FPR estimates unreliable). +- **Canonical spec patches** that add HEURISTIC warnings, clarify that + window-level `σ_q` and `D₂` are deterministic features rather than + estimators, document the null-model mismatch for prime gaps, and address + multiple-testing and edge-effect considerations. +- **Continuation** (deepseek-v4-flash) extending the canonical spec patches + with predictive-versus-contemporaneous fusion semantics, ground-truth + caveats, parameter-sensitivity reporting requirements, edge-effect handling, + reproducibility requirements, and an interpretation caveat for the final + verdict surface. + +--- + +## Adding a New Review + +When emitting new review artifacts: + +1. Write the answer to + `shared-data/artifacts/deepseek_review/_deepseek__.md`. + The literal `_deepseek_` segment is the **provider tag** and is held + constant across all DeepSeek-family reviews; `` is the specific + model identifier (e.g. `deepseek-v3.2`, `deepseek-v4-flash`). The two + segments are kept separate so future provider-level tooling (rate caps, + budget accounting, fleet-wide audits) can filter on the provider tag + without parsing the `` slug. This is why the canonical example + filenames contain `_deepseek_deepseek-v3.2_` — the doubled `deepseek` is + intentional and reflects `_`. +2. Write the matching receipt alongside it with the same stem and + `.receipt.json` suffix, using `ollama_deepseek_review_receipt_v1` for the + primary review and `ollama_deepseek_review_continuation_receipt_v1` for any + continuation. +3. Populate `context_files` with repo-relative paths to every file consumed + by the prompt so future agents can reproduce the prompt body. Continuation + receipts omit `context_files` and `message_keys` records the alternate + shape of the continuation response; consumers reconstruct continuation + context via the primary receipt indexed by `previous_answer_path` (see + [[#Reconstructing context for continuations]] above). +4. Record `prompt_sha256` and `answer_sha256` for integrity verification. +5. Commit the answer and receipt together — the receipt is meaningless + without the answer it indexes, and the answer is unverifiable without the + receipt. + +--- + +## Related + +- [[Build-System]] — pinned Python interpreter that drives the review adapter + and ensures prompt-hash reproducibility across runs. +- `5-Applications/tools-scripts/llm/deepseek_review_adapter.py` — adapter that + emits the receipt + answer pair. +- `6-Documentation/docs/distilled/` — canonical specs that reviews validate + against (e.g. `ArithmeticSpec_Corrected_2026-05-11.md`). +- `0-Core-Formalism/lean/Semantics/Semantics/HCMMR/Kernels/` — Lean kernels + cross-referenced as review context. diff --git a/6-Documentation/wiki/Home.md b/6-Documentation/wiki/Home.md index 8b874dea..a1c753c1 100644 --- a/6-Documentation/wiki/Home.md +++ b/6-Documentation/wiki/Home.md @@ -9,6 +9,9 @@ | `docs/GLOSSARY.md` | Project-wide glossary — all terms across all domains | | `wiki/Concept-Archive.md` | Concept archive — canonical, speculative, held, lossy, retired, and abandoned terms | | `docs/BEGINNERS_MAP.md` | Narrative onboarding — what this stack is and why it exists | +| `wiki/Build-System.md` | Build system — pinned Python (`3.11.15`), uv integration, VSCode tasks, npm scripts | +| `wiki/Text-to-CAD-Environment.md` | Text-to-CAD environment — CAD-specific venv sequencing, `build123d` / `OCP` verification, agent contract | +| `wiki/DeepSeek-Review-Process.md` | AI-assisted mathematical review — receipt schema, two-stage pipeline, prime-gap example | | `docs/VISION_NORTH_STAR.md` | Long-term vision — where the stack converges | | `docs/PHI_CENTER_REVAMP.md` | Phi-centered cockpit architecture — cost/efficiency comparison root | | `docs/BRAIN_AS_MANIFOLD.md` | Biological manifold theory — hyperbolic geometry, intelligence ladder, Physarum | @@ -63,3 +66,19 @@ | `CITATION.cff` | Terminology neutrality map — technical terms vs cultural aliases | | `PROJECT_MAP.md` | Repository-wide directory structure and module map | | `MATH_MODEL_MAP.tsv` | Full equation registry indexed by phinary ID | + +## Build System & Environments + +| Document | Summary | +|---|---| +| `wiki/Build-System.md` | Python `3.11.15` pin via `.python-version`, uv install path, VSCode interpreter, npm script surface | +| `wiki/Text-to-CAD-Environment.md` | CAD-specific sequencing that consumes the canonical setup commands in `wiki/Build-System.md` | +| `GETTING_STARTED.md` | Lean toolchain installation and end-to-end Lean build walkthrough | + +## AI-Assisted Review + +| Document | Summary | +|---|---| +| `wiki/DeepSeek-Review-Process.md` | Receipt schema (`ollama_deepseek_review_receipt_v1`), two-stage pipeline (`deepseek-v3.2` + `deepseek-v4-flash` continuation), prime-gap entropy-collapse example | +| `shared-data/artifacts/deepseek_review/` | Paired answer + receipt artifacts for each review run | +| `5-Applications/tools-scripts/llm/deepseek_review_adapter.py` | Adapter that emits the answer / receipt pair | diff --git a/6-Documentation/wiki/Text-to-CAD-Environment.md b/6-Documentation/wiki/Text-to-CAD-Environment.md new file mode 100644 index 00000000..38818500 --- /dev/null +++ b/6-Documentation/wiki/Text-to-CAD-Environment.md @@ -0,0 +1,60 @@ +# Text-to-CAD Environment + +> **Source:** [[Home|Wiki Home]] · [[Build-System]] · `5-Applications/text-to-cad/README.md` · `5-Applications/text-to-cad/AGENTS.md` + +The Text-to-CAD harness (`5-Applications/text-to-cad/`) drives agentic 3D +modeling by exposing `build123d` and `OCP` (OpenCascade) bindings to coding +agents like Codex and Claude Code. The canonical VSCode task and npm script +matrix lives in [[Build-System]]. This page stays focused on the CAD-specific +environment shape, sequencing, and agent constraints. + +For the agent contract (file-targeted skills, viewer handoff rules, prompt-ref +grammar), see `5-Applications/text-to-cad/AGENTS.md`. + +--- + +## CAD Environment Setup + +The Text-to-CAD harness uses a repo-local virtual environment at +`5-Applications/text-to-cad/.venv` that is created from the pinned Python +interpreter described in [[Build-System#Python Environment Management]]. + +### Bootstrap order + +```bash +# 1. From the repository root +npm run install-python # uv python install 3.11.15 +npm run setup-cad-env # creates 5-Applications/text-to-cad/.venv +npm run verify-cad # prints "CAD dependencies OK" on success +``` + +The `Setup CAD Environment` task is idempotent — re-running it against an +existing `.venv` will reuse it and only update pinned packages. To force a +clean rebuild, remove `5-Applications/text-to-cad/.venv` first. + +For the exact VSCode task labels, npm script definitions, and command bodies, +use [[Build-System]]. Do not duplicate that matrix here; when a task or script +changes, update [[Build-System]] and keep this page limited to the CAD workflow +that consumes those commands. + +### Agent contract + +The harness's `AGENTS.md` requires all CAD tooling to be invoked through +`./.venv/bin/python` from `5-Applications/text-to-cad/`. The `Verify CAD +Dependencies` task is the canonical preflight check before running any of the +skill scripts (`gen_step_part`, `gen_step_assembly`, `gen_urdf`, `cadref`, +`snapshot`). If the verification fails, agents are expected to re-run the +`Setup CAD Environment` task before attempting CAD generation. + +--- + +## Related + +- [[Build-System]] — Python version pinning, uv integration, VSCode interpreter + configuration that this environment builds on. +- `5-Applications/text-to-cad/README.md` — user-facing quick start, feature + list, and bundled skill catalog. +- `5-Applications/text-to-cad/AGENTS.md` — agent contract, viewer handoff + rules, and common harness commands. +- `5-Applications/text-to-cad/requirements-cad.txt` — pinned CAD dependency + set installed into `.venv`.