n8n-nodes-puter-ai/README.md

Advanced n8n node for Puter.js AI with RAG agentic capabilities, document processing, audio transcription, Supabase integration, and cost-optimized model priorities

# n8n-nodes-puter-ai v2.0.0 🚀

An advanced n8n community node for Puter.js AI with **RAG agentic capabilities**, document processing, Supabase integration, and cost-optimized model selection.

## 🌟 New in v2.0.0

🤖 **Agentic RAG**: Intelligent document-based reasoning and synthesis
📄 **Document Processing**: Auto-detect and process files from Telegram/other sources
🗄️ **Supabase Integration**: Vector storage with pgvector for semantic search
💰 **Cost Optimization**: Starting from $0.10 with google/gemma-2-27b-it
🔍 **Vector Search**: Semantic document search with similarity scoring
📱 **Auto-Detection**: Automatically process documents from input data

## 🚀 Features

### 🤖 **AI Operations**
- **Chat Completion**: Standard AI chat with cost-optimized models
- **RAG Chat**: Enhanced responses with document context
- **Agentic RAG**: Intelligent document-based reasoning
- **Vector Search**: Semantic document search

### 📄 **Document Processing**
- **Multi-Format Support**: PDF, DOCX, TXT, MD files
- **Auto-Detection**: Process files from Telegram/other sources
- **Text Extraction**: Advanced content parsing
- **Vector Embeddings**: Generate embeddings for semantic search

### 🗄️ **Database Integration**
- **Supabase Integration**: Vector storage with pgvector
- **Document Storage**: Organized with metadata and tags
- **Similarity Search**: Fast vector-based retrieval
- **Auto-Indexing**: Automatic embedding generation

### 💰 **Cost Optimization**
- **google/gemma-2-27b-it**: $0.10 (most cost-effective)
- **gemini-1.5-flash**: $0.225
- **gemini-2.0-flash**: $0.30
- **gpt-4o-mini**: $0.375
- **Smart Fallback**: Automatic model switching

### 🔐 **Account Management**
- **Multiple Account Fallback**: Primary + 2 fallback accounts
- **Smart Strategies**: Sequential or random selection
- **Enhanced Tracking**: Monitor costs and usage across accounts
- **Robust Error Handling**: Comprehensive retry logic

## Installation

### Community Nodes (Recommended)

1. Go to **Settings > Community Nodes** in your n8n instance
2. Select **Install a community node**
3. Enter `n8n-nodes-puter-ai`
4. Click **Install**

### Manual Installation

```bash
# In your n8n root folder
npm install n8n-nodes-puter-ai@2.0.0
```

## 🎯 Operations

### 1. **Document Processing**
Process and store documents for RAG functionality:
- **File Upload**: Process files from Telegram or other sources
- **Text Content**: Process raw text content
- **URL/Link**: Download and process documents from URLs
- **Auto-Storage**: Automatically store in Supabase with embeddings

### 2. **Vector Search**
Search documents by semantic similarity:
- **Natural Language Queries**: Search using plain English
- **Similarity Scoring**: Get relevance scores for results
- **Configurable Results**: Control number of documents returned
- **Fast Retrieval**: Optimized vector search with HNSW indexing

### 3. **Agentic RAG**
Intelligent document-based reasoning:
- **Context Building**: Automatically retrieve relevant documents
- **Multi-Source Synthesis**: Combine information from multiple documents
- **Citation Support**: Track which documents were used
- **Intelligent Responses**: AI reasoning over document context

### 4. **Chat Completion**
Standard AI chat with cost optimization:
- **Cost-Optimized Models**: Automatic selection of cheapest effective model
- **Model Fallback**: Try alternative models if primary fails
- **Account Fallback**: Switch accounts automatically
- **Usage Tracking**: Monitor costs and token consumption

### 5. **RAG Chat**
Enhanced chat with document context:
- **Context Integration**: Include relevant documents in responses
- **Smart Retrieval**: Automatically find related content
- **Enhanced Accuracy**: More accurate responses with document backing
- **Flexible Context**: Control how much context to include

## Configuration

### 1. Supabase Setup (Required for RAG)

