AI Agent

The AI agent provides a chat-based financial assistant powered by OpenAI's function calling.

Overview

The agent lives in the agent app and has no models or migrations -- it's a stateless service that processes chat messages and calls tools against the user's data.

Available Functions

The agent has access to 6 tools via OpenAI function calling:

Function	Description
get_transactions(filters)	Query user's transactions with optional filters
get_spending_summary(period, category)	Aggregated spending data by period/category
get_budget_status()	Current budget utilization across all budgets
create_transaction(data)	Add a new expense or income transaction
get_category_list()	List available categories
get_recurring_rules()	List user's recurring transactions

System Prompt Context

Each request injects the following context into the system prompt:

• Current month's spending totals by category
• Active budget limits and utilization percentages
• User's currency preference (PHP or USD)
• Current date/time in Philippine timezone

API Endpoints

Method	Endpoint	Description
POST	/api/v1/agent/chat/	Send a message to the AI agent
GET	/api/v1/agent/quick-actions/	List quick action prompts

Chat Request

{
    "message": "How much did I spend on food this month?"
}

Chat Response

{
    "response": "You've spent PHP 5,432.50 on food this month across 12 transactions...",
    "tool_calls": [
        {
            "function": "get_spending_summary",
            "arguments": {"period": "month", "category": "food"}
        }
    ]
}

Quick Actions

Predefined prompts shown as chips in the mobile UI:

• "How much did I spend this month?"
• "What's my budget status?"
• "Show my recent transactions"
• "Add an expense"

Rate Limits

• 50 agent requests per user per day
• 3,000 input tokens per request maximum
• 30-second timeout per request

Tool Execution Loop

The agent uses a tool loop pattern:

1. Send user message + system context to OpenAI
2. If the response includes tool calls, execute them against the user's data
3. Send tool results back to OpenAI
4. Repeat until OpenAI returns a final text response (no more tool calls)
5. Return the final response to the client