Direct LLM Call

Source: examples/agents/direct_llm_call.py

Introduction

Engineering-design studies show that transparent prompt-to-response traces are essential for credible evaluation and human oversight; the benchmark framing in Toward Engineering AGI and the collaboration framing in Human-AI collaboration by design both depend on this visibility, while llama.cpp server docs ground practical local deployment. This example is the smallest reproducible path for observing one direct call end to end with runtime traces.

Technical Implementation

  1. Configure Tracer with JSONL + console output so each run emits machine-readable traces and lifecycle logs.

  2. Build the runtime surface (public APIs only) and execute DirectLLMCall.run(...) with a fixed request_id.

  3. Capture structured outputs from runtime execution and preserve termination metadata for analysis.

  4. Print a compact JSON payload including trace_info for deterministic tests and docs examples.

        flowchart LR
    A["Input prompt or scenario"] --> B["main(): runtime wiring"]
    B --> C["DirectLLMCall.run(...)"]
    C --> D["WorkflowRuntime executes one direct call"]
    C --> E["Tracer JSONL + console events"]
    D --> F["ExecutionResult/payload"]
    E --> F
    F --> G["Printed JSON output"]
    
 1from __future__ import annotations
 2
 3import json
 4from pathlib import Path
 5
 6from design_research_agents import (
 7    DirectLLMCall,
 8    LlamaCppServerLLMClient,
 9    Tracer,
10)
11
12
13def main() -> None:
14    """Execute one direct model call with explicit tracing."""
15    # Fixed request id keeps traces and docs output deterministic across runs.
16    request_id = "example-direct-llm-design-001"
17    tracer = Tracer(
18        enabled=True,
19        trace_dir=Path("artifacts/examples/traces"),
20        enable_jsonl=True,
21        enable_console=True,
22    )
23
24    # Run the direct LLM call using a convenience wrapper. Using this with statement will automatically shut down the
25    # client when we're done.
26    with LlamaCppServerLLMClient() as llm_client:
27        llm = DirectLLMCall(llm_client=llm_client, tracer=tracer)
28        prompt = (
29            "Write one sentence describing the one primary engineering specification for a "
30            "field-repairable wearable sensor enclosure."
31        )
32        result = llm.run(
33            prompt=prompt,
34            request_id=request_id,
35        )
36
37    # Print the results
38    summary = result.summary()
39    print(json.dumps(summary, ensure_ascii=True, indent=2, sort_keys=True))
40
41
42if __name__ == "__main__":
43    main()

Expected Results

Run Command

PYTHONPATH=src python3 examples/agents/direct_llm_call.py

Example output shape (values vary by run):

{
  "success": true,
  "final_output": "<example-specific payload>",
  "terminated_reason": "<string-or-null>",
  "error": null,
  "trace": {
    "request_id": "<request-id>",
    "trace_dir": "artifacts/examples/traces",
    "trace_path": "artifacts/examples/traces/run_<timestamp>_<request_id>.jsonl"
  }
}

References