# PtcRunner v0.10.1 - Table of Contents

A BEAM-native Elixir library for Programmatic Tool Calling (PTC) with a lispy DSL (subset of Clojure). PTC lets LLMs generate small programs that orchestrate multiple tool calls and data transformations in code.

## Pages

- [PtcRunner](readme.md)
- [LICENSE](license.md)
- [Changelog](changelog.md)

- SubAgent Guides
  - [Getting Started with SubAgents](subagent-getting-started.md)
  - [LLM Setup](subagent-llm-setup.md)
  - [Text Mode SubAgents](subagent-text-mode.md)
  - [Core Concepts](subagent-concepts.md)
  - [Composition Patterns](subagent-patterns.md)
  - [Navigator Pattern: Journaled Tasks (Advanced)](subagent-navigator.md)
  - [Recursive Language Model (RLM) Patterns](subagent-rlm-patterns.md)
  - [Testing SubAgents](subagent-testing.md)
  - [Troubleshooting SubAgents](subagent-troubleshooting.md)
  - [Observability](subagent-observability.md)
  - [Message Compression](subagent-compression.md)
  - [Advanced Topics](subagent-advanced.md)
  - [Prompt Customization](subagent-prompts.md)

- Integration Guides
  - [Phoenix Streaming with SubAgent.chat/3](phoenix-streaming.md)
  - [Structured Output Callbacks](structured-output-callbacks.md)

- Reference
  - [Signature Syntax](signature-syntax.md)
  - [Benchmark Evaluation](benchmark-eval.md)
  - [PTC-Lisp Language Specification](ptc-lisp-specification.md)
  - [Clojure Conformance Gaps](clojure-conformance-gaps.md)
  - [PTC-Lisp Function Reference](function-reference.md)
  - [Clojure Core Audit for PTC-Lisp](clojure-core-audit.md)
  - [Clojure String Audit for PTC-Lisp](clojure-string-audit.md)
  - [Clojure Set Audit for PTC-Lisp](clojure-set-audit.md)
  - [Java Math Audit for PTC-Lisp](java-math-audit.md)
  - [Java Interop Reference for PTC-Lisp](java-interop.md)

- Livebooks
  - [PTC-Lisp Playground](ptc_runner_playground.md)
  - [SubAgent Examples](ptc_runner_llm_agent.md)
  - [Joke Workflow: LangGraph vs PTC-Lisp](joke_workflow.md)
  - [Observability &amp; Tracing](observability_and_tracing.md)

## Modules

- [PtcRunner.Lisp.CoreAST](PtcRunner.Lisp.CoreAST.md): Core, validated AST for PTC-Lisp.
- [PtcRunner.Lisp.Format](PtcRunner.Lisp.Format.md): Format PTC-Lisp values for human/LLM display.
- [PtcRunner.SubAgent.LLMResolver](PtcRunner.SubAgent.LLMResolver.md): LLM resolution and invocation for SubAgents.
- [PtcRunner.SubAgent.LLMTool](PtcRunner.SubAgent.LLMTool.md): LLM-powered tools for classification, evaluation, and judgment.
- [PtcRunner.SubAgent.Loop.LLMRetry](PtcRunner.SubAgent.Loop.LLMRetry.md): LLM retry logic with configurable backoff strategies.

- Core
  - [PtcRunner](PtcRunner.md): BEAM-native Programmatic Tool Calling (PTC) library.
  - [PtcRunner.Chunker](PtcRunner.Chunker.md): Text chunking utilities for RLM preprocessing.
  - [PtcRunner.Context](PtcRunner.Context.md): Manages context, memory, and tools for program execution.
  - [PtcRunner.Dotenv](PtcRunner.Dotenv.md): Loads environment variables from `.env` files.
  - [PtcRunner.Mustache](PtcRunner.Mustache.md): Standalone Mustache template parser and expander.
  - [PtcRunner.Sandbox](PtcRunner.Sandbox.md): Executes programs in isolated BEAM processes with resource limits.
  - [PtcRunner.Schema](PtcRunner.Schema.md): Declarative schema module that defines all DSL operations.
  - [PtcRunner.Step](PtcRunner.Step.md): Result of executing a PTC program or SubAgent mission.
  - [PtcRunner.Template](PtcRunner.Template.md): Represents a template with extracted placeholders.
  - [PtcRunner.Tool](PtcRunner.Tool.md): Normalized tool definition for PTC-Lisp and SubAgent.
  - [PtcRunner.Turn](PtcRunner.Turn.md): Captures a single LLM interaction cycle in a SubAgent execution.

