release: v0.0.5 — consolidation of 59 PRs + changelog + evidence review

.env.example

@@ -12,15 +12,41 @@
 
 
 # ============================================================
-# Sandbox compute (Modal) — REQUIRED for any agent that runs code
+# Sandbox compute — REQUIRED for any agent that runs code
 # ============================================================
-# Modal powers `execute_code` (the data-science sandbox). Without
-# these the agent can still chat but can't run notebooks/scripts.
-# Get them from https://modal.com/settings/tokens — click
+# The compute provider powers `execute_code` (the data-science
+# sandbox), notebook kernels and model-serving deployments. Without
+# credentials the agent can still chat but can't run notebooks or
+# scripts. Pick ONE provider:
+#   modal   (default) — needs MODAL_TOKEN_*
+#   runpod            — needs the RUNPOD_* block below
+COMPUTE_PROVIDER=modal
+
+# ---- Modal (COMPUTE_PROVIDER=modal) ------------------------
+# Get tokens from https://modal.com/settings/tokens — click
 # "New Token" and copy both halves.
 MODAL_TOKEN_ID=ak-xxxxxxxxxxxxxxxxxxxxxx
 MODAL_TOKEN_SECRET=as-xxxxxxxxxxxxxxxxxxxxxx
 
+# ---- RunPod (COMPUTE_PROVIDER=runpod) ----------------------
+# Two key pairs from https://console.runpod.io:
+#   API key    — Settings → API Keys
+#   S3 API key — Settings → S3 API Keys (network-volume access)
+# The datacenter hosts the network volume AND all workers; it must
+# support the S3 API (e.g. US-KS-2, EU-RO-1, EU-CZ-1, EUR-IS-1).
+# See docs/compute-providers.md for the full setup walkthrough
+# (including publishing the worker image).
+# RUNPOD_API_KEY=rpa_xxxxxxxxxxxxxxxxxxxxxx
+# RUNPOD_S3_ACCESS_KEY_ID=user_xxxxxxxxxxxx
+# RUNPOD_S3_SECRET_ACCESS_KEY=rps_xxxxxxxxxxxxxxxxxxxxxx
+# RUNPOD_DATACENTER_ID=US-KS-2
+# Auto-created on first use when unset; pin after the first run.
+# RUNPOD_NETWORK_VOLUME_ID=
+# RUNPOD_NETWORK_VOLUME_SIZE_GB=100
+# Override to your own registry copy of docker/runpod-worker.
+# RUNPOD_WORKER_IMAGE=ghcr.io/lucastononro/trainable-runpod-worker:latest
+# RUNPOD_MAX_WORKERS=3
+
 
 # ============================================================
 # LLM provider auth — pick at least one
@@ -80,6 +106,35 @@ CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxxxxxxxxx
 # BACKEND_PORT=8001
 
 
+# ============================================================
+# Optional — security
+# ============================================================
+# Opt-in bearer-token auth for the API. Unset (default) = every
+# endpoint stays open, exactly as before — fine for localhost dev.
+# When set, all /api/* requests must send
+#   Authorization: Bearer <token>
+# Exempt: /api/health, /api/readyz, and CORS preflight. The SSE
+# stream endpoint (/api/sessions/<id>/stream) also accepts
+# ?token=<token>, since the browser EventSource API cannot send
+# an Authorization header. Set this whenever the backend is
+# exposed beyond localhost (e.g. docker-compose.prod.yml).
+#
+# NOTE: ?token= is part of the URL, so uvicorn/nginx/proxy access
+# logs record it verbatim. If the stream endpoint is used behind
+# such a component, redact the token query parameter from access
+# logs (custom uvicorn access-log format, nginx log masking) or
+# restrict log access.
+# API_AUTH_TOKEN=change-me-to-a-long-random-string
+
+# Allowed browser origins for CORS, comma-separated. Defaults to
+# the local frontend (http://localhost:3000, http://127.0.0.1:3000).
+# The frontend normally proxies /api through Next.js (same-origin),
+# so you only need this when a browser calls the backend origin
+# directly. A `*` entry is honored but credentials are then
+# disabled — never both.
+# CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+
+
 # ============================================================
 # Optional — observability
 # ============================================================
@@ -94,11 +149,36 @@ CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxxxxxxxxx
 # SENTRY_ENVIRONMENT=local
 
 
