feat: add adaptive context productivity evaluation

.env.example

@@ -53,7 +53,7 @@ ENGRAPHIS_API_TOKEN=
 # A 64-hex value is used as a raw 32-byte key; anything else is treated as a passphrase.
 # WARNING: lose this key = lose the data (no recovery). In production, inject it from a
 # secrets manager (or ENGRAPHIS_DB_KEY_FILE), NOT from this file. An existing PLAINTEXT
-# db cannot just be keyed — migrate it (dump → import into a fresh keyed db).
+# db cannot just be keyed. Migrate it (dump → import into a fresh keyed db).
 # ENGRAPHIS_DB_KEY=
 # ...or read the key from a file (e.g. a mounted docker/k8s secret):
 # ENGRAPHIS_DB_KEY_FILE=/run/secrets/engraphis_db_key
@@ -66,6 +66,7 @@ ENGRAPHIS_EMBED_MODEL=sentence-transformers/all-MiniLM-L6-v2
 
 # ── LLM (external, you choose the provider) ─────────────────────────────────
 # Provider: openai | anthropic | google | openrouter | custom
+# Copy-ready provider setups and endpoint requirements: docs/LLM_PROVIDERS.md
 # ── v2 write-path fact extraction (optional) ─────────────────────────────────
 # "none" (default): store text as given. "chunk": deterministic offline chunks.
 # "llm": free-form fact extraction. "llm_structured": schema-validated typed facts,
@@ -80,7 +81,7 @@ ENGRAPHIS_LLM_AUTO_EXTRACT=0
 
 # ── Knowledge-graph extraction (powers the dashboard Graph tab) ──────────────
 # "regex" (default): dependency-free heuristic NER runs on every ingest so the Graph tab
-# has nodes — no API key, safe offline. "none": disable heuristic text extraction.
+# has nodes: no API key, safe offline. "none": disable heuristic text extraction.
 # Validated entity/relation metadata from "llm_structured" still feeds the graph
 # automatically. Existing memories are backfilled when a workspace graph first opens.
 ENGRAPHIS_GRAPH_EXTRACTOR=regex
@@ -122,7 +123,7 @@ ENGRAPHIS_RETENTION_SUPERVISOR=none
 # header entirely, which is what you want when a fronting proxy sets its own.
 # The default CSP is strict same-origin and contains no unsafe-inline; dashboard CSS,
 # JavaScript, and vendored libraries are served under /static.
-# Quote the values — both contain characters a shell would otherwise split on.
+# Quote the values because both contain characters a shell would otherwise split on.
 # ENGRAPHIS_CSP="default-src 'self'; frame-ancestors 'none'"   # replace the policy
 # ENGRAPHIS_CSP=""                                             # send no CSP at all
 # ENGRAPHIS_HSTS="max-age=31536000; includeSubDomains"
@@ -140,6 +141,12 @@ ENGRAPHIS_LLM_API_KEY=sk-your-key-here
 # For openrouter / custom: the base URL of the OpenAI-compatible endpoint.
 #   openrouter: https://openrouter.ai/api/v1
 #   custom:     https://your-endpoint/v1
+#   ollama:     http://localhost:11434/v1
+# Ollama example (replace the model with one you have pulled):
+#   ENGRAPHIS_LLM_PROVIDER=custom
+#   ENGRAPHIS_LLM_MODEL=qwen2.5-coder:latest
+#   ENGRAPHIS_LLM_API_KEY=ollama  # must be non-empty; default local Ollama ignores it
+#   ENGRAPHIS_LLM_BASE_URL=http://localhost:11434/v1
 # ENGRAPHIS_LLM_BASE_URL=https://openrouter.ai/api/v1
 # Optional: extra headers (JSON string) for custom providers.
 # ENGRAPHIS_LLM_EXTRA_HEADERS={"HTTP-Referer":"https://myapp.com","X-Title":"engraphis"}
