feat(cli): add demos and portable trace tooling #41

Merged

lost-rob0t merged 21 commits from feature/issue-19-cli-demo-trace into main

2026-08-13 06:13:02 +00:00

lost-rob0t commented

2026-08-13 05:59:15 +00:00

(Migrated from github.com)

Summary

add a thin rlm_cli facade and bin/prolog-rlm.pl entrypoint over the existing production runtime
support credential-free deterministic demos for opaque context, capability-gated tool use, adaptive recursion, supervised agents, graph checkpoint/resume, and the dual-version MCP facade
add hosted OpenRouter direct completion and a one-command bounded real depth-1 RLM flow using the production provider/completion/context/recursion stack
make the default CLI RLM orchestration deterministic: a trusted local typed-plan skeleton performs one opaque context slice and one recursive child provider call, instead of wasting provider tokens asking a root model to echo a fixed JSON plan
keep model-selected root planning available through the normal library-level rlm_completion/4 API; the CLI quick path is intentionally the reliable operability surface
support arbitrary OpenAI-compatible endpoints with explicit model selection and env/no-credential configuration
add prolog-rlm.trace.v1 JSON and JSONL trace export; preserve dict/list structure and encode compound Prolog terms explicitly as $term + args
add a minimal hierarchical trace viewer that can inspect exported files in a fresh SWI process
expose CLI/demo/trace readiness and public helpers through the main rlm entrypoint
add deterministic PlUnit coverage for the CLI router, provider configuration, demos, fixed depth-1 RLM skeleton, trace round-trips, JSONL, and viewer behavior
add exact CLI smoke coverage in CI: credential-free demo + graph trace/view on every run, plus a literal one-command real RLM invocation in the credentialed OpenRouter lane
document provider configuration, budgets, capability boundaries, failure semantics, trace format, and reproducible hosted/local examples in the root README, docs/cli-demo-traces.md, and examples/README.md

CLI examples

swipl -q -s bin/prolog-rlm.pl -- demo
swipl -q -s bin/prolog-rlm.pl -- demo recursion --view
swipl -q -s bin/prolog-rlm.pl -- direct "Reply with DIRECT_OK"
swipl -q -s bin/prolog-rlm.pl -- rlm "What token is in the context?" --context "TOKEN_42"
swipl -q -s bin/prolog-rlm.pl -- graph --trace /tmp/graph.json
swipl -q -s bin/prolog-rlm.pl -- trace-view /tmp/graph.json

Architecture

The CLI does not introduce a second runtime. Direct requests use rlm_chain/llm_query; RLM requests use rlm_completion; demos call rlm_context, rlm_tool, rlm_recursion_runtime, rlm_agent, rlm_graph, and rlm_mcp; trace output serializes the structured results those subsystems already return.

The default RLM CLI path is intentionally bounded to trusted typed plan -> context slice -> depth-1 child RLM -> real provider model -> final result. Root and child capabilities are explicit and narrowed, and CLI budget flags map to runtime budgets instead of widening authority. The injected CLI planner consumes zero provider tokens and makes no network request.

Validation

The deterministic suite passes static production/live-test loading, complete PlUnit, benchmark/conformance, the credential-free CLI/trace smoke, graph/artifact fresh-process restart checks, and whitespace checks. The first credentialed CLI attempt exposed a real design problem: asking a provider to echo the known plan used 2,151 tokens and exceeded the 1,800-token CLI budget. The CLI now constructs that fixed plan locally and reserves provider inference for the recursive child; the updated PR lane validates that exact one-command path.

Closes #19

## Summary - add a thin `rlm_cli` facade and `bin/prolog-rlm.pl` entrypoint over the existing production runtime - support credential-free deterministic demos for opaque context, capability-gated tool use, adaptive recursion, supervised agents, graph checkpoint/resume, and the dual-version MCP facade - add hosted OpenRouter direct completion and a one-command bounded real depth-1 RLM flow using the production provider/completion/context/recursion stack - make the default CLI RLM orchestration deterministic: a trusted local typed-plan skeleton performs one opaque context slice and one recursive child provider call, instead of wasting provider tokens asking a root model to echo a fixed JSON plan - keep model-selected root planning available through the normal library-level `rlm_completion/4` API; the CLI quick path is intentionally the reliable operability surface - support arbitrary OpenAI-compatible endpoints with explicit model selection and env/no-credential configuration - add `prolog-rlm.trace.v1` JSON and JSONL trace export; preserve dict/list structure and encode compound Prolog terms explicitly as `$term` + `args` - add a minimal hierarchical trace viewer that can inspect exported files in a fresh SWI process - expose CLI/demo/trace readiness and public helpers through the main `rlm` entrypoint - add deterministic PlUnit coverage for the CLI router, provider configuration, demos, fixed depth-1 RLM skeleton, trace round-trips, JSONL, and viewer behavior - add exact CLI smoke coverage in CI: credential-free demo + graph trace/view on every run, plus a literal one-command real RLM invocation in the credentialed OpenRouter lane - document provider configuration, budgets, capability boundaries, failure semantics, trace format, and reproducible hosted/local examples in the root README, `docs/cli-demo-traces.md`, and `examples/README.md` ## CLI examples ```sh swipl -q -s bin/prolog-rlm.pl -- demo swipl -q -s bin/prolog-rlm.pl -- demo recursion --view swipl -q -s bin/prolog-rlm.pl -- direct "Reply with DIRECT_OK" swipl -q -s bin/prolog-rlm.pl -- rlm "What token is in the context?" --context "TOKEN_42" swipl -q -s bin/prolog-rlm.pl -- graph --trace /tmp/graph.json swipl -q -s bin/prolog-rlm.pl -- trace-view /tmp/graph.json ``` ## Architecture The CLI does not introduce a second runtime. Direct requests use `rlm_chain`/`llm_query`; RLM requests use `rlm_completion`; demos call `rlm_context`, `rlm_tool`, `rlm_recursion_runtime`, `rlm_agent`, `rlm_graph`, and `rlm_mcp`; trace output serializes the structured results those subsystems already return. The default RLM CLI path is intentionally bounded to trusted typed plan -> context slice -> depth-1 child RLM -> real provider model -> final result. Root and child capabilities are explicit and narrowed, and CLI budget flags map to runtime budgets instead of widening authority. The injected CLI planner consumes zero provider tokens and makes no network request. ## Validation The deterministic suite passes static production/live-test loading, complete PlUnit, benchmark/conformance, the credential-free CLI/trace smoke, graph/artifact fresh-process restart checks, and whitespace checks. The first credentialed CLI attempt exposed a real design problem: asking a provider to echo the known plan used 2,151 tokens and exceeded the 1,800-token CLI budget. The CLI now constructs that fixed plan locally and reserves provider inference for the recursive child; the updated PR lane validates that exact one-command path. Closes #19