PromptForge.Testing 0.2.0

PromptForge

Strongly-typed LLM prompt construction, response parsing, validation, retry, and multi-provider management for .NET 9+

Why PromptForge?

Packages

Quick Start

dotnet add package PromptForge.Core
dotnet add package PromptForge.OpenAI

Program.cs (minimal API or console)

using Microsoft.Extensions.DependencyInjection;
using PromptForge.Core.Abstractions;
using PromptForge.Core.Builder;
using PromptForge.Core.DependencyInjection;
using PromptForge.OpenAI;
using System.ComponentModel.DataAnnotations;

var services = new ServiceCollection();
services.AddLlmKit(options =>
{
    options.UseOpenAI(Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);
    options.Defaults.Temperature(0.2).MaxTokens(512);
});

var sp = services.BuildServiceProvider();
var llm = sp.GetRequiredService<ILlmClient>();

// Build a typed prompt
var prompt = Prompt.For<ReviewRequest>()
    .System("You are a product review analyst. Respond in JSON.")
    .User("Analyze: {{ReviewText}}")
    .Build(new ReviewRequest { ReviewText = "Amazing headphones!" });

// Execute with retry and typed parsing
ReviewAnalysis result = await llm
    .Complete(prompt)
    .ParseAs<ReviewAnalysis>()
    .WithRetry(maxAttempts: 3);

Console.WriteLine($"Sentiment: {result.Sentiment} ({result.Confidence:P0})");

// --- Models ---
record ReviewRequest(string ReviewText);

class ReviewAnalysis
{
    [AllowedValues("positive", "negative", "neutral", "mixed")]
    public string Sentiment { get; set; } = string.Empty;

    [Range(0.0, 1.0)]
    public double Confidence { get; set; }
}

Multi-Turn Conversations

using PromptForge.Core.Conversation;

var conversation = new ConversationSession()
    .WithSystemMessage("You are a helpful assistant.")
    .WithTruncationStrategy(TruncationStrategy.TrimOldest(maxMessages: 20));

while (true)
{
    var userInput = Console.ReadLine()!;
    var reply = await llm.Continue(conversation)
        .WithUserMessage(userInput)
        .AsText();
    Console.WriteLine(reply);
    // conversation.Messages is automatically updated
}

Source Generator

using PromptForge.Core.Attributes;
using System.ComponentModel.DataAnnotations;

[LlmResponse]
public partial class InvoiceData
{
    [Required]
    public string InvoiceNumber { get; set; } = string.Empty;

    [Range(0, 1_000_000)]
    public decimal TotalAmount { get; set; }
}
// Generated: InvoiceData.JsonSchema, InvoiceData.Parse(string), InvoiceData.GetSchemaFragment()

Template validation:

[PromptTemplate]
public partial class ExtractInvoicePrompt : PromptTemplate<InvoiceInput, InvoiceData>
{
    public override string System => "Extract invoice fields from raw OCR text.";
    public override string User => "Invoice text:\n\n{{RawText}}";
    // {{UnknownField}} → compile error PF0001
}

DI Configuration

services.AddLlmKit(options =>
{
    // Primary provider
    options.UseOpenAI(apiKey, model: "gpt-4o");

    // Fallback chain (tries Anthropic if OpenAI fails with 429/503)
    // options.UseProviderChain(chain => chain
    //     .Primary(openAiProvider)
    //     .FallbackTo(anthropicProvider), modelName: "gpt-4o");

    // Named clients for different quality tiers
    options.AddAnthropicClient("quality", anthropicKey, "claude-sonnet-4-6");

    // Middleware pipeline
    options.UseLogging();
    options.UseCaching(o => o.Duration = TimeSpan.FromMinutes(10));

    // Defaults applied to every call
    options.Defaults
        .Temperature(0.2)
        .MaxTokens(1024)
        .MaxRetries(3);

    // Cost tracking
    options.OnUsage((usage, ctx) =>
        metrics.RecordTokens(ctx.ProviderName, usage.TotalTokens));

    // OpenTelemetry
    options.EnableOpenTelemetry();
});

Testing

using PromptForge.Testing;

var fake = new FakeLlmProvider()
    .Returns("{\"sentiment\":\"positive\",\"confidence\":0.9}")
    .ThenThrows(new PromptForgeRateLimitException("fake"));

var services = new ServiceCollection();
services.AddLlmKit(o => o.UseProvider(fake, "fake-model"));
var llm = services.BuildServiceProvider().GetRequiredService<ILlmClient>();

// ... run your logic ...

fake.Verify(calls => calls.Count == 1);

Exception Hierarchy

PromptForgeException
├── PromptForgeParseException       — JSON deserialization failed
├── PromptForgeValidationException  — DataAnnotations validation failed
├── PromptForgeTemplateException    — Unresolved {{Variable}} at runtime
├── PromptForgeProviderException    — HTTP 4xx/5xx from provider
│   └── PromptForgeRateLimitException — HTTP 429
├── PromptForgeTimeoutException     — Request exceeded configured timeout
└── PromptForgeRetryExhaustedException — All attempts exhausted

OperationCanceledException is never caught and always propagates.

License

MIT — see LICENSE