@@ -179,15 +186,15 @@ ENGRAPHIS_LLM_API_KEY=sk-your-key-here
 # The plan is resolved automatically: once this installation has reached the control plane
 # it reads the authoritative entitlement (plan and feature list) and caches it beside the
 # cloud session, so a Pro or Team badge is correct on every later boot including offline
-# ones. The refresh is opportunistic and runs on a background thread — it never blocks or
+# ones. The refresh is opportunistic and runs on a background thread. It never blocks or
 # delays startup, and it never fails the dashboard when the cloud is unreachable. Before
 # the very first successful contact a connected installation is presented as Pro, the
 # smallest paid plan, so a paying customer is never shown the free local core.
 #
 # ENGRAPHIS_CLOUD_PLAN is an override for the cases automatic resolution cannot cover: an
 # air-gapped deployment, or one pinned to a short-lived ENGRAPHIS_CLOUD_ACCESS_TOKEN that
 # cannot refresh. It takes precedence over the cached entitlement. Accepts pro, team, or
-# free. It is presentation only — setting it grants nothing, because Engraphis Cloud
+# free. It is presentation only. Setting it grants nothing, because Engraphis Cloud
 # authorizes every paid call regardless of what this client displays.
 # ENGRAPHIS_CLOUD_PLAN=team
 #
@@ -208,7 +215,7 @@ ENGRAPHIS_LLM_API_KEY=sk-your-key-here
 # snapshots, while an installation connected to Engraphis Cloud is allowed by default,
 # because connecting already accepts the terms covering managed analytics, dreaming, and
 # consolidation. This variable is an explicit operator override, not a customer-facing
-# setting — set it to 0 to opt a connected installation back out, or to 1 to force
+# setting: set it to 0 to opt a connected installation back out, or to 1 to force
 # managed compute on regardless of session state. The cloud service remains authoritative
 # for all paid computation.
 # ENGRAPHIS_MANAGED_COMPUTE_CONSENT=0
@@ -220,36 +227,36 @@ ENGRAPHIS_LLM_API_KEY=sk-your-key-here
 # These settings are used by advanced deployments, operators, and internal
 # subsystems. Leave commented unless your deployment needs them.
 
-# Logging — defaults to INFO, text format.
+# Logging: defaults to INFO, text format.
 # ENGRAPHIS_LOG_LEVEL=INFO
 # ENGRAPHIS_LOG_FORMAT=text
 # ENGRAPHIS_LOG_JSON=0
 
-# CORS — comma-separated origins allowed to call the dashboard REST API.
+# CORS: comma-separated origins allowed to call the dashboard REST API.
 # Default: http://127.0.0.1:<ENGRAPHIS_PORT> and
 # http://localhost:<ENGRAPHIS_PORT>. Explicit values replace both loopback origins.
 # ENGRAPHIS_CORS_ORIGINS=https://myapp.example.com
 
-# Rate limiting — requests per window. Default: 0 (disabled), with a 60s window
+# Rate limiting: requests per window. Default: 0 (disabled), with a 60s window
 # used when ENGRAPHIS_RATE_LIMIT is set above zero.
 # ENGRAPHIS_RATE_LIMIT=0
 # ENGRAPHIS_RATE_WINDOW=60
 
-# HTTPS security origin — used for HTTP-to-HTTPS redirects and security headers.
+# HTTPS security origin: used for HTTP-to-HTTPS redirects and security headers.
 # ENGRAPHIS_PUBLIC_URL wins; when unset, security falls back to
 # ENGRAPHIS_DASHBOARD_URL, then the legacy ENGRAPHIS_RELAY_PUBLIC_URL setting.
 # These settings do not change CORS; configure ENGRAPHIS_CORS_ORIGINS separately.
 # ENGRAPHIS_PUBLIC_URL=https://engraphis.example.com
 # ENGRAPHIS_RELAY_PUBLIC_URL=https://relay.example.com
 
