Pmad.AI
0.0.3
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
<PackageReference Include="Pmad.AI" Version="0.0.3" />
<PackageVersion Include="Pmad.AI" Version="0.0.3" />
<PackageReference Include="Pmad.AI" />
paket add Pmad.AI --version 0.0.3
#r "nuget: Pmad.AI, 0.0.3"
#:package Pmad.AI@0.0.3
#addin nuget:?package=Pmad.AI&version=0.0.3
#tool nuget:?package=Pmad.AI&version=0.0.3
Pmad.AI
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 structuredFunctionCallContent. - 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)onChatClientBuilder. - 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 manualDetectStreamingRepetition) 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)andSerializeArguments) with recursive, reflection-free JSON canonicalization.
- Seamless pipeline middleware integration via
Shell Security Validation (
ReadOnlyCommandValidator):- Multi-dialect shell security validator supporting
BashandPowerShell. - 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.
- Multi-dialect shell security validator supporting
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
FlushAfterEachTurnto 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), andRedactor.
- Emits full verbatim multi-turn conversation sessions formatted strictly as single-line JSONL adhering to the OpenAI chat completions & fine-tuning schema (
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) exceedingFallbackCharacterLimit(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
MutateInPlaceflag:false(default) preserves caller history via shallow copies;truemodifies lists in-place with zero allocations. - Integrates with
ISpeculativeSummarizerfor background precomputed summaries.
- Unified compaction architecture sharing
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
JsonSchemavalidation against registeredAIFunctioninstances. - Parameter injection protection against leading hyphen (
-) option injection and shell metacharacters. - Middleware integration via
builder.UseLenientToolDispatch().
- Canonical tool alias resolution, case-insensitive parameter remapping, and virtual-to-shell command translation templates (
Roslyn Incremental Source Generators & Analyzers (
Pmad.AI.SourceGenerators):- Roslyn analyzer emitting compile-time diagnostics:
PMAD001(invalid parameter alias),PMAD002(duplicate tool alias), andPMAD003(unnamed lambda tool alias). - Incremental generator automatically synthesizing
GeneratedToolMappings.Create()from[ToolAlias],[ToolParameterAlias], and[ToolTranslation]attributes.
- Roslyn analyzer emitting compile-time diagnostics:
Zero-Allocation Heuristic Token Estimator (
HeuristicTokenEstimator):- Fast blended token approximations operating over
ReadOnlySpan<char>with zero heap allocation.
- Fast blended token approximations operating over
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:
Recommended SLM Pipeline (for Small Language Models $\le 8\text{B}$)
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).
Recommended Local LLM Pipeline (for Capable Local Models $\ge 14\text{B}$)
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.AIandMicrosoft.Extensions.Logging.Abstractions.
License
This project is licensed under the MIT License.
| Product | Versions 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. |
-
net10.0
- Microsoft.Extensions.AI (>= 10.9.0)
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.11)
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.