dsh-context-guardian 0.1.0-alpha.10

package/cg_anchors.js

@@ -0,0 +1,203 @@
+// cg_anchors.js -- anchor recovery for the context-guardian.
+// After a conversation region is compacted into a checkpoint, find the named
+// things (files, identifiers, URLs, code spans) that the checkpoint dropped but
+// that later turns still reference, plus the constraints/decisions the summary
+// forgot. Pure library: no imports, no I/O, no clock, no mutated globals.
+
+export const ANCHORS_REV = 'cg-anchors-1'
+
+const UNIQUE_CAP = 2000
+const RETURN_CAP = 200
+const LOST_CAP = 40
+const ITEM_CAP = 20
+
+const CARRIED_HEADER = '[context-guardian: carried facts -- named before this checkpoint and still referenced after it, but missing from the summary above]'
+
+const RE_URL = /https?:\/\/[^\s)\]>"'`]+/g
+const RE_PATH = /(?:[A-Za-z]:[\\/])?(?:[\w.\-]+[\\/])+[\w.\-]+\.[A-Za-z0-9]{1,8}\b/g
+const RE_FILE = /\b[\w\-]+\.(py|js|mjs|cjs|ts|tsx|jsx|json|md|yml|yaml|toml|txt|sh|bat|ps1|csv|html|css|sql|go|rs|java|c|cpp|h)\b/g
+const RE_CALL = /\b([A-Za-z_][A-Za-z0-9_]{2,})\(/g
+
+const RE_TRAILING = /[.,;:!?]+$/
+const RE_WHITESPACE = /\s+/g
+
+const K_CODE = 1
+const K_URL = 2
+const K_PATH = 3
+const K_FILE = 4
+const K_CALL = 5
+
+// Defensive coercion: never throw, never leak a non-string into a regex.
+function asText(value) {
+  if (typeof value === 'string') return value
+  if (value === null || value === undefined) return ''
+  try {
+    return String(value)
+  } catch {
+    return ''
+  }
+}
+
+function asList(value) {
+  if (Array.isArray(value)) return value
+  if (value === null || value === undefined) return []
+  return [value]
+}
+
+function asItems(value) {
+  return asList(value).map((entry) => {
+    if (entry !== null && typeof entry === 'object') return entry
+    return { cat: '', text: asText(entry) }
+  })
+}
+
+function norm(s) {
+  return asText(s).toLowerCase().replace(RE_WHITESPACE, ' ').trim().replace(RE_TRAILING, '')
+}
+
+function pushCandidate(bag, text, kind, start) {
+  if (text === '') return
+  bag.push({ text, lc: text.toLowerCase(), kind, start, seq: bag.length })
+}
+
+// Kind 1: code spans, one per odd split segment that has a closing backtick.
+function collectCodeSpans(text, bag) {
+  const segments = text.split('`')
+  let offset = 0
+  for (let i = 0; i < segments.length; i += 1) {
+    const segment = segments[i]
+    const start = offset
+    offset += segment.length + 1
+    if (i % 2 !== 1 || i >= segments.length - 1) continue
+    if (segment.includes('\n')) continue
+    const trimmed = segment.trim()
+    if (trimmed.length < 3 || trimmed.length > 120) continue
+    pushCandidate(bag, trimmed, K_CODE, start)
+  }
+}
+
+function collectMatches(text, re, kind, bag, group) {
+  for (const m of text.matchAll(re)) {
+    let value = group === 0 ? m[0] : m[group]
+    if (value === undefined) continue
+    if (kind === K_URL) value = value.replace(RE_TRAILING, '')
+    if (value === '') continue
+    pushCandidate(bag, value, kind, m.index)
+  }
+}
+
+// An occurrence is redundant only when it is a strict sub-string of a longer
+// anchor AND it is not a distinct mention in its own right: either it was found
+// by a different extractor (a path containing a bare file name), or the shorter
+// match physically lies inside the longer one in this text.
+function insideShorter(cand, other) {
+  return cand.start >= other.start && cand.start + cand.text.length <= other.start + other.text.length
+}
+
+function isRedundant(cand, unique) {
+  for (const other of unique) {
+    if (other === cand) continue
+    if (other.lc.length <= cand.lc.length) continue
+    if (!other.lc.includes(cand.lc)) continue
+    if (cand.kind !== other.kind || insideShorter(cand, other)) return true
+  }
+  return false
+}
+
+export function extractAnchors(text) {
+  if (typeof text !== 'string' || text === '') return []
+
+  const bag = []
+  collectCodeSpans(text, bag)
+  collectMatches(text, RE_URL, K_URL, bag, 0)
+  collectMatches(text, RE_PATH, K_PATH, bag, 0)
+  collectMatches(text, RE_FILE, K_FILE, bag, 0)
+  collectMatches(text, RE_CALL, K_CALL, bag, 1)
+  if (bag.length === 0) return []
+
+  bag.sort((a, b) => (a.start - b.start) || (a.seq - b.seq))
+
+  const seen = new Set()
+  const unique = []
+  for (const cand of bag) {
+    if (seen.has(cand.lc)) continue
+    seen.add(cand.lc)
+    unique.push(cand)
+    if (unique.length >= UNIQUE_CAP) break
+  }
+
+  const out = []
+  for (const cand of unique) {
+    if (isRedundant(cand, unique)) continue
+    out.push(cand.text)
+    if (out.length >= RETURN_CAP) break
+  }
+  return out
+}
+
+export function findLostAnchors({ regionTexts = [], laterTexts = [], checkpointText = '', memoryTexts = [] } = {}) {
+  const region = asList(regionTexts).map(asText).join('\n')
+  const later = asList(laterTexts).map(asText).join('\n').toLowerCase()
+  const haystack = (asText(checkpointText) + '\n' + asList(memoryTexts).map(asText).join('\n')).toLowerCase()
+
+  const recurring = []
+  for (const anchor of extractAnchors(region)) {
+    if (later.includes(anchor.toLowerCase())) recurring.push(anchor)
+  }
+
+  const kept = []
+  const lost = []
+  for (const anchor of recurring) {
+    if (haystack.includes(anchor.toLowerCase())) {
+      kept.push(anchor)
+    } else if (lost.length < LOST_CAP) {
+      lost.push(anchor)
+    }
+  }
+  return { recurring, kept, lost }
+}
+
+export function lostConstraints({ regionItems = [], checkpointText = '' } = {}) {
+  const target = norm(checkpointText)
+  const out = []
+  for (const item of asItems(regionItems)) {
+    const cat = asText(item.cat)
+    if (cat !== 'constraints' && cat !== 'decisions') continue
+    const text = norm(item.text)
+    if (text === '') continue
+    if (target.includes(text)) continue
+    out.push(item)
+    if (out.length >= ITEM_CAP) break
+  }
+  return out
+}
+
+export function renderCarried(lost = [], items = [], maxChars = 1600) {
+  const anchors = asList(lost).map(asText).filter((s) => s !== '')
+  const carried = []
+  for (const item of asItems(items)) {
+    const cat = asText(item.cat)
+    if (cat !== 'constraints' && cat !== 'decisions') continue
+    const text = asText(item.text)
+    if (text === '') continue
+    carried.push(cat === 'constraints' ? '- constraint: ' + text : '- decision: ' + text)
+  }
+
+  const candidates = []
+  for (const anchor of anchors) candidates.push('- `' + anchor + '`')
+  for (const line of carried) candidates.push(line)
+  if (candidates.length === 0) return ''
+
+  const limit = Number.isFinite(maxChars) ? maxChars : 0
+  const lines = [CARRIED_HEADER]
+  let width = CARRIED_HEADER.length
+  for (const line of candidates) {
+    // join('\n') costs one separator per extra line: width + line + count.
+    if (width + 1 + line.length > limit) break
+    lines.push(line)
+    width += 1 + line.length
+  }
+  const leftOut = candidates.length - (lines.length - 1)
+  if (leftOut > 0) lines.push('- (+' + leftOut + ' more; recall by seq)')
+  return lines.join('\n')
+}

package/cg_autorecall.js

@@ -0,0 +1,215 @@
+import { pathToFileURL } from 'node:url'
+import { renderMessage } from './cg_recall.js'
+
+export const RECALL_TAG = '[context-guardian recall]'
+export const STOP = Object.freeze(['JSON', 'YAML', 'HTML', 'HTTP', 'HTTPS', 'URL', 'API', 'CSV', 'SQL', 'TODO', 'NOTE', 'README'])
+
+const MAX_NAMES = 12
+const HIT_CHARS = 200
+const WINDOW = 80
+
+export function extractNames(text) {
+  const s = String(text ?? '')
+  const regexes = [
+    /\bdoc\d+\b/gi,
+    /\bL\d{3}\b/g,
+    /\b[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)+\b/g,
+    /\b[A-Z][A-Z0-9]{2,}(?:[-_][A-Z0-9]+)*\b/g,
+    /"([^"\n]{3,60})"|'([^'\n]{3,60})'|`([^`\n]{3,60})`/g
+  ]
+
+  const matches = []
+
+  for (let i = 0; i < regexes.length; i++) {
+    const re = regexes[i]
+    let match
+    while ((match = re.exec(s)) !== null) {
+      // For the quoted alternation the interesting value is the captured inner
+      // text; the other four keep the whole match.
+      const value = i === 4 ? (match[1] !== undefined ? match[1] : match[2] !== undefined ? match[2] : match[3]) : match[0]
+      matches.push({ index: match.index, value })
+    }
+  }
+
+  matches.sort((a, b) => a.index - b.index)
+
+  const seen = new Set()
+  const result = []
+
+  for (const m of matches) {
+    if (result.length >= MAX_NAMES) break
+    if (m.value === undefined) continue
+    if (seen.has(m.value) || STOP.includes(m.value)) continue
+    seen.add(m.value)
+    result.push(m.value)
+  }
+
+  return result
+}
+
+export function linePairs(text) {
+  const s = String(text ?? '')
+  const re = /\b(doc\d+)\b[^\n]{0,40}?\b(L\d{3})\b/gi
+  const pairs = []
+  const seen = new Set()
+  let match
+
+  while ((match = re.exec(s)) !== null) {
+    const doc = match[1]
+    const line = match[2].toUpperCase()
+    const key = doc.toLowerCase() + ' ' + line.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    pairs.push({ doc, line })
+  }
+
+  return pairs
+}
+
+export function staleRecall(input = {}) {
+  const inp = input && typeof input === 'object' ? input : {}
+  const userText = String(inp.userText ?? '')
+  const live = String(inp.liveText ?? '').toLowerCase()
+  const maxHits = Number.isFinite(inp.maxHits) ? inp.maxHits : 3
+  const maxChars = Number.isFinite(inp.maxChars) ? inp.maxChars : 600
+
+  const nodes = (Array.isArray(inp.nodes) ? inp.nodes : [])
+    .filter((n) => n && n.message)
+    .sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0))
+
+  const rendered = nodes.map((n) => {
+    let text
+    try {
+      text = renderMessage(n.message)
+    } catch (err) {
+      text = ''
+    }
+    return { seq: n.seq, text: String(text ?? '') }
+  })
+
+  const hits = []
+  let used = 0
+
+  function add(label, seq, text) {
+    if (hits.length >= maxHits) return
+    const t = String(text).slice(0, HIT_CHARS)
+    if (used + t.length > maxChars) return
+    hits.push({ label, seq, text: t })
+    used += t.length
+  }
+
+  // Step 1: "docNN LNNN" pairs pull the exact archived line back in.
+  const pairs = linePairs(userText)
+  const pairNames = new Set()
+
+  for (const { doc, line } of pairs) {
+    pairNames.add(doc.toLowerCase())
+    pairNames.add(line.toLowerCase())
+  }
+
+  for (const { doc, line } of pairs) {
+    const lowerDoc = doc.toLowerCase()
+    // Built from the upper-cased line number: the regex is not case-insensitive
+    // and archived lines start with "L017", not "l017".
+    const re = new RegExp('^\\s*' + line + '\\b.*$', 'm')
+
+    let foundEntry = null
+    for (const entry of rendered) {
+      if (entry.text.toLowerCase().includes(lowerDoc) && re.test(entry.text)) {
+        foundEntry = entry
+        break
+      }
+    }
+    if (!foundEntry) continue
+
+    const found = foundEntry.text.match(re)
+    const lineText = (found && found[0] ? found[0] : '').trim()
+    if (!lineText) continue
+    if (live.includes(lineText.toLowerCase())) continue
+    add(doc + ' ' + line, foundEntry.seq, lineText)
+  }
+
+  // Step 2: every other name that is neither a pair name nor still live.
+  for (const name of extractNames(userText)) {
+    const key = name.toLowerCase()
+    if (pairNames.has(key) || live.includes(key)) continue
+
+    let foundEntry = null
+    for (const entry of rendered) {
+      if (entry.text.toLowerCase().includes(key)) {
+        foundEntry = entry
+        break
+      }
+    }
+    if (!foundEntry) continue
+
+    const at = foundEntry.text.toLowerCase().indexOf(key)
+    if (at === -1) continue
+
+    const len = foundEntry.text.length
+    const start = Math.max(0, at - WINDOW)
+    const end = Math.min(len, at + key.length + WINDOW)
+    const body = foundEntry.text.slice(start, end).replace(/[\n\t]+/g, ' ')
+
+    add(name, foundEntry.seq, (start > 0 ? '…' : '') + body + (end < len ? '…' : ''))
+  }
+
+  if (hits.length === 0) return ''
+
+  return RECALL_TAG + ' from earlier in this session (compacted out of view):\n' +
+    hits.map((h) => '- ' + h.label + ' (seq ' + h.seq + '): ' + h.text).join('\n')
+}
+
+function userNode(seq, text) {
+  return { seq, message: { role: 'user', content: [{ type: 'text', text }] } }
+}
+
+export function selftest() {
+  const FENCE = '`'.repeat(3)
+  const doc = (k) => Array.from({ length: 100 }, (_, i) => 'L' + String(i + 1).padStart(3, '0') + ' Word' + k + ' line ' + (i + 1) + '; code C' + k + String(i + 1).padStart(3, '0') + '.').join('\n')
+  const nodes = [1, 2, 4].map((k, i) => userNode(10 * (i + 1), 'Reading task ' + k + '. Below is lines 1-100 of the read-only file doc0' + k + '.txt.\n' + FENCE + '\n' + doc(k) + '\n' + FENCE))
+  const ask = 'Final check, part 2. Reply with ONLY a JSON object: {"doc01 L017": ?, "doc02 L058": ?, "doc04 L081": ?}.'
+  const checks = [
+    ['names_in_order_unique_stoplisted', () => JSON.stringify(extractNames('see HeronNest and MAPLE-123, then "the blue file" and doc03 L044 and HeronNest again in JSON')) === JSON.stringify(['HeronNest', 'MAPLE-123', 'the blue file', 'doc03', 'L044'])],
+    ['line_pairs', () => JSON.stringify(linePairs(ask)) === JSON.stringify([{ doc: 'doc01', line: 'L017' }, { doc: 'doc02', line: 'L058' }, { doc: 'doc04', line: 'L081' }])],
+    ['bench_three_early_lines_recalled', () => {
+      const r = staleRecall({ userText: ask, liveText: 'summary: three reading tasks were done', nodes })
+      return r.startsWith(RECALL_TAG) && r.includes('code C1017') && r.includes('code C2058') && r.includes('code C4081')
+    }],
+    ['live_line_not_recalled', () => {
+      const live = 'L017 Word1 line 17; code C1017.'
+      const r = staleRecall({ userText: ask, liveText: live, nodes })
+      return !r.includes('C1017') && r.includes('C2058')
+    }],
+    ['max_three_hits_and_600_chars', () => {
+      const r = staleRecall({ userText: ask + ' also MAPLE-123', liveText: '', nodes: nodes.concat([userNode(50, 'the codename is MAPLE-123')]) })
+      return r.split('\n').length === 4 && r.length <= 600 + 200
+    }],
+    ['name_absent_from_live_recalled', () => {
+      const r = staleRecall({ userText: 'what was MAPLE-123 again?', liveText: 'nothing here', nodes: [userNode(5, 'For reference: the release codename for project Heron is MAPLE-123.')] })
+      return r.includes('MAPLE-123 (seq 5)')
+    }],
+    ['name_still_live_skipped', () => staleRecall({ userText: 'what was MAPLE-123 again?', liveText: 'Heron is MAPLE-123', nodes: [userNode(5, 'Heron is MAPLE-123')] }) === ''],
+    ['nothing_found_empty_string', () => staleRecall({ userText: 'hello there', liveText: '', nodes }) === '' && staleRecall() === ''],
+  ]
+  let passed = 0
+  for (const [name, fn] of checks) {
+    let ok = false
+    let label = name
+    try {
+      ok = Boolean(fn())
+    } catch (err) {
+      label = name + ' (raised ' + (err && err.name) + ': ' + (err && err.message) + ')'
+    }
+    if (ok) passed += 1
+    console.log((ok ? 'ok   ' : 'FAIL ') + label)
+  }
+  const failed = checks.length - passed
+  console.log('cg_autorecall selftest: ' + checks.length + ' checks, ' + passed + ' passed, ' + failed + ' failed')
+  return { checks: checks.length, passed, failed }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href && process.argv.includes('--selftest')) {
+  const r = selftest()
+  process.exit(r.failed === 0 && r.checks > 0 ? 0 : 1)
+}