-# Trusted local peers — comma-separated addresses exempt from rate limiting.
+# Trusted local peers: comma-separated addresses exempt from rate limiting.
 # ENGRAPHIS_LOCAL_TRUSTED_PEERS=127.0.0.1,::1
 
-# Import roots — semicolon-separated (Windows) or colon-separated (POSIX)
+# Import roots: semicolon-separated (Windows) or colon-separated (POSIX)
 # directories allowed as import sources.
 # ENGRAPHIS_IMPORT_ROOTS=/srv/docs:/home/user/notes
 
-# Memory engine tuning — decay halflife (days), chunk sizing (tokens),
+# Memory engine tuning: decay halflife (days), chunk sizing (tokens),
 # proactive context loop, and reranker model.
 # ENGRAPHIS_DECAY_HALFLIFE_DAYS=30
 # ENGRAPHIS_CHUNK_TOKENS=512
@@ -263,15 +270,15 @@ ENGRAPHIS_LLM_API_KEY=sk-your-key-here
 # ENGRAPHIS_LOOP_TOP_K=10
 # ENGRAPHIS_RERANK_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
 
-# Workspace allow-list — comma-separated names. Empty = all allowed.
+# Workspace allow-list: comma-separated names. Empty = all allowed.
 # ENGRAPHIS_WORKSPACES=acme,personal
 
-# Cloud Sync relay — endpoint and optional token for self-hosted relay.
+# Cloud Sync relay: endpoint and optional token for self-hosted relay.
 # ENGRAPHIS_RELAY_URL=https://relay.example.com
 # ENGRAPHIS_SYNC_TOKEN=
 # ENGRAPHIS_SYNC_READ_ONLY=0
 
-# Hosted plan upgrade URLs — override the default upgrade landing pages.
+# Hosted plan upgrade URLs: override the default upgrade landing pages.
 # ENGRAPHIS_UPGRADE_URL=
 # ENGRAPHIS_PRO_UPGRADE_URL=
 # ENGRAPHIS_TEAM_UPGRADE_URL=

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0

.github/workflows/public-benchmarks.yml