1. **Create Supabase Project**: Go to [supabase.com](https://supabase.com) and create a new project
2. **Enable Vector Extension**: Run the provided `supabase-setup.sql` script in your SQL editor
3. **Configure Supabase Credentials** in n8n:
   - **Supabase URL**: `https://your-project.supabase.co`
   - **Anon Key**: Your public anon key
   - **Service Role Key**: Your service role key (for admin operations)
   - **Enable Vector Storage**: ✅ True
   - **Documents Table**: `documents`
   - **Embeddings Table**: `document_embeddings`
   - **Vector Dimension**: `1536`
   - **Similarity Threshold**: `0.7`
   - **Max Documents Retrieved**: `5`

### 2. Puter AI Credentials

1. Go to **Credentials** in your n8n instance
2. Click **Add Credential**
3. Search for **Puter AI API**
4. Configure with **cost-optimized model priorities**:
   - **Primary Account**: Your main Puter.js username/password
   - **Primary Models**: `google/gemma-2-27b-it`, `gemini-1.5-flash`, `gemini-2.0-flash`, `gpt-4o-mini`
   - **Fallback Account 1**: Backup username/password
   - **Fallback 1 Models**: `gemini-1.5-flash`, `gpt-4o-mini`, `gemini-2.0-flash`
   - **Fallback Account 2**: Second backup username/password
   - **Fallback 2 Models**: `google/gemma-2-27b-it`, `gemini-1.5-flash`
   - **Enable Auto Fallback**: ✅ True
   - **Fallback Strategy**: Sequential (recommended)

### 2. Add the Node

1. In your workflow, click **Add Node**
2. Search for **Puter AI**
3. Configure the node parameters

## Node Parameters

### Operation
- **Chat Completion**: Standard AI chat with cost optimization
- **RAG Chat**: Chat with document context for enhanced responses
- **Document Processing**: Process and store documents for RAG
- **Vector Search**: Search documents by semantic similarity
- **Agentic RAG**: Intelligent document-based reasoning

### Model Strategy
- **Use Credential Priority (Recommended)**: Uses cost-optimized model order from credentials
- **Override with Specific Model**: Choose a specific model
- **Auto (Smart Selection)**: Automatically select best model

### Cost-Optimized Models (by price)
- **google/gemma-2-27b-it ($0.10)**: Most cost-effective
- **gemini-1.5-flash ($0.225)**: Good balance of cost/performance
- **gemini-2.0-flash ($0.30)**: Latest Gemini model
- **gpt-5-nano ($0.35)**: Ultra-low-cost tier
- **gpt-4o-mini ($0.375)**: OpenAI's efficient model
- **o4-mini (~$0.40)**: Balanced performance
- **gpt-4.1-nano (~$0.45)**: Advanced reasoning at low cost
- **meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo ($0.88)**: Open-source option
- **Auto (Smart Selection)**: Automatically selects the best available model

### Response Format
- **Simple Text**: Just the AI response
- **Formatted with Metadata**: Includes model, usage, and timing info
- **Telegram Ready**: Pre-formatted for Telegram bots with emojis and styling
- **Raw Response**: Complete API response

## Usage Examples

### Basic Chat
```json
{
  "operation": "chatCompletion",
  "model": "gpt-4o",
  "message": "Hello, how are you?",
  "responseFormat": "simple"
}
```

### RAG-Enhanced Chat
```json
{
  "operation": "ragChat",
  "model": "claude-3-5-sonnet",
  "message": "What are the legal requirements?",
  "ragContext": "Legal document content here...",
  "responseFormat": "formatted"
}
```

### Telegram Bot Integration
```json
{
  "operation": "chatCompletion",
  "model": "auto",
  "message": "{{$json.message.text}}",
  "responseFormat": "telegram"
}
```

## Error Handling

The node automatically handles:
- **Authentication failures**: Retries with fresh tokens
- **Rate limits**: Switches to fallback account
- **Model unavailability**: Tries alternative models
- **Usage limits**: Seamlessly switches accounts

## Fallback Logic

1. **Primary Account**: Attempts request with main account
2. **Account Fallback**: On 400 errors, switches to fallback account
3. **Model Fallback**: If model fails, tries alternatives in priority order:
   - o3 → o1-pro → gpt-4o → claude-3-5-sonnet → o1 → gpt-4o-mini → gemini-2.0-flash

## License

MIT

## Support

For issues and feature requests, please visit: [GitHub Repository](https://github.com/yourusername/n8n-nodes-puter-ai)