package/cg_configure.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+cg_configure.py (shipped in the wheel as `context-guardian-configure`; `python configure.py` in a clone still works)
+============
+Interactive first-run setup for Context Guardian. Asks a few questions about
+YOUR hardware/backend and writes them to .env, so you never hand-edit a config
+file and guess.
+
+    python configure.py
+
+Every question has a sensible default (press Enter to accept). Numeric answers
+are validated, so a typo tells you rather than crashing Guardian at startup.
+Re-run any time to change your answers, or edit .env directly.
+"""
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent
+ENV_PATH = REPO_ROOT / ".env"
+
+# Context-window presets, smallest to largest, with rough guidance.
+#
+# The VRAM notes are DELIBERATELY approximate and framed for the audience this
+# tool serves: someone running a quantized ~7-14B model on a consumer GPU. The
+# context window drives the KV-cache size, which is only PART of your VRAM use
+# (the model weights are the other, larger part), and it scales with the
+# model's size too -- a 30B model at 32K needs far more than an 8B at 32K. So
+# treat these as "you'll want at least this much headroom on a typical mid-size
+# model", not a guarantee. The real number for YOUR setup comes from
+# `ollama ps` while your model is loaded. Bigger model => bump a tier.
+CONTEXT_OPTIONS = [
+    (4096,   "Light use / short chats.        Roughly 8 GB+ VRAM on a small model."),
+    (8192,   "Everyday agent use.             Roughly 10 GB+ VRAM."),
+    (16384,  "Comfortable coding/agent work.  Roughly 12 GB+ VRAM."),
+    (32768,  "Full agent sessions (default).  Roughly 12-16 GB VRAM on a 7-14B model."),
+    (65536,  "Large context.                  Roughly 20-24 GB VRAM, or heavy quant."),
+    (131072, "Very large context.             24 GB+ VRAM / aggressive quantization."),
+]
+DEFAULT_CTX = 32768
+STANDARD_CTX = {tok for tok, _ in CONTEXT_OPTIONS}
+
+
+def ask_str(prompt: str, default: str) -> str:
+    print("\n" + prompt)
+    return input(f"  [{default}]: ").strip() or default
+
+
+def ask_int(prompt: str, default: int, lo: int = 1, hi: int = 10_000_000) -> int:
+    """A validated positive integer. Re-asks on garbage instead of writing a
+    value that makes Guardian throw ValueError at import."""
+    while True:
+        raw = input(f"\n{prompt}\n  [{default}]: ").strip()
+        if not raw:
+            return default
+        try:
+            val = int(raw.replace(",", "").replace("_", ""))
+        except ValueError:
+            print(f"  '{raw}' is not a whole number. Digits only "
+                  f"(e.g. 8192), no units or letters.")
+            continue
+        if not (lo <= val <= hi):
+            print(f"  {val} is out of range. Expected {lo}..{hi}.")
+            continue
+        return val
+
+
+def ask_float(prompt: str, default: float, lo: float, hi: float) -> float:
+    while True:
+        raw = input(f"\n{prompt}\n  [{default}]: ").strip()
+        if not raw:
+            return default
+        try:
+            val = float(raw)
+        except ValueError:
+            print(f"  '{raw}' is not a number.")
+            continue
+        if not (lo <= val <= hi):
+            print(f"  {val} is out of range. Expected {lo}..{hi}.")
+            continue
+        return val
+
+
+def ask_keep_recent():
+    """None = the token-budget default (the key is NOT written, so the proxy
+    keeps the newest messages that fit in ~20% of the usable window, at least
+    4). A number = keep exactly that many messages (the old behaviour)."""
+    while True:
+        raw = input("\nWhat stays verbatim (never summarized)?\n"
+                    "  Enter = auto (newest ~20% of the window, at least 4 messages),\n"
+                    "  or a fixed number of messages\n  [auto]: ").strip().lower()
+        if raw in ("", "auto"):
+            return None
+        if raw.isdigit() and 1 <= int(raw) <= 1000:
+            return int(raw)
+        print(f"  '{raw}' is not a number from 1 to 1000 or 'auto'.")
+
+
+def ask_context() -> int:
+    """A menu of context-window presets with VRAM guidance, plus a custom
+    option that CONFIRMS a non-standard value back to the user."""
+    print("\nContext window size (in TOKENS) of the model you're actually running.")
+    print("This is the single most important setting -- it MUST match how your")
+    print("backend/model is really configured (check `ollama ps` while loaded),")
+    print("not the model's theoretical max.\n")
+    for i, (tok, blurb) in enumerate(CONTEXT_OPTIONS, 1):
+        star = "  <- default" if tok == DEFAULT_CTX else ""
+        print(f"  {i}) {tok:>7,} tokens   {blurb}{star}")
+    print(f"  {len(CONTEXT_OPTIONS) + 1}) other        Enter a custom number")
+
+    default_idx = [i for i, (t, _) in enumerate(CONTEXT_OPTIONS, 1)
+                   if t == DEFAULT_CTX][0]
+    while True:
+        raw = input(f"\n  Choose 1-{len(CONTEXT_OPTIONS) + 1} "
+                    f"[{default_idx}]: ").strip()
+        if not raw:
+            return DEFAULT_CTX
+        if not raw.isdigit():
+            print("  Enter the NUMBER of an option above.")
+            continue
+        choice = int(raw)
+        if 1 <= choice <= len(CONTEXT_OPTIONS):
+            return CONTEXT_OPTIONS[choice - 1][0]
+        if choice == len(CONTEXT_OPTIONS) + 1:
+            # Ceiling deliberately far above any real context window: an
+            # unusually large number should reach the CONFIRMATION below
+            # (showing the user their actual figure), not be silently rejected
+            # as out of range. Letters/negatives are still refused by ask_int.
+            custom = ask_int("  Custom context window, in tokens", DEFAULT_CTX,
+                             lo=256, hi=100_000_000)
+            if custom in STANDARD_CTX:
+                return custom
+            # Non-standard value: confirm it back with the ACTUAL number, so a
+            # fat-fingered 132768 or 13212348 is caught before it is written.
+            print(f"\n  {custom:,} is not one of the standard sizes.")
+            ok = input(f"  Are you sure you want a context window of "
+                       f"{custom:,} tokens? [y/N]: ").strip().lower()
+            if ok == "y":
+                return custom
+            print("  Okay, let's pick again.")
+            continue
+        print(f"  {choice} is not one of the options.")
+
+
+def main(argv=None) -> int:
+    argv = sys.argv[1:] if argv is None else list(argv)
+    if "-h" in argv or "--help" in argv:
+        print((__doc__ or "").strip())
+        print(f"\n.env is written to: {ENV_PATH}")
+        return 0
+    print("Context Guardian -- first-run setup")
+    print("=" * 40)
+    print("Press Enter on any question to accept the default in [brackets].")
+
+    if ENV_PATH.exists():
+        if input(f"\n.env already exists at {ENV_PATH}. Overwrite? [y/N]: "
+                 ).strip().lower() != "y":
+            print("Left the existing .env untouched. Edit it by hand to tweak "
+                  "one value.")
+            return 0
+
+    answers = {}
+    answers["GUARDIAN_UPSTREAM_URL"] = ask_str(
+        "OpenAI-compatible backend Guardian should forward to\n"
+        "  (your Ollama /v1 endpoint, or another proxy in front of it)",
+        "http://localhost:11434/v1")
+    answers["GUARDIAN_NUM_CTX"] = str(ask_context())
+    answers["GUARDIAN_PORT"] = str(ask_int(
+        "Port Context Guardian itself should listen on", 8786,
+        lo=1, hi=65535))
+    answers["GUARDIAN_COMPACT_THRESHOLD"] = str(ask_float(
+        "Fraction of the context window at which Guardian compacts (0.1-1.0)",
+        0.85, lo=0.1, hi=1.0))
+    keep = ask_keep_recent()
+    if keep is not None:
+        answers["GUARDIAN_KEEP_RECENT_MESSAGES"] = str(keep)
+    answers["GUARDIAN_UPSTREAM_TIMEOUT"] = str(ask_int(
+        "Seconds to wait for the upstream backend to respond\n"
+        "  (raise this if a slow local \"thinking\" model gives 500s only on "
+        "real requests)", 600, lo=1, hi=86400))
+    answers["GUARDIAN_LOG_PATH"] = ask_str(
+        "Where to log compaction events (JSON lines)",
+        "logs/context_guardian_log.json")
+
+    lines = ["# Generated by configure.py -- edit freely, or re-run configure.py.\n"]
+    for k, v in answers.items():
+        lines.append(f"{k}={v}\n")
+    ENV_PATH.write_text("".join(lines), encoding="utf-8")
+
+    ctx = int(answers["GUARDIAN_NUM_CTX"])
+    print(f"\nWrote {ENV_PATH}")
+    if ctx not in STANDARD_CTX:
+        print(f"  (custom context window: {ctx:,} tokens)")
+    print("\nNext steps:")
+    print("  1. pip install -r requirements.txt")
+    print("  2. Make sure your real backend is already running.")
+    print("  3. python context_guardian.py")
+    print(f"  4. Point your CLI's OPENAI_BASE_URL at "
+          f"http://localhost:{answers['GUARDIAN_PORT']}/v1")
+    print("\nSee README.md's \"Testing before you trust it\" section before "
+          "pointing a real session at it.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())