scripts/README.md

# scripts/

Utility and diagnostic scripts. None are part of the production application. Run from the repo root with the project venv.

All scripts require `PYTHONPATH=src` (set in the invocation below or via `$env:PYTHONPATH = "src"`).

## Scripts

### agent_e2e_smoke.py

Drive the real agent harness end-to-end against the live llama.cpp server — loads a fixture session and runs one SPEAK turn and one ACT turn through `run_agent_turn_streaming`, printing streamed tokens, tool activity, and the final `TurnResult`. Proves the full agent-forward pipeline end-to-end.

**Requires: live llama.cpp server** (`docker compose up`).

```powershell
$env:PYTHONPATH = "src"; & .\.venv\Scripts\python.exe scripts\agent_e2e_smoke.py
```

### enforce_probe.py

Diagnose which structured-output enforcement path the running llama.cpp server honors — tests the full `response_format` matrix (bare shape vs. OpenAI-standard `json_schema` wrapper) so you know what the server actually enforces. Distinct from `llm_smoke_test.py`: this is specifically about schema enforcement paths, not general inference.

**Requires: live llama.cpp server** (`docker compose up`).

```powershell
$env:PYTHONPATH = "src"; & .\.venv\Scripts\python.exe scripts\enforce_probe.py
```

### lint_import_dependencies.py

AST-based one-directional import lint (anti-specialization guardrail, M22 item 12). Enforces that the renderer-agnostic / substrate-agnostic core modules (`contracts`, `context_packer`, `validator`, `reducer`, `graph_repository`, `response_format`) never import from `loosecanvas.extractors`. Run as part of CI or before committing changes to core modules.

**Does not require a live server** — pure static analysis.

```powershell
& .\.venv\Scripts\python.exe scripts\lint_import_dependencies.py
```

### llm_smoke_test.py

Live llama.cpp inference probe for the local Gemma 4 server — sends a basic completion request and validates the response. General-purpose LLM connectivity and inference check (distinct from `enforce_probe.py` which focuses on schema enforcement).

**Requires: live llama.cpp server** (`docker compose up`).

```powershell
$env:PYTHONPATH = "src"; & .\.venv\Scripts\python.exe scripts\llm_smoke_test.py
```

### text_graph_article_probe.py

Measure text-to-graph extraction performance on a realistic large (wiki-sized) input — builds a multi-paragraph article with many distinct concepts, times the real adapter end-to-end, and reports chunk count, node/edge totals, and wall time. Compares sequential vs. concurrent extraction paths.

**Requires: live llama.cpp server** (`docker compose up`).

```powershell
$env:PYTHONPATH = "src"; & .\.venv\Scripts\python.exe scripts\text_graph_article_probe.py
```

### text_graph_latency_probe.py

Latency probe for the M04b text-to-graph call path — measures where time goes in a schema-constrained extraction call, isolating: constrained vs. unconstrained generation, the effect of `max_tokens`, and chunk size / call-count scaling. Prints the server's own `timings` (prompt/predicted tokens-per-second) for data-driven tuning.

**Requires: live llama.cpp server** (`docker compose up`).

```powershell
$env:PYTHONPATH = "src"; & .\.venv\Scripts\python.exe scripts\text_graph_latency_probe.py
```