- SubAgent
  - [PtcRunner.SubAgent](PtcRunner.SubAgent.md): Agentic loop for LLM-driven PTC-Lisp execution.
  - [PtcRunner.SubAgent.Chaining](PtcRunner.SubAgent.Chaining.md): Chaining functions for SubAgent pipelines.
  - [PtcRunner.SubAgent.CompiledAgent](PtcRunner.SubAgent.CompiledAgent.md): A compiled SubAgent with pre-derived PTC-Lisp logic.
  - [PtcRunner.SubAgent.Compiler](PtcRunner.SubAgent.Compiler.md): Compilation logic for SubAgents.
  - [PtcRunner.SubAgent.Compression](PtcRunner.SubAgent.Compression.md): Behaviour for message history compression strategies.
  - [PtcRunner.SubAgent.Compression.SingleUserCoalesced](PtcRunner.SubAgent.Compression.SingleUserCoalesced.md): Default compression strategy that coalesces all context into a single USER message.
  - [PtcRunner.SubAgent.Debug](PtcRunner.SubAgent.Debug.md): Debug helpers for visualizing SubAgent execution.
  - [PtcRunner.SubAgent.Definition](PtcRunner.SubAgent.Definition.md): Struct and type definitions for SubAgent configuration.
  - [PtcRunner.SubAgent.JsonParser](PtcRunner.SubAgent.JsonParser.md): Extracts JSON from LLM responses, handling common formatting quirks.
  - [PtcRunner.SubAgent.KeyNormalizer](PtcRunner.SubAgent.KeyNormalizer.md): Normalizes map keys from hyphens to underscores at the tool boundary.
  - [PtcRunner.SubAgent.Loop](PtcRunner.SubAgent.Loop.md): Core agentic loop that manages LLM↔tool cycles.
  - [PtcRunner.SubAgent.Loop.Budget](PtcRunner.SubAgent.Loop.Budget.md): Budget checking, callback handling, and fallback recovery for SubAgent execution.
  - [PtcRunner.SubAgent.Loop.JsonHandler](PtcRunner.SubAgent.Loop.JsonHandler.md): Shared JSON response handling for text mode variants.
  - [PtcRunner.SubAgent.Loop.Metrics](PtcRunner.SubAgent.Loop.Metrics.md): Telemetry, tracing, and usage metrics for SubAgent execution.
  - [PtcRunner.SubAgent.Loop.ResponseHandler](PtcRunner.SubAgent.Loop.ResponseHandler.md): Response parsing and validation for LLM responses.
  - [PtcRunner.SubAgent.Loop.ReturnValidation](PtcRunner.SubAgent.Loop.ReturnValidation.md): Return type validation for SubAgent execution.
  - [PtcRunner.SubAgent.Loop.State](PtcRunner.SubAgent.Loop.State.md): Typed state struct for the SubAgent execution loop.
  - [PtcRunner.SubAgent.Loop.StepAssembler](PtcRunner.SubAgent.Loop.StepAssembler.md): Final step assembly for SubAgent execution.
  - [PtcRunner.SubAgent.Loop.TextMode](PtcRunner.SubAgent.Loop.TextMode.md): Unified execution loop for text output mode.
  - [PtcRunner.SubAgent.Loop.ToolNormalizer](PtcRunner.SubAgent.Loop.ToolNormalizer.md): Tool preparation and wrapping for SubAgent execution.
  - [PtcRunner.SubAgent.Loop.TurnFeedback](PtcRunner.SubAgent.Loop.TurnFeedback.md): Turn feedback formatting for SubAgent execution.
  - [PtcRunner.SubAgent.ProgressRenderer](PtcRunner.SubAgent.ProgressRenderer.md): Renders a markdown checklist from plan steps and summaries.
  - [PtcRunner.SubAgent.PromptExpander](PtcRunner.SubAgent.PromptExpander.md): Template string expansion with placeholder validation.
  - [PtcRunner.SubAgent.Validator](PtcRunner.SubAgent.Validator.md): Validates SubAgent options at construction time.

