# PtcRunner v0.7.0 - 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)
  - [JSON Mode SubAgents](subagent-json-mode.md)
  - [Core Concepts](subagent-concepts.md)
  - [Composition Patterns](subagent-patterns.md)
  - [Navigator Pattern: Journaled Tasks](subagent-navigator.md)
  - [Meta Planner: Autonomous Planning and Self-Correction](subagent-meta-planner.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)

- Reference
  - [Signature Syntax](signature-syntax.md)
  - [Benchmark Evaluation](benchmark-eval.md)
  - [PTC-Lisp Language Specification](ptc-lisp-specification.md)

- Livebooks
  - [PTC-Lisp Playground](ptc_runner_playground.md)
  - [SubAgent Examples](ptc_runner_llm_agent.md)
  - [Meta Planner: Autonomous Planning](meta_planner.md)
  - [Joke Workflow: LangGraph vs PTC-Lisp](joke_workflow.md)
  - [Observability & Tracing](observability_and_tracing.md)

## Modules

- [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.Kino.TraceTree](PtcRunner.Kino.TraceTree.md): Interactive trace tree widget for Livebook.
- [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.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.CoreAST](PtcRunner.Lisp.CoreAST.md): Core, validated AST for PTC-Lisp.
- [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.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.Format](PtcRunner.Lisp.Format.md): Format PTC-Lisp values for human/LLM display.
- [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.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.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.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.
- [PtcRunner.MetaPlanner](PtcRunner.MetaPlanner.md): Generate and repair execution plans for multi-agent workflows.
- [PtcRunner.Mustache](PtcRunner.Mustache.md): Standalone Mustache template parser and expander.
- [PtcRunner.Plan](PtcRunner.Plan.md): Parsed execution plan for multi-agent workflows.
- [PtcRunner.PlanCritic](PtcRunner.PlanCritic.md): Adversarial review of execution plans before they run.
- [PtcRunner.PlanExecutor](PtcRunner.PlanExecutor.md): Execute plans with automatic replanning support.
- [PtcRunner.PlanRunner](PtcRunner.PlanRunner.md): Execute parsed plans with SubAgents.
- [PtcRunner.PlanTracer](PtcRunner.PlanTracer.md): Real-time terminal visualization for PlanExecutor events.
- [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.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.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.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.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](PtcRunner.SubAgent.Loop.md): Core agentic loop that manages LLM↔tool cycles.
- [PtcRunner.SubAgent.Loop.JsonMode](PtcRunner.SubAgent.Loop.JsonMode.md): Execution loop for JSON output mode.
- [PtcRunner.SubAgent.Loop.LLMRetry](PtcRunner.SubAgent.Loop.LLMRetry.md): LLM retry logic with configurable backoff strategies.
- [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.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.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.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.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.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.TypeExtractor](PtcRunner.SubAgent.TypeExtractor.md): Extract signature and description from Elixir function @spec and @doc.
- [PtcRunner.SubAgent.Validator](PtcRunner.SubAgent.Validator.md): Validates SubAgent options at construction time.
- [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.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): Handles safe JSON encoding for telemetry events.
- [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.
- [PtcRunner.Turn](PtcRunner.Turn.md): Captures a single LLM interaction cycle in a SubAgent execution.

- Exceptions
  - [PtcRunner.Lisp.ExecutionError](PtcRunner.Lisp.ExecutionError.md): Exception used to signal execution errors during Lisp evaluation.
  - [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.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.