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://www.hardkoded.com/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
| Type | Builder | Answer |
|---|
| Choice | Question.Choice(instructions, criteria) | choice, probabilities, confidence |
| Score | Question.Score(instructions, level0, level1, …) | score, legend, probabilities, confidence |
| Noul | Question.Noul(instructions, criteria?) | noul (P(yes), 0–1) |
| Box | Question.Box(instructions) | box (Top, Bottom, Left, Right), nullable confidence |
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).
| Option | Environment | Default |
|---|
ApiKey | TYPESAFE_API_KEY | required |
BaseUrl | TYPESAFE_BASE_URL | https://api.typesafe.ai |
DefaultModel | TYPESAFE_DEFAULT_MODEL | jev-latest |
LogLevel | TYPESAFE_LOG_LEVEL | warn |
TimeoutMs | — | 10000 per attempt |
Retry | — | 2 retries, 500–5000ms backoff, 25% jitter |
Compression | — | true |
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 / configurationApiException — non-2xx after retries (BadRequestException, AuthenticationException, PermissionDeniedException, NotFoundException, UnprocessableEntityException, RateLimitException, InternalServerException)ApiConnectionException / ApiTimeoutExceptionApiUserAbortException — 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
samples/TypeSafe.AI.Sdk.WallySample finds a character in a busy scene with Question.Box and saves a copy of the scene with a box around him. It takes the paths of your own images, because the sample ships none:
dotnet run --project samples/TypeSafe.AI.Sdk.WallySample -- scene.png character.png found.png
Documentation
Preview the docs site locally with cd docs-site && npm ci && npm run api && npm run dev, then open http://localhost:4321/typesafe-sdk-dotnet/ for the landing page and http://localhost:4321/typesafe-sdk-dotnet/docs/ for the guides.
