NAME

WebService::TypeSafe - Perl client for TypeSafe AI's System One (Jev) API

SYNOPSIS

use WebService::TypeSafe qw(choice noul score);

my $client = WebService::TypeSafe->new(
    api_key => $api_key,
);
my $result = $client->system_one(
    state => { message => 'My payment failed. Please help now.' },
    questions => {
        urgent => noul(
            instructions => 'Does `message` convey urgency?',
        ),
        department => choice(
            instructions => 'Which team should handle `message`?',
            criteria => {
                billing   => 'Payments, invoices, or refunds',
                technical => 'Bugs, outages, or integrations',
                other     => undef,
            },
        ),
        frustration => score(
            instructions => 'How frustrated is the customer?',
            criteria => ['Calm', 'Concerned', 'Very angry'],
        ),
    },
);

say $result->answers->{urgent}->noul;
say $result->choices->{department}->choice;

DESCRIPTION

This module provides an idiomatic synchronous Perl interface matching the official TypeSafe Python and JavaScript SDKs: typed question constructors, typed response objects, model listing, retries, environment configuration, and structured exceptions.

CONFIGURATION

Pass the API key explicitly when constructing the client:

my $client = WebService::TypeSafe->new(
    api_key => $api_key,
);

The value can come from your application's configuration or secret manager. Do not hard-code or commit the actual key.

If api_key is omitted, the client optionally falls back to TYPESAFE_API_KEY:

my $client = WebService::TypeSafe->new;

Explicit constructor values take precedence over environment variables.

• api_key constructor option (primary API)

• TYPESAFE_API_KEY (optional fallback when api_key is omitted)

• TYPESAFE_DEFAULT_MODEL (defaults to jev-latest)

• TYPESAFE_BASE_URL (defaults to https://api.typesafe.ai)

AUTHOR

Provided by Data Sculpting Inc.

Email: info@datasculpting.com

Website: https://datasculpting.com/

LICENSE

Copyright (c) 2026 Data Sculpting Inc.

This library is released under the MIT License.