JRK.JevRunner
0.7.2
dotnet add package JRK.JevRunner --version 0.7.2
NuGet\Install-Package JRK.JevRunner -Version 0.7.2
<PackageReference Include="JRK.JevRunner" Version="0.7.2" />
<PackageVersion Include="JRK.JevRunner" Version="0.7.2" />
<PackageReference Include="JRK.JevRunner" />
paket add JRK.JevRunner --version 0.7.2
#r "nuget: JRK.JevRunner, 0.7.2"
#:package JRK.JevRunner@0.7.2
#addin nuget:?package=JRK.JevRunner&version=0.7.2
#tool nuget:?package=JRK.JevRunner&version=0.7.2
JRK.JevRunner
A .NET client for Jev and the TypeSafe System One API. Submit application state and named questions, and consume typed responses.
0.7.1 highlights
- Automatically installed
JEV100andJEV101usage analyzers and IDE code fixes help preserve automatic backtick quoting and remove redundant explicit backticks. Escape.Interpolated(...)formats preserved interpolations into strings while automatically quoting state references and paths.- Diagnostics follow generic constraint chains; code fixes retain qualification when needed to avoid name conflicts. The Image package receives tooling through its core package dependency, without duplicate assemblies.
See the 0.7.1 release notes for details. The client still requires .NET 11 and preview C# features.
Requirements
- .NET 11 or later
- A TypeSafe API key
Installation
dotnet add package JRK.JevRunner
The package embeds its source generator and depends on JRK.JevRunner.Analyzers
for usage diagnostics and code fixes. NuGet installs that dependency automatically;
no separate analyzer reference is needed. Only the analyzer package contains the
usage-analyzer and code-fix DLLs, so adding a direct reference to that same package
does not introduce a second physical copy. These assemblies are compile-time assets
under analyzers/dotnet/cs/, not runtime assemblies, and target netstandard2.0,
while the client targets net11.0.
JEV100 warns when interpolating a state reference or path into a plain string loses
automatic backtick quoting. Its code fix wraps the interpolation in Escape.Interpolated(...)
to preserve and quote its arguments. JEV101 warns about redundant explicit backticks around
state references in preserved interpolations, with a fix to remove them.
See analyzer documentation
for examples and .editorconfig configuration.
The code fix emits the short helper name where safe, retaining namespace or root qualification only when needed to avoid name conflicts. Analysis also recognizes marker interfaces inherited through generic class constraints and constraint chains.
For repository development, analyzer project references are not transitive. Playground and the Image library explicitly reference the analyzer and code-fix projects. The Image NuGet package relies on its core package dependency for tooling rather than bundling duplicate assemblies. Pack the analyzer dependency before the client and publish both packages together. For local packaging checks:
dotnet pack JRK.JevRunner.Analyzers/JRK.JevRunner.Analyzers.csproj -c Release
dotnet pack JRK.JevRunner/JRK.JevRunner.csproj -c Release
dotnet build JRK.JevRunner.SourceGenerators/JRK.JevRunner.SourceGenerators.Sample/JRK.JevRunner.SourceGenerators.Sample.csproj -c Release -p:UsePackedJevRunner=true
dotnet pack JRK.JevRunner.Image/JRK.JevRunner.Image.csproj -c Release
dotnet build JRK.JevRunner.SourceGenerators/JRK.JevRunner.SourceGenerators.Sample/JRK.JevRunner.SourceGenerators.Sample.csproj -c Release -p:UsePackedJevRunner=true -p:UseImageOnly=true
dotnet build JRK.JevRunner.SourceGenerators/JRK.JevRunner.SourceGenerators.Sample/JRK.JevRunner.SourceGenerators.Sample.csproj -c Release -p:UsePackedJevRunner=true -p:IncludeImagePackage=true
dotnet build JRK.JevRunner.SourceGenerators/JRK.JevRunner.SourceGenerators.Sample/JRK.JevRunner.SourceGenerators.Sample.csproj -c Release -p:UsePackedJevRunner=true -p:IncludeImagePackage=true -p:IncludeStandaloneAnalyzers=true
These build-only smoke checks compile generated queries and assert exactly one resolved
usage-analyzer, code-fix, and source-generator assembly for core alone, Image alone,
core plus Image, and an additional direct analyzer reference. They use local package feeds and the current
version settings; -p:JevRunnerPackageVersion=... overrides the consumed version.
Use a new package version for each published fix; replacing an existing version can
leave consumers or IDEs using cached assemblies.
Package restores audit both direct and transitive dependencies and fail on known vulnerabilities or audit-feed failures. To repeat the advisory check:
dotnet restore all.slnx --force-evaluate
dotnet package list --project all.slnx --vulnerable --include-transitive --no-restore
Quick start
Set the TYPESAFE_API_KEY environment variable to your API key. Do not commit API keys to source control.
using JRK.JevRunner;
using JRK.JevRunner.Requests;
var apiKey = Environment.GetEnvironmentVariable("TYPESAFE_API_KEY")
?? throw new InvalidOperationException("Set TYPESAFE_API_KEY before running.");
var runner = JevRunner.Init(apiKey);
var request = new Request("The brown fox jumped over the lazy dog.", JevModel.Latest)
.AddQuestion(new NoulQuestionBuilder(
"dog_was_jumped_over",
"Did any animal jump over a lazy dog?"));
var response = await runner.Execute(request);
Console.WriteLine(response.GetRequiredNoulAnswer("dog_was_jumped_over"));
Custom backtick-quoted references
The public IBackTick interface lets you create domain-specific reference types
that receive the same automatic quoting as StateReference and StatePath.
Implement Value; the default BackTickQuoted implementation wraps it in backticks.
using JRK.JevRunner;
var reference = new TicketReference("ticket.messages[0].text");
var instructions = Escape.Interpolated($"Summarize {reference}.");
// Summarize `ticket.messages[0].text`.
public sealed record TicketReference(string Value) : IBackTick;
Pass the interpolation directly to Escape.Interpolated(...), or preserve it as a
FormattableString and use .Escaped. Converting it to a plain string first loses
automatic quoting. Do not add explicit backticks around the interpolation. The
JEV100 and JEV101 analyzers also recognize custom IBackTick implementations.
Custom implementations are responsible for validating their values: IBackTick
does not reject whitespace or embedded backticks, unlike the built-in reference
types. This interface only controls instruction formatting; it does not register
state fields or resolve references against request state.
Models and request validation
Requests without an explicit model use JevModel.Latest, including requests with
Box questions. An explicitly supplied model is never overridden. Box questions
require jev-1.14.0 or later; JevModel.Preview remains available as an explicit choice.
JevVersions provides Latest, Preview, Version1_13_0, and Version1_14_0
string constants and the known-version list Versions. Inspect a JevModel with
IsLatest, IsPreview, IsKnownVersion, or IsVersion(version).
Request.StrictValidation defaults to false. Before sending a request, the
runner logs a warning for an unknown model identifier or for Box questions using
jev-1.13.0, but still sends the request. Set StrictValidation = true to throw
InvalidOperationException for either condition before any HTTP request:
var request = new Request("Application state", JevModel.Latest)
{
StrictValidation = true
};
The bundled known-version list may lag the API: an unknown identifier is not necessarily unsupported by TypeSafe. These checks do not replace API validation or guarantee that a request is valid.
Long context (opt-in)
Set request.LongContextEnabled = true or call the chainable
request.EnableLongContext() extension from JRK.JevRunner to send
TypeSafe-Danger-Zone-Long-Context: true for that request. The default is disabled.
var request = new Request("Application state", JevModel.Latest)
.EnableLongContext()
.AddQuestion(new NoulQuestionBuilder("ready", "Is the application ready?"));
This opts into context beyond TypeSafe's default 64 KB limit. TypeSafe cautions that longer context is slower and less accurate than staying within the default limit; enable it only for requests that need it. Other API limits still apply.
Images (experimental)
Jev's image API is dreamer-ready, not production-ready: request formats, limits,
and accuracy may change. Images can be used with Noul, Choice, Score, and Box
questions. Box answers contain normalized Top, Bottom, Left, and Right
edges and answer-level Confidence.
Use AssetState to associate a state field with an image. AddImageAsset reads the
file asynchronously, base64-encodes its bytes, and uses its extension as the image
format. It accepts an optional IFileSystem for file access.
Using the runner initialized in the quick start:
using JRK.JevRunner;
using JRK.JevRunner.Infrastructure;
using JRK.JevRunner.Requests;
using TruePath;
var state = new AssetState();
await state.AddImageAsset(
"photo",
Guid.NewGuid().ToString(),
AbsolutePath.Create(Path.GetFullPath("photo.jpg")));
var request = new Request(state, JevModel.Latest)
.AddQuestion(new NoulQuestionBuilder(
"person_present",
"Is there a person in `photo`?"));
var response = await runner.Execute(request);
Console.WriteLine(response.GetRequiredNoulAnswer("person_present").Noul);
Populate the state before constructing the request: its assets are collected
by the constructor. A generated [JevQuery] can likewise expose an AssetState
as its State property; populate it before calling GetRequest() or Execute().
For manual configuration, add an ImageAsset(reference, format, base64) to
request.Assets and place the same reference in the state, instructions, or
criteria. Use unique references such as UUIDs to avoid accidental text matches.
Base64 must contain only the encoded bytes, without a data: prefix.
Requests containing assets automatically send
TypeSafe-Danger-Zone-Images: true. Images are sent in the JSON assets map,
not as multipart uploads. A filename or image URL alone does not upload an image.
Prepare PNG or JPEG images before sending: each dimension must be 280–1568 pixels,
each file at most 16 MiB, and the request body at most 32 MiB. Base64 increases the
body size. Rotate the pixels upright; the API does not apply EXIF orientation.
The helper does not resize, rotate, convert, or validate image data. Use a lowercase
.png, .jpg, or .jpeg extension that matches the file contents.
For an explicit per-file check before upload, use ImageValidator from the optional
JRK.JevRunner.Image package. Or see Validate and prepare images.
See the TypeSafe image documentation for all limits.
Validate and prepare images
The optional JRK.JevRunner.Image package provides ImageValidator, proportional
ImageScaler.Upscale/Downscale, and experimental automatic asset adjustment.
Validation returns typed dimension or string errors and a result-level
SuggestedScaling; call ThrowIfInvalid() to reject a failed validation.
Suggestions only describe dimension-error direction and do not guarantee that
resizing will make an image valid. See the image preparation examples and limitations.
To register already-prepared bytes without writing another file:
byte[] imageBytes = new JRK.JevRunner.Image.ImageScaler().Downscale(
AbsolutePath.Create(@"C:\images\photo.jpg"));
var state = new AssetState().AddAsset("photo",
new ImageAsset(Guid.NewGuid().ToString(), "png", imageBytes));
ImageScaler returns PNG bytes. ImageAsset accepts them through FileData,
which exposes Bytes and Base64; the constructor does not validate or convert
the supplied format.
Locate objects with Box questions
Using the populated state above:
var request = new Request(state)
.AddQuestion(new BoxQuestionBuilder("Head", "Find the head in `photo`."));
var response = await runner.Execute(request);
var head = response.GetRequiredBoxAnswer("Head");
Console.WriteLine($"Top: {head.Top}, left: {head.Left}, confidence: {head.Confidence.Value}");
Without an explicit model, execution selects JevModel.Latest, including for Box
questions added after construction. An explicitly supplied model is never overridden.
Box questions require jev-1.14.0 or later; see request validation.
For generated queries, expose a GenericBoxQuestionDefinition<string> property
or implement IBoxQuestionDefinition<TInstruction>. A question property named
Head generates GetHeadAnswer(response) and a BoxAnswer property named Head
on the response wrapper. See the generator's Box example.
Render bounding boxes
The optional JRK.JevRunner.Image package provides a SkiaSharp BoxRenderer.
The core client does not depend on it. With the original image path and a Box answer:
using JRK.JevRunner.Image;
var imagePath = AbsolutePath.Create(Path.GetFullPath("photo.jpg"));
byte[] png = new BoxRenderer().DrawBox(imagePath, head);
await File.WriteAllBytesAsync("annotated.png", png);
DrawBox accepts one BoxAnswer or an IEnumerable<BoxAnswer> through AppliedBox,
and returns PNG bytes without modifying the source. Multiple boxes share the supplied
color and stroke width. See the image package documentation
for styling, coordinate validation, native dependencies, and multi-box examples.
API errors
Known HTTP errors throw JevKnownException from JRK.JevRunner.Infrastructure.
Its InnerException retains the original HttpRequestException, including the
status code, and its nullable Content exposes the response body as an
ErrorContent union (JsonNode or string). Empty or whitespace-only bodies
produce null content.
using JRK.JevRunner.Infrastructure;
try
{
var response = await runner.Execute(request);
}
catch (JevKnownException error)
{
Console.Error.WriteLine(error.Message);
if (error.InnerException is HttpRequestException httpError)
Console.Error.WriteLine($"HTTP status: {httpError.StatusCode}");
if (error.Content is { } content)
Console.Error.WriteLine(content.Value);
}
Handled status codes are 400, 401, 413, 415, 422, 429, and 529, with 509 retained for compatibility. Other status codes pass through as HTTP exceptions regardless of whether their response body is JSON or plain text. Transport failures pass through without an HTTP response. The client does not automatically retry rate-limit or overload responses.
Non-empty error bodies are parsed as JSON when possible. Plain text, malformed JSON, and JSON null are retained as raw strings rather than masking the HTTP failure with a JSON parsing exception.
See the TypeSafe error-code documentation.
Samples
See the samples and run instructions for runnable examples, including:
- AnimalQuiz: identify a hidden animal through yes-or-no questions in an interactive console game.
- BlackJack (Halvtolv): play a Danish blackjack variant against a Jev-controlled dealer that reasons about visible cards and round history to decide whether to stop or draw.
- FileGrouping: classify files with Jev and move them into category folders.
- FileImageAnalyzer: analyze local photos for pets, children, and screenshots, and display images with a child bounding box.
Generated queries
Alternatively you can mark a partial class or record class with [JevQuery] and supply readable State
and JevModel properties. Note that State can be a string, array or any object. Question properties implement one of
INoulQuestionDefinition<TInstruction>, IChoiceQuestionDefinition<TInstruction>,
IScoreQuestionDefinition<TInstruction>, or IBoxQuestionDefinition<TInstruction> from JRK.JevRunner.Annotation.
The generator adds GetRequest(), Execute(runner, cancellationToken), and named
typed answer accessors such as GetBudgetAnswer(Response). Generated Execute
returns Task<{QueryName}ResponseWrapper>. The wrapper exposes getter-only typed
answer properties named after the query's questions and the original .Response.
For example, using the runner initialized in the quick start:
using JRK.JevRunner.Annotation;
using JRK.JevRunner.Requests;
var query = new AnimalQuery();
var result = await query.Execute(runner);
Console.WriteLine(result.DogJumpedOver);
var response = result.Response; // Original Response for direct runtime API access.
[JevQuery]
public partial class AnimalQuery
{
public string State => "The brown fox jumped over the lazy dog.";
public JevModel JevModel => global::JRK.JevRunner.Requests.JevModel.Latest;
public JumpQuestion DogJumpedOver { get; } = new();
}
public class JumpQuestion : INoulQuestionDefinition<string>
{
public string Instructions => "Did any animal jump over a lazy dog?";
public string? Yes => "An animal jumped over a lazy dog.";
public string? No => "No animal jumped over a lazy dog.";
}
Execute(runner, cancellationToken) builds the request and forwards the optional
cancellation token to the runner. In this example it returns an
AnimalQueryResponseWrapper with a NoulAnswer property named DogJumpedOver.
GetRequest() and GetDogJumpedOverAnswer(Response) remain available for manual
execution and answer lookup. Wrapper answer properties throw if an answer is
missing or has a mismatched type.
Criteria are generated only when both Yes and No are non-null; otherwise
criteria remain unset.
Question attributes have been replaced by definition interfaces. Choice definitions
provide ChoiceCriteria[] Choices; score definitions provide string[] Criterias
and now have only the instruction generic parameter. Noul definitions provide
optional Yes and No descriptions: both must be non-null to generate criteria.
If either is null, the runtime omits the JSON criteria member.
See the generator contract and diagnostics and the mixed-query sample.
This package is targeting C# 15 and dotnet sdk which is currently in the time of writing in preview
Dependency notes
This library uses TruePath.TestableIO.System.IO,
which builds on TruePath and
TestableIO.System.IO.
License
MIT License. Copyright (c) 2026 Jeppe Roi Kristensen.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net11.0 is compatible. |
-
net11.0
- JRK.JevRunner.Analyzers (>= 0.7.2)
- TruePath.TestableIO.System.IO (>= 1.0.1)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on JRK.JevRunner:
| Package | Downloads |
|---|---|
|
JRK.JevRunner.Image
Optional SkiaSharp image helpers for JRK.JevRunner. Validate image files, proportionally upscale or downscale them, and render normalized Jev bounding-box answers without modifying source files. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.7.2 | 95 | 11/9/2026 |
| 0.7.1 | 98 | 11/5/2026 |
| 0.7.1-preview-01 | 94 | 11/5/2026 |
| 0.7.1-dev-02 | 88 | 11/5/2026 |
| 0.7.0 | 98 | 11/4/2026 |
| 0.6.0 | 116 | 10/26/2026 |
| 0.6.0-preview-01 | 104 | 10/25/2026 |
| 0.5.0 | 105 | 10/19/2026 |
| 0.5.0-preview-02 | 97 | 10/19/2026 |
| 0.5.0-preview-01 | 103 | 10/18/2026 |
| 0.4.0 | 111 | 10/17/2026 |
| 0.3.1 | 100 | 10/11/2026 |
| 0.3.0 | 98 | 10/11/2026 |
| 0.3.0-preview-01 | 97 | 10/11/2026 |
| 0.2.0 | 103 | 10/10/2026 |
| 0.2.0-preview-01 | 111 | 10/10/2026 |
| 0.1.0 | 104 | 10/9/2026 |
| 0.0.3 | 102 | 10/9/2026 |
| 0.0.2 | 103 | 10/9/2026 |
| 0.0.1 | 105 | 10/9/2026 |
Fix issue when no image was passed
- When no asset where added. Incorrect body was generated when doing Jev request