chore(delphi): standardize venv as .venv and add Pyright config (#2560)

Editor language servers (Pyright, Pylance, VS Code, Cursor, Claude Code LSP)
auto-discover `.venv` but not the previous `delphi-env`, so opening the
project produced a flood of "missing import" errors for both third-party and
first-party modules. Switch to the conventional `.venv` name and add
`[tool.pyright]` to `delphi/pyproject.toml` so source roots, the venv
location, and the Python version are explicit.

The Pyright config lives inside `delphi/`, but editors look at the workspace
root. To bridge that, `make venv` now also creates `polis/.venv → delphi/.venv`
when the root symlink is absent, so opening Claude Code / VS Code / Cursor at
the repo root finds the interpreter too. The invariant is documented in
`delphi/CLAUDE.md`.

Migration if you have an existing `delphi-env/` you want to keep:

    ln -sfn delphi-env delphi/.venv

`TESTING_LOG.md` left as-is (historical log of past actions, not setup docs).

Author: jucor

README.md

@@ -269,6 +269,8 @@ You can specify these `-f docker-compose.yml -f docker-compose.dev.yml` argument
 You can create your own `docker-compose.x.yml` file as an overlay and add or modify any values you need to differ
 from the defaults found in the `docker-compose.yml` file and pass it as the second argument to the `docker compose -f` command above.
 
+To work on the **delphi** Python ML service outside Docker (run tests locally, get a working language server in your editor, etc.), see [`delphi/README.md`](/delphi/README.md#local-python-development).
+
 ### Testing
 
 We use Cypress for automated, end-to-end browser testing for PRs on GitHub (see badge above).

delphi/.gitignore

@@ -117,6 +117,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+# Legacy venv names (no longer canonical, but may linger in existing checkouts)
 delphi-env/
 delphi-dev-env/
 

delphi/CLAUDE.md

@@ -18,6 +18,20 @@ this avoids the confusion of having anything called a "cid", the joke was "conve
 
 this was built in two parts, the pca/kmenas/repness and the umap/narrative, and these are combined in the run_delphi.sh script.
 
+## Local Python Environment
+
+Canonical venv: `delphi/.venv` (Python 3.12). Setup is documented for humans in
+[`README.md`](README.md#local-python-development) and
+[`docs/QUICK_START.md`](docs/QUICK_START.md#environment-setup) — see those for
+the `make venv` / `uv sync` workflows.
+
+Invariant to be aware of when navigating this repo: **both `delphi/.venv` and
+`polis/.venv` should point at the same environment** (one real, the other a
+symlink). The Pyright config (`[tool.pyright]` in `delphi/pyproject.toml`)
+resolves `venv = ".venv"` to `delphi/.venv`; editors opening at the repo root
+look for `polis/.venv`. If you see unresolved imports while working in this
+codebase, check that both paths exist and resolve to the same env.
+
 ## Database Interactions
 
 ### Querying Local PostgreSQL Database

delphi/Makefile

@@ -20,15 +20,31 @@ setup-dev: install-dev ## Set up development environment
 	@echo "2. Set up your database connection"
 	@echo "3. Create DynamoDB tables: make setup-dynamodb"
 
-venv: ## Create canonical virtual environment (delphi-env)
-	@echo "Creating canonical virtual environment: delphi-env"
-	@if [ ! -d "delphi-env" ]; then \
-		python3 -m venv delphi-env; \
+venv: ## Create canonical virtual environment (.venv)
+	@echo "Creating canonical virtual environment: .venv"
+	@# Clean up a broken symlink first so `python3 -m venv` doesn't fail on
+	@# "File exists" when .venv points at a now-missing target.
+	@if [ -L ".venv" ] && [ ! -e ".venv" ]; then \
+		echo "Removing broken .venv symlink"; \
+		rm .venv; \
+	fi
+	@if [ ! -d ".venv" ]; then \
+		python3 -m venv .venv; \
 		echo "✓ Virtual environment created"; \
 	else \
 		echo "✓ Virtual environment already exists"; \
 	fi
-	@echo "To activate: source delphi-env/bin/activate"
+	@# Mirror the venv at the repo root so editors opening the workspace at
+	@# the parent directory (polis/) auto-discover the interpreter too.
+	@if [ -L "../.venv" ] && [ ! -e "../.venv" ]; then \
+		echo "Removing broken ../.venv symlink"; \
+		rm ../.venv; \
+	fi
+	@if [ ! -e "../.venv" ]; then \
+		ln -sfn delphi/.venv ../.venv; \
+		echo "✓ Linked ../.venv → delphi/.venv (for editor auto-discovery at repo root)"; \
+	fi
+	@echo "To activate: source .venv/bin/activate"
 	@echo "Then run: make install-dev"
 
 venv-check: ## Check virtual environment status
@@ -43,7 +59,7 @@ venv-check: ## Check virtual environment status
 		fi; \
 	else \
 		echo "❌ No virtual environment active"; \
-		echo "Run: source delphi-env/bin/activate"; \
+		echo "Run: source .venv/bin/activate"; \
 	fi
 
 setup-dynamodb: ## Create local DynamoDB tables

delphi/README.md

@@ -1,5 +1,36 @@
 # Pol.is Math (Python Implementation)
 
+## Local Python development
+
+Run locally (outside Docker) with either `make` or `uv`:
+
+```bash
+# Option A: make + pip
+cd delphi
+make venv                # Creates delphi/.venv + a polis/.venv symlink for editor discovery
+source .venv/bin/activate
+make install-dev         # Installs delphi with dev + notebook extras
+
+# Option B: uv (faster, locked deps)
+cd delphi
+uv sync                  # Creates delphi/.venv with all dependencies
+ln -sfn delphi/.venv ../.venv   # One-time, for editor discovery at the repo root
+```
+
+**Why two `.venv` paths?** Pyright (configured in `delphi/pyproject.toml`)
+looks for the venv at `delphi/.venv`, but editors and IDEs (VS Code, Cursor,
+Claude Code, JetBrains) opening the workspace at the repo root look for
+`polis/.venv`. Both must exist — either as the real venv directory or as a
+symlink to it. `make venv` creates both; the `uv` path needs the one-time
+symlink. If your editor's language server reports "missing imports" for
+`numpy`, `polismath`, etc., this is the usual cause.
+
+If you have a leftover `delphi-env/` from before the rename, adopt it without
+reinstalling: `ln -sfn delphi-env delphi/.venv`.
+
+For a full walkthrough (tests, real data, system tests), see
+[`docs/QUICK_START.md`](docs/QUICK_START.md).
+
 ## Quickstart example
 
 ```bash

delphi/delphi

@@ -6,9 +6,16 @@ SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
 # Path to the Python CLI script and virtual environment
 CLI_SCRIPT="$SCRIPT_DIR/scripts/delphi_cli.py"
-VENV_DIR="$SCRIPT_DIR/delphi-env"
+VENV_DIR="$SCRIPT_DIR/.venv"
 
-# Check if the virtual environment exists
+# Clean up a broken symlink (the target was deleted or moved) so the venv
+# creation below doesn't fail with "File exists".
+if [ -L "$VENV_DIR" ] && [ ! -e "$VENV_DIR" ]; then
+    echo "Removing broken venv symlink: $VENV_DIR"
+    rm "$VENV_DIR"
+fi
+
+# Check if the virtual environment exists (real dir or working symlink to one)
 if [ ! -d "$VENV_DIR" ]; then
     echo "Setting up Delphi CLI environment..."
     python3 -m venv "$VENV_DIR"

delphi/docs/QUICK_START.md

@@ -4,40 +4,44 @@ This guide provides the essential steps to get started with the Python implement
 
 ## Environment Setup
 
-The Python implementation requires Python 3.8+ (ideally Python 3.12) and several dependencies.
+The Python implementation requires **Python 3.12** (pinned in `pyproject.toml`).
 
-### Creating a New Virtual Environment
+### Creating a Virtual Environment
 
-It's recommended to create a fresh virtual environment:
+The recommended way is `make venv`, which also sets up the editor-discovery
+symlink at the repo root in one step:
 
 ```bash
-# Navigate to the delphi directory
 cd delphi
-
-# Create a new virtual environment
-python3 -m venv delphi-env
-
-# Activate the virtual environment
-source delphi-env/bin/activate  # On Linux/macOS
-# or
-delphi-env\Scripts\activate     # On Windows
+make venv                # Creates delphi/.venv and (if missing) polis/.venv → delphi/.venv
+source .venv/bin/activate
+make install-dev         # Installs delphi with dev + notebook extras
 ```
 
-Your command prompt should now show `(delphi-env)` indicating the environment is active.
+Alternatively, with [uv](https://github.com/astral-sh/uv) (faster, locked
+dependencies via `requirements.lock`):
 
-### Installing Dependencies
+```bash
+cd delphi
+uv sync                          # Creates delphi/.venv with all dependencies
+ln -sfn delphi/.venv ../.venv    # One-time, for editor discovery at the repo root
+```
 
-With your virtual environment activated, install the package and its dependencies:
+Plain `python3 -m venv .venv` + `pip install -e ".[dev,notebook]"` also works
+if you prefer not to use `make` or `uv`; just remember to create the
+`../.venv → delphi/.venv` symlink manually so editors find the interpreter.
 
-```bash
-# Install the polismath package in development mode
-pip install -e .
+On Windows, replace `source .venv/bin/activate` with `.venv\Scripts\activate`.
 
-# Install additional packages for visualization and notebooks
-pip install matplotlib seaborn jupyter
-```
+### Why two `.venv` paths?
 
-This will install the package in development mode with all required dependencies.
+Pyright's configuration (`[tool.pyright]` in `delphi/pyproject.toml`) makes
+`delphi/` the project root, so it looks for the venv at `delphi/.venv`.
+Editors and IDEs (VS Code, Cursor, Claude Code, JetBrains) opening the
+workspace at the repo root look for `polis/.venv`. **Both must exist** —
+either as the real venv directory or as a symlink to it. If your language
+server reports unresolved imports for `numpy`, `polismath`, or similar, this
+is almost always the cause.
 
 ## Running Tests
 

delphi/docs/RUNNING_THE_SYSTEM.md

@@ -27,13 +27,13 @@ This document provides a comprehensive guide on how to set up, run, and test the
 cd delphi
 
 # Create a virtual environment
-python -m venv delphi-env
+python -m venv .venv
 
 # Activate the virtual environment
 # On Linux/macOS
-source delphi-env/bin/activate
+source .venv/bin/activate
 # On Windows
-delphi-env\Scripts\activate
+.venv\Scripts\activate
 ```
 
 ## Package Installation

delphi/notebooks/README.md

@@ -28,7 +28,7 @@ To run these notebooks:
 
    ```bash
    cd delphi
-   source delphi-env/bin/activate
+   source .venv/bin/activate
    jupyter lab
    ```
 

delphi/notebooks/launch_notebook.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # Activate the virtual environment
-source ../delphi-env/bin/activate
+source ../.venv/bin/activate
 
 # Launch Jupyter Lab
 jupyter lab