Building the return object

Building the return object

The return object is the C# type JevDotNet creates from an API response. Each public property with a Jev question attribute asks one question. The property name becomes that question's ID, and the property type determines how the answer is returned.

This is the return-object step of the implementation walkthrough. Work through the class and enum rules below, then evaluate text and use the result.

Before you start

Install JevDotNet into a .NET 8+ project:

dotnet add package JevDotNet

using System.ComponentModel;
using JevDotNet;
using JevDotNet.Models;

1. Choose the answers you need

For a support message, you might want a category, a severity score, and a yes/no decision. Define one property per question:

public sealed class SupportAssessment
{
    [JevChoiceQuestion<Category>("What is the primary category?")]
    public Category? Category { get; set; }

    [JevScoreQuestion<Severity>("How severe is the customer's issue?")]
    public double? Severity { get; set; }

    [JevNoulQuestion("Is the product broken?", threshold: 0.7)]
    public bool? IsBroken { get; set; }
}

The class needs a public parameterless constructor so EvaluateAsync<SupportAssessment>() can create it. Its question properties need public setters. An ordinary public class with no constructor declared meets the constructor requirement. At least one property must carry a Jev question attribute; unannotated properties are ignored.

The question text must be nonempty. Give each question a clear, single decision to make from the input text.

2. Define criteria with enums

Choice uses enum members as the available answers. Add Description attributes when the member name alone does not explain the criterion:

public enum Category
{
    [Description("Questions about using or troubleshooting the product")]
    Technical,

    [Description("Questions about invoices, payments, or subscriptions")]
    Billing,

    Other
}

Score uses an enum with 2 to 10 ordered levels. JevDotNet orders its members by their underlying numeric values and sends their descriptions (or names when no description is present) as the scale criteria:

public enum Severity
{
    Cosmetic = 0,
    Degraded = 1,
    Blocking = 2
}

Explicit values make the intended order easy to review. Score returns a numeric value; the enum defines the scale and is not itself the property type.

3. Verify the return object with an evaluation

Store your TypeSafe AI API key outside source code, such as in an environment variable or .NET user secrets.

string apiKey = Environment.GetEnvironmentVariable("JEV_API_KEY")
    ?? throw new InvalidOperationException("Set JEV_API_KEY first.");

JevClient client = new(apiKey);

JevResponse<SupportAssessment> response =
    await client.EvaluateAsync<SupportAssessment>(
        "The customer cannot sign in after resetting their password.");

SupportAssessment result = response.Result;
Category? category = result.Category;
double? severity = result.Severity;
bool? isBroken = result.IsBroken;

long inputTokens = response.InputTokenCount;
long outputTokens = response.OutputTokenCount;

The library creates a new SupportAssessment, reads the answers by property name, and sets each attributed property. If the API omits an answer or returns an incompatible answer, evaluation throws instead of silently leaving that property unset.

4. Choose simple or detailed properties

The example above keeps only the values. You can choose detailed result records when you also need confidence, probabilities, or a Score legend:

public sealed class DetailedSupportAssessment
{
    [JevChoiceQuestion<Category>("What is the primary category?")]
    public JevChoice<Category>? Category { get; set; }

    [JevScoreQuestion<Severity>("How severe is the customer's issue?")]
    public JevScore<Severity>? Severity { get; set; }

    [JevNoulQuestion("Is the product broken?")]
    public JevNoul? IsBroken { get; set; }
}

JevResponse<DetailedSupportAssessment> detailedResponse =
    await client.EvaluateAsync<DetailedSupportAssessment>(
        "The customer cannot sign in after resetting their password.");

Category? detailedCategory = detailedResponse.Result.Category?.Choice;
double? categoryConfidence = detailedResponse.Result.Category?.Confidence;
double? detailedSeverity = detailedResponse.Result.Severity?.Score;
double? breakageProbability = detailedResponse.Result.IsBroken?.Probability;
bool? aboveSeventyPercent = detailedResponse.Result.IsBroken?.IsAtLeast(0.7);

JevNoul.Value uses the default threshold of 0.5. To apply a custom threshold directly during mapping, use a bool or bool? property and put threshold on [JevNoulQuestion] as in the first example. For each primitive's full behavior and examples, see Choice, Score, and Noul. The question type matrix compares all property shapes.

Checklist

• One Jev question attribute per question property, with nonempty question text.
• A public, writable property for each answer; property names are the question IDs.
• The same enum type in a Choice attribute and its Choice property.
• A Score enum with 2–10 members ordered by numeric value.
• A public parameterless constructor on a class used as the result type.
• An API key supplied from outside the source code.

Next: Evaluate text and use the result explains token usage, detailed fields, cancellation, and client options. For validation errors, see Troubleshooting return objects.