TypeSafe.AI.Sdk 0.7.0

TypeSafe.AI.Sdk

Community .NET client for TypeSafe AI — a port of @typesafe-ai/sdk by Dario Kondratiuk.

This is not an official TypeSafe product and is not endorsed by TypeSafe. Behavior is aligned with the JavaScript SDK and the TypeSafe docs.

Package id: TypeSafe.AI.Sdk
Docs site: https://hardkoded.github.io/typesafe-sdk-dotnet/

Install

dotnet add package TypeSafe.AI.Sdk

Targets net10.0 (latest LTS) and netstandard2.0. Requires the .NET 10 SDK to build (global.json).

Quickstart

Set TYPESAFE_API_KEY in your environment, then:

using TypeSafe.AI.Sdk;

using var client = new TypeSafeClient();
var response = await client.SystemOneAsync(
    new { document = "I was charged twice. Please fix this ASAP." },
    ("category", Question.Choice("What is this ticket about?",
        ("billing", null),
        ("technical", null),
        ("other", null))));

Console.WriteLine(response.GetChoice("category").Choice);

That mirrors the JavaScript quickstart. You can also pass apiKey to the constructor.

Questions

Batch independent questions in one SystemOneAsync call. See primitives.

Images

Image support is experimental. Opt in by sending the TypeSafe-Danger-Zone-Images: true header (DefaultHeaders on the client, or RequestOptions.Headers for one call). Images must be PNG or JPEG. Create one with new Image(bytes), Image.FromFile(path), or Image.FromBase64(text), then use it in any of three ways:

var photo = Image.FromFile("returns/RMA-1042.jpg");
var catalog = Image.FromFile("catalog/mug.png");

// 1. Place it in the state, question instructions, or criteria.
await client.SystemOneAsync(
    new { claim = "The mug arrived with a chipped rim.", photo },
    ("damaged", Question.Noul("Is the product in the photo damaged?")));

// 2. Write it into text with TextWithAssets.From (and TextWithAssets.Join for lists).
await client.SystemOneAsync(
    TextWithAssets.From($"The customer sent {photo}. The catalog photo is {catalog}."),
    ("same", Question.Noul(TextWithAssets.From($"Does {photo} show {catalog}?"))));

// 3. Choose your own references with SystemOneRequest.Assets.
await client.SystemOneAsync(new SystemOneRequest
{
    State = "The customer sent <photo>.",
    Questions = Question.Map(("damaged", Question.Noul("Is <photo> damaged?"))),
    Assets = new Dictionary<string, Image> { ["<photo>"] = photo },
});

To locate something in an image, ask a Question.Box question with the jev-preview model. The answer's Box holds Top/Bottom (fractions of height) and Left/Right (fractions of width), and Confidence is null when the API reports none:

var response = await client.SystemOneAsync(new SystemOneRequest
{
    State = photo,
    Questions = Question.Map(("damage", Question.Box("The damaged area of the product"))),
    Model = "jev-preview",
});
var box = response.GetBox("damage").Box;

Requests with images are sent as multipart/form-data. An image in a plain interpolated string, or a name in Assets that the request never uses, throws a TypeSafeException before sending. See Images.

Configuration

Explicit options win, then environment variables, then SDK defaults (same as JS).

Retryable HTTP statuses: 408, 429, 500–599. Connection errors and timeouts retry by default. Retry-After / retry-after-ms are honored up to 60s.

Request bodies of 1 KiB or more are compressed with zstd and sent with Content-Encoding: zstd. Smaller bodies fit in one TCP segment, so they are sent as-is. Set Compression = false to send every body uncompressed, for example to an API that doesn't accept compressed requests.

using var client = new TypeSafeClient(new TypeSafeClientOptions
{
    ApiKey = "tsk_...",
    TimeoutMs = 20_000,
    Retry = new RetryPolicy { MaxRetries = 4 },
});

Dependency injection

services.AddTypeSafeClient(options =>
{
    options.ApiKey = builder.Configuration["TYPESAFE_API_KEY"];
});

public sealed class Tickets(ITypeSafeClient typesafe) { /* ... */ }

Uses IHttpClientFactory and the named client TypeSafe.AI.

Errors

Exceptions mirror the JS hierarchy (TypeSafeError → TypeSafeException, and so on):

• TypeSafeException — validation / configuration
• ApiException — non-2xx after retries (BadRequestException, AuthenticationException, PermissionDeniedException, NotFoundException, UnprocessableEntityException, RateLimitException, InternalServerException)
• ApiConnectionException / ApiTimeoutException
• ApiUserAbortException — cancelled CancellationToken

Pack

Versioning is MinVer from git tags prefixed with v:

git tag v0.7.0
dotnet pack src/TypeSafe.AI.Sdk/TypeSafe.AI.Sdk.csproj -c Release -o artifacts

Without a tag, packs are 0.7.0-preview.0 (or a later preview derived from height).

Tests

dotnet test

Unit tests mock HTTP and do not need a key. Live tests in tests/TypeSafe.AI.Sdk.IntegrationTests skip unless TYPESAFE_API_KEY is set.

Sample

export TYPESAFE_API_KEY=tsk_...
dotnet run --project samples/TypeSafe.AI.Sdk.Sample

Documentation

• TypeSafe concepts and HTTP API: https://docs.typesafe.ai/sdk · https://docs.typesafe.ai/api.md
• JavaScript SDK (parity source): https://github.com/typesafe-ai/typesafe-sdk-js
• This port: docs site (DocFX) · CONTRIBUTING.md · agent skill

Build the docs site locally with dotnet tool update -g docfx && docfx docs/docfx.json --serve.