openrag-sdk

When the user asks to integrate the OpenRAG SDK or use OpenRAG in their application, follow this workflow. ## Initial assessment phase Before starting SDK integration: 1. Identify the OpenRAG instance: - Determine the base URL (e.g., `http://localhost:3000`, `https://api.example.com`) - Check if authentication is required (API key) - Test API availability: `curl <base_url>` or `curl <base_url>/health` 2. Identify the target application: - Programming language (Python, JavaScript/TypeScript) - Framework (if any): FastAPI, Flask, Express, React, Next.js, etc. - Project structure and existing dependencies 3. Determine integration requirements: - RAG chat functionality (streaming or non-streaming) - Semantic search - Document ingestion and management - Knowledge filters - Conversation history management - Settings management ## Primary goals - Install the appropriate SDK package for the target language - Configure authentication and connection settings - Implement core functionality with working code examples - Add proper error handling - Test the integration locally - Document the integration for maintainability ## SDK installation ### Python SDK **Package:** [`openrag-sdk`](https://pypi.org/project/openrag-sdk/) Installation: ```bash pip install openrag-sdk ``` Or with uv: ```bash uv add openrag-sdk ``` ### TypeScript/JavaScript SDK **Package:** [`openrag-sdk`](https://libraries.io/npm/openrag-sdk) Installation: ```bash npm install openrag-sdk ``` Or with other package managers: ```bash yarn add openrag-sdk pnpm add openrag-sdk bun add openrag-sdk ``` ### MCP Server **Package:** [`openrag-mcp`](https://pypi.org/project/openrag-mcp/) For MCP integration (Model Context Protocol): ```bash pip install openrag-mcp ``` Or with uvx: ```bash uvx openrag-mcp ``` ## Configuration ### Python SDK Configuration The SDK can be configured via environment variables or constructor arguments: **Environment Variables:** ```bash OPENRAG_API_KEY=your-api-key # Required if authentication is enabled OPENRAG_URL=http://localhost:3000 # Optional, defaults to localhost:3000 ``` **Constructor Arguments:** ```python from openrag_sdk import OpenRAGClient # Using environment variables (auto-discovers OPENRAG_API_KEY and OPENRAG_URL) client = OpenRAGClient() # Using explicit arguments client = OpenRAGClient( api_key="orag_...", base_url="https://api.example.com" ) ``` ### TypeScript SDK Configuration Similar configuration options for TypeScript: ```typescript import { OpenRAGClient } from 'openrag-sdk'; // Using environment variables const client = new OpenRAGClient(); // Using explicit configuration const client = new OpenRAGClient({ apiKey: 'orag_...', baseUrl: 'https://api.example.com' }); ``` ## Core functionality examples ### 1. Chat (Non-streaming) **Python:** ```python import asyncio from openrag_sdk import OpenRAGClient async def main(): # Client auto-discovers OPENRAG_API_KEY and OPENRAG_URL from environment async with OpenRAGClient() as client: # Simple chat response = await client.chat.create(message="What is RAG?") print(response.response) print(f"Chat ID: {response.chat_id}") # Continue conversation followup = await client.chat.create( message="Tell me more", chat_id=response.chat_id ) print(followup.response) asyncio.run(main()) ``` **TypeScript:** ```typescript import { OpenRAGClient } from 'openrag-sdk'; async function main() { const client = new OpenRAGClient(); // Simple chat const response = await client.chat.create({ message: "What is RAG?" }); console.log(response.response); console.log(`Chat ID: ${response.chatId}`); // Continue conversation const followup = await client.chat.create({ message: "Tell me more", chatId: response.chatId }); console.log(followup.response); } main(); ``` ### 2. Chat (Streaming) **Python:** ```python async def streaming_chat(): chat_id = None async with OpenRAGClient() as client: # Stream responses async for event in await client.chat.create( message="Explain RAG", stream=True ): if event.type == "content": print(event.delta, end="", flush=True) elif event.type == "sources": for source in event.sources: print(f"\nSource: {source.filename}") elif event.type == "done": chat_id = event.chat_id asyncio.run(streaming_chat()) ``` **Python with stream() context manager:** ```python async def streaming_with_context(): async with OpenRAGClient() as client: # Full event iteration async with client.chat.stream(message="Explain RAG") as stream: async for event in stream: if event.type == "content": print(event.delta, end="", flush=True) # Access aggregated data after iteration print(f"\nChat ID: {stream.chat_id}") # Get final text directly async with client.chat.stream(message="Explain RAG") as stream: text = await stream.final_text() print(text) asyncio.run(streaming_with_context()) ``` **TypeScript:** ```typescript async function streamingChat() { const client = new OpenRAGClient(); const stream = await client.chat.create({ message: "Explain RAG", stream: true }); for await (const event of stream) { if (event.type === 'content') { process.stdout.write(event.delta); } else if (event.type === 'sources') { for (const source of event.sources) { console.log(`\nSource: ${source.filename}`); } } else if (event.type === 'done') { console.log(`\nChat ID: ${event.chatId}`); } } } ``` ### 3. Conversation History **Python:** ```python async def manage_conversations(): async with OpenRAGClient() as client: # List all conversations conversations = await client.chat.list() for conv in conversations.conversations: print(f"{conv.chat_id}: {conv.title}") if not conversations.conversations: print("No conversations found") return chat_id = conversations.conversations[0].chat_id # Get specific conversation with messages conversation = await client.chat.get(chat_id) for msg in conversation.messages: print(f"{msg.role}: {msg.content}") # Delete conversation await client.chat.delete(chat_id) asyncio.run(manage_conversations()) ``` **TypeScript:** ```typescript async function manageConversations() { const client = new OpenRAGClient(); // List all conversations const conversations = await client.chat.list(); for (const conv of conversations.conversations) { console.log(`${conv.chatId}: ${conv.title}`); } if (!conversations.conversations.length) { console.log("No conversations found"); return; } const chatId = conversations.conversations[0].chatId; // Get specific conversation const conversation = await client.chat.get(chatId); for (const msg of conversation.messages) { console.log(`${msg.role}: ${msg.content}`); } // Delete conversation await client.chat.delete(chatId); } ``` ### 4. Search **Python:** ```python async def search_knowledge(): async with OpenRAGClient() as client: # Basic search results = await client.search.query("document processing") for result in results.results: print(f"{result.filename} (score: {result.score})") print(f"{result.text[:100]}...") # Search with filters from openrag_sdk import SearchFilters results = await client.search.query( "API documentation", filters=SearchFilters( data_sources=["api-docs.pdf"], document_types=["application/pdf"] ), limit=5, score_threshold=0.5 ) asyncio.run(search_knowledge()) ``` **TypeScript:** ```typescript async function searchKnowledge() { const client = new OpenRAGClient(); // Basic search const results = await client.search.query("document processing"); for (const result of results.results) { console.log(`${result.filename} (score: ${result.score})`); console.log(`${result.text.substring(0, 100)}...`); } // Search with filters const filtered = await client.search.query("API documentation", { filters: { data_sources: ["api-docs.pdf"], document_types: ["application/pdf"] }, limit: 5, scoreThreshold: 0.5 }); } ``` ### 5. Document Management **Python:** ```python async def manage_documents(): async with OpenRAGClient() as client: # Ingest a file (waits for completion by default) result = await client.documents.ingest(file_path="./report.pdf") print(f"Status: {result.status}") # Ingest from file object with open("./report.pdf", "rb") as f: result = await client.documents.ingest(file=f, filename="report.pdf") # Poll for completion manually final_status = await client.documents.wait_for_task(result.task_id) print(f"Status: {final_status.status}") print(f"Successful files: {final_status.successful_files}") # Delete a document result = await client.documents.delete("report.pdf") print(f"Success: {result.success}") asyncio.run(manage_documents()) ``` **TypeScript:** ```typescript async function manageDocuments() { const client = new OpenRAGClient(); // Ingest a file const result = await client.documents.ingest({ filePath: "./report.pdf" }); console.log(`Status: ${result.status}`); // Poll for completion const finalStatus = await client.documents.waitForTask(result.task_id); console.log(`Status: ${finalStatus.status}`); console.log(`Successful files: ${finalStatus.successful_files}`); // Delete a document const deleteResult = await client.documents.delete("report.pdf"); console.log(`Success: ${deleteResult.success}`); } ``` ### 6. Settings Management **Python:** ```python async def manage_settings(): async with OpenRAGClient() as client: # Get settings settings = await client.settings.get() print(f"LLM Provider: {settings.agent.llm_provider}") print(f"LLM Model: {settings.agent.llm_model}") print(f"Embedding Model: {settings.knowledge.embedding_model}") # Update settings await client.settings.update({ "llm_provider": "openai", "llm_model": "gpt-4o", "embedding_provider": "openai", "embedding_model": "text-embedding-3-small" }) asyncio.run(manage_settings()) ``` **TypeScript:** ```typescript async function manageSettings() { const client = new OpenRAGClient(); // Get settings const settings = await client.settings.get(); console.log(`LLM Provider: ${settings.agent.llmProvider}`); console.log(`LLM Model: ${settings.agent.llmModel}`); // Update settings await client.settings.update({ llm_provider: "openai", llm_model: "gpt-4o", embedding_provider: "openai", embedding_model: "text-embedding-3-small" }); } ``` ### 7. Knowledge Filters **Python:** ```python