@restnfeel/agentc-starter-kit/src/lib/chatbot/docs/INTEGRATION_GUIDE.md

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

# Integration Guide

This guide provides step-by-step instructions for integrating the RAG Chatbot Library into different types of applications.

## Table of Contents

- [Next.js Integration](#nextjs-integration)
- [React App Integration](#react-app-integration)
- [Supabase Setup](#supabase-setup)
- [Environment Configuration](#environment-configuration)
- [Production Deployment](#production-deployment)
- [Troubleshooting](#troubleshooting)

## Next.js Integration

### 1. Installation

```bash
npm install @restnfeel/agentc-starter-kit
npm install @supabase/supabase-js @prisma/client
```

### 2. Environment Setup

Create a `.env.local` file in your project root:

```env
# OpenAI Configuration
NEXT_PUBLIC_OPENAI_API_KEY=your_openai_api_key

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Optional: Anthropic for alternative LLM
NEXT_PUBLIC_ANTHROPIC_API_KEY=your_anthropic_api_key
```

### 3. Basic Implementation

#### App Router (app directory)

Create `app/chat/page.tsx`:

```tsx
"use client";

import {
  ChatbotProvider,
  ChatbotWidget,
} from "@restnfeel/agentc-starter-kit/chatbot";

export default function ChatPage() {
  const config = {
    llm: {
      provider: "openai" as const,
      model: "gpt-3.5-turbo",
      apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY!,
    },
    vectorStore: {
      provider: "supabase" as const,
      url: process.env.NEXT_PUBLIC_SUPABASE_URL!,
      apiKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
      dimensions: 1536,
    },
  };

  return (
    <ChatbotProvider config={config}>
      <div className="container mx-auto p-8">
        <h1 className="text-3xl font-bold mb-8">AI Chat Assistant</h1>
        <ChatbotWidget position="bottom-right" />
      </div>
    </ChatbotProvider>
  );
}
```

#### Pages Router (pages directory)

Create `pages/chat.tsx`:

```tsx
import {
  ChatbotProvider,
  ChatbotWidget,
} from "@restnfeel/agentc-starter-kit/chatbot";
import { GetStaticProps } from "next";

interface ChatPageProps {
  config: any;
}

export default function ChatPage({ config }: ChatPageProps) {
  return (
    <ChatbotProvider config={config}>
      <div className="container mx-auto p-8">
        <h1 className="text-3xl font-bold mb-8">AI Chat Assistant</h1>
        <ChatbotWidget position="bottom-right" />
      </div>
    </ChatbotProvider>
  );
}

export const getStaticProps: GetStaticProps = async () => {
  const config = {
    llm: {
      provider: "openai" as const,
      model: "gpt-3.5-turbo",
      apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY!,
    },
    vectorStore: {
      provider: "supabase" as const,
      url: process.env.NEXT_PUBLIC_SUPABASE_URL!,
      apiKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
      dimensions: 1536,
    },
  };

  return {
    props: {
      config,
    },
  };
};
```

### 4. Advanced Next.js Setup with API Routes

Create `pages/api/chatbot/[...params].ts`:

```tsx
import { NextApiRequest, NextApiResponse } from "next";
import { ChatbotAPI } from "@restnfeel/agentc-starter-kit/chatbot/core";

const api = new ChatbotAPI();

// Initialize API on first request
let initialized = false;

async function ensureInitialized() {
  if (!initialized) {
    await api.initialize({
      llm: {
        provider: "openai",
        model: "gpt-3.5-turbo",
        apiKey: process.env.OPENAI_API_KEY!,
      },
      vectorStore: {
        provider: "supabase",
        url: process.env.SUPABASE_URL!,
        apiKey: process.env.SUPABASE_SERVICE_ROLE_KEY!,
        dimensions: 1536,
      },
    });
    initialized = true;
  }
}

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  try {
    await ensureInitialized();

    const { params } = req.query;
    const action = params?.[0];

    switch (action) {
      case "message":
        if (req.method === "POST") {
          const { content, conversationId } = req.body;
          const result = await api.sendMessage(content, conversationId);
          return res.status(200).json(result);
        }
        break;

      case "upload":
        if (req.method === "POST") {
          // Handle file upload
          const { file, metadata } = req.body;
          const result = await api.uploadDocument(file, metadata);
          return res.status(200).json(result);
        }
        break;

      case "search":
        if (req.method === "GET") {
          const { q, limit } = req.query;
          const result = await api.searchSimilarDocuments(
            q as string,
            Number(limit) || 10
          );
          return res.status(200).json(result);
        }
        break;

      default:
        return res.status(404).json({ error: "Endpoint not found" });
    }
  } catch (error) {
    console.error("API Error:", error);
    return res.status(500).json({ error: "Internal server error" });
  }
}
```

## React App Integration

### 1. Create React App Setup

```bash
npx create-react-app my-chatbot-app --template typescript
cd my-chatbot-app
npm install @restnfeel/agentc-starter-kit @supabase/supabase-js
```

### 2. Basic Integration

Update `src/App.tsx`:

```tsx
import React from "react";
import {
  ChatbotProvider,
  ChatbotWidget,
} from "@restnfeel/agentc-starter-kit/chatbot";
import "./App.css";

const chatbotConfig = {
  llm: {
    provider: "openai" as const,
    model: "gpt-3.5-turbo",
    apiKey: process.env.REACT_APP_OPENAI_API_KEY!,
  },
  vectorStore: {
    provider: "memory" as const, // Use memory for development
    dimensions: 1536,
  },
};

function App() {
  return (
    <div className="App">
      <ChatbotProvider config={chatbotConfig}>
        <header className="App-header">
          <h1>My App with AI Assistant</h1>
          <p>
            Your application content goes here. The chatbot will appear as a
            floating widget.
          </p>
        </header>

        <ChatbotWidget position="bottom-right" showSuggestedQuestions={true} />
      </ChatbotProvider>
    </div>
  );
}

export default App;
```

### 3. Environment Variables for React

Create `.env` file:

```env
REACT_APP_OPENAI_API_KEY=your_openai_api_key
REACT_APP_SUPABASE_URL=your_supabase_url
REACT_APP_SUPABASE_ANON_KEY=your_supabase_anon_key
```

## Supabase Setup

### 1. Create Supabase Project

1. Go to [supabase.com](https://supabase.com)
2. Create a new project
3. Note your project URL and anon key

### 2. Database Setup

Execute these SQL commands in the Supabase SQL editor:

```sql
-- Enable necessary extensions
CREATE EXTENSION IF NOT EXISTS "vector";
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Create documents table
CREATE TABLE documents (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  content TEXT NOT NULL,
  metadata JSONB DEFAULT '{}',
  embedding VECTOR(1536),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Create conversations table
CREATE TABLE conversations (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  title VARCHAR(255) NOT NULL DEFAULT 'New Conversation',
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Create messages table
CREATE TABLE messages (
  id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
  conversation_id UUID REFERENCES conversations(id) ON DELETE CASCADE,
  role VARCHAR(20) NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
  content TEXT NOT NULL,
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Create indexes for better performance
CREATE INDEX idx_documents_embedding ON documents USING ivfflat (embedding vector_cosine_ops);
CREATE INDEX idx_messages_conversation_id ON messages(conversation_id);
CREATE INDEX idx_documents_metadata ON documents USING gin(metadata);

-- Row Level Security (RLS) policies
ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
ALTER TABLE conversations ENABLE ROW LEVEL SECURITY;
ALTER TABLE messages ENABLE ROW LEVEL SECURITY;

-- Allow all operations for authenticated users (adjust as needed)
CREATE POLICY "Allow all for authenticated users" ON documents
  FOR ALL USING (auth.role() = 'authenticated');

CREATE POLICY "Allow all for authenticated users" ON conversations
  FOR ALL USING (auth.role() = 'authenticated');

CREATE POLICY "Allow all for authenticated users" ON messages
  FOR ALL USING (auth.role() = 'authenticated');
```

### 3. Storage Setup

Create a storage bucket for documents:

```sql
-- Create storage bucket for documents
INSERT INTO storage.buckets (id, name, public) VALUES ('documents', 'documents', false);

-- Create storage policy
CREATE POLICY "Allow authenticated uploads" ON storage.objects
  FOR INSERT WITH CHECK (bucket_id = 'documents' AND auth.role() = 'authenticated');

CREATE POLICY "Allow authenticated reads" ON storage.objects
  FOR SELECT USING (bucket_id = 'documents' AND auth.role() = 'authenticated');
```

## Environment Configuration

### Development Environment

```env
# AI Provider Configuration
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Optional: Custom Configuration
CHATBOT_MAX_TOKENS=1000
CHATBOT_TEMPERATURE=0.7
CHATBOT_LOG_LEVEL=debug
```

### Production Environment

```env
# Use environment-specific values
NODE_ENV=production

# AI Provider Configuration
OPENAI_API_KEY=${OPENAI_API_KEY}
ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

# Supabase Configuration
SUPABASE_URL=${SUPABASE_URL}
SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
SUPABASE_SERVICE_ROLE_KEY=${SUPABASE_SERVICE_ROLE_KEY}

# Production Optimizations
CHATBOT_MAX_TOKENS=2000
CHATBOT_TEMPERATURE=0.5
CHATBOT_LOG_LEVEL=error
```

## Production Deployment

### Vercel Deployment

1. **Prepare your project:**

```bash
npm run build
```

2. **Set environment variables in Vercel dashboard:**

   - `NEXT_PUBLIC_OPENAI_API_KEY`
   - `NEXT_PUBLIC_SUPABASE_URL`
   - `NEXT_PUBLIC_SUPABASE_ANON_KEY`

3. **Deploy:**

```bash
npx vercel
```

### Netlify Deployment

1. **Build command:** `npm run build`
2. **Publish directory:** `dist` or `build`
3. **Environment variables:**
   - `REACT_APP_OPENAI_API_KEY`
   - `REACT_APP_SUPABASE_URL`
   - `REACT_APP_SUPABASE_ANON_KEY`

### Docker Deployment

Create `Dockerfile`:

```dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]
```

Create `docker-compose.yml`:

```yaml
version: "3.8"
services:
  chatbot-app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
    restart: unless-stopped
```

## Performance Optimization

### 1. Lazy Loading

```tsx
import { lazy, Suspense } from "react";

const ChatbotWidget = lazy(() =>
  import("@restnfeel/agentc-starter-kit/chatbot").then((module) => ({
    default: module.ChatbotWidget,
  }))
);

function App() {
  return (
    <div>
      <Suspense fallback={<div>Loading chat...</div>}>
        <ChatbotWidget />
      </Suspense>
    </div>
  );
}
```

### 2. Caching Configuration

```tsx
const config = useMemo(
  () => ({
    llm: {
      provider: "openai" as const,
      model: "gpt-3.5-turbo",
      apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY!,
    },
    vectorStore: {
      provider: "supabase" as const,
      url: process.env.NEXT_PUBLIC_SUPABASE_URL!,
      apiKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
      dimensions: 1536,
    },
  }),
  []
);
```

### 3. Bundle Analysis

```bash
# Analyze bundle size
npm install --save-dev @next/bundle-analyzer

# Add to next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
});

module.exports = withBundleAnalyzer({
  // your next config
});

# Run analysis
ANALYZE=true npm run build
```

## Troubleshooting

### Common Issues

#### 1. "Module not found" errors

**Problem:** Import errors when using the library

**Solution:**

```tsx
// ✅ Correct import
import { ChatbotProvider } from "@restnfeel/agentc-starter-kit/chatbot";

// ❌ Incorrect import
import { ChatbotProvider } from "@restnfeel/agentc-starter-kit/chatbot/core";
```

#### 2. API Key not working

**Problem:** API requests failing with authentication errors

**Solution:**

- Verify API key is correctly set in environment variables
- Check the key has the correct permissions
- Ensure the key is not expired

```tsx
// Add error handling
const config = {
  llm: {
    provider: "openai" as const,
    model: "gpt-3.5-turbo",
    apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY || "",
  },
};

// Validate API key
if (!config.llm.apiKey) {
  console.error("OpenAI API key is required");
}
```

#### 3. Supabase connection issues

**Problem:** Cannot connect to Supabase

**Solution:**

- Verify URL and keys are correct
- Check RLS policies allow your operations
- Ensure database schema is properly set up

```tsx
import { createClient } from "@supabase/supabase-js";

// Test connection
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// Test query
const testConnection = async () => {
  const { data, error } = await supabase.from("documents").select("count");
  if (error) {
    console.error("Supabase connection failed:", error);
  } else {
    console.log("Supabase connected successfully");
  }
};
```

#### 4. Build errors in production

**Problem:** TypeScript or build errors in production

**Solution:**

- Ensure all dependencies are installed
- Check TypeScript configuration
- Verify environment variables are available

```json
// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "jsx": "react-jsx",
    "strict": true
  }
}
```

### Debug Mode

Enable debug logging:

```tsx
const config = {
  // ... other config
  debug: process.env.NODE_ENV === "development",
  onError: (error) => {
    console.error("Chatbot Error:", error);
    // Send to error tracking service in production
  },
};
```

### Performance Monitoring

```tsx
import { useChatbot } from "@restnfeel/agentc-starter-kit/chatbot";

function PerformanceMonitor() {
  const { isProcessing } = useChatbot();

  useEffect(() => {
    if (isProcessing) {
      const start = performance.now();

      return () => {
        const duration = performance.now() - start;
        console.log(`Response time: ${duration}ms`);
      };
    }
  }, [isProcessing]);

  return null;
}
```

## Support

For additional help:

- 📖 [API Documentation](./API.md)
- 🐛 [GitHub Issues](https://github.com/restnfeel/agentc-starter-kit/issues)
- 💬 [Discord Community](https://discord.gg/restnfeel)
- 📧 [Email Support](mailto:support@restnfeel.com)