@@ -0,0 +1,157 @@
+name: Public benchmarks
+
+on:
+  workflow_dispatch:
+    inputs:
+      suite:
+        description: "Protected benchmark suite to run"
+        required: true
+        type: choice
+        options:
+          - hosted-luna-full
+      run_id:
+        description: "Unique operator-supplied run identifier"
+        required: true
+        type: string
+      max_hosted_calls:
+        description: "Exact full-run call ceiling reported by the frozen dry-run"
+        required: true
+        type: string
+      prerequisites_reviewed:
+        description: "Smoke and pilot reports were completed and reviewed"
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: public-benchmark-${{ inputs.suite }}-${{ inputs.run_id }}
+  cancel-in-progress: false
+
+jobs:
+  benchmark:
+    name: ${{ inputs.suite }} / ${{ inputs.run_id }}
+    environment: public-benchmark-protected
+    runs-on: [self-hosted, benchmark]
+    timeout-minutes: 1440
+    steps:
+      - name: Check out the requested revision
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          fetch-depth: 0
+
+      - name: Verify immutable clean source
+        shell: bash
+        run: |
+          set -euo pipefail
+          test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
+          test -z "$(git status --porcelain=v1 --untracked-files=all)"
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Install the protected benchmark environment
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[all,test,hosted-eval]"
+
+      - name: Create persistent private working directories
+        shell: bash
+        env:
+          RUN_ID: ${{ inputs.run_id }}
+          AUTHORIZED_CALLS: ${{ inputs.max_hosted_calls }}
+          PREREQUISITES_REVIEWED: ${{ inputs.prerequisites_reviewed }}
+          STATE_ROOT: ${{ vars.ENGRAPHIS_BENCHMARK_STATE_ROOT }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$RUN_ID" =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ ]]; then
+            echo "run_id must start with an alphanumeric and contain at most 128 safe characters" >&2
+            exit 2
+          fi
+          if [[ ! "$AUTHORIZED_CALLS" =~ ^[1-9][0-9]*$ ]]; then
+            echo "max_hosted_calls must be an explicit positive integer" >&2
+            exit 2
+          fi
+          if [ "$PREREQUISITES_REVIEWED" != "true" ]; then
+            echo "smoke and pilot prerequisites must be reviewed before a full run" >&2
+            exit 2
+          fi
+          if [ -z "$STATE_ROOT" ] || [[ "$STATE_ROOT" == *$'\n'* ]]; then
+            echo "ENGRAPHIS_BENCHMARK_STATE_ROOT must be configured on the protected runner" >&2
+            exit 2
+          fi
+          mkdir -p -- "$STATE_ROOT"
+          state_root_real="$(realpath "$STATE_ROOT")"
+          workspace_real="$(realpath "$GITHUB_WORKSPACE")"
+          if [ "$state_root_real" = "/" ] || [ "$state_root_real" = "$workspace_real" ] || \
+             [[ "$state_root_real" == "$workspace_real/"* ]]; then
+            echo "benchmark state must be outside the checkout" >&2
+            exit 2
+          fi
+          state_dir="$state_root_real/$RUN_ID"
+          mkdir -p -- "$state_dir"
+          chmod 700 "$state_root_real" "$state_dir"
+          printf 'BENCHMARK_STATE_DIR=%s\n' "$state_dir" >> "$GITHUB_ENV"
+          mkdir -p public-artifacts
+
+      - name: Safe orchestrator dry-run (zero hosted calls)
+        shell: bash
+        env:
+          AUTHORIZED_CALLS: ${{ inputs.max_hosted_calls }}
+        run: |
+          set -euo pipefail
+          python -m eval.hosted_luna --dry-run --full \
+            > "$BENCHMARK_STATE_DIR/plan.json"
+          python - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          path = Path(os.environ["BENCHMARK_STATE_DIR"]) / "plan.json"
+          plan = json.loads(path.read_text(encoding="utf-8"))
+          if plan.get("dry_run") is not True:
+              raise SystemExit("orchestrator did not report dry_run=true")
+          if plan.get("config", {}).get("stage") != "full":
+              raise SystemExit("orchestrator dry-run did not bind the full stage")
+          calls = plan.get("config", {}).get("projected_max_hosted_calls")
+          if not isinstance(calls, int) or calls <= 0:
+              raise SystemExit("dry-run did not provide a positive call ceiling")
+          if str(calls) != os.environ["AUTHORIZED_CALLS"]:
+              raise SystemExit("operator ceiling does not exactly match the frozen dry-run")
+          (path.parent / "max-hosted-calls").write_text(str(calls), encoding="ascii")
+          PY
+
+      - name: Execute the frozen benchmark plan
+        shell: bash
+        run: |
+          set -euo pipefail
+          max_calls="$(cat "$BENCHMARK_STATE_DIR/max-hosted-calls")"
+          test "$max_calls" -gt 0
+          python -m eval.hosted_luna --full \
+            --max-hosted-calls "$max_calls" \
+            --private-records "$BENCHMARK_STATE_DIR/records.jsonl" \
+            --public-report "$BENCHMARK_STATE_DIR/public.json"
+
+      - name: Validate the public artifact and its claim boundary
+        shell: bash
+        env:
+          RUN_ID: ${{ inputs.run_id }}
+        run: |
+          set -euo pipefail
+          python -m eval.public_readiness \
+            --artifact "$BENCHMARK_STATE_DIR/public.json"
+          cp "$BENCHMARK_STATE_DIR/public.json" "public-artifacts/$RUN_ID.json"
+          sha256sum "public-artifacts/$RUN_ID.json" > "public-artifacts/$RUN_ID.json.sha256"
+
+      - name: Upload redacted public artifacts only
+        if: ${{ success() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: public-benchmark-${{ inputs.suite }}-${{ inputs.run_id }}
+          path: public-artifacts/
+          if-no-files-found: error
+          retention-days: 14