ai-agent-personal-finance-assistant
このプロジェクトは、個人の財務管理を支援するAIエージェントを開発することを目的としています。ユーザーの収入や支出を分析し、予算を提案する機能を持っています。TypeScriptで実装されており、拡張性が高い設計が特徴です。
GitHubスター
0
ユーザー評価
未評価
フォーク
0
イシュー
0
閲覧数
3
お気に入り
0
README
RAG Next.js TypeScript Application
A modern Retrieval-Augmented Generation (RAG) chat application built with Next.js, TypeScript, and powered by OpenAI's GPT models with vector-based document retrieval using Vectorize.io.
🚀 Features
- AI-Powered Chat: Interactive chat interface with GPT-4o-mini
- Document Retrieval: RAG system that retrieves relevant context from vectorized documents
- Real-time Sources: View document sources that inform AI responses
- Modern UI: Clean, responsive interface built with Tailwind CSS
- Type Safety: Full TypeScript implementation
🛠️ Tech Stack
- Framework: Next.js 15 with App Router
- Language: TypeScript
- AI/ML: OpenAI GPT-4o-mini, AI SDK
- Vector Database: Vectorize.io
- Styling: Tailwind CSS
- Icons: Lucide React
📋 Prerequisites
Before setting up this project, you'll need:
- Node.js (v18 or higher)
- pnpm: Install pnpm
- OpenAI API Key: Get one here
- Vectorize.io Account: Sign up here
🔧 Installation
Install dependencies
pnpm installSet up environment variables
Create a
.env.localfile in the root directory of your project:# Create the file (from project root) touch .env.localOpen the file in your editor and add the following variables:
# OpenAI Configuration OPENAI_API_KEY=your_openai_api_key_here # Vectorize.io Configuration VECTORIZE_PIPELINE_ACCESS_TOKEN=your_vectorize_access_token_here VECTORIZE_ORGANIZATION_ID=your_vectorize_organization_id_here VECTORIZE_PIPELINE_ID=your_vectorize_pipeline_id_hereImportant: The
.env.localfile is automatically ignored by git, keeping your API keys secure.
🔑 Environment Variables Setup
OpenAI API Key
- Visit OpenAI Platform
- Sign in or create an account
- Click "Create new secret key"
- Give your key a name (e.g., "rag-next-app")
- Copy the generated key immediately (you won't see it again!)
- In your
.env.localfile, replaceyour_openai_api_key_herewith your actual key:OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx
Vectorize.io Configuration
- Sign up at Vectorize.io
- Create a new organization
- Navigate to your organization settings
- Create a new pipeline:
- Choose "Document Retrieval" as the pipeline type
- Configure your pipeline settings
- Save the pipeline
- Generate an access token:
- Go to "API Tokens" in your organization settings
- Create a new token with "Retrieval Access" permissions
- Copy the token
- From your Vectorize dashboard, copy these values to your
.env.local:VECTORIZE_PIPELINE_ACCESS_TOKEN=eyJhbGciOi... (your full token) VECTORIZE_ORGANIZATION_ID=527d9a27-c34a-4d0a-8fde-... (your org ID) VECTORIZE_PIPELINE_ID=aip0c318-344a-4721-a9e7-... (your pipeline ID)
Verifying Your Setup
After adding all environment variables, your .env.local file should look similar to this:
# OpenAI Configuration
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx
# Vectorize.io Configuration
VECTORIZE_PIPELINE_ACCESS_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
VECTORIZE_ORGANIZATION_ID=527d9a27-c34a-4d0a-8fde-1129a57eb5b8
VECTORIZE_PIPELINE_ID=aip0c318-344a-4721-a9e7-5526c96d9b49
Note: Never commit your .env.local file to version control!
🚀 Getting Started
Start the development server
pnpm devOpen your browser
Navigate to http://localhost:3000
Test the application
- Visit the main page to see the Next.js welcome screen
- Go to
/vectorizeto access the RAG chat interface - Start asking questions about your vectorized documents
🏗️ Application Architecture
Sequence Diagram
The following sequence diagram illustrates the complete interaction flow for both RAG Chat and Agent Chat functionalities:
This diagram shows the step-by-step interactions between users, frontend components, API endpoints, services, and external APIs for both RAG and Agent chat flows.
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ FRONTEND (Next.js) │
├─────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ / (Home) │ │ /vectorize │ │ /agent │ │
│ │ page.tsx │ │ page.tsx │ │ page.tsx │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ chat.tsx │ │ agent-chat.tsx │ │
│ │ (RAG Chat UI) │ │ (Agent Chat UI) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │ │
│ │ │ │
│ ┌─────────────────┐ │ │
│ │sources-display │ │ │
│ │ .tsx │ │ │
│ └─────────────────┘ │ │
└─────────────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ API LAYER │
├─────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ /api/chat │ │ /api/agent │ │
│ │ route.ts │ │ route.ts │ │
│ │ (RAG Endpoint) │ │(Agent Endpoint) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ generateText() │ │ streamText() │ │
│ │ (Single Call) │ │ (Multi-Step) │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ │ AGENT TOOLS │ │
│ ├───────────────────┤ │
│ │ • getLocation() │ │
│ │ • getWeather() │ │
│ │ • searchDocuments │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ SERVICE LAYER │
├─────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ │
│ │ RetrievalService│ ◄──────────────────────────────────┐ │
│ │ (/lib/retrieval)│ │ │
│ └─────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌─────────────────┐ │ │
│ │ VectorizeService│ │ │
│ │ (/lib/vectorize)│ │ │
│ └─────────────────┘ │ │
│ │ │
│ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ /lib/utils.ts │ │ /lib/consts.ts │ │ │
│ │ (Utilities) │ │ (Constants) │ │ │
│ └─────────────────┘ └─────────────────┘ │ │
└─────────────────────────────────────────────────────────────────────────────┘
│ │
▼ │
┌─────────────────────────────────────────────────────────────────────────────┐ │
│ EXTERNAL APIs │ │
├─────────────────────────────────────────────────────────────────────────────┤ │
│ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ OpenAI API │ │ Vectorize.io │ ◄───────────────┘ │
│ │ │ │ │ │
│ │ • GPT-4o │ │ • Document │ │
│ │ • GPT-4o-mini │ │ Retrieval │ │
│ │ • Text │ │ • Vector Search │ │
│ │ Generation │ │ • Embeddings │ │
│ └─────────────────┘ └─────────────────┘ │
│ ▲ ▲ │
│ │ │ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ OPENAI_API_KEY │ │ VECTORIZE_* │ │
│ │ │ │ ENV VARIABLES │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
DATA FLOW:
┌─────────────────────────────────────────────────────────────────────────────┐
│ RAG CHAT FLOW: │
│ User Input → /api/chat → RetrievalService → VectorizeService → Documents │
│ ↓ │
│ OpenAI API ← Context + Messages ← Formatted Documents ← Vectorize.io │
│ ↓ │
│ Response + Sources → Chat UI │
│ │
│ AGENT FLOW: │
│ User Input → /api/agent → AI decides tools → Multi-step execution │
│ ↓ │
│ Tools: getLocation() + getWeather() + searchDocuments() │
│ ↓ │
│ Streaming Response → Agent Chat UI │
└─────────────────────────────────────────────────────────────────────────────┘
📁 Project Structure
rag-next-typescript/
├── app/
│ ├── agent/ # AI Agent interface
│ │ └── page.tsx # Agent page (server-rendered)
│ ├── api/
│ │ ├── agent/ # Agent API with multi-step tools
│ │ │ └── route.ts # Streaming agent endpoint
│ │ └── chat/ # Traditional RAG chat API
│ │ └── route.ts # Single-turn RAG endpoint
│ ├── vectorize/ # RAG chat interface
│ │ └── page.tsx # Vectorize chat page
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Home page
├── components/
│ ├── agent-chat.tsx # Agent chat component (client-side)
│ ├── chat.tsx # RAG chat component
│ └── sources-display.tsx # Document sources display
├── lib/
│ ├── consts.ts # Constants and loading messages
│ ├── retrieval.ts # Document retrieval service
│ ├── utils.ts # Utility functions
│ └── vectorize.ts # Vectorize.io API integration
├── types/
│ ├── chat.ts # Chat-related types
│ └── vectorize.ts # Vectorize API types
└── .env.local # Environment variables
🔄 How It Works
- User Input: User types a question in the chat interface
- Document Retrieval: The system queries Vectorize.io to find relevant documents
- Context Formation: Retrieved documents are formatted as context
- AI Generation: OpenAI GPT-4o-mini generates a response using the context
- Response Display: The answer is shown with source documents for transparency
🎯 Usage
Chat Interface
- Navigate to
/vectorizefor the main chat interface - Type questions related to your vectorized documents
- View source documents that informed each AI response
- Enjoy real-time loading animations and smooth interactions
Adding Documents
To add documents to your vector database, you'll need to use the Vectorize.io platform or API to upload and process your documents before they can be retrieved by this application.
🛠️ Available Scripts
pnpm dev- Start development server with Turbopackpnpm build- Build the application for productionpnpm start- Start the production serverpnpm lint- Run ESLint
🔍 Troubleshooting
Common Issues
Missing Environment Variables
- Ensure all required environment variables are set in
.env.local - Check that your API keys are valid and have proper permissions
- Ensure all required environment variables are set in
Vectorize Connection Issues
- Verify your Vectorize.io credentials
- Ensure your pipeline is properly configured and has documents
OpenAI API Errors
- Check your OpenAI API key validity
- Ensure you have sufficient credits/quota
Error Messages
Failed to retrieve documents from Vectorize- Check Vectorize.io configurationFailed to process chat- Usually indicates OpenAI API issues
📖 Learn More
Next.js Resources
AI & RAG Resources
🚀 Deployment
Vercel (Recommended)
- Push your code to a Git repository
- Connect your repository to Vercel
- Add your environment variables in the Vercel dashboard
- Deploy automatically on every push
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
作者情報
0
フォロワー
0
リポジトリ
0
Gist
0
貢献数
スレッド