Pmad.AI 0.0.3

There is a newer version of this package available.
See the version list below for details.
dotnet add package Pmad.AI --version 0.0.3
                    
NuGet\Install-Package Pmad.AI -Version 0.0.3
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Pmad.AI" Version="0.0.3" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Pmad.AI" Version="0.0.3" />
                    
Directory.Packages.props
<PackageReference Include="Pmad.AI" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Pmad.AI --version 0.0.3
                    
#r "nuget: Pmad.AI, 0.0.3"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Pmad.AI@0.0.3
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Pmad.AI&version=0.0.3
                    
Install as a Cake Addin
#tool nuget:?package=Pmad.AI&version=0.0.3
                    
Install as a Cake Tool

Pmad.AI

NuGet License: MIT

Pmad.AI provides battle-tested, Native AOT-ready AI utilities, resilient tool-calling infrastructure, conversation history compactors, and protocol transformers for .NET applications, AI agents, and proxies.

Targeting .NET 10.0 with <IsAotCompatible>true</IsAotCompatible>, Pmad.AI contains zero heavy runtime dependencies, zero runtime reflection, and strict trim safety.

WARNING: This is an early release, API or behavior may change before 1.0.0.


Features

  • Resilient Tool Call Healing (ToolCallHealingChatClient & ToolCallHealingTransform):

    • Transparently repairs malformed function calls generated by open-weights models (Qwen, DeepSeek, Mistral, Hermes).
    • Promotes pseudo-tags in text (<tool_call>{...}</tool_call> or <function_call>{...}</function_call>) into structured FunctionCallContent.
    • Strips markdown code fences (json ... ) inside argument payloads.
    • Repairs trailing commas in JSON argument payloads ({"arg": "val",}).
    • Repairs unescaped control characters (literal newlines \n, carriage returns \r, tabs \t) inside JSON string parameters.
    • Supports configurable StreamingHealingMode:
      • PrefixTriggered (default): zero-latency streaming for prose; buffers only when tag prefixes (<tool_call>, <function_call>, Action:) are encountered.
      • FullBuffer: buffers the entire streaming response before emission.
      • Disabled: passes streaming tokens through untouched.
  • Tool Loop Circuit Breaker (ToolLoopCircuitBreaker & ToolLoopCircuitBreakerChatClient):

    • Seamless pipeline middleware integration via .UseToolLoopCircuitBreaker(breaker) on ChatClientBuilder.
    • Non-streaming protection: intercepts tool calls in GetResponseAsync, tracks invocations on unchanged state, and replaces infinite ping-pong loops with diagnostic circuit-breaker messages ([Circuit Breaker Tripped] ...).
    • Streaming protection: $N$-gram streaming repetition scanner in GetStreamingResponseAsync (and manual DetectStreamingRepetition) to halt degenerate runaway loops ($\le 48$ characters before trip), gracefully terminating the stream with a diagnostic stop reason.
    • Multi-tool alternating cycle detection (detects $A \to B \to A \to B$ ping-pong patterns across tool history).
    • Native AOT trim-safe argument serialization (EvaluateToolInvocation(name, dictionary) and SerializeArguments) with recursive, reflection-free JSON canonicalization.
  • Shell Security Validation (ReadOnlyCommandValidator):

    • Multi-dialect shell security validator supporting Bash and PowerShell.
    • Enforces default-deny binary/cmdlet allowlists.
    • Blocks subshells ($(), backticks, <()), redirection operators (>, >>, <, <<), environment variable / brace expansions, and dangerous flags (find -exec/-delete, rg --pre, sed -i, git commit/push/clean).
    • Validation throughput exceeding 900,000 ops/sec.
  • Verbatim Transcript Logging (VerbatimTranscriptChatClient):

    • Produces complete, audit-grade Markdown transcripts of multi-turn agent sessions.
    • Generates YAML frontmatter, collapsible system instructions / tool definitions, turn badges, token consumption summaries, and elapsed turn latencies.
    • Coalesces streaming chunks in real time.
    • Optional FlushAfterEachTurn to protect against process crashes.
  • OpenAI JSONL Verbatim Transcripts (OpenAiJsonlTranscriptChatClient):

    • Emits full verbatim multi-turn conversation sessions formatted strictly as single-line JSONL adhering to the OpenAI chat completions & fine-tuning schema ({"messages": [{"role": "user", ...}, {"role": "assistant", "content": null, "tool_calls": [...]}, {"role": "tool", "tool_call_id": "...", "name": "...", "content": "..."}]}).
    • Uses write-ahead temp-file staging (TempFilePath): on each turn, input messages are streamed and flushed to disk before invoking the inner client, enabling instant crash forensics if an unhandled runtime failure occurs.
    • Flushes the complete conversation as a single atomic JSON line upon conversation completion or disposal (DisposeAsync / Dispose), ensuring concurrency-safe dataset building without line interleaving or partial/corrupted lines, and cleans up the staging file (DeleteTempFileOnSuccess).
    • Flat $O(1)$ memory consumption: zero in-memory message caching, handling massive payloads with Native AOT trim-safety.
    • Supports configurable ReasoningMode (None, ReasoningContent, ThinkTags), tool schema definitions (IncludeTools), and Redactor.
  • Conversation History Compaction (ThinkingTraceCompactor & ToolResultCompactor):

    • Unified compaction architecture sharing ICompactionOptions: deterministic threshold (FallbackCharacterLimit), prefix preservation (FallbackPrefixLength), suffix preservation (FallbackSuffixLength), and optional background speculative summarizer (ISpeculativeSummarizer).
    • ThinkingTraceCompactor & ThinkingTraceCompactionChatClient: collapses verbose reasoning traces (TextReasoningContent) outside the active turn window (KeepVerbatimCount) exceeding FallbackCharacterLimit (default: 1,750), replacing them with precomputed summaries or deterministic prefix-suffix truncated monologues while preserving short traces verbatim to maximize KV-cache reuse.
    • ToolResultCompactor & ToolResultCompactionChatClient: prunes bulky tool outputs (compiler logs, test runs, file reads) outside the active window using configurable prefix/suffix retention.
    • Configurable MutateInPlace flag: false (default) preserves caller history via shallow copies; true modifies lists in-place with zero allocations.
    • Integrates with ISpeculativeSummarizer for background precomputed summaries.
  • Declarative Tool Dispatching (LenientToolDispatcher):

    • Canonical tool alias resolution, case-insensitive parameter remapping, and virtual-to-shell command translation templates ({name} and {name:default}).
    • Startup two-way JsonSchema validation against registered AIFunction instances.
    • Parameter injection protection against leading hyphen (-) option injection and shell metacharacters.
    • Middleware integration via builder.UseLenientToolDispatch().
  • Roslyn Incremental Source Generators & Analyzers (Pmad.AI.SourceGenerators):

    • Roslyn analyzer emitting compile-time diagnostics: PMAD001 (invalid parameter alias), PMAD002 (duplicate tool alias), and PMAD003 (unnamed lambda tool alias).
    • Incremental generator automatically synthesizing GeneratedToolMappings.Create() from [ToolAlias], [ToolParameterAlias], and [ToolTranslation] attributes.
  • Zero-Allocation Heuristic Token Estimator (HeuristicTokenEstimator):

    • Fast blended token approximations operating over ReadOnlySpan<char> with zero heap allocation.