+# ============================================================
+# Datastore secrets — REQUIRED by docker-compose.prod.yml
+# ============================================================
+# Prod has NO built-in defaults: docker-compose.prod.yml fails fast
+# (`config`/`up` errors out) if any of these are unset. The backend's
+# DATABASE_URL and AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY are derived
+# from these values, so the app credentials always match the datastores.
+# Replace the placeholders below with strong, unique secrets.
+#
+# Postgres superuser/database (postgres service + backend DATABASE_URL):
+POSTGRES_USER=trainable
+POSTGRES_PASSWORD=change-me-strong-db-password
+POSTGRES_DB=trainable
+#
+# MinIO root credentials (minio service + backend AWS_ACCESS_KEY_ID/SECRET):
+MINIO_ROOT_USER=change-me-minio-user
+MINIO_ROOT_PASSWORD=change-me-strong-minio-password
+#
+# Container image tags for the prebuilt prod images (default: latest):
+# TRAINABLE_BACKEND_TAG=latest
+# TRAINABLE_FRONTEND_TAG=latest
+
+
 # ============================================================
 # Advanced — overridden by docker-compose.prod.yml
 # ============================================================
-# Don't set these unless you're running outside docker-compose.
-# DATABASE_URL=postgresql+asyncpg://trainable:trainable@postgres:5432/trainable
+# docker-compose.prod.yml sets these for the backend container from the
+# datastore secrets above; only set them by hand when running the
+# backend OUTSIDE docker-compose (docker-compose.yml uses fixed dev creds).
+# DATABASE_URL=postgresql+asyncpg://<POSTGRES_USER>:<POSTGRES_PASSWORD>@postgres:5432/<POSTGRES_DB>
 # S3_ENDPOINT=http://minio:9000
-# AWS_ACCESS_KEY_ID=minioadmin
-# AWS_SECRET_ACCESS_KEY=minioadmin
+# AWS_ACCESS_KEY_ID=<same as MINIO_ROOT_USER>
+# AWS_SECRET_ACCESS_KEY=<same as MINIO_ROOT_PASSWORD>

.github/workflows/ci.yml

@@ -23,7 +23,8 @@ jobs:
         with:
           python-version: "3.11"
           cache: pip
-      - run: pip install ruff
+      # Keep in sync with the ruff-pre-commit rev in .pre-commit-config.yaml.
+      - run: pip install "ruff==0.15.22"
       - run: ruff check .
       - run: ruff format --check .
 
@@ -33,13 +34,59 @@ jobs:
     defaults:
       run:
         working-directory: backend
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: trainable_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      TEST_DATABASE_URL: postgresql+asyncpg://postgres:postgres@localhost:5432/trainable_test
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
           cache: pip
-      - run: pip install -r requirements.txt
+      # Install from the hashed lockfile so CI resolves exactly what ships
+      # in the Docker image (#128). requirements.txt stays the edited input.
+      - run: pip install --require-hashes -r requirements.lock
+      # Coverage is scoped to production code: backend/.coveragerc omits
+      # tests/ so the gate reflects untested application code (with tests
+      # included the total was ~66%; production-only it is ~51%).
+      - run: |
+          pytest tests/ -v --tb=short \
+            --cov=. \
+            --cov-report=xml \
+            --cov-report=term-missing \
+            --cov-fail-under=50
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: backend-coverage
+          path: backend/coverage.xml
+
+  cli-test:
+    name: CLI Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: pip install pytest .
       - run: pytest tests/ -v --tb=short
 
   backend-security:
@@ -58,6 +105,91 @@ jobs:
       - run: bandit -r . -x ./tests --severity-level medium -f json -o bandit-report.json || true
       - run: bandit -r . -x ./tests --severity-level high
 
