# Module Overview

## Module Summary

The framework publishes 12 runtime modules. The root Maven reactor also builds
`tnsai-bom` for dependency management and `tnsai-rewrite` for build-time
OpenRewrite migration recipes; those two artifacts are not runtime modules.

| Module | Purpose | Key Classes |
|--------|---------|-------------|
| **Core** | Agent lifecycle, roles, actions, events, SPI, tool dispatch | Agent, AgentBuilder, Role, ActionExecutor, ToolMethodRegistry, ToolMethodDispatcher |
| **LLM** | Provider-agnostic LLM abstraction + streaming | LLMClient, ChatRequest, ChatResponse, ChatChunk |
| **Coordination** | Multi-agent groups, protocols, voting | AgentGroup, ProtocolManager, LeaderElection |
| **Intelligence** | Planning, reasoning, RAG, learning | PlannerHandle, ReasoningStrategy, KnowledgeBase |
| **Quality** | Observability, security, validation | AgentTrace, SecurityEnforcer, InvariantChecker |
| **Evaluation** | Evaluators, benchmarks, quality gates | Evaluator, BenchmarkRunner, QualityGate, EvalTest |
| **Tools** | 63 POJO toolkits (209 @Tool methods) across 29 categories | CsvTools, JsonTools, PdfTools, WebSearchTools, AcademicTools, … |
| **MCP** | Model Context Protocol client/server | McpClient, McpServer, McpTransport, TnsAIToolProvider |
| **Server** | WebSocket backend, RAG pipeline, tool approval | TnsServer, ServerFileTools, ServerShellTools, ServerGitTools |
| **Channels** | External messaging adapters | ChannelAdapter, InboundMessage, OutboundMessage |
| **Payments** | x402 payments, requirements, wallets, settlement | X402Config, PaymentRequirement, Wallet |
| **Integration** | Cross-module integration tests | End-to-end scenarios |

## When to Use What

### Minimal Agent (Core + LLM)
```xml
tnsai-core + tnsai-llm
```
Chat-capable agent with roles and actions. No tools, no coordination.

### Agent with Tools (+ Tools)
```xml
tnsai-core + tnsai-llm + tnsai-tools
```
Agent can search the web, read files, execute code, query databases.

### Multi-Agent System (+ Coordination)
```xml
tnsai-core + tnsai-llm + tnsai-coordination
```
Agent groups, leader election, negotiation protocols, task delegation.

### Smart Agent (+ Intelligence)
```xml
tnsai-core + tnsai-llm + tnsai-intelligence
```
GOAP/HTN planning, ReAct/ToT reasoning, RAG, learning from feedback.

### Production Agent (+ Quality + Evaluation)
```xml
tnsai-core + tnsai-llm + tnsai-quality + tnsai-evaluation
```
OpenTelemetry tracing, security enforcement, automated evaluation, quality gates.

### Agent that pays (+ Payments)
```xml
tnsai-core + tnsai-llm + tnsai-payments
```
x402 settlement via `X402PaymentBroker` / `Wallet`. Free internal traffic
keeps the default `PaymentBroker.noOp()` in core — pull this module when the
agent must quote, sign, or settle.

### Full Stack
```xml
all 12 runtime modules
```
WebSocket API, session management, RAG pipeline, tool approval UI.

## Module Dependencies

| Module | Depends On |
|--------|-----------|
| Core | — (foundation) |
| LLM | Core |
| Coordination | Core |
| Intelligence | Core, Coordination (runtime) |
| Quality | Core, LLM |
| Evaluation | Core, Quality |
| Tools | Core, Quality |
| MCP | Core |
| Channels | Core |
| Payments | Core |
| Integration | All |
| Server | Core, LLM, Coordination (runtime), Quality |