# @restnfeel/agentc-starter-kit

🚀 **완전한 AI 챗봇 솔루션 라이브러리**

RAG(Retrieval-Augmented Generation) 기반 AI 챗봇을 웹사이트에 쉽게 통합하고, 관리자 도구로 완전히 관리할 수 있는 React 컴포넌트 패키지입니다.

[![npm version](https://badge.fury.io/js/@restnfeel%2Fagentc-starter-kit.svg)](https://badge.fury.io/js/@restnfeel%2Fagentc-starter-kit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 주요 특징

- 🎯 **핵심 컴포넌트**: 챗봇(2개) + 관리자(6개) 컴포넌트로 완전한 솔루션
- 📱 **완전 반응형**: 데스크톱과 모바일 모두 최적화된 UI/UX
- 🎨 **커스터마이징 가능**: 테마, 색상, 위치 등 자유로운 스타일링
- 🔌 **RAG API 호환**: 문서 기반 AI 응답 시스템과 바로 연동
- ⚙️ **완전한 관리자 도구**: 문서 업로드, RSS 관리, 에이전트 설정까지
- 📦 **제로 설정**: 설치 후 바로 사용 가능
- 🛡️ **TypeScript 지원**: 완전한 타입 안전성

## 📦 설치

```bash
npm install @restnfeel/agentc-starter-kit
```

## 🚀 빠른 시작

### 1️⃣ FloatingChatButton (권장)

대부분의 웹사이트에 적합한 플로팅 챗봇 버튼입니다.

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

export default function App() {
  return (
    <div>
      <h1>내 웹사이트</h1>

      {/* 우측 하단에 플로팅 챗봇 */}
      <FloatingChatButton
        apiEndpoint="/api/rag/answer"
        position="bottom-right"
        theme="light"
      />
    </div>
  );
}
```

### 2️⃣ MobileFullscreenChat (모바일 최적화)

모바일에서 전체화면 채팅 경험이 필요한 경우 사용합니다.

```tsx
import { MobileFullscreenChat } from "@restnfeel/agentc-starter-kit";
import { useState } from "react";

export default function MobileApp() {
  const [isChatOpen, setIsChatOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsChatOpen(true)}>고객지원 채팅</button>

      <MobileFullscreenChat
        isOpen={isChatOpen}
        onClose={() => setIsChatOpen(false)}
        apiEndpoint="/api/rag/answer"
      />
    </div>
  );
}
```

## 🎯 실제 사용 예시

### 💼 비즈니스 웹사이트

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

export default function BusinessSite() {
  return (
    <>
      <main>
        <h1>우리 회사 소개</h1>
        <p>회사 내용...</p>
      </main>

      {/* 24/7 고객지원 챗봇 */}
      <FloatingChatButton
        apiEndpoint="/api/customer-support"
        initialMessage="안녕하세요! 궁금한 것이 있으시면 언제든 물어보세요."
        customStyles={{
          backgroundColor: "#2563eb",
          color: "white",
        }}
      />
    </>
  );
}
```

### 🛍️ 전자상거래 사이트

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

export default function EcommerceSite() {
  return (
    <>
      <ProductList />

      {/* 쇼핑 도우미 챗봇 */}
      <FloatingChatButton
        apiEndpoint="/api/shopping-assistant"
        position="bottom-left"
        size="large"
        initialMessage="상품에 대해 궁금한 점이 있으시면 물어보세요!"
      />
    </>
  );
}
```

### 3️⃣ RAG Admin Components (관리자용)

관리자 대시보드에서 AI 챗봇을 설정하고 관리할 수 있는 컴포넌트들입니다.

```tsx
import {
  RAGAdminIntegrated, // 통합 관리자 컴포넌트 (권장)
  RAGManager, // RAG 테스트
  DocumentUploader, // 문서 업로드
  RSSManager, // RSS 관리
  QALearningManager, // Q&A 학습
  AgentConfigManager, // 에이전트 설정
} from "@restnfeel/agentc-starter-kit";

// 모든 관리 기능이 포함된 통합 컴포넌트 (권장)
function AdminPage() {
  return (
    <RAGAdminIntegrated
      title="AI 챗봇 관리"
      subtitle="문서 업로드, RSS 관리, 에이전트 설정"
      defaultTab="search"
    />
  );
}

// 또는 개별 컴포넌트 사용
function CustomAdminPage() {
  return (
    <div>
      <h1>AI 챗봇 관리</h1>
      <RAGManager /> {/* RAG 답변 테스트 */}
      <DocumentUploader /> {/* 문서 업로드 */}
      <RSSManager /> {/* RSS 피드 관리 */}
      <QALearningManager /> {/* Q&A 학습 */}
      <AgentConfigManager /> {/* 에이전트 설정 */}
    </div>
  );
}
```

## ⚙️ API 참조

### FloatingChatButton Props

| Prop             | Type                                                           | Default             | 설명           |
| ---------------- | -------------------------------------------------------------- | ------------------- | -------------- |
| `theme`          | `"light" \| "dark"`                                            | `"light"`           | 테마           |
| `position`       | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"`    | 버튼 위치      |
| `size`           | `"small" \| "medium" \| "large"`                               | `"medium"`          | 버튼 크기      |
| `apiEndpoint`    | `string`                                                       | `"/api/rag/answer"` | API 엔드포인트 |
| `initialMessage` | `string`                                                       | -                   | 초기 인사말    |
| `customStyles`   | `React.CSSProperties`                                          | -                   | 커스텀 CSS     |

### MobileFullscreenChat Props

| Prop             | Type                | Default             | 설명             |
| ---------------- | ------------------- | ------------------- | ---------------- |
| `isOpen`         | `boolean`           | -                   | 채팅창 열림 상태 |
| `onClose`        | `() => void`        | -                   | 닫기 콜백        |
| `theme`          | `"light" \| "dark"` | `"light"`           | 테마             |
| `apiEndpoint`    | `string`            | `"/api/rag/answer"` | API 엔드포인트   |
| `initialMessage` | `string`            | -                   | 초기 인사말      |

### RAGAdminIntegrated Props

| Prop             | Type      | Default    | 설명                                                         |
| ---------------- | --------- | ---------- | ------------------------------------------------------------ |
| `title`          | `string`  | -          | 관리자 패널 제목                                             |
| `subtitle`       | `string`  | -          | 관리자 패널 부제목                                           |
| `defaultTab`     | `string`  | `"search"` | 기본 탭 ("search", "upload", "rss", "qa", "chunks", "agent") |
| `className`      | `string`  | -          | 커스텀 CSS 클래스                                            |
| `showNavigation` | `boolean` | `true`     | 네비게이션 표시 여부                                         |

### 개별 Admin Components

각 관리자 컴포넌트는 독립적으로 사용할 수 있습니다:

- **`RAGManager`**: RAG 시스템 테스트 및 답변 확인
- **`DocumentUploader`**: 문서 업로드 및 벡터화
- **`RSSManager`**: RSS 피드 관리 및 자동 업데이트
- **`QALearningManager`**: Q&A 학습 데이터 관리
- **`AgentConfigManager`**: 에이전트 설정 (이름, 성격, 인사말 등)

## 🎨 커스터마이징

### 테마 변경

```tsx
// 다크 테마
<FloatingChatButton theme="dark" />

// 커스텀 색상
<FloatingChatButton
  customStyles={{
    backgroundColor: "#16a085",
    color: "white",
    borderRadius: "50%"
  }}
/>
```

### 위치 및 크기 조정

```tsx
// 좌측 하단, 큰 크기
<FloatingChatButton
  position="bottom-left"
  size="large"
/>

// 우측 상단, 작은 크기
<FloatingChatButton
  position="top-right"
  size="small"
/>
```

## 🔌 백엔드 API 연동

챗봇은 다음 형식의 API 응답을 기대합니다:

```json
{
  "answer": "AI가 생성한 응답 텍스트",
  "sources": [
    {
      "title": "참고 문서 제목",
      "score": 0.95
    }
  ]
}
```

### Next.js API Route 예시

```tsx
// app/api/rag/answer/route.ts
export async function POST(request: Request) {
  const { query, history } = await request.json();

  // RAG 시스템 호출
  const answer = await ragSystem.generateAnswer(query, history);

  return Response.json({
    answer: answer.text,
    sources: answer.sources,
  });
}
```

## 📱 반응형 동작

`FloatingChatButton`은 자동으로 반응형으로 동작합니다:

- **데스크톱**: 우측 하단 플로팅 팝업 창
- **모바일**: 전체화면 채팅 모드

더 세밀한 제어가 필요하다면 두 컴포넌트를 조합해서 사용하세요.

## 🛠️ 개발 환경 설정

### Tailwind CSS 설정

```js
// tailwind.config.js
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@restnfeel/agentc-starter-kit/**/*.{js,ts,jsx,tsx}",
  ],
  // ... 기타 설정
};
```

### TypeScript 지원

패키지는 완전한 TypeScript 지원을 제공합니다:

```tsx
import type {
  FloatingButtonProps,
  MobileFullscreenChatProps,
  Message,
  ChatSession,
} from "@restnfeel/agentc-starter-kit";
```

## 📊 로드맵

- [ ] 🎨 더 많은 테마 옵션
- [ ] 🌍 다국어 지원 (i18n)
- [ ] 📈 분석 및 메트릭스
- [ ] 🔊 음성 채팅 지원
- [ ] 📎 파일 업로드 지원

## 🤝 기여하기

이슈 및 풀 리퀘스트를 환영합니다!

## 📄 라이선스

MIT License - 자유롭게 사용하세요!

## 💬 지원

- 📧 이메일: support@restnfeel.com
- 📚 문서: [문서 사이트 URL]
- 🐛 버그 리포트: [GitHub Issues]

---

**AgentC Starter Kit**으로 멋진 AI 챗봇을 만들어보세요! 🚀