- SubAgent — Signatures
  - [PtcRunner.SubAgent.Sigils](PtcRunner.SubAgent.Sigils.md): Sigils for SubAgent templates.
  - [PtcRunner.SubAgent.Signature](PtcRunner.SubAgent.Signature.md): Signature parsing and validation for SubAgents.
  - [PtcRunner.SubAgent.Signature.Coercion](PtcRunner.SubAgent.Signature.Coercion.md): Coerce values to expected types with warning generation.
  - [PtcRunner.SubAgent.Signature.Parser](PtcRunner.SubAgent.Signature.Parser.md): NimbleParsec-based parser for signature strings.
  - [PtcRunner.SubAgent.Signature.ParserHelpers](PtcRunner.SubAgent.Signature.ParserHelpers.md): Helper functions for signature parser AST building.

  - [PtcRunner.SubAgent.Signature.Renderer](PtcRunner.SubAgent.Signature.Renderer.md): Renders signatures back to string representation.
  - [PtcRunner.SubAgent.Signature.TypeResolver](PtcRunner.SubAgent.Signature.TypeResolver.md): Resolve paths against parsed signature types.
  - [PtcRunner.SubAgent.Signature.Validator](PtcRunner.SubAgent.Signature.Validator.md): Validates data against signature type specifications.
  - [PtcRunner.SubAgent.TypeExtractor](PtcRunner.SubAgent.TypeExtractor.md): Extract signature and description from Elixir function @spec and @doc.

- SubAgent — Prompts &amp; Tools
  - [PtcRunner.PromptLoader](PtcRunner.PromptLoader.md): Compile-time utilities for loading prompt templates from files.
  - [PtcRunner.Prompts](PtcRunner.Prompts.md): Centralized prompt loading for PtcRunner.
  - [PtcRunner.SubAgent.BuiltinTools](PtcRunner.SubAgent.BuiltinTools.md): Pure functions for resolving builtin tool families into tool maps.
  - [PtcRunner.SubAgent.Namespace](PtcRunner.SubAgent.Namespace.md): Renders namespaces for the USER message (REPL with Prelude model).
  - [PtcRunner.SubAgent.Namespace.Data](PtcRunner.SubAgent.Namespace.Data.md): Renders the data/ namespace section.
  - [PtcRunner.SubAgent.Namespace.ExecutionHistory](PtcRunner.SubAgent.Namespace.ExecutionHistory.md): Renders tool call history and println output.
  - [PtcRunner.SubAgent.Namespace.Tool](PtcRunner.SubAgent.Namespace.Tool.md): Renders available tools for the USER message namespace section.
  - [PtcRunner.SubAgent.Namespace.TypeVocabulary](PtcRunner.SubAgent.Namespace.TypeVocabulary.md): Converts Elixir values to human-readable type labels.
  - [PtcRunner.SubAgent.Namespace.User](PtcRunner.SubAgent.Namespace.User.md): Renders the user/ namespace section (LLM-defined functions and values).
  - [PtcRunner.SubAgent.SubAgentTool](PtcRunner.SubAgent.SubAgentTool.md): Wraps a SubAgent as a callable tool for parent agents.
  - [PtcRunner.SubAgent.SystemPrompt](PtcRunner.SubAgent.SystemPrompt.md): System prompt generation for SubAgent LLM interactions.
  - [PtcRunner.SubAgent.SystemPrompt.Output](PtcRunner.SubAgent.SystemPrompt.Output.md): Expected output section generation for SubAgent prompts.
  - [PtcRunner.SubAgent.Telemetry](PtcRunner.SubAgent.Telemetry.md): Telemetry event emission for SubAgent execution.
  - [PtcRunner.SubAgent.ToolSchema](PtcRunner.SubAgent.ToolSchema.md): Converts Tool structs to OpenAI-format JSON Schema tool definitions.

