typesafe-java

Java 21 client for the TypeSafe API. Send a state (any JSON value) plus a set of Noul/Choice/Score questions, get back typed answers.

Save a token to ~/.typesafe.apikey first — either way below picks it up automatically.

Quickstart

As a Java library

ApiKey token = ApiKey.fromDefaultFile(); // reads ~/.typesafe.apikey
// or: ApiKey.fromEnv();                 // reads the TYPESAFE_API_KEY environment variable
TypeSafeClient client = TypeSafeClient.builder(token).build();

EvaluateRequest request = EvaluateRequest.of(
        State.text("Help! My payouts have been failing for 3 days."),
        Map.of("is_urgent", Question.noul("Does this convey urgency?")));

Answer.Noul answer = client.evaluate(request).nouls().get("is_urgent");
answer.noul(); // e.g. 0.92

Or skip the Map/cast with a typed record (typesafe-java-mapping):

record UrgencyCheck(@Noul("Does this convey urgency?") double isUrgent) {
}

MappingTypeSafeClient client = TypeSafeClient.builder(token).build(MappingTypeSafeClient::decorate);
UrgencyCheck result = client.evaluateTyped(
        State.text("Help! My payouts have been failing for 3 days."), UrgencyCheck.class);
result.isUrgent(); // e.g. 0.92

See Install below to add it as a dependency, or the tutorial for the full walkthrough — including every way to provide the token, in how-to.md.

From the command line

No Java coding required — the cli module builds a self-contained uber-jar, handy for wiring a check into a Jenkins job, a shell script, or any other CI pipeline without writing a line of Java. Download it from Maven Central (under the all classifier — the plain artifact is just this module's own classes, not runnable on its own; the latest release notes link straight to the jar), or build it from source:

./mvnw -pl cli -am package -DskipTests

Either way, run it the same way:

java -jar typesafe-java-cli-*-all.jar \
        --state "My card was charged twice." \
        --noul "urgent=Is this urgent?" \
        --min "urgent=0.5" || echo "not urgent enough"

Exits 1 if --min's threshold isn't met, so it doubles as a pass/fail gate — stdout stays silent by default; add --print urgent for the value or --verbose for the full response as JSON. See how-to.md for the full flag reference (--choice/--score, --print, --verbose, ...).

Install

Maven, via the BOM (see the Maven Central badge above for the latest version):

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.github.dfa1.typesafe-java</groupId>
      <artifactId>typesafe-java-bom</artifactId>
      <version>0.5.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.github.dfa1.typesafe-java</groupId>
    <artifactId>typesafe-java-client-jdk</artifactId>
  </dependency>
  <dependency>
    <groupId>io.github.dfa1.typesafe-java</groupId>
    <artifactId>typesafe-java-jackson3</artifactId>
  </dependency>
</dependencies>

On Android, or anywhere else java.net.http isn't available, swap typesafe-java-client-jdk for typesafe-java-client-okhttp.

Modules

Module	Contains
core	TypeSafeClient, the DTOs, and the JsonCodec/HttpTransport SPIs
client-jdk	HttpTransport backed by java.net.http
client-okhttp	HttpTransport backed by OkHttp — an alternative for environments java.net.http doesn't cover, e.g. Android
jackson2 / jackson3	JsonCodec backed by Jackson 2.x / 3.x
testkit	RecordingTypeSafeClient/FailingTypeSafeClient, TypeSafeClient test doubles for unit tests
mapping	MappingTypeSafeClient — maps a @Noul/@Choice/@Score-annotated record to/from EvaluateRequest/EvaluateResponse
bom	dependency management for the modules above
cli	ad hoc checks from a terminal; runnable uber-jar under the all classifier, java -jar
acceptance	live-API tests only — not published

See ADR 0001 for why it's split this way.

Docs

Structured by Diataxis:

• Tutorial — your first evaluation, end to end
• How-to — task-oriented recipes: codecs, transports, testing, the CLI, ...
• Reference — full API surface
• Explanation — design rationale

Build

./mvnw clean verify                                # build + unit tests, all modules
./mvnw test -pl acceptance -am -DexcludedGroups=    # + live-API acceptance tests, needs ~/.typesafe.apikey

License

MIT — see LICENSE.

Reference

• Introduction
• API reference