🤖 OCI-based High-Availability KakaoTalk AI Chatbot

This project is an AI Chatbot for KakaoTalk Open Builder, deployed on Oracle Cloud Infrastructure (OCI). It utilizes FastAPI for asynchronous processing to overcome KakaoTalk's strict 5-second response timeout, integrating LLM (OpenAI) and Web Search capabilities to provide intelligent, context-aware responses.

🏗 System Architecture

The system follows a secure 2-Tier Architecture on OCI, separating public ingress from private application logic.

graph TD
    User([User]) -->|KakaoTalk API| LB["OCI Load Balancer (Public Subnet)"]
    LB -->|HTTPS /healthcheck| Nginx["Nginx Reverse Proxy (Private Instance)"]
    
    subgraph "Private Network (Security Enhanced)"
        Nginx -->|Proxy Pass :8000| App["FastAPI Application"]
        App <-->|History & Context| Redis[("Redis")]
    end
    
    subgraph "External Integrations"
        App <-->|LLM Query| OpenAI["LLM Provider (AX/OpenAI)"]
        App <-->|Search| Search["Search Agent (Tavily/DDG)"]
        App -.->|Async Callback| Kakao["Kakao API Server"]
    end

    Bastion["Bastion Host"] -.->|SSH Tunnel| Nginx

Loading

Infrastructure Highlights

• OCI Load Balancer: Handles SSL termination (Let's Encrypt) and performs round-robin distribution with health checks (/healthcheck).
• Network Security:
  • Public Subnet: Contains only the Load Balancer and Bastion Host.
  • Private Subnet: Hosts the application server, accessible only via the Load Balancer (HTTP) or Bastion (SSH).
• Nginx Proxy: Acts as a reverse proxy, forwarding traffic from port 80 to the FastAPI app on port 8000, and adding security headers.

✨ Key Features

1. Smart Search Agent

• Context Awareness: The bot analyzes the user's query to determine if real-time information (news, weather, facts) is required.
• Web Integration: Uses Tavily or DuckDuckGo to fetch live data if the LLM's internal knowledge is insufficient.
• Synthesis: Combines search results with LLM capabilities to generate accurate, referenced answers.

2. Async Callback Handling (Timeout Protection)

• Problem: KakaoTalk Open Builder requires a response within 5 seconds. Complex LLM queries often take longer.
• Solution:
  • If the answer is ready within 4.5 seconds (SKILL_TIMEOUT), it returns immediately.
  • If delayed, it sends a "waiting" response (useCallback: true) and processes the logic in the background.
  • Once complete, the final answer is sent via the Kakao Callback API.

3. Conversation History

• Redis Backend: Stores user chat history (up to N_HISTORY turns) to maintain context across multiple interactions.
• TTL Management: Sessions automatically expire after a set period to manage memory efficiently.

📂 Project Structure

app/
├── main.py             # Core FastAPI application (LLM logic, Search, Routes)
├── runner.py           # Uvicorn launcher with custom HealthCheck log filtering
├── .env.default        # Environment variable template
└── requirements.txt    # Dependencies

🚀 Installation & Setup

1. Prerequisites

• Python 3.11+
• Redis Server
• Oracle Cloud Account (for infrastructure)
• KakaoTalk Channel Admin Access

2. Environment Configuration

Copy .env.default to .env and configure the following:

# --- Core ---
SKILL_TIMEOUT=4.5           # Safety margin for Kakao's 5s timeout
N_HISTORY=20                # Number of conversation turns to remember

# --- API Keys ---
AX_API_URL=https://...      # LLM API Endpoint
AX_API_KEY=sk-...           # LLM API Key
TAVILY_API_KEY=tvly-...     # (Optional) For specialized web search

# --- Redis ---
REDIS_HOST=localhost
REDIS_PORT=6379

# --- Kakao ---
KAKAO_ADMIN_KEY=...         # For future administrative features

3. Running the Application

Use runner.py to start the server. It includes a custom logging filter to suppress noise from Load Balancer health checks.

# Install dependencies
pip install -r requirements.txt

# Run server
python runner.py

The server will start on 0.0.0.0:8000.

⚙️ Kakao Open Builder Configuration

To connect this bot to KakaoTalk, configure your Skill settings as follows:

1. Skill URL: https://<YOUR_DOMAIN>/basic
2. Fallback Block:
   • Set this skill as the default for the Fallback Block.
   • Bot Response: Check "Use Skill Data".
3. Callback Settings:
   • Enable Callback.
   • Timeout Message: "Answers are being prepared. Please wait a moment!"

🛡 Security Note

• This project is designed to run behind a Firewall or Security List.
• Ensure port 8000 is NOT exposed directly to the public internet. It should only accept traffic from the Nginx proxy (localhost or private subnet).