Jev.Net 0.4.0

Jev.Net

A lightweight .NET client for the TypeSafe AI API — System One / Jev. Ask small typed questions about text or structured state and get calibrated probabilities back that your code can act on.

A community package. Not affiliated with or endorsed by TypeSafe AI.

dotnet add package Jev.Net

Why this one

One dependency. Microsoft.Extensions.Logging.Abstractions, and nothing else. Retries, backoff, Retry-After and per-attempt timeouts are about a hundred lines of its own, so it drops into a library, a CLI, a desktop app or a worker without changing what your dependency graph looks like. That promise is enforced: CI reads the packed .nuspec and fails on a second dependency. Targets net8.0 and net10.0, and is trim- and Native AOT-compatible — a smoke app is published as a native binary and run on every build.

The Python SDK, in C#. It is a faithful port of the official typesafe-sdk (read at 0.7.0): the same request shape, the same protected headers, the same exception hierarchy and the same message text, the same retry rules, the same dotted field paths when a response is malformed. Its test suite is a mirror of upstream's, file by file — so behaviour you read about in TypeSafe's docs, or debugged once in Python, is the behaviour you get here. Where .NET forces a difference, it is listed at the bottom.

Looking for something else?

TypeSafeAI.Net by Hawxy is an excellent community SDK with a different focus, and it got here first: dependency-injection and IHttpClientFactory integration, enum-typed choices, a QuestionSet builder with typed handles, Native AOT support, and a companion package of Microsoft.Extensions.AI middleware (guardrails, routing, evaluators). If that is the shape of your app, use it — the two projects make different trade-offs on purpose, and both speak the same API.

Quick start

await using var client = new TypeSafeClient();            // key from TYPESAFE_API_KEY

var result = await client.SystemOneAsync(
    "I was charged twice. Please help.",
    new Dictionary<string, Question>
    {
        ["billing"] = new Noul("Is this about billing?"),
        ["tone"]    = new Choice(["calm", "frustrated", "angry"], "What is the customer's tone?"),
        ["urgency"] = new Score(["can wait", "this week", "today"], "How urgent is this ticket?"),
    });

double billing = result.Nouls["billing"].Noul;            // probability of YES — 0.5 is "unsure", not "medium"
string tone    = result.Choices["tone"].Choice;
double urgency = result.Scores["urgency"].Score;          // may fall between rubric levels

Questions are independent and answered in one round trip, so ask everything about a state together.

Typed answers by name

Derive from SystemOneResponse and declare answer-typed properties; each is filled from the answer of the same name ([JsonPropertyName], else the property name — exact, case-insensitive, then snake_case). Every such property is required — a missing answer, or one of the wrong kind, is a TypeSafeApiResponseValidationException naming the field — unless you mark it [OptionalAnswer].

sealed class Ticket : SystemOneResponse
{
    public NoulAnswer Billing { get; set; } = null!;
    public ChoiceAnswer Tone { get; set; } = null!;
    [OptionalAnswer] public ScoreAnswer? Urgency { get; set; }
}

var ticket = await client.SystemOneAsync<Ticket>(state, questions);

To read the body into a type that is entirely yours, pass JSON metadata — source-generated for trimmed and AOT apps, or reflection-based when that doesn't matter:

var viaSourceGen  = await client.SystemOneAsync(state, questions, options: null, MyJsonContext.Default.MyEnvelope); // AOT-safe
var viaReflection = await client.SystemOneAsync<MyEnvelope>(state, questions, options: null, ResponseJson.SnakeCase);

State, instructions and criteria: JsonContent

Everywhere the API takes "text, an object, or an array", the SDK takes a JsonContent. It converts implicitly from string and from JsonNode; JsonContent.From(value) serializes anything else (pass a JsonTypeInfo<T> as the second argument in a trimmed or AOT app). Nodes are deep-cloned in and out, so one JsonObject can appear in several questions and a question can be sent any number of times — System.Text.Json nodes have a single parent, and encoding by reference would throw on the second use.

null means omit for an optional field; JsonContent.Null means send an explicit null. A choice label mapped to null is sent as null (undescribed — interpreted by its name).

Limits. The API documents at most 255 choice options and 2–10 score levels. Jev.Net, like the Python SDK, does not enforce these client-side — an out-of-range question comes back as a TypeSafeUnprocessableEntityException naming the field. What IS rejected before the network is structural, not schema: a null or missing state, an empty question set, a null question, an empty score rubric, and a raw question without a type (or a raw choice/score without criteria).

Raw questions

A JsonObject converts implicitly to a Question and is sent exactly as given — the escape hatch for fields or question types the API adds before this SDK models them. Only its structure is checked (type present; choice and score have criteria; a score rubric is nonempty); its schema is left to the API.

Testing code that uses the client

TypeSafeClient implements ITypeSafeClient, so your code can take the interface and your tests can hand it a fake — and the fake can return genuine responses, decoded and validated exactly as the client would:

var raw = new RawHttpResponse(200, headers: null, Encoding.UTF8.GetBytes(recordedJson));
var response = SystemOneResponse.FromHttpResponse(raw);      // or FromHttpResponse<Ticket>(raw)

The same call turns a cached or replayed body back into a response; a non-2xx snapshot throws the matching exception. To fake at the HTTP level instead, give the real client a Handler.

Samples

samples/Jev.Net.Samples has three small programs in the shape of TypeSafe's cookbooks — each keeps the workflow in code and asks the model only for the judgment:

