OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
feat: Agent skills for OpenRAG installation and SDK support (#1427)
Mike Fortman71d39651e6ca
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonnew file mode 100644index 000000000..8789051a3--- /dev/null+++ b/.claude-plugin/marketplace.json@@ -0,0 +1,12 @@+{+ "name": "openrag",+ "description": "Agent plugins for working with OpenRAG.",+ "owner": { "name": "langflow-ai" },+ "plugins": [+ {+ "name": "openrag",+ "source": "./plugins/openrag",+ "description": "Guided installation and SDK integration skills for OpenRAG."+ }+ ]+}diff --git a/.claude/skills/install b/.claude/skills/installnew file mode 120000index 000000000..3770ea72b--- /dev/null+++ b/.claude/skills/install@@ -0,0 +1 @@+../../plugins/openrag/skills/install\ No newline at end of filediff --git a/.claude/skills/sdk b/.claude/skills/sdknew file mode 120000index 000000000..b58ff5b98--- /dev/null+++ b/.claude/skills/sdk@@ -0,0 +1 @@+../../plugins/openrag/skills/sdk\ No newline at end of filediff --git a/.gitignore b/.gitignoreindex 5391089d7..08112c6d2 100644--- a/.gitignore+++ b/.gitignore@@ -24,6 +24,7 @@ wheels/!src/tui/_assets/flows/*.json!src/tui/_assets/flows/components/*.json!frontend/*.json+!**/.claude-plugin/*.json.DS_Store/config/@@ -38,12 +39,13 @@ langflow-data/node_modules# AI Tools-/.claude-/CLAUDE.md+# Per-contributor Claude Code state is ignored, but shared skills and+# plugin manifests (.claude/skills, .claude-plugin) are tracked.+/.claude/*+!/.claude/skills//.gemini/GEMINI.md/.bob-/AGENTS.mddocuments/warmup_ocr.pdfdocuments/openrag-documentation.pdfdocuments/ibm_anthropic.pdfdiff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 000000000..2a5f6f838--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,39 @@+# Agent Instructions++This repository ships with **agent skills** that any compliant agent can use to help users install OpenRAG and integrate the OpenRAG SDK. The canonical skill files are markdown with YAML frontmatter (the [Agent Skills](https://github.com/anthropics/skills) format), and live under `plugins/openrag/skills/`.++## Available skills++| Skill | File | Purpose |+| --- | --- | --- |+| `openrag_install` | [`plugins/openrag/skills/install/SKILL.md`](plugins/openrag/skills/install/SKILL.md) | Plan and execute a minimal OpenRAG installation, verify locally. |+| `openrag_sdk` | [`plugins/openrag/skills/sdk/SKILL.md`](plugins/openrag/skills/sdk/SKILL.md) | Guide SDK integration (Python, TypeScript, MCP) with code examples. |++## How to use these skills++Pick the path that matches your agent runtime.++### Claude Code (this repo)++`.claude/skills/` symlinks into the plugin, so after cloning the repo the skills are auto-discovered by Claude Code — invoke with `/install` or `/sdk`, or let Claude trigger them automatically based on the description fields.++### Claude Code (install globally, any repo)++```+/plugin marketplace add langflow-ai/openrag+/plugin install openrag@openrag+```++### Claude Agent SDK / other skill-aware runtimes++Point your skill loader at `plugins/openrag/skills/`. Each subdirectory is one skill.++### Any other agent (generic)++Read the `SKILL.md` files directly. The frontmatter `description` tells you when the skill is relevant; the body is the instruction set to follow.++## Skill authoring notes++- Skill bodies are intentionally kept agent-neutral. Do not add references to tools or features that only exist in one runtime (for example, do not name specific slash commands, hook systems, or task-tracking tools).+- Claude-Code-specific plumbing belongs in `plugin.json` or `.claude/`, not in `SKILL.md`.+- See `plugins/README.md` for the full layout and distribution model.diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 000000000..15ccfbef1--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1 @@+See [AGENTS.md](AGENTS.md) for instructions that apply to Claude Code and other agent runtimes working in this repository.diff --git a/plugins/README.md b/plugins/README.mdnew file mode 100644index 000000000..28e494821--- /dev/null+++ b/plugins/README.md@@ -0,0 +1,76 @@+# OpenRAG Agent Plugins++This directory contains agent **skills** that help users work with OpenRAG. A skill is a `SKILL.md` file (YAML frontmatter + markdown body) that an AI agent reads to know *when* and *how* to assist with a particular task.++The canonical content lives here; it is surfaced to agents through several distribution paths described below.++## Layout++```+openrag/+├── .claude-plugin/+│ └── marketplace.json # turns the repo into a Claude Code marketplace+├── plugins/+│ ├── README.md # this file+│ └── openrag/ # one plugin, can grow to many+│ ├── .claude-plugin/+│ │ └── plugin.json # plugin manifest (name, version, repo)+│ └── skills/+│ ├── install/SKILL.md # guided OpenRAG installation+│ └── sdk/SKILL.md # OpenRAG SDK integration helper+├── .claude/+│ └── skills/ # symlinks into plugins/openrag/skills+│ ├── install -> ../../plugins/openrag/skills/install+│ └── sdk -> ../../plugins/openrag/skills/sdk+└── AGENTS.md # entry point for any agent working in the repo+```++The skills under `plugins/openrag/skills/` are the single source of truth. Everything else (`.claude/skills/` symlinks, marketplace/plugin manifests, `AGENTS.md`) points at them, so edits in one place propagate everywhere.++## How users consume the skills++There are four ways to get these skills in front of an agent.++### 1. Clone this repo and use Claude Code++No install step. `.claude/skills/` symlinks into the plugin, so Claude Code auto-discovers `install` and `sdk` when it starts in this directory. Invoke with `/install` or `/sdk`, or let Claude trigger them automatically based on the `description` fields.++### 2. Install into Claude Code globally (any project)++```+/plugin marketplace add langflow-ai/openrag+/plugin install openrag@openrag+```++The first command registers this repo as a marketplace (reads `.claude-plugin/marketplace.json`). The second installs the `openrag` plugin defined in `plugins/openrag/.claude-plugin/plugin.json`. The skills then work in any directory, not just this repo.++### 3. Load from the Claude Agent SDK or other skill-aware runtimes++Point your skill loader at `plugins/openrag/skills/`. Each subdirectory is one skill. The SKILL.md format is Anthropic's Agent Skills spec and is consumed by the Claude Agent SDK and compatible runtimes.++### 4. Any other agent (generic)++Read `SKILL.md` directly. The frontmatter `description` tells the agent when the skill is relevant; the markdown body is the instruction set. `AGENTS.md` at the repo root lists the available skills and links to them.++## Authoring new skills++When adding a skill:++1. Create `plugins/openrag/skills/<name>/SKILL.md` with frontmatter:+ ```yaml+ ---+ name: <name>+ description: When the agent should invoke this skill (one sentence, specific).+ ---+ ```+2. Add a symlink so Claude Code in this repo picks it up:+ ```+ ln -s ../../plugins/openrag/skills/<name> .claude/skills/<name>+ ```+3. List it in `AGENTS.md` so non-Claude agents can find it.+4. Keep the body **agent-neutral**: no references to tools or features that only exist in one runtime (no `TodoWrite`, no specific slash-command assumptions, no hook-based automations). Describe actions in generic terms: read files, run commands, fetch URLs, ask the user.+5. Put Claude-Code-specific configuration (permissions, hooks) in `plugin.json` or `.claude/`, not in `SKILL.md`.++## Versioning++Bump `plugins/openrag/.claude-plugin/plugin.json`'s `version` field when the skill set changes materially. Marketplace users pin to specific versions.diff --git a/plugins/openrag/.claude-plugin/plugin.json b/plugins/openrag/.claude-plugin/plugin.jsonnew file mode 100644index 000000000..b85d80996--- /dev/null+++ b/plugins/openrag/.claude-plugin/plugin.json@@ -0,0 +1,6 @@+{+ "name": "openrag",+ "version": "0.1.0",+ "description": "OpenRAG agent skills: guided installation and SDK integration helpers.",+ "repository": "https://github.com/langflow-ai/openrag"+}diff --git a/plugins/openrag/skills/install/SKILL.md b/plugins/openrag/skills/install/SKILL.mdnew file mode 100644index 000000000..3e954edec--- /dev/null+++ b/plugins/openrag/skills/install/SKILL.md@@ -0,0 +1,150 @@+---+name: openrag_install+description: Plan and execute a minimal OpenRAG installation with requirement drafting, task tracking, configuration guidance, and local verification+---++When the user asks to install OpenRAG, follow this workflow in order.++## Initial assessment phase+Before starting installation, check for an existing OpenRAG installation:+1. Check if `~/.openrag/tui/.env` exists+2. If it exists:+ - Read the configuration to understand what's already set up+ - Check if services are currently running with `docker compose ps` for the generated OpenRAG compose file, or by filtering on the compose project/labels instead of `docker ps --filter "name=openrag"`+ - Inform the user about the existing installation+ - Ask if they want to:+ - Start existing services (if stopped)+ - Reconfigure existing installation+ - Verify existing installation+ - Proceed with fresh installation (will use existing config)+3. If no existing installation found, proceed with fresh installation workflow++## Primary goals+- Produce a grounded installation spec in `requirements.md`+- Break the work into executable tasks in `todo.md`+- Implement all tasks that can be completed in the current environment+- Pause for user action when a task requires credentials, configuration choices, or other interactive input+- Verify the installation locally until `http://localhost:3000` launches without startup errors and `http://localhost:5001/docs` is reachable+- Treat browser onboarding after the app launches as user-owned and outside installation completion++## Requirements authoring phase+First, create or update `requirements.md` using the official OpenRAG installation documentation:+- Use `https://docs.openr.ag/install-options` as the source of truth+- Do not hallucinate implementation details that are not supported by the documentation or the local environment+- Prioritize the minimal installation path and the fewest necessary steps+- Organize requirements into logical categories+- Use numbered identifiers in the format `REQ-001`, `REQ-002`, and so on+- Include acceptance criteria for every requirement+- Include requirements covering:+ - System prerequisites and resource requirements+ - Configuration and security+ - Platform compatibility+ - Edge cases and troubleshooting considerations++Include the following specific requirement in the spec:+- Non-containerized service: `docling-serve` on port `5001`+- It is a required bundled Python service+- It is bundled with OpenRAG and managed by `uvx` or `uv`+- It should be automatically started and stopped via `uvx openrag`+- It should be available at `http://localhost:5001/docs`+- Verification should include either `lsof -i :5001` or `curl http://localhost:5001/docs`+- Do not immediately flag failure if `http://localhost:5001/docs` is not ready right after startup; wait and re-check because `docling-serve` may come up after the main OpenRAG services++## Requirements review phase+After drafting `requirements.md`:+- Review it for gaps, ambiguities, contradictions, and missing edge cases+- Tighten vague language+- Add missing acceptance criteria where needed+- Update the file before moving to implementation planning++## Task planning and execution phase+After `requirements.md` is stable:+1. Read `requirements.md`+2. Create `todo.md` that breaks the work into concrete tasks+3. Implement each task that is relevant to the current environment+4. For user-interactive tasks, do not guess or fabricate values; instruct the user to complete the step and confirm when done+5. Mark tasks complete in `todo.md` only after they pass validation+6. If troubleshooting partially started OpenRAG services, stop all services before attempting to start them again++## CRITICAL: Interactive Terminal Limitation+**Most agent shell tools cannot drive interactive terminal applications that require user input.** This includes any command that renders a TUI, prompts for passwords, or expects arrow-key navigation.++When the installation reaches the point where `uvx openrag` needs to be run:++### What NOT to do:+- Do NOT attempt to run `uvx openrag` through the agent's shell tool expecting to interact with it+- Do NOT try to use background processes for interactive commands+- Do NOT assume you can send input to an already-running interactive terminal++### What TO do:+1. **Explicitly instruct the user** to open a NEW terminal window/tab outside the agent's shell+2. Provide the exact command to run: `uvx --python 3.13 openrag`+3. Give step-by-step instructions for what they will see and how to respond:+ - First run: Select "Reconfigure" (option 2)+ - Set OpenSearch Admin password (MUST be strong)+ - Set Langflow Admin password (can autogenerate or manual)+ - Accept defaults for other prompts (press 'N' or skip)+ - Return to menu and select "Start services" (option 1)+ - Wait for "Services are running" message+4. **Wait for user confirmation** that they completed the steps+5. **After confirmation**, verify the installation using non-interactive commands:+ - Check container status: `docker ps --filter "name=openrag"`+ - Verify ports: `lsof -i :3000` and `lsof -i :5001`+ - Test endpoints: `curl http://localhost:3000` and `curl http://localhost:5001/docs`++### Example user instruction format:+```+The next step requires running an interactive command that I cannot control directly.++Please open a NEW terminal window (separate from this agent session) and run:++ uvx --python 3.13 openrag++You will see a menu. Follow these steps:+1. Type '2' and press Enter (Reconfigure)+2. Enter a STRONG OpenSearch Admin password (write it down!)+3. Enter Langflow Admin password (or autogenerate)+4. Press 'N' or skip for other prompts+5. Type '1' and press Enter (Start services)+6. Wait for "Services are running" message++Once complete, come back here and confirm: "Configuration and services started successfully"+```++## User-interactive guidance+When a task requires user input, secret values, or interactive terminal control:+- Tell the user exactly what action they need to take+- Explain how you will verify completion+- Wait for confirmation before proceeding+- Explicitly instruct the user that the OpenSearch password must be strong, defaults can be used for all other values to get started quickly+- **ALWAYS instruct users to run `uvx openrag` in a separate terminal outside the agent's shell**+- Provide explicit step-by-step guidance for what they will see and how to respond+- After user confirms completion, verify using non-interactive commands++## Safety and accuracy rules+- Prefer official documentation and observed local state over assumptions+- Do not invent ports, services, commands, configuration keys, or file locations unless verified+- Keep installation steps as simple and minimal as possible+- Use secure defaults and align with OWASP-style handling of secrets and credentials+- Call out platform-specific limitations when they affect installation or verification+- **Be explicit that the agent's shell cannot drive interactive TUI applications**+- **Never attempt to run `uvx openrag` interactively through the agent's shell**+- Do not treat delayed startup alone as a failure condition when output is still progressing normally++## Verification and completion+Before considering the installation complete:+- Verify all completed tasks against the acceptance criteria in `requirements.md`+- Confirm required services are running+- Verify `http://localhost:3000` first+- Wait briefly, then verify `docling-serve` is reachable at `http://localhost:5001/docs`+- If OpenRAG services were restarted during troubleshooting, verify they are all healthy after the clean restart+- Only escalate to troubleshooting if repeated checks fail after a reasonable delay or the terminal shows explicit errors+- Consider the installation complete once the app launches without startup errors on `http://localhost:3000` and `http://localhost:5001/docs` is reachable+- Do not treat provider selection or browser onboarding completion as part of installation completion++## Collaboration style+- Be explicit about what is known, what is inferred, and what still needs verification+- Surface ambiguities early and resolve them before implementation+- Keep outputs structured and easy to audit+- Iterate on `requirements.md` and `todo.md` as new validated information is discovered+- **Clearly communicate when user action is required in a separate terminal**diff --git a/plugins/openrag/skills/sdk/SKILL.md b/plugins/openrag/skills/sdk/SKILL.mdnew file mode 100644index 000000000..02b6b605c--- /dev/null+++ b/plugins/openrag/skills/sdk/SKILL.md@@ -0,0 +1,990 @@+---+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:+```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+async def use_knowledge_filters():+ async with OpenRAGClient() as client:+ # Create a knowledge filter+ result = await client.knowledge_filters.create({+ "name": "Technical Docs",+ "description": "Filter for technical documentation",+ "queryData": {+ "query": "technical",+ "filters": {+ "document_types": ["application/pdf"]+ },+ "limit": 10,+ "scoreThreshold": 0.5+ }+ })+ filter_id = result.id++ # Search for filters+ filters = await client.knowledge_filters.search("Technical")+ for f in filters:+ print(f"{f.name}: {f.description}")++ # Update a filter+ await client.knowledge_filters.update(filter_id, {+ "description": "Updated description"+ })++ # Delete a filter+ await client.knowledge_filters.delete(filter_id)++ # Use filter in chat+ response = await client.chat.create(+ message="Explain the API",+ filter_id=filter_id+ )++ # Use filter in search+ results = await client.search.query(+ "API endpoints",+ filter_id=filter_id+ )++asyncio.run(use_knowledge_filters())+```++**TypeScript:**+```typescript+async function useKnowledgeFilters() {+ const client = new OpenRAGClient();++ // Create a knowledge filter+ const result = await client.knowledgeFilters.create({+ name: "Technical Docs",+ description: "Filter for technical documentation",+ queryData: {+ query: "technical",+ filters: {+ documentTypes: ["application/pdf"]+ },+ limit: 10,+ scoreThreshold: 0.5+ }+ });+ const filterId = result.id;++ // Use filter in chat+ const response = await client.chat.create({+ message: "Explain the API",+ filterId: filterId+ });++ // Use filter in search+ const results = await client.search.query({+ query: "API endpoints",+ filterId: filterId+ });+}+```++## Error handling++### Python Error Handling+```python+from openrag_sdk import (+ OpenRAGError,+ AuthenticationError,+ NotFoundError,+ ValidationError,+ RateLimitError,+ ServerError+)++async def handle_errors():+ try:+ async with OpenRAGClient() as client:+ response = await client.chat.create(message="Hello")+ except AuthenticationError as e:+ print(f"Invalid API key: {e.message}")+ except NotFoundError as e:+ print(f"Resource not found: {e.message}")+ except ValidationError as e:+ print(f"Invalid request: {e.message}")+ except RateLimitError as e:+ print(f"Rate limited: {e.message}")+ except ServerError as e:+ print(f"Server error: {e.message} (status: {e.status_code})")+ except OpenRAGError as e:+ print(f"API error: {e.message} (status: {e.status_code})")+```++### TypeScript Error Handling+```typescript+import {+ OpenRAGClient,+ OpenRAGError,+ AuthenticationError,+ NotFoundError,+ ValidationError,+ RateLimitError,+ ServerError+} from 'openrag-sdk';++async function handleErrors() {+ try {+ const client = new OpenRAGClient();+ const response = await client.chat.create({ message: "Hello" });+ } catch (error) {+ if (error instanceof AuthenticationError) {+ console.error(`Invalid API key: ${error.message}`);+ } else if (error instanceof NotFoundError) {+ console.error(`Resource not found: ${error.message}`);+ } else if (error instanceof ValidationError) {+ console.error(`Invalid request: ${error.message}`);+ } else if (error instanceof RateLimitError) {+ console.error(`Rate limited: ${error.message}`);+ } else if (error instanceof ServerError) {+ console.error(`Server error: ${error.message}`);+ } else if (error instanceof OpenRAGError) {+ console.error(`API error: ${error.message}`);+ }+ }+}+```++## Integration patterns++### Pattern 1: FastAPI Backend+```python+from fastapi import FastAPI, HTTPException+from openrag_sdk import OpenRAGClient+from pydantic import BaseModel++app = FastAPI()+client = OpenRAGClient()++class ChatRequest(BaseModel):+ message: str+ chat_id: str | None = None+[email protected]("/api/chat")+async def chat(request: ChatRequest):+ try:+ response = await client.chat.create(+ message=request.message,+ chat_id=request.chat_id+ )+ return {+ "answer": response.response,+ "sources": [{"filename": s.filename, "score": s.score} for s in response.sources],+ "chat_id": response.chat_id+ }+ except Exception as e:+ raise HTTPException(status_code=500, detail=str(e))+[email protected]("/api/search")+async def search(query: str, limit: int = 10):+ try:+ results = await client.search.query(query, limit=limit)+ return {+ "results": [+ {+ "filename": r.filename,+ "text": r.text,+ "score": r.score+ }+ for r in results.results+ ]+ }+ except Exception as e:+ raise HTTPException(status_code=500, detail=str(e))+```++### Pattern 2: Express.js Backend+```typescript+import express from 'express';+import { OpenRAGClient } from 'openrag-sdk';++const app = express();+const client = new OpenRAGClient();++app.use(express.json());++app.post('/api/chat', async (req, res) => {+ try {+ const { message, chatId } = req.body;+ const response = await client.chat.create({+ message,+ chatId+ });++ res.json({+ answer: response.response,+ sources: response.sources.map(s => ({+ filename: s.filename,+ score: s.score+ })),+ chatId: response.chatId+ });+ } catch (error) {+ res.status(500).json({ error: error.message });+ }+});++app.get('/api/search', async (req, res) => {+ try {+ const { query, limit = 10 } = req.query;+ const results = await client.search.query({+ query: query as string,+ limit: Number(limit)+ });++ res.json({+ results: results.results.map(r => ({+ filename: r.filename,+ text: r.text,+ score: r.score+ }))+ });+ } catch (error) {+ res.status(500).json({ error: error.message });+ }+});++app.listen(3001, () => {+ console.log('Server running on port 3001');+});+```++### Pattern 3: React Frontend+```typescript+import { useState } from 'react';+import { OpenRAGClient } from 'openrag-sdk';++// Note: In production, proxy API calls through your backend+// to avoid exposing API keys in the browser+const client = new OpenRAGClient({+ baseUrl: process.env.REACT_APP_OPENRAG_URL+});++function ChatComponent() {+ const [message, setMessage] = useState('');+ const [chatId, setChatId] = useState<string | null>(null);+ const [response, setResponse] = useState('');+ const [loading, setLoading] = useState(false);++ const handleSubmit = async (e: React.FormEvent) => {+ e.preventDefault();+ setLoading(true);++ try {+ const result = await client.chat.create({+ message,+ chatId,+ limit: 5+ });++ setResponse(result.response);+ setChatId(result.chatId);+ setMessage('');+ } catch (error) {+ console.error('Chat error:', error);+ } finally {+ setLoading(false);+ }+ };++ return (+ <div>+ <form onSubmit={handleSubmit}>+ <input+ value={message}+ onChange={(e) => setMessage(e.target.value)}+ placeholder="Ask a question..."+ disabled={loading}+ />+ <button type="submit" disabled={loading}>+ {loading ? 'Sending...' : 'Send'}+ </button>+ </form>+ {response && (+ <div className="response">+ {response}+ </div>+ )}+ </div>+ );+}+```++### Pattern 4: Streaming in React+```typescript+import { useState } from 'react';+import { OpenRAGClient } from 'openrag-sdk';++function StreamingChat() {+ const [message, setMessage] = useState('');+ const [response, setResponse] = useState('');+ const [streaming, setStreaming] = useState(false);+ const client = new OpenRAGClient();++ const handleSubmit = async (e: React.FormEvent) => {+ e.preventDefault();+ setStreaming(true);+ setResponse('');++ try {+ const stream = await client.chat.create({+ message,+ stream: true+ });++ for await (const event of stream) {+ if (event.type === 'content') {+ setResponse(prev => prev + event.delta);+ }+ }+ } catch (error) {+ console.error('Streaming error:', error);+ } finally {+ setStreaming(false);+ setMessage('');+ }+ };++ return (+ <div>+ <form onSubmit={handleSubmit}>+ <input+ value={message}+ onChange={(e) => setMessage(e.target.value)}+ disabled={streaming}+ />+ <button type="submit" disabled={streaming}>+ {streaming ? 'Streaming...' : 'Send'}+ </button>+ </form>+ <div className="response">+ {response}+ {streaming && <span className="cursor">▊</span>}+ </div>+ </div>+ );+}+```++## Security best practices++1. **Never expose API keys in client-side code**+ - Always proxy requests through your backend+ - Use environment variables for API keys+ - Implement proper authentication in your backend++2. **Use HTTPS in production**+ - Always use HTTPS for production deployments+ - Configure proper SSL/TLS certificates++3. **Validate and sanitize inputs**+ - Validate user inputs before sending to OpenRAG+ - Sanitize outputs before displaying to users+ - Implement rate limiting on your endpoints++4. **Implement proper error handling**+ - Don't expose sensitive information in error messages+ - Log errors securely for debugging+ - Provide user-friendly error messages++5. **Follow OWASP guidelines**+ - Implement proper authentication and authorization+ - Protect against common vulnerabilities (XSS, CSRF, etc.)+ - Keep dependencies up to date++## Testing strategies++### Python Testing+```python+import pytest+from openrag_sdk import OpenRAGClient++async def client():+ async with OpenRAGClient() as client:+ yield client++async def test_chat_basic(client):+ response = await client.chat.create(message="Hello")+ assert response.response is not None+ assert isinstance(response.sources, list)+ assert response.chat_id is not None++async def test_search_with_filters(client):+ results = await client.search.query(+ "test",+ filters={"document_types": ["application/pdf"]}+ )+ assert isinstance(results.results, list)+```++### TypeScript Testing+```typescript+import { describe, it, expect } from 'vitest';+import { OpenRAGClient } from 'openrag-sdk';++describe('OpenRAG SDK', () => {+ const client = new OpenRAGClient();++ it('should chat successfully', async () => {+ const response = await client.chat.create({+ message: 'Hello'+ });++ expect(response.response).toBeDefined();+ expect(response.sources).toBeInstanceOf(Array);+ expect(response.chatId).toBeDefined();+ });++ it('should search with filters', async () => {+ const results = await client.search.query({+ query: 'test',+ filters: {+ documentTypes: ['application/pdf']+ }+ });++ expect(results.results).toBeInstanceOf(Array);+ });+});+```++## Troubleshooting++### Connection Issues+- Verify the base URL is correct (e.g., `http://localhost:3000` or `https://api.example.com`)+- Test connectivity: `curl <base_url>` or `curl <base_url>/health`+- Check network connectivity if OpenRAG is on a remote server+- Ensure no firewall or network policies blocking the connection+- Verify DNS resolution if using a domain name++### Authentication Errors+- Verify API key is correct if authentication is enabled+- Check API key is properly set in environment variables+- Ensure API key has necessary permissions++### Performance Optimization+- Use appropriate `limit` values (don't retrieve more sources than needed)+- Set reasonable `score_threshold` to filter low-quality results+- Implement caching for frequently asked questions+- Use connection pooling for high-traffic applications+- Consider using streaming for better user experience++### Response Quality Issues+- Adjust `score_threshold` to filter irrelevant results+- Review and update system prompt for better responses+- Ensure knowledge base has relevant documents+- Consider using knowledge filters for domain-specific queries++## Deployment considerations++1. **Environment configuration**+ - Use different configs for dev/staging/prod+ - Store sensitive data in environment variables or secrets management+ - Use configuration files for non-sensitive settings++2. **Health checks**+ - Implement health check endpoints in your application+ - Monitor OpenRAG service availability+ - Set up alerts for failures++3. **Monitoring and logging**+ - Add logging for SDK calls+ - Track metrics (response times, error rates, etc.)+ - Use structured logging for better analysis++4. **Fallback handling**+ - Implement graceful degradation if OpenRAG is unavailable+ - Provide cached responses when possible+ - Show appropriate error messages to users++5. **Scaling**+ - Consider load balancing for high-traffic scenarios+ - Implement request queuing if needed+ - Monitor resource usage and scale accordingly++## Documentation requirements++After integration, document:+- SDK setup and configuration steps+- Available endpoints and their usage+- Example requests and responses+- Error codes and handling strategies+- Performance characteristics and limitations+- Maintenance procedures and troubleshooting++## Verification checklist++Before considering integration complete:+- [ ] SDK package installed successfully+- [ ] Client successfully connects to OpenRAG+- [ ] Chat functionality works (both streaming and non-streaming)+- [ ] Search returns relevant results+- [ ] Document ingestion works+- [ ] Settings can be retrieved and updated+- [ ] Knowledge filters can be created and used+- [ ] Error handling is implemented+- [ ] Tests are passing+- [ ] Documentation is complete+- [ ] Security best practices are followed+- [ ] Performance is acceptable for use case++## Additional resources++- **Python SDK:** https://pypi.org/project/openrag-sdk/+- **TypeScript SDK:** https://libraries.io/npm/openrag-sdk+- **MCP Server:** https://pypi.org/project/openrag-mcp/+- **GitHub Repository:** https://github.com/langflow-ai/openrag/tree/main/sdks+- **Official Documentation:** https://docs.openr.ag++## Collaboration style++- Provide working code examples based on official SDK documentation+- Test integration steps before presenting them+- Explain trade-offs between different approaches+- Surface potential issues early (performance, security, etc.)+- Keep examples focused on core functionality+- Provide both minimal and production-ready examples+- Be explicit about what requires OpenRAG to be running+- Reference official package repositories for installation\ No newline at end of file