- PTC-Lisp
  - [PtcRunner.Lisp](PtcRunner.Lisp.md): Execute PTC programs written in Lisp DSL (Clojure subset).
  - [PtcRunner.Lisp.AST](PtcRunner.Lisp.AST.md): AST node types for PTC-Lisp
  - [PtcRunner.Lisp.Analyze](PtcRunner.Lisp.Analyze.md): Validates and desugars RawAST into CoreAST.
  - [PtcRunner.Lisp.Analyze.Conditionals](PtcRunner.Lisp.Analyze.Conditionals.md): Conditional analysis for `if`, `if-not`, `when`, `when-not`, `if-let`,
`when-let`, `if-some`, `when-some`, `when-first`, `cond`, `case`, and `condp` forms.
  - [PtcRunner.Lisp.Analyze.Definitions](PtcRunner.Lisp.Analyze.Definitions.md): Definition analysis for `def`, `defonce`, and `defn` forms.
  - [PtcRunner.Lisp.Analyze.Iteration](PtcRunner.Lisp.Analyze.Iteration.md): Iteration analysis for `doseq` and `for` comprehensions.
  - [PtcRunner.Lisp.Analyze.Patterns](PtcRunner.Lisp.Analyze.Patterns.md): Pattern analysis and destructuring for let bindings and function parameters.
  - [PtcRunner.Lisp.Analyze.Predicates](PtcRunner.Lisp.Analyze.Predicates.md): Predicate analysis for `where` clauses and predicate combinators.
  - [PtcRunner.Lisp.Analyze.ShortFn](PtcRunner.Lisp.Analyze.ShortFn.md): Analyzer for short function syntax (#()).
  - [PtcRunner.Lisp.ClojureValidator](PtcRunner.Lisp.ClojureValidator.md): Validates PTC-Lisp programs against Babashka/Clojure.
  - [PtcRunner.Lisp.CoreToSource](PtcRunner.Lisp.CoreToSource.md): Convert Core AST (the analyzed/desugared representation) back to PTC-Lisp source strings.
  - [PtcRunner.Lisp.DataKeys](PtcRunner.Lisp.DataKeys.md): Static analysis to extract data keys accessed by a PTC-Lisp program.
  - [PtcRunner.Lisp.Env](PtcRunner.Lisp.Env.md): Builds the initial environment with builtins for PTC-Lisp.
  - [PtcRunner.Lisp.Formatter](PtcRunner.Lisp.Formatter.md): Serialize PTC-Lisp AST to source code string.
  - [PtcRunner.Lisp.LanguageSpec](PtcRunner.Lisp.LanguageSpec.md): Language specification compositions for PTC-Lisp.
  - [PtcRunner.Lisp.Parser](PtcRunner.Lisp.Parser.md): NimbleParsec-based parser for PTC-Lisp.
  - [PtcRunner.Lisp.ParserHelpers](PtcRunner.Lisp.ParserHelpers.md): Helper functions for parser reductions
  - [PtcRunner.Lisp.Registry](PtcRunner.Lisp.Registry.md): Single source of truth for PTC-Lisp function metadata.
  - [PtcRunner.Lisp.SpecValidator](PtcRunner.Lisp.SpecValidator.md): Validates PTC-Lisp specification against implementation.
  - [PtcRunner.Lisp.SymbolCounter](PtcRunner.Lisp.SymbolCounter.md): Counts unique user-defined symbols and keywords in a parsed Lisp AST.

- PTC-Lisp — Evaluation
  - [PtcRunner.Lisp.Eval](PtcRunner.Lisp.Eval.md): Evaluates CoreAST into values.
  - [PtcRunner.Lisp.Eval.Apply](PtcRunner.Lisp.Eval.Apply.md): Function application dispatch for Lisp evaluation.
  - [PtcRunner.Lisp.Eval.Context](PtcRunner.Lisp.Eval.Context.md): Evaluation context for the Lisp interpreter.
  - [PtcRunner.Lisp.Eval.Helpers](PtcRunner.Lisp.Eval.Helpers.md): Shared helper functions for Lisp evaluation.
  - [PtcRunner.Lisp.Eval.Patterns](PtcRunner.Lisp.Eval.Patterns.md): Pattern matching for let bindings in Lisp evaluation.
  - [PtcRunner.Lisp.Eval.Where](PtcRunner.Lisp.Eval.Where.md): Where predicates and comparison helpers for Lisp evaluation.
  - [PtcRunner.Lisp.ExecutionError](PtcRunner.Lisp.ExecutionError.md): Exception used to signal execution errors during Lisp evaluation.
  - [PtcRunner.Lisp.Runtime](PtcRunner.Lisp.Runtime.md): Built-in functions for PTC-Lisp.
  - [PtcRunner.Lisp.Runtime.Callable](PtcRunner.Lisp.Runtime.Callable.md): Dispatch helper for calling Lisp functions from Collection operations.
  - [PtcRunner.Lisp.Runtime.Collection](PtcRunner.Lisp.Runtime.Collection.md): Collection operations for PTC-Lisp runtime.
  - [PtcRunner.Lisp.Runtime.Collection.Normalize](PtcRunner.Lisp.Runtime.Collection.Normalize.md): Predicate and collection normalization helpers for collection operations.
  - [PtcRunner.Lisp.Runtime.Collection.Select](PtcRunner.Lisp.Runtime.Collection.Select.md): Selection operations for PTC-Lisp collections: filter, remove, find,
some, every?, not_any?, take_while, drop_while.
  - [PtcRunner.Lisp.Runtime.Collection.Transform](PtcRunner.Lisp.Runtime.Collection.Transform.md): Transformation operations for PTC-Lisp collections: map, mapv, mapcat,
keep, map_indexed, pluck.
  - [PtcRunner.Lisp.Runtime.FlexAccess](PtcRunner.Lisp.Runtime.FlexAccess.md): Flexible key access helpers for PTC-Lisp runtime.
  - [PtcRunner.Lisp.Runtime.Interop](PtcRunner.Lisp.Runtime.Interop.md): Simulated Java interop for PTC-Lisp.

  - [PtcRunner.Lisp.Runtime.MapOps](PtcRunner.Lisp.Runtime.MapOps.md): Map operations for PTC-Lisp runtime.
  - [PtcRunner.Lisp.Runtime.Math](PtcRunner.Lisp.Runtime.Math.md): Arithmetic operations for PTC-Lisp runtime.
  - [PtcRunner.Lisp.Runtime.Predicates](PtcRunner.Lisp.Runtime.Predicates.md): Type predicates, numeric predicates, and logic operations for PTC-Lisp runtime.
  - [PtcRunner.Lisp.Runtime.Regex](PtcRunner.Lisp.Runtime.Regex.md): Minimal, safe Regex support for PTC-Lisp.
Uses Erlang's :re directly with match limits for ReDoS protection.

  - [PtcRunner.Lisp.Runtime.SpecialValues](PtcRunner.Lisp.Runtime.SpecialValues.md): Unified handling for IEEE 754 special values (Infinity, NaN) in PTC-Lisp.

  - [PtcRunner.Lisp.Runtime.String](PtcRunner.Lisp.Runtime.String.md): String manipulation and parsing operations for PTC-Lisp runtime.
  - [PtcRunner.Lisp.TypeError](PtcRunner.Lisp.TypeError.md): Raised by Lisp runtime functions when arguments have the wrong type.

- LLM
  - [PtcRunner.LLM](PtcRunner.LLM.md): Behaviour and convenience API for LLM adapters.
  - [PtcRunner.LLM.DefaultRegistry](PtcRunner.LLM.DefaultRegistry.md): Default model registry with built-in aliases for common LLM providers.
  - [PtcRunner.LLM.Registry](PtcRunner.LLM.Registry.md): Behaviour and unified interface for model resolution.
  - [PtcRunner.LLM.ReqLLMAdapter](PtcRunner.LLM.ReqLLMAdapter.md): Built-in LLM adapter using `req_llm`.

- Observability
  - [PtcRunner.Kino.TraceTree](PtcRunner.Kino.TraceTree.md): Interactive trace tree widget for Livebook.
  - [PtcRunner.Metrics.Statistics](PtcRunner.Metrics.Statistics.md): Statistical comparison functions for benchmark results.
  - [PtcRunner.Metrics.TurnAnalysis](PtcRunner.Metrics.TurnAnalysis.md): Extracts per-turn interaction quality metrics from SubAgent execution results.
  - [PtcRunner.TraceContext](PtcRunner.TraceContext.md): Centralizes process dictionary access for tracing context.
  - [PtcRunner.TraceLog](PtcRunner.TraceLog.md): Captures SubAgent execution events to JSONL files for offline analysis.
  - [PtcRunner.TraceLog.Analyzer](PtcRunner.TraceLog.Analyzer.md): Offline analysis of trace log files.
  - [PtcRunner.TraceLog.Collector](PtcRunner.TraceLog.Collector.md): GenServer that collects trace events and writes them to a JSONL file.
  - [PtcRunner.TraceLog.Event](PtcRunner.TraceLog.Event.md): Builds v2 flat event envelopes for trace logging.
  - [PtcRunner.TraceLog.Handler](PtcRunner.TraceLog.Handler.md): Telemetry handler that captures SubAgent events for trace logging.
  - [PtcRunner.Tracer](PtcRunner.Tracer.md): Immutable trace recorder for SubAgent execution.
  - [PtcRunner.Tracer.Timeline](PtcRunner.Tracer.Timeline.md): Text-based timeline visualization for execution traces.

- Exceptions
  - [PtcRunner.SubAgentError](PtcRunner.SubAgentError.md): Exception raised by `SubAgent.run!/2` and `SubAgent.then!/2` when execution fails.
  - [PtcRunner.ToolExecutionError](PtcRunner.ToolExecutionError.md): Exception raised when a tool execution fails.

## Mix Tasks

- [mix parallel_workers](Mix.Tasks.ParallelWorkers.md): Run the parallel workers (LLM-orchestrated map-reduce) example.
- [mix ptc.clojure_audit](Mix.Tasks.Ptc.ClojureAudit.md): Generates markdown reports comparing PTC-Lisp builtins against Clojure and Java namespaces.
- [mix ptc.gen_docs](Mix.Tasks.Ptc.GenDocs.md): Generates documentation from `priv/functions.exs`
- [mix ptc.install_babashka](Mix.Tasks.Ptc.InstallBabashka.md): Installs Babashka for Clojure validation.
- [mix ptc.repl](Mix.Tasks.Ptc.Repl.md): Starts an interactive REPL for testing PTC-Lisp expressions.
- [mix ptc.smoke](Mix.Tasks.Ptc.Smoke.md): Runs .clj files through both PTC-Lisp and Babashka/Clojure, comparing results.
- [mix ptc.update_spec_checksums](Mix.Tasks.Ptc.UpdateSpecChecksums.md): Regenerates the spec checksums file for drift detection.
- [mix ptc.validate_spec](Mix.Tasks.Ptc.ValidateSpec.md): Validates PTC-Lisp specification against implementation.