Installation

dotnet add package Pmad.AI

Namespaces

Pmad.AI is organized into focused, capability-based namespaces. Following standard .NET conventions, pipeline middleware extensions (.Use*()) reside in the root Pmad.AI namespace for immediate discovery:

Namespace Responsibility Primary Types
Pmad.AI Root pipeline registration & middleware extensions UseToolCallHealing, UseToolLoopCircuitBreaker, UseThinkingTraceCompaction, UseToolResultCompaction, UseLenientToolDispatch, UseVerbatimTranscript
Pmad.AI.Tools Tool dispatching, aliasing, translations, and attributes LenientToolDispatcher, ToolMapping, ToolTranslation, [ToolAlias], [ToolParameterAlias], [ToolTranslation]
Pmad.AI.Healing Payload healing and protocol repair for local/open-weights models ToolCallHealingTransform, ToolCallHealingChatClient, StreamingHealingMode
Pmad.AI.Guardrails Execution loop breaker and shell security validation ToolLoopCircuitBreaker, ToolLoopCircuitBreakerChatClient, ReadOnlyCommandValidator, CommandValidationRule, ShellDialect
Pmad.AI.Compaction Context window history compaction and speculative summarization ICompactionOptions, ToolResultCompactor, ThinkingTraceCompactor, ThinkingTraceCompactionChatClient, ISpeculativeSummarizer, OllamaSpeculativeSummarizer, OllamaApiClient
Pmad.AI.Transcripts Audit-grade Markdown transcript logging VerbatimTranscriptChatClient, VerbatimTranscriptOptions
Pmad.AI.Tokens Fast zero-allocation token estimation HeuristicTokenEstimator

