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).

$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).

$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.

& .\.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).

$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).

$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).

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