hardkoded/typesafe-sdk-dotnet/typesafe-dotnet

TypeSafe .NET SDK

This skill is for `TypeSafe.AI.Sdk` (dotnet add package TypeSafe.AI.Sdk), a community port of `@typesafe-ai/sdk` by Dario Kondratiuk. It is not an official TypeSafe product.

Live TypeSafe docs remain the source of truth for concepts. This skill covers the .NET client surface.

• Index: https://docs.typesafe.ai/llms.txt
• HTTP API: https://docs.typesafe.ai/api.md
• JS SDK (parity source): https://docs.typesafe.ai/sdk/javascript.md
• Official agent skill (language-agnostic design): https://docs.typesafe.ai/agent-skill.md

When to use which question

• Choice criteria is a map of label → description (null if the label is enough). Not a list.
• Score criteria is an ordered list (index 0, 1, …). Not a map. The API accepts 2–10 levels.
• Noul criteria is optional { true, false } descriptions (NoulCriteria / NoulCriteria.Yes / NoulCriteria.No).
• A Noul of 0.5 means yes and no are equally likely, not “medium intensity”. Use Score for a spectrum.
• Question IDs are for your code only. Put the full meaning in instructions.
• Ask every independent question over the same state in one SystemOneAsync call (speculative fan-out). A second request is only needed when the next state or option set depends on an earlier answer.

Construct state

state can be a string, null, array, or object (Dictionary<string, object?>, anonymous type, JsonNode). Prefer named JSON fields. Point instructions at nested values with backticked paths: ` ticket.messages[0].text `.

using TypeSafe.AI.Sdk;
 
using var client = new TypeSafeClient(); // reads TYPESAFE_API_KEY
var result = await client.SystemOneAsync(
    new
    {
        ticket = new { subject = "Duplicate charge", body = "Charged twice. Refund ASAP." },
        policy = "Duplicate charges are refundable.",
    },
    Question.Map(
        ("refund", Question.Noul("Does `ticket.body` request a refund?")),
        ("team", Question.Choice("Which team should handle `ticket`?",
            ("billing", "Payments, invoicing, refunds"),
            ("technical", "Bugs and outages"),
            ("other", null))),
        ("urgency", Question.Score("How urgent is `ticket`?", "can wait", "this week", "today"))),
    cancellationToken: cancellationToken);
 
var refund = result.GetNoul("refund").Noul;
var team = result.GetChoice("team");
var urgency = result.GetScore("urgency");

instructions and criteria values may be strings, objects, arrays, or null (structured questions). See https://docs.typesafe.ai/primitives/advanced.md.

Client, env, retries

Environment (empty/whitespace ignored; constructor wins):

Retry defaults match JS: MaxRetries = 2, BackoffInitialMs = 500, BackoffMaxMs = 5000, BackoffJitter = 0.25, statuses 408/429/5xx, honor Retry-After up to 60s, retry connection errors and timeouts. Timeout is per attempt (default 10s), not a total budget.

services.AddTypeSafeClient(o => o.TimeoutMs = 20_000);
// ITypeSafeClient from DI; named HttpClient: TypeSafeClient.HttpClientName

Every public async method takes CancellationToken. Cancel → ApiUserAbortException (not retried).

Errors

Do not invent request/response fields. Usage is input_tokens / output_tokens (Usage.InputTokens / OutputTokens, both int? and null when the API reports no count). Models: client.Models.ListAsync().

Agent habits

1. Read https://docs.typesafe.ai/llms.txt and the relevant primitive page before writing questions.
2. Keep questions and thresholds in one file for human review.
3. Use probabilities when you have a statistical rule; use confidence as a second axis for Choice/Score, not as a substitute for Noul.
4. Validate on the user’s data. Cookbook numbers are examples, not defaults.
5. Keep API keys server-side. Never commit TYPESAFE_API_KEY.