# Installation

Add TnsAI to your project. The recommended path is via the **BOM** — one version number covers every module.

All `tnsai-*` artifacts are published to Maven Central under the
`dev.tnsai` group. Browse them at
[central.sonatype.com/namespace/dev.tnsai](https://central.sonatype.com/namespace/dev.tnsai).
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`; new projects start there.
Java packages (`com.tnsai.*`) do not change.

## Prerequisites

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

## Maven (recommended — via BOM)

Import the BOM once in `<dependencyManagement>`, then list the modules you need in `<dependencies>` without any `<version>` tag:

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.tnsai</groupId>
            <artifactId>tnsai-bom</artifactId>
            <version>0.16.4</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

```kotlin
dependencies {
    implementation(platform("dev.tnsai:tnsai-bom:0.16.4"))
    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 12 runtime modules:

| Module | What it provides |
|---|---|
| `tnsai-core` | Agent lifecycle, action routing, tools, capabilities, streaming |
| `tnsai-llm` | `LLMClientFactory` clients — full inventory on [LLM Providers](../capabilities/llm/providers.md) |
| `tnsai-intelligence` | RAG, knowledge bases, planning, reasoning, context management |
| `tnsai-coordination` | Multi-agent groups, topologies, negotiation, workflows |
| `tnsai-quality` | OpenTelemetry, Prometheus, prompt injection detection, sandboxing |
| `tnsai-evaluation` | G-Eval, release gates, regression detection |
| `tnsai-mcp` | Model Context Protocol — client, server, stdio/SSE/streamable-HTTP transports |
| `tnsai-tools` | 63 POJO toolkits (209 `@Tool` methods) across web, file, DB, code, media, fintech, … |
| `tnsai-channels` | Telegram / CLI / Email / Slack / Discord / WhatsApp channel adapters via SPI |
| `tnsai-payments` | x402 payment flows, policy enforcement, receipts, and settlement adapters |
| `tnsai-integration` | External framework bridges and integration tests |
| `tnsai-server` | HTTP/WebSocket agent server (Javalin-based) |

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](module-overview.md).

## Without the BOM (not recommended)

If for some reason you want to pin module versions individually:

```xml
<dependency>
    <groupId>dev.tnsai</groupId>
    <artifactId>tnsai-core</artifactId>
    <version>0.16.4</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 — stick with the BOM unless you have a specific reason.

## Logging — pick an SLF4J backend

TnsAI uses [SLF4J](https://www.slf4j.org) 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:

| Context | Recommended | Notes |
|---|---|---|
| **Production**, no Spring Boot | `logback-classic` | Battle-tested, async, structured logging |
| **Production**, with Spring Boot | _nothing — already there_ | Spring Boot Starter brings logback-classic transitively |
| **CLI / small tool** | `slf4j-simple` | Plain console output, one extra dep |
| **Tests only** | `slf4j-simple` (test scope) | What most TnsAI examples use |
| **No logs wanted** | `slf4j-nop` | Silently drops every log call |

### Logback (recommended for production)

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

### SLF4J Simple (tests / CLI)

```xml
<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

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

## Environment variables

| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_API_KEY` | Claude API key |
| `OPENAI_API_KEY` | OpenAI API key |
| `BRAVE_API_KEY` | Brave Search API key |
| `TAVILY_API_KEY` | Tavily Search API key |

For the full list, see [reference/configuration](../reference/configuration.md).

## Next

- [Quickstart](quickstart.md) — Build your first agent in five minutes.
- [Module Overview](module-overview.md) — Which modules you need for your use case.