Skip to content

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.json
new file mode 100644
index 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/install
new file mode 120000
index 000000000..3770ea72b
--- /dev/null
+++ b/.claude/skills/install
@@ -0,0 +1 @@
+../../plugins/openrag/skills/install
\ No newline at end of file
diff --git a/.claude/skills/sdk b/.claude/skills/sdk
new file mode 120000
index 000000000..b58ff5b98
--- /dev/null
+++ b/.claude/skills/sdk
@@ -0,0 +1 @@
+../../plugins/openrag/skills/sdk
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 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.md
documents/warmup_ocr.pdf
documents/openrag-documentation.pdf
documents/ibm_anthropic.pdf
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.json
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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