Usage Examples

1. Battle-Tested Pipeline Presets: SLM vs. Local LLM

Pmad.AI exposes first-class pipeline presets configured specifically for model weight tiers:

Empirically proven on benchmarks to deliver maximum task success, token savings (-33.8%), and execution speed. Combines deterministic thinking trace compaction and tool result compaction without speculative natural-language SLM interference:

using Microsoft.Extensions.AI;
using Pmad.AI;

// innerChatClient can be LlamaSharpChatClient, OllamaChatClient, or any IChatClient
var client = new ChatClientBuilder(innerChatClient)
    .UseRecommendedSlmPipeline(dispatcher)
    .Build();

Pipeline order: Lenient Tool Dispatch $\to$ Circuit Breaker ($\text{PingPongThreshold} = 3$) $\to$ Deterministic Thinking Trace Compaction ($\text{Verbatim} = 5$, no SLM summarizer) $\to$ Deterministic Tool Result Compaction ($\text{Verbatim} = 5$) $\to$ Tool Call Healing (innermost).

Enables full optimizations including thinking trace compaction and optional background speculative summarization:

using Microsoft.Extensions.AI;
using Pmad.AI;

// Pure deterministic compaction:
var client = new ChatClientBuilder(innerChatClient)
    .UseRecommendedLocalLlmPipeline(dispatcher)
    .Build();

// Or with an asynchronous background speculative summarizer:
var clientWithSlm = new ChatClientBuilder(innerChatClient)
    .UseRecommendedLocalLlmPipeline(dispatcher, summarizer: ollamaSummarizer)
    .Build();

2. Custom Agent Pipeline Assembly

Combine healing, history compaction, transcript recording, and lenient tool dispatch into a single custom pipeline:

using Microsoft.Extensions.AI;
using Pmad.AI;
using Pmad.AI.Healing;

var client = new ChatClientBuilder(innerChatClient)
    // 1. Audit transcript logging
    .UseVerbatimTranscript(options =>
    {
        options.OutputDirectory = "docs/transcripts";
        options.SessionTitle = "Feature Implementation Agent";
        options.FlushAfterEachTurn = true;
    })
    // 2. Loop circuit breaker (halts runaway token loops and tool ping-pong)
    .UseToolLoopCircuitBreaker()
    // 3. Reasoning trace compaction (keeps last 5 turns verbatim)
    .UseThinkingTraceCompaction(options =>
    {
        options.KeepVerbatimCount = 5;
        options.FallbackCharacterLimit = 1750;
        options.MutateInPlace = false;
    })
    // 4. Bulky tool result compaction (keeps last 10 turns verbatim)
    .UseToolResultCompaction(options =>
    {
        options.KeepVerbatimCount = 10;
        options.FallbackCharacterLimit = 1750;
        options.FallbackPrefixLength = 1500;
        options.FallbackSuffixLength = 250;
        options.MutateInPlace = false;
    })
    // 5. Lenient tool dispatching (alias resolution & parameter coercion)
    .UseLenientToolDispatch(dispatcher)
    // 6. Automatic healing of malformed tool calls & pseudo-tags
    .UseToolCallHealing(options =>
    {
        options.StreamingMode = StreamingHealingMode.PrefixTriggered;
    })
    .Build();

