> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avyratech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Readiness

> How to make Tonnex features accessible and reliable for AI agents.

# AI Readiness

Tonnex is built to be **AI-Native**. This means our infrastructure is optimized for AI agents to perform tasks on behalf of users.

## Key Principles

1. **Semantic Consistency**: Database columns, API endpoints, and UI labels should share the same terminology.
2. **Context-Rich Metadata**: Provide descriptions in Swagger and Database schemas.
3. **Predictable Side Effects**: AI should know exactly what will happen when it calls an API (e.g., "This will create an invoice and notify the client").
4. **Data Separation**: AI sees summaries and metadata — never raw data. The frontend receives full data via side channels (`_rawData`, `_fullRows`).

## AI Agent Integration (Future)

Our API is designed to support:

* **Function Calling**: LLMs can directly call our API using the provided OpenAPI specs.
* **Model Context Protocol (MCP)**: Providing a bridge for AI tools to query business data securely.

## Agentic Architecture

The AI module follows Anthropic's **"Building Effective Agents"** patterns:

### Pattern 1: Intent Routing

Each user message is classified into one of four intents before processing:

| Intent     | Example                      | Tools Loaded                                                   |
| ---------- | ---------------------------- | -------------------------------------------------------------- |
| `query`    | "How many trips today?"      | `listAvailableAPIs`, `getAPIDetails`, `callAPI`                |
| `action`   | "Create a trip from Chennai" | `listAvailableAPIs`, `getAPIDetails`, `callAPI`                |
| `report`   | "Vehicle report for March"   | `getReportableFields`, `buildReport`, `saveReport` + API tools |
| `generate` | "Write an email to Siva"     | `generateArtifact` only                                        |

This reduces context window usage by 30-50% per request by loading only relevant tools.

### Pattern 2: Smart Tools (Server-Side Intelligence)

Tools return **structured summaries**, not raw data:

```typescript theme={null}
// callAPI LIST response → AI sees:
{ type: "list", totalCount: 15, entityType: "clients",
  items: [{ id: "abc", label: "ABC Corp", status: "active" }] }

// callAPI CREATE response → AI sees:
{ type: "record", action: "created", id: "xyz", label: "TRP-2026-0042",
  status: "DRAFT", keyFields: { tripDate: "2026-03-21" } }
```

Full data goes to the frontend via `_rawData` (for `callAPI`) or `_fullRows` (for `buildReport`).

### Pattern 3: On-Demand Discovery

Instead of embedding a 150-line schema in the system prompt, AI calls `getReportableFields(entity)` to discover valid columns and joins on demand.

### Pattern 4: Context Management

Old tool results are stripped from conversation history before re-sending to the AI model. Only the last 4 messages retain full tool results.

## AI Chat Panel (`AiChatPanel`)

The `AiChatPanel` component (`apps/web/components/ai/ai-chat-panel.tsx`) is a sidebar chat UI powered by **Gemini** via the Vercel AI SDK.

### Streaming Architecture

| Layer       |                                                          Configuration |
| ----------- | ---------------------------------------------------------------------: |
| Client hook |                     `useChat` from `@ai-sdk/react` with `maxSteps: 10` |
| Transport   | `DefaultChatTransport` with `api` URL including `?chatId=` query param |
| Server      |                `streamText` from `ai` with `stopWhen: stepCountIs(10)` |
| Model       |         `gemini-2.0-flash-001` (default, configurable via AI Settings) |

**Critical Rules:**

* `chatId` must be passed as a **URL query param** (e.g. `/api/ai/chat?chatId=xxx`), NOT in the request body. `DefaultChatTransport` owns the body shape (`{ messages: [...] }`); adding extra fields breaks stream parsing.

## Tool Registry (`tool-registry.ts`)

The tool registry provides 7 tools organized by purpose:

| Tool                  | Purpose                                              |
| --------------------- | ---------------------------------------------------- |
| `listAvailableAPIs`   | Discover all API endpoints                           |
| `getAPIDetails`       | Get full schema for one endpoint                     |
| `callAPI`             | Execute an API call (returns smart summary)          |
| `getReportableFields` | Discover columns/joins for a report entity           |
| `buildReport`         | Build structured report (returns metadata, not rows) |
| `saveReport`          | Persist a report configuration                       |
| `generateArtifact`    | Generate standalone content (docs, emails)           |

### Data Security

The following fields are classified as **sensitive** and are never included in AI tool summaries:

* Personal identifiers: `gstNo`, `panNo`, `aadharNo`, `epfNumber`, `esaNumber`
* Banking: `bankAccount`, `ifscCode`, `upiId`, `accountNumber`, `accountHolderName`
* Contact: `email`, `phone`, `address`

These fields exist in `_rawData`/`_fullRows` for frontend display but are stripped from AI-facing summaries.

## New UI Features

### 💎 Fade Mode (Enterprise-Grade)

Assistant messages now reveal text word-by-word with a smooth fade-in animation, providing a premium feel.

### 🔳 Fullscreen Chat

The header **Fullscreen** button toggles a focused modal view for the entire AI conversation.

### 🌟 Thinking Shimmer

The AI thinking indicator uses a high-contrast shimmer effect optimized for both light and dark backgrounds.

### 📊 View Data Button

When `callAPI` returns a list of records, a teal **"View Data"** button appears, allowing users to view the full dataset in the Artifact Viewer — the same way reports are displayed.

## Error Handling & Self-Correction

The Tonnex AI is designed to be agentic. If a tool call fails, the AI will:

1. Receive a `correctionHint` from the backend.
2. Analyze the valid field names or join requirements.
3. Automatically retry with corrected parameters (up to 10 times).

This prevents the "Failure Loop" and ensures higher success rates for complex reports.

* `maxSteps` on the client **must match** the server `stepCountIs(N)`. Without this, multi-step tool calls silently abort after the first tool result.
* Always use a valid Google model ID (e.g. `gemini-2.0-flash-001`, `gemini-1.5-flash-latest`). Invalid model IDs produce silent 400 errors that look like "streaming not working."

### Expandable Textarea

The input supports a **ChatGPT-style expand mode**:

* Click the **Maximize** button inside the textarea (top-right) to expand to full panel height.
* Press `Esc` or the **Minimize** button to collapse.
* `Shift+Enter` inserts new lines in expanded mode; `Enter` sends.
* Messages area animates out when expanded, giving the input full space.

## Best Practices for Developers

* **Write descriptive JSDoc**: AI tools like Cursor use your comments to understand logic.
* **Never expose raw data to AI**: Always use `buildSmartResponse()` or return structured summaries from tools.
* **Use `_rawData`/`_fullRows` side channels**: These fields carry full data to the frontend without going through the AI model.
* **Use Zod strictly**: Our shared `packages/utils` ensure that AI-generated data is validated before hitting the database.