dotnet run --project samples/Jev.Net.Samples -f net10.0 -- routing     # needs TYPESAFE_API_KEY; the tests run all three offline

The C# blocks in this README are regions of ReadmeSnippets.cs in that project: they are compiled on every build, and a test fails if the two drift apart.

Errors

Message reads POST https://api.typesafe.ai/v1/systemone: 429 <server's explanation> (request_id=…). The endpoint never carries credentials, a query string, or a fragment.

Caller cancellation is not a timeout: cancelling your token surfaces as OperationCanceledException, is never retried, and also interrupts a wait between retries.

Retries

RetryPolicy defaults: 2 retries; 408, 429 and 5xx; connection and timeout failures; exponential backoff from 0.5s to 5s with up to 25% subtracted as jitter; Retry-After / retry-after-ms honored (however long); and a 30s total budget per call that stops before a wait that would exceed it, rethrowing the last error. Set it on the client, or per call through RequestOptions.Retry. RetryPolicy.None disables retrying.

Configuration

Explicit options win; blank environment values count as unset. Authorization, Accept, User-Agent, X-TypeSafe-SDK and X-TypeSafe-Runtime are protected — neither default nor per-call headers can replace them.

Logging (category Jev.Net): one Information line per attempt; headers and bodies at Debug. Credential-bearing headers — and any header whose name contains token or secret — are redacted. Bodies are not: they are whatever state you sent. Don't enable Debug where that matters.

Pin a model (jev-1.13.0, not jev-latest) wherever you have tuned thresholds against its probabilities.

Observability

Traces and metrics come through ActivitySource and Meter, which ship in the .NET runtime — so OpenTelemetry support costs no dependency — and with nobody listening, the SDK skips the bookkeeping entirely.

services.AddOpenTelemetry()
    .WithTracing(tracing => tracing.AddSource(TypeSafeTelemetry.ActivitySourceName))
    .WithMetrics(metrics => metrics.AddMeter(TypeSafeTelemetry.MeterName));

One client span covers one SDK call including its retries (http.request.resend_count). The individual HTTP attempts are not duplicated here: they come from .NET's own HTTP instrumentation, and appear beneath this span only if you turn that on as well — .AddHttpClientInstrumentation() from OpenTelemetry.Instrumentation.Http, or .AddSource("System.Net.Http"). The snippet above subscribes to Jev.Net alone. It carries the operation, status, requested and answering model, token counts and the x-typesafe-request-id.

None of your content is recorded — no state, questions, answers or headers. Two things you configure are: the model name you asked for (jev_net.request.model), and your base URL's host and path (server.address, url.full — never its credentials or query). A failed span's description is fixed text — HTTP <status>, invalid response body, cancelled, or the exception's type — never the server's message, which could echo your request. The per-attempt child spans are .NET's, not ours. To keep those clean as well, the SDK never sends a base URL's user:password@ on the wire and never adds a query string.

Python SDK → Jev.Net

If you know typesafe-sdk, you already know this. Everything in the left column behaves the same on the right.

Differences from the Python SDK

• Async only. No synchronous client; that is the .NET convention for HTTP.
• Durations are TimeSpan, so the NaN/infinite-seconds cases upstream validates cannot be written. There is one per-attempt timeout rather than httpx's connect/read/write/pool split.
• HttpMessageHandler / HttpClient stand in for httpx's transport / client. A supplied HttpClient is disposed with the SDK client, as upstream — set DisposeHttpClient = false for one from IHttpClientFactory. When you supply one, its own Timeout still caps every attempt.
• Questions are a closed class hierarchy, so "a question that is not a question" cannot be constructed; typed questions validate at construction with ArgumentExceptions rather than pydantic errors.
• No covariant question maps — IReadOnlyDictionary is invariant in its value; declare the dictionary as Dictionary<string, Question>.
• Optional answers are marked, not inferred. Python reads Optional[...]; here a property is required unless it carries [OptionalAnswer]. Nullability is metadata the trimmer removes, so inferring from it would make the same class validate differently in a Native AOT build.
• Traces and metrics (ActivitySource / Meter) — upstream has neither; this is what a .NET service expects.
• TimeProvider is accepted for the retry clock — a .NET addition. So are ITypeSafeClient, result.UnmodeledAnswers (the receiving half of raw questions), ScoreAnswer.MostLikely (the mode, beside the averaged Score) and TypeSafeDefaults.SdkVersion.
• It identifies itself as jev-net/<version>, not as the official SDK.

Tests

dotnet test --solution Jev.Net.slnx

Offline and sub-second: a stub HttpMessageHandler, an injected environment reader, an injected delay, and a manual clock. LiveIntegrationTests is the one class that calls the real API, and it is opt-in — it needs TYPESAFE_LIVE_TESTS=1 and TYPESAFE_API_KEY, and reports Inconclusive otherwise.

The suite was mutation-checked: the client was broken on purpose in nine places (protected headers, the retry budget, header redaction, strict number decoding, node cloning, jitter, retry-after-ms precedence, cancellation-vs-timeout, unknown answer types) and every break is caught.

tests/Jev.Net.AotSmoke is not a test project but a console app: CI publishes it with PublishAot and runs the native binary on Linux and Windows, exercising request encoding, retries, answers-by-property-name, source-generated JSON, and error mapping after the trimmer and AOT compiler have been through them.

License

MIT. See NOTICE for the upstream attribution.