2. Declarative Tool Dispatching (LenientToolDispatcher)

Declare tools, aliases, and translations declaratively:

using Microsoft.Extensions.AI;
using Pmad.AI.Tools;

// 1. Register canonical tools
var readFileTool = AIFunctionFactory.Create(
    (string path) => File.ReadAllText(path),
    "read_file",
    "Reads content from a file");

// 2. Ingest mappings (can also be generated via [ToolAlias] source generator)
var dispatcher = new LenientToolDispatcher(new ToolDispatcherConfiguration
{
    Tools = new Dictionary<string, ToolMapping>
    {
        ["read_file"] = new ToolMapping
        {
            Aliases = ["read", "get_file", "cat"],
            ParameterAliases = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                ["file_path"] = "path",
                ["filePath"] = "path",
                ["target"] = "path"
            }
        }
    }
});
dispatcher.RegisterTools([readFileTool]);

// 3. Enforce startup validation (ensures zero typos or schema drift)
dispatcher.Validate(throwOnError: true);

// 4. Dispatches aliased calls transparently
var result = await dispatcher.ExecuteAsync("get_file", new Dictionary<string, object?>
{
    ["file_path"] = "src/Program.cs"
});

3. Tool Loop Circuit Breaker (ToolLoopCircuitBreaker & UseToolLoopCircuitBreaker)

Detect and halt degenerate token loops during streaming and infinite tool invocation ping-pong:

Pipeline Middleware (UseToolLoopCircuitBreaker)

Register ToolLoopCircuitBreakerChatClient middleware directly with ChatClientBuilder:

using Microsoft.Extensions.AI;
using Pmad.AI;
using Pmad.AI.Guardrails;

var client = new ChatClientBuilder(innerChatClient)
    // Intercepts repetitive tool calls and streaming loops automatically
    .UseToolLoopCircuitBreaker(new ToolLoopCircuitBreaker(new ToolLoopCircuitBreakerOptions
    {
        PingPongThreshold = 2,
        NgramMinLength = 16,
        NgramMinOccurrences = 3
    }))
    .Build();

// 1. Non-streaming (GetResponseAsync):
// If the model invokes identical tools/arguments on unchanged state consecutively,
// the call is intercepted and replaced with a diagnostic circuit-breaker message:
// "[Circuit Breaker Tripped] Duplicate tool invocation detected: 'read_file'..."

// 2. Streaming (GetStreamingResponseAsync):
// If repeating token n-grams are detected, the stream emits a diagnostic stop update
// with FinishReason = ChatFinishReason.Stop and aborts early, saving GPU/CPU cycles.
Standalone & Programmatic Evaluation

ToolLoopCircuitBreaker can also be evaluated directly for custom agent loops:

using Pmad.AI.Guardrails;

var breaker = new ToolLoopCircuitBreaker(new ToolLoopCircuitBreakerOptions
{
    CanonicalizeJsonArguments = true,
    PingPongThreshold = 2,
    NgramMinLength = 16,
    NgramMinOccurrences = 3
});

// 1. Tool invocation evaluation (supports dictionaries or raw JSON strings)
var args = new Dictionary<string, object?> { ["path"] = "src/App.cs" };
var invocationCheck = breaker.EvaluateToolInvocation("read_file", args, stateSignature: "git_rev_123");
if (invocationCheck.IsLoopDetected)
{
    // Tripped: inject corrective instruction instead of spinning
    Console.WriteLine($"Loop tripped: {invocationCheck.DiagnosticMessage}");
}

// 2. Streaming repetition inspection over ReadOnlySpan<char>
var streamCheck = breaker.DetectStreamingRepetition(accumulatedOutputSpan);
if (streamCheck.IsLoopDetected)
{
    // Abort streaming generation early
    cancellationSource.Cancel();
}

4. Shell Security Validation (ReadOnlyCommandValidator)

Enforce default-deny security policies on shell execution tools:

using System.Text.RegularExpressions;
using Pmad.AI.Guardrails;

