Skip to main content

​
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:
IntentExampleTools 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: 
// 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

LayerConfiguration
Client hookuseChat from @ai-sdk/react with maxSteps: 10
TransportDefaultChatTransport with api URL including ?chatId= query param
ServerstreamText from ai with stopWhen: stepCountIs(10)
Modelgemini-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:
ToolPurpose
listAvailableAPIsDiscover all API endpoints
getAPIDetailsGet full schema for one endpoint
callAPIExecute an API call (returns smart summary)
getReportableFieldsDiscover columns/joins for a report entity
buildReportBuild structured report (returns metadata, not rows)
saveReportPersist a report configuration
generateArtifactGenerate 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.