+  backend-vuln-scan:
+    name: Backend Dependency Vulnerability Scan (advisory)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          # Match backend/Dockerfile (python:3.13-slim) so the audited
+          # dependency resolution mirrors what actually ships.
+          python-version: "3.13"
+          cache: pip
+      # Install from the hashed lockfile (#128) so the audit covers exactly
+      # what ships in the Docker image; pip-audit itself is installed
+      # separately (it isn't part of the locked application tree).
+      - run: |
+          pip install --require-hashes -r requirements.lock
+          pip install pip-audit
+      # Advisory only: known advisories (e.g. transitive starlette/mcp/
+      # python-multipart CVEs) already exist in the dependency tree today,
+      # and shouldn't block CI. Flip this to blocking (drop
+      # continue-on-error) once those are triaged and cleared.
+      - name: pip-audit
+        run: pip-audit
+        continue-on-error: true
+
+  frontend-vuln-scan:
+    name: Frontend Dependency Vulnerability Scan (advisory)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      # Advisory only: known advisories (next/glob/prismjs/postcss/js-yaml)
+      # already exist in the dependency tree today, and shouldn't block CI.
+      # Flip this to blocking (drop continue-on-error) once those are
+      # triaged and cleared.
+      - name: npm audit
+        run: npm audit
+        continue-on-error: true
+
+  image-scan:
+    name: Container Image Vulnerability Scan (advisory)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - image: trainable-backend
+            context: ./backend
+          - image: trainable-frontend
+            context: ./frontend
+            target: runner
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v4
+      - name: Build ${{ matrix.image }} image (local only, not pushed)
+        uses: docker/build-push-action@v7
+        with:
+          context: ${{ matrix.context }}
+          target: ${{ matrix.target || '' }}
+          push: false
+          load: true
+          tags: ${{ matrix.image }}:ci-scan
+      # Advisory only: base-image and OS-package advisories aren't triaged
+      # yet and shouldn't block CI. Flip to blocking (drop
+      # continue-on-error, or set exit-code back to 1 without the wrapper)
+      # once they are.
+      - name: Trivy scan
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        continue-on-error: true
+        with:
+          image-ref: ${{ matrix.image }}:ci-scan
+          format: table
+          severity: "CRITICAL,HIGH"
+          exit-code: "1"
+
   frontend-lint:
     name: Frontend Lint & Typecheck
     runs-on: ubuntu-latest
@@ -75,6 +207,23 @@ jobs:
       - run: npx next lint
       - run: npx tsc --noEmit
       - run: npx prettier --check 'src/**/*.{ts,tsx,css}'
+      - run: npm test
+
+  frontend-test:
+    name: Frontend Tests
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      - run: npm test
 
   frontend-build:
     name: Frontend Build

.github/workflows/publish-image.yml

@@ -25,7 +25,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: docker/login-action@v3
+      - uses: docker/login-action@v4
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -43,9 +43,9 @@ jobs:
 
       - uses: docker/setup-qemu-action@v3
 
-      - uses: docker/setup-buildx-action@v3
+      - uses: docker/setup-buildx-action@v4
 
-      - uses: docker/build-push-action@v5
+      - uses: docker/build-push-action@v7
         with:
           context: ${{ matrix.context }}
           target: ${{ matrix.target || '' }}

.github/workflows/publish.yml

@@ -21,7 +21,7 @@ jobs:
         working-directory: cli
         run: python -m build
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: cli/dist/
@@ -33,7 +33,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# Pre-commit hooks for Trainable. See CONTRIBUTING.md.
+# Install: pip install pre-commit && pre-commit install
+# Run manually: pre-commit run --all-files
+# Generated / vendored artifacts: not hand-edited, so keep the hooks off them.
+exclude: |
+  (?x)^(
+    package-lock\.json|
+    frontend/package-lock\.json|
+    frontend/tsconfig\.tsbuildinfo|
+    .*\.excalidraw|
+    sample-data/.*
+  )$
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Keep in sync with the pinned ruff version in .github/workflows/ci.yml.
+    rev: v0.15.22
+    hooks:
+      # Lint (with autofix) the backend Python code using backend/pyproject.toml.
+      - id: ruff
+        args: [--fix]
+        files: ^backend/
+      # Format the backend Python code.
+      - id: ruff-format
+        files: ^backend/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: detect-private-key

AGENTS.md

@@ -42,7 +42,8 @@ frontend (Next.js)  ─ SSE ─►  backend (FastAPI)  ──►  Modal sandboxe
 
 ## How to contribute (PR workflow)
 
-1. **Branch from `main`** (or the current release branch if a release is in flight). Branch name uses `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `ci/` prefixes.
+0. **Merge to the integration branch, always.** Integration happens on the current release/integration branch (`release/v0.0.5`), never directly on `main`. Branch from it, open PRs with it as base, and record each merge in the ledger (`STAGING-v0.0.5.md` on that branch) so the consolidation stays backtrackable. `main` only moves when the integration branch is promoted as a release.
+1. **Branch from the integration branch** (per rule 0). Branch name uses `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `ci/` prefixes.
 2. **Open an issue first** for anything beyond a small fix. The issue is where scope gets pinned; the PR is where code lands. We've burned weeks on PRs whose scope drifted because no issue anchored it.
 3. **Keep PRs reviewable.** Soft cap: <500 lines diff, single concern. If you're at 1000+ lines or touching unrelated areas, split.
 4. **Commit message uses conventional commits** (`feat:`, `fix:`, `refactor:`, etc.). The body explains the *why*, not the *what*.