var validator = new ReadOnlyCommandValidator(new ReadOnlyCommandValidatorOptions
{
    Dialect = ShellDialect.Bash,
    BlockSubshells = true,
    BlockRedirection = true,
    AllowedBinaries = ["find", "rg", "grep", "cat", "ls", "git", "head", "tail", "wc", "cd", "csnav", "mdfetch"],
    CommandRules =
    {
        ["csnav"] = new CommandValidationRule
        {
            AllowedSubcommands = ["references", "definition", "implementations", "explore", "decompile", "server"],
            FlagsWithArgs = ["-s", "--solution", "--format"],
            NestedSubcommands =
            {
                ["server"] = new CommandValidationRule
                {
                    AllowedSubcommands = ["status", "start", "reload"]
                }
            }
        },
        ["mdfetch"] = new CommandValidationRule
        {
            ArgumentsRegex = new Regex(@"^https?://\S+$", RegexOptions.IgnoreCase)
        }
    }
});

// Safe commands: Allowed
var res1 = validator.ValidateCommand("git status --short");
Console.WriteLine(res1.IsAllowed); // True

// Mutating / dangerous commands: Blocked
var res2 = validator.ValidateCommand("git commit -m 'unauthorized'");
Console.WriteLine(res2.IsAllowed); // False (Reason: Git subcommand 'commit' disallowed)

var res3 = validator.ValidateCommand("cat file.txt > /etc/shadow");
Console.WriteLine(res3.IsAllowed); // False (Reason: Redirection operator '>' disallowed)

var res4 = validator.ValidateCommand("echo $(whoami)");
Console.WriteLine(res4.IsAllowed); // False (Reason: Subshell operator '$(' disallowed)

5. Declarative Attributes & Roslyn Generator

Use attributes on tools to automatically generate dispatch mappings at compile-time:

using Microsoft.Extensions.AI;
using Pmad.AI.Tools;

public static class AgentTools
{
    [ToolAlias("search", "query_db")]
    [ToolParameterAlias("query", "q", "pattern")]
    [ToolParameterAlias("maxResults", "limit", "count")]
    public static string SearchDatabase(string query, int maxResults = 10)
    {
        return $"Results for {query} (up to {maxResults})";
    }
}

The source generator emits GeneratedToolMappings.Create(), which can be passed directly to the dispatcher constructor: new LenientToolDispatcher(GeneratedToolMappings.Create()).


6. Zero-Allocation Token Estimation & Model Presets

Estimate tokens instantly over ReadOnlySpan<char> without loading vocabulary tables into memory:

using Pmad.AI.Tokens;

// General-purpose balanced default
int tokens = HeuristicTokenEstimator.Default.Estimate("Hello world".AsSpan());

// Fine-tuned presets for specific tokenizer families
int qwenTokens = HeuristicTokenEstimator.Qwen.Estimate(prompt.AsSpan());
int gemmaTokens = HeuristicTokenEstimator.Gemma.Estimate(prompt.AsSpan());

// Extract the 4 primitive structural metrics for profiling/diagnostics
TokenMetrics metrics = HeuristicTokenEstimator.Analyze(prompt.AsSpan());
Console.WriteLine($"Words: {metrics.Words}, Symbols: {metrics.Symbols}, Non-ASCII: {metrics.NonAscii}, Chars: {metrics.CharCount}");
int estFromMetrics = HeuristicTokenEstimator.Qwen.Estimate(in metrics);

Target Frameworks & AOT Compatibility

  • Target Framework: .NET 10.0
  • Trimmable and Native AOT compatible (<IsAotCompatible>true</IsAotCompatible>).
  • Dependencies: Only Microsoft.Extensions.AI and Microsoft.Extensions.Logging.Abstractions.

License

This project is licensed under the MIT License.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Pmad.AI:

Package Downloads
Pmad.AI.LlamaSharp

Microsoft.Extensions.AI adapter for local LLamaSharp (llama.cpp) inference, supporting streaming, multimodal vision, tool calling, and open-weights chat formatting.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.0.4 102 11/6/2026
0.0.3 103 11/4/2026
0.0.2 101 11/3/2026
0.0.1 165 10/21/2026