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

# Overview

> OpenAI-powered conversational agent for OLIVE wallet operations

# Agent-TS Overview

Agent-TS is the TypeScript implementation of the OLIVE conversational agent, powered by OpenAI's Assistant API with function calling capabilities.

## Purpose

The agent provides an automated conversational interface for OLIVE mobile-money users, enabling self-service operations through natural language:

<CardGroup cols={2}>
  <Card title="WhatsApp Integration" icon="message">
    Handles user messages from WhatsApp Business API and external clients
  </Card>

  <Card title="Wallet Operations" icon="wallet">
    Check balance, send money, view transactions, manage linked cards
  </Card>

  <Card title="KYC Processing" icon="id-card">
    Upload and validate identity documents with OCR and fraud detection
  </Card>

  <Card title="Natural Language" icon="brain">
    OpenAI-powered intent recognition and response generation
  </Card>
</CardGroup>

## Key Features

### OpenAI Function Calling

The agent leverages OpenAI's function calling to execute wallet operations:

```typescript theme={null}
// Example: User asks "What is my balance?"
// OpenAI recognizes intent and calls check_balance function

const tools = [
  {
    type: "function",
    function: {
      name: "check_balance",
      description: "Get the user's current wallet balance",
      parameters: {
        type: "object",
        properties: {
          currency: { type: "string", enum: ["SLE", "USD"] }
        }
      }
    }
  }
];
```

### Available Operations

| Operation            | Description                                 |
| -------------------- | ------------------------------------------- |
| `check_balance`      | Get current wallet balance                  |
| `get_transactions`   | View transaction history                    |
| `initiate_transfer`  | Send money to another user or card          |
| `get_account_limits` | Check spending and transaction limits       |
| `get_user_cards`     | List linked NFC cards                       |
| `link_card`          | Activate and link a new card                |
| `block_card`         | Freeze a card                               |
| `unblock_card`       | Reactivate a blocked card                   |
| `upload_kyc_image`   | Submit KYC document for verification        |
| `upgrade_kyc`        | Complete KYC upgrade with front/back images |

### KYC Fraud Detection

Multi-layer validation for Sierra Leone National ID cards:

1. **OpenAI Vision API** - Document authenticity validation
2. **Tesseract OCR** - Text extraction and tampering detection
3. **Cross-Validation** - Data consistency between front and back images

## Architecture

```mermaid theme={null}
graph LR
    subgraph Input
        WH[WhatsApp Webhook]
    end

    subgraph Agent
        EX[Express Server]
        OA[Olive Agent]
        TL[Tool Handlers]
    end

    subgraph Services
        GC[Gateway Client]
        S3[S3 Uploader]
        OCR[OCR Service]
        ID[ID Validator]
    end

    subgraph External
        OAI[OpenAI API]
        GW[OLIVE Gateway]
        AWS[AWS S3]
    end

    WH --> EX
    EX --> OA
    OA --> OAI
    OA --> TL
    TL --> GC
    TL --> S3
    TL --> OCR
    TL --> ID
    GC --> GW
    S3 --> AWS
    ID --> OAI
```

## User Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant A as Agent-TS
    participant O as OpenAI
    participant G as Gateway

    U->>A: "Send 5000 to +23279123456"
    A->>O: Chat completion request
    O-->>A: Function call: initiate_transfer
    A->>G: POST /wallet/transfer-p2p
    G-->>A: Transfer result
    A->>O: Function result
    O-->>A: "Transfer of 5,000 SLE sent successfully"
    A-->>U: Response message
```

## Quick Start

### Prerequisites

* Node.js 18+
* OpenAI API key
* Gateway API key
* AWS credentials (for KYC document storage)

### Installation

```bash theme={null}
cd agent-ts
npm install
cp .env.example .env
# Edit .env with your configuration
npm run dev
```

### Docker

```bash theme={null}
docker compose up -d --build agent
```

## Project Structure

```
agent-ts/
├── src/
│   ├── index.ts              # Express server & webhooks
│   ├── olive-agent.ts        # OpenAI Agent implementation
│   ├── gateway-client.ts     # Gateway API client
│   ├── tools/
│   │   ├── wallet.ts         # Balance, transfers
│   │   ├── cards.ts          # Card operations
│   │   ├── kyc.ts            # KYC upload & validation
│   │   └── registration.ts   # User registration
│   ├── ocr-service.ts        # Tesseract OCR
│   ├── id-card-validator.ts  # Vision AI validation
│   └── s3-uploader.ts        # KYC document storage
├── Dockerfile
└── package.json
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/agent-ts/configuration">
    Environment variables and setup
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/agent-ts/tools">
    Complete tool documentation
  </Card>

  <Card title="KYC Validation" icon="shield-check" href="/agent-ts/kyc-validation">
    OCR and fraud detection details
  </Card>

  <Card title="Webhooks" icon="webhook" href="/agent-ts/webhooks">
    WhatsApp integration setup
  </Card>
</CardGroup>