Turn debug artifacts off by default and keep them inside the session

Mirrors GitHub commit b436978. Debug output includes unmasked document text; it is now opt-in and written to <session>/debug/. Also replaces retired Llama model names in docstrings, defaults and docs.

.env.example

@@ -2,5 +2,5 @@
 GROQ_API_KEY="replace_with_your_groq_api_key"
 
 # Optional model overrides
-# GROQ_MODEL="meta-llama/llama-4-scout-17b-16e-instruct"
-# GROQ_CLASSIFIER_MODEL="llama-3.1-8b-instant"
+# GROQ_MODEL="openai/gpt-oss-120b"
+# GROQ_CLASSIFIER_MODEL="openai/gpt-oss-20b"

config/settings.yaml

@@ -45,8 +45,11 @@ pipeline:
   session_ttl_days: 30
 
 debug:
-  # Master switch — set to false to skip all debug artifact writing.
-  enabled: true
+  # Master switch. Off by default: debug artifacts include the raw (unmasked)
+  # document text. Turn on only for local debugging with synthetic documents.
+  # When on, the API writes artifacts inside the session folder, so they are
+  # removed with the session (DELETE /api/session/{id} or the TTL cleanup).
+  enabled: false
   # Root folder for debug runs. Each execution creates a timestamped sub-folder.
   output_dir: "./output/debug"
   # Save the raw Markdown produced by docling for each PDF.

docs/hugging-face.md

@@ -30,8 +30,8 @@ GROQ_API_KEY=your_groq_key
 Optional secrets or variables:
 
 ```text
-GROQ_MODEL=meta-llama/llama-4-scout-17b-16e-instruct
-GROQ_CLASSIFIER_MODEL=llama-3.1-8b-instant
+GROQ_MODEL=openai/gpt-oss-120b
+GROQ_CLASSIFIER_MODEL=openai/gpt-oss-20b
 ```
 
 ## Public Demo Safety

src/agents.py

@@ -6,8 +6,8 @@ Architecture
   PDF path
     → docling  (PDF → Markdown)
     → PIIMasker.mask()
-    → InsuranceExtractionAgents.classify_document()  [LLM: llama-3.1-8b-instant]
-    → extract_schedule() | extract_certificate()     [LLM: llama-4-scout-17b]
+    → InsuranceExtractionAgents.classify_document()  [LLM: classifier_model, gpt-oss-20b]
+    → extract_schedule() | extract_certificate()     [LLM: model, gpt-oss-120b]
     → UKMotorGoldenRecord (with source_document provenance)
 """
 from __future__ import annotations
@@ -173,9 +173,9 @@ class InsuranceExtractionAgents:
     """
     Specialist extraction agents for UK Motor Insurance documents.
 
-    Uses two LLM models:
-    - llama-3.1-8b-instant     — fast document type classification
-    - llama-4-scout-17b-16e    — deep structured extraction (Schedule / Certificate)
+    Uses two LLM models, both set in config/settings.yaml:
+    - classifier_model (openai/gpt-oss-20b)  — fast document type classification
+    - model (openai/gpt-oss-120b)            — structured extraction (Schedule / Certificate)
 
     Parameters
     ----------
@@ -206,7 +206,7 @@ class InsuranceExtractionAgents:
 
     def classify_document(self, markdown_text: str) -> str:
         """
-        Use llama-3.1-8b-instant to classify the document type.
+        Use the classifier model to classify the document type.
 
         The LLM is the primary classifier.  If it fails or returns an invalid
         label, the keyword heuristic is used as a fallback.  A discrepancy

src/api.py

@@ -52,15 +52,13 @@ logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(na
 
 # ---------------------------------------------------------------------------
 # Session storage directory  (project_root/output/sessions/<timestamp>_<uuid>/)
-# Debug artifacts directory  (project_root/output/debug/run_<timestamp>/)
+# Debug artifacts for API runs live inside each session folder (<session>/debug/),
+# so deleting a session also deletes them.
 # ---------------------------------------------------------------------------
 
 _SESSION_DIR = Path(__file__).parent.parent / "output" / "sessions"
 _SESSION_DIR.mkdir(parents=True, exist_ok=True)
 
-_DEBUG_DIR = Path(__file__).parent.parent / "output" / "debug"
-_DEBUG_DIR.mkdir(parents=True, exist_ok=True)
-
 _STATIC_DIR = Path(__file__).parent.parent / "ui" / "dist"
 _SAMPLE_PACK_DIR = Path(__file__).parent.parent / "sample_data" / "policytrace_demo_pack"
 
@@ -279,10 +277,10 @@ async def process_documents(files: list[UploadFile] = File(...)):
     docs_dir = session_dir / "docs"
     docs_dir.mkdir(parents=True, exist_ok=True)
 
-    # ── Create timestamped debug directory ────────────────────────────────
+    # ── Debug directory (inside the session, so it is deleted with it) ────
     debug_dir: Path | None = None
     if settings.debug.enabled:
-        debug_dir = _DEBUG_DIR / f"run_{run_ts}"
+        debug_dir = session_dir / "debug"
         debug_dir.mkdir(parents=True, exist_ok=True)
         logger.info("Debug artifacts → %s", debug_dir)
 
@@ -423,7 +421,8 @@ async def delete_session(session_id: str):
     Permanently delete a session directory and all its contents.
 
     This removes the uploaded PDFs, the Golden Record JSON, the review state,
-    and all debug artifacts for this session.
+    and any debug artifacts (they are written to <session>/debug/ when
+    settings.debug.enabled is true).
     """
     import shutil
     session_dir = _get_session_dir(session_id)

src/settings.py

@@ -49,8 +49,8 @@ _DEFAULT_ENTITIES = [
 
 
 class LLMSettings(BaseModel):
-    model: str = "llama-3.3-70b-versatile"
-    classifier_model: str = "llama-3.1-8b-instant"
+    model: str = "openai/gpt-oss-120b"
+    classifier_model: str = "openai/gpt-oss-20b"
     max_retries: int = 2
 
 

tests/test_settings.py

@@ -0,0 +1,12 @@
+"""Guards on the shipped configuration."""
+from pathlib import Path
+
+import yaml
+
+_SETTINGS = Path(__file__).resolve().parent.parent / "config" / "settings.yaml"
+
+
+def test_debug_artifacts_are_off_by_default():
+    """Debug artifacts include unmasked document text, so they must be opt-in."""
+    cfg = yaml.safe_load(_SETTINGS.read_text(encoding="utf-8"))
+    assert cfg["debug"]["enabled"] is False