/sdk

name: openrag_sdk
description: Guide developers through integrating the OpenRAG SDK into applications with code examples, configuration, and best practices

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:

pip install openrag-sdk

Or with uv:

uv add openrag-sdk

TypeScript/JavaScript SDK

**Package:** [`openrag-sdk`](https://libraries.io/npm/openrag-sdk)

Installation:

npm install openrag-sdk

Or with other package managers:

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):

pip install openrag-mcp

Or with uvx:

uvx openrag-mcp

Configuration

Python SDK Configuration

The SDK can be configured via environment variables or constructor arguments:

**Environment Variables:**

OPENRAG_API_KEY=your-api-key  # Required if authentication is enabled
OPENRAG_URL=http://localhost:3000  # Optional, defaults to localhost:3000

**Constructor Arguments:**

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:

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:**

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:**

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:**

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:**

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:**

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