Installation

All tnsai-* artifacts are published under the dev.tnsai group. From 0.18.2 on, releases are published only to the TnsAI Maven repository at https://repo.tnsai.dev/maven2, so your build must declare that repository (see Add the TnsAI repository). Artifacts are GPG-signed with the same key as before, fingerprint 1771 0028 01D4 D7A1 0F5B F8F7 D60C FDA9 7540 3254 (long key ID D60CFDA975403254). The io.github.tansuasici coordinate is retired. Releases through 0.15.0 were published there as real artifacts and stay published. 0.15.1 is the handover: on the old coordinate it is a relocation POM pointing at dev.tnsai, so a project still on the retired groupId reaches the new one by bumping to 0.15.1. Bumping to 0.15.0 instead resolves a real artifact and leaves you on the retired coordinate, with no warning. dev.tnsai starts at 0.15.1, and new projects start there. Java packages (com.tnsai.*) do not change.

Quick setup (Maven)

Add the repository and import the BOM in your pom.xml:

<repositories>
  <repository>
    <id>tnsai</id>
    <url>https://repo.tnsai.dev/maven2</url>
  </repository>
</repositories>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>dev.tnsai</groupId>
      <artifactId>tnsai-bom</artifactId>
      <version>0.18.6</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

The sections below cover each step, Gradle, repository managers and the modules to list in <dependencies>.

Prerequisites

• Java 21+
• Maven 3.9+ or Gradle 8+

Add the TnsAI repository

Declare repo.tnsai.dev next to Maven Central. A 0.18.2 or later BOM or module resolves only with it.

Maven, in your pom.xml, as a direct child of <project>:

<repositories>
    <repository>
        <id>tnsai</id>
        <url>https://repo.tnsai.dev/maven2</url>
    </repository>
</repositories>

Maven still uses Central, which every build inherits. It queries repositories declared in the POM first, so lookups for other groups also reach repo.tnsai.dev before Central and miss there.

Gradle (Kotlin DSL):

repositories {
    mavenCentral()
    maven("https://repo.tnsai.dev/maven2")
}

A build that declares repositories centrally, in settings.gradle.kts under dependencyResolutionManagement, adds the maven(...) line there instead: FAIL_ON_PROJECT_REPOS rejects a project-level block and PREFER_SETTINGS ignores it.

If your builds resolve through a repository manager (Nexus, Artifactory) with a <mirrorOf>*</mirrorOf> or external:* mirror in settings.xml, the mirror also takes over the tnsai repository. Either add https://repo.tnsai.dev/maven2 as a proxy to the group the mirror URL points at, or exclude it by appending ,!tnsai to your existing value, as in <mirrorOf>*,!tnsai</mirrorOf> or <mirrorOf>external:*,!tnsai</mirrorOf>.

Maven (recommended, via BOM)

With the repository declared, import the BOM once in <dependencyManagement>, then list the modules you need in <dependencies> without any <version> tag:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.tnsai</groupId>
            <artifactId>tnsai-bom</artifactId>
            <version>0.18.6</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>dev.tnsai</groupId>
        <artifactId>tnsai-core</artifactId>
    </dependency>
    <dependency>
        <groupId>dev.tnsai</groupId>
        <artifactId>tnsai-llm</artifactId>
    </dependency>
    <!-- pick any other tnsai-* module — versions come from the BOM -->
</dependencies>

To upgrade: change the single <version> on tnsai-bom. Every tnsai-* module moves together.

Gradle

repositories {
    mavenCentral()
    maven("https://repo.tnsai.dev/maven2")
}

dependencies {
    implementation(platform("dev.tnsai:tnsai-bom:0.18.6"))
    implementation("dev.tnsai:tnsai-core")
    implementation("dev.tnsai:tnsai-llm")
    // pick any other tnsai-* module — versions come from the BOM
}

Available modules

The BOM aligns the versions of 13 runtime modules:

The root reactor also builds tnsai-bom, which carries dependency-management metadata, and tnsai-rewrite, which ships build-time OpenRewrite migration recipes. Neither is a runtime framework module.

Detailed per-module guidance → Module Overview.

Without the BOM (not recommended)

If for some reason you want to pin module versions individually (from 0.18.2, the repository is still required):

<dependency>
    <groupId>dev.tnsai</groupId>
    <artifactId>tnsai-core</artifactId>
    <version>0.18.6</version>
</dependency>

This works but you're now responsible for keeping every tnsai-* dep on the same version. BOM mismatch is the #1 source of runtime surprises, so stick with the BOM unless you have a specific reason.

Logging: pick an SLF4J backend

TnsAI uses SLF4J for all internal logging. SLF4J is a facade. TnsAI itself only depends on slf4j-api, the interface layer. You must add a logging implementation to your own project, otherwise SLF4J prints

SLF4J: No SLF4J providers were found.
SLF4J: Defaulting to no-operation (NOP) logger implementation.

at startup and you'll see no log output at all.

This is the standard Java pattern (Spring, Jackson, Apache HTTP Client, etc. all behave the same way). Libraries don't ship a log backend so they don't conflict with whatever you're already using.

Pick one based on your context:

Logback (recommended for production)

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.5.18</version>
</dependency>

SLF4J Simple (tests / CLI)

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.17</version>
    <scope>test</scope>
</dependency>

Drop <scope>test</scope> if you want it on the production classpath too.

Silence all logging

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-nop</artifactId>
    <version>2.0.17</version>
</dependency>

Environment variables

For the full list, see reference/configuration.

Next

• Quickstart: Build your first agent in five minutes.
• Module Overview: Which modules you need for your use case.