rag
Purpose
This skill implements Retrieval-Augmented Generation (RAG) for OpenClaw, enabling AI models to query external knowledge bases and integrate results into responses, enhancing accuracy for tasks like question-answering.
When to Use
Use this skill when your AI needs dynamic access to external data, such as querying a vector database for real-time information in NLP tasks, handling knowledge gaps in models, or augmenting responses in chatbots. Avoid it for purely generative tasks without external dependencies.
Key Capabilities
- Fetches documents from vector databases (e.g., Pinecone, FAISS) using similarity search.
- Integrates retrieved content into AI prompts for generation.
- Supports embedding models for query vectorization (e.g., via Hugging Face transformers).
- Handles chunking of large documents and relevance scoring.
- Configurable via JSON files for custom sources and thresholds.
Usage Patterns
Always set the API key via environment variable: export OPENCLAW_API_KEY=$SERVICE_API_KEY. For CLI, use openclaw rag with required flags. In code, import the skill and call methods like rag.retrieve(). Pattern: Query -> Retrieve -> Augment -> Generate. Ensure queries are under 512 tokens to avoid truncation.
Common Commands/API
- CLI Command:
openclaw rag query --db pinecone --index myindex --query "What is RAG?" --top-k 5
- Flags: --db specifies database (e.g., pinecone, faiss), --index for collection name, --top-k for result count, --query for search string.
- API Endpoint: POST /v1/rag/retrieve with JSON body:
{"query": "Explain AI", "db": "pinecone", "top_k": 3}
- Response: JSON object with keys like "results" (array of documents) and "scores".
- Code Snippet (Python):
import openclaw client = openclaw.Client(api_key=os.environ['OPENCLAW_API_KEY']) results = client.rag.retrieve(query="What is NLP?", db="faiss", top_k=4) - Config Format: JSON file (e.g., rag_config.json):
{"db": "pinecone", "api_endpoint": "https://api.pinecone.io", "embedding_model": "text-embedding-ada-002"}Load it via:openclaw rag config load --file rag_config.json.
Integration Notes
Integrate by wrapping RAG calls around your AI pipeline: First, call rag.retrieve() to get context, then pass it to your model's prompt. For multi-skill workflows, chain with "aiml" skills by piping outputs (e.g., use RAG results as input to a generation skill). Handle asynchronous calls with await client.rag.retrieve_async() in async environments. Test integrations in a sandbox with mock databases to verify data flow.
Error Handling
Check for common errors like authentication failures (e.g., "401 Unauthorized" if $OPENCLAW_API_KEY is invalid) by verifying env vars first. For query errors, catch exceptions like RetrievalError and retry with exponential backoff:
try:
results = client.rag.retrieve(query=query)
except openclaw.RetrievalError as e:
if e.status_code == 404:
print("Database not found; create index first.")
else:
raiseLog all errors with details (e.g., error codes, messages) and use --debug flag in CLI for verbose output. Always validate inputs (e.g., ensure query is a string) before calling.
Concrete Usage Examples
- Example 1: CLI Query for Knowledge Retrieval Use to answer user questions: Run
openclaw rag query --db faiss --index docs_index --query "Summarize RAG technique" --top-k 3. This retrieves top 3 documents from the "docs_index" database and outputs them. Pipe the result:openclaw rag query... | openclaw aiml generate --prompt "Use this context:". - Example 2: Code Integration for AI Response In a Python script, augment a chatbot:
query = "What is machine learning?" context = client.rag.retrieve(query=query, db="pinecone", top_k=2) full_prompt = f"Context: {context}\nAnswer: {query}" response = client.aiml.generate(prompt=full_prompt) print(response)This fetches relevant context and passes it to the AI for a informed response.
Graph Relationships
- Related to: aiml (for generation integration), nlp (for text processing), vector-db (for data storage dependencies).
- Depends on: embedding skills for vectorization.
- Used by: knowledge-base skills for external data access.