Spring Boot Starter¶

Auto-configures a TypeSafeClient bean from spring.ai.typesafe.* properties.

Quick Start¶

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-starter-typesafe</artifactId>
    <version>0.3.0-SNAPSHOT</version>
</dependency>

spring.ai.typesafe.api-key=${TYPESAFE_API_KEY}

That is the whole setup. Inject the client anywhere:

@Bean
CommandLineRunner demo(TypeSafeClient typeSafeClient) {
    return args -> {
        SystemOneResponse response = typeSafeClient.systemOne(
                "My card was charged twice.",
                Map.of("refund_requested", Noul.of("Is the customer asking for money back?")));
    };
}

Properties¶

spring.ai.typesafe.api-key=${TYPESAFE_API_KEY}
spring.ai.typesafe.base-url=https://api.typesafe.ai
spring.ai.typesafe.model=jev-latest
spring.ai.typesafe.timeout=10s
spring.ai.typesafe.retry.max-retries=2
spring.ai.typesafe.retry.initial-backoff=500ms
spring.ai.typesafe.retry.max-backoff=5s
spring.ai.typesafe.retry.jitter=0.25
spring.ai.typesafe.retry.total-timeout=30s

Property	Default	Description
`api-key`	—	The API key. No bean is created when the property is not defined; a blank value fails startup.
`base-url`	`https://api.typesafe.ai`	The API base URL.
`model`	`jev-latest`	Applied to requests that do not name a model.
`timeout`	`10s`	Per-attempt HTTP timeout.
`retry.*`	see Errors and Retries	Retry budget and backoff.

Conditional wiring¶

The TypeSafeClient bean is created only when the api-key property is defined, so an application that does not configure TypeSafe at all still starts. A property that is defined but blank, such as ${TYPESAFE_API_KEY:} with the variable unset, fails startup with a message naming the property, and so does an unresolved ${TYPESAFE_API_KEY} placeholder. Guard your own beans the same way if they depend on the client:

@Bean
@ConditionalOnBean(TypeSafeClient.class)
JevJudge answerQualityJudge(TypeSafeClient typeSafeClient) {
    return JevJudge.builder(typeSafeClient)
        .score("helpfulness", helpfulnessRubric, 2.0d)
        .build();
}

Defining your own TypeSafeClient bean switches the auto-configuration off entirely.

Environment variables and properties¶

The plain-Java client falls back to TYPESAFE_API_KEY, TYPESAFE_BASE_URL and TYPESAFE_DEFAULT_MODEL. Under Boot, base-url and model always have property defaults and are always passed explicitly, so only the key reaches the client from the environment — and only through the ${TYPESAFE_API_KEY} placeholder you write in your properties.

Do not export TYPESAFE_BASE_URL while developing

The plain-Java builder falls back to it, so an exported value silently redirects any throwaway main you write, and the live ITs. That is also how to point them at a compatible server on purpose; see Using Laya.

Endpoints bean¶

The starter also contributes the API paths the client uses as a TypeSafeAutoConfiguration.TypeSafeEndpoints record, which is occasionally useful for observability or for building a health check:

@Bean
HealthIndicator jevHealth(TypeSafeClient client,
        TypeSafeAutoConfiguration.TypeSafeEndpoints endpoints) {
    // endpoints.systemOnePath(), endpoints.modelsPath()
}