GuidedMind RAG SDK Python

Official Python SDK for the GuidedMind platform. A production-ready, type-safe client for interacting with GuidedMind's RAG, Short Memory, and Long Memory services.

Features

• Type-safe interfaces with Pydantic v2 data models
• Async support for non-blocking operations
• Comprehensive error handling with custom exceptions
• Automatic retries with exponential backoff
• Secure by default with HTTPS enforcement and API key validation
• Structured logging with API key redaction
• Unified client for RAG, Short Memory, and Long Memory operations

Quick Start

Installation

pip install guidedmind-rag-sdk-python

Get Your API Key

1. Sign up at GuidedMind
2. Navigate to API Keys in your dashboard
3. Generate a new API key

Basic Usage

from guidedmind import Client

# Initialize client with API key
client = Client(api_key="your_api_key")

# Or use environment variable
# export GUIDEDMIND_API_KEY="your_api_key"
client = Client()

Core Functionality

1. RAG (Retrieval-Augmented Generation)

Search your documents with semantic, keyword, or hybrid search.

from guidedmind import Client, SearchMethod

client = Client(api_key="your_api_key")

# Simple semantic search
response = client.search(query="What are the main features?")

print(f"Found {len(response.results)} results")
for result in response.results:
    print(f"- {result.content[:100]}... (score: {result.score:.3f})")

# Advanced hybrid search
response = client.search(
    query="Explain the microservices architecture",
    limit=10,
    threshold=0.75,
    search_method=SearchMethod.HYBRID,
    include_metadata=True
)

print(f"Search method: {response.metadata.search_method_used}")
print(f"Processing time: {response.metadata.processing_time_ms}ms")

2. Short Memory

Session-based conversation memory with automatic expiration.

from guidedmind import Client

client = Client(api_key="your_api_key")

# Add conversation records
user_record = client.memory.short.add_record(
    session_id="session-123",
    role="user",
    content="What pricing plans do you offer?"
)

assistant_record = client.memory.short.add_record(
    session_id="session-123",
    role="assistant",
    content="We offer Free, Pro, and Enterprise plans."
)

# Retrieve all records for a session
records = client.memory.short.get_records(session_id="session-123")

print(f"Total records: {records.total}")
for record in records.records:
    print(f"{record.role}: {record.content}")

3. Long Memory

Persistent, searchable conversation memory with automatic summarization.

from guidedmind import Client

client = Client(api_key="your_api_key")

# Store conversation records
client.memory.long.store_record(
    user_id="user-456",
    role="user",
    content="I'm interested in the Pro plan for my team of 10"
)

client.memory.long.store_record(
    user_id="user-456",
    role="assistant",
    content="The Pro plan includes advanced features for teams up to 20 members."
)

# Search long-term memories
response = client.memory.long.search(
    query="What did the user say about pricing?",
    limit=10,
    threshold=0.75
)

print(f"Found {response.total} relevant memories")
for result in response.results:
    print(f"- {result.content} (score: {result.score:.3f})")

4. Document Management

Upload and process documents for RAG.

from guidedmind import Client

client = Client(api_key="your_api_key")

# Upload and process a document
response = client.documents.upload_and_process(
    file_path="technical-docs.pdf",
    metadata={"team": "engineering", "version": "2.1"}
)

print(f"Document uploaded: {response.document_id}")
print(f"Chunks created: {response.chunks_created}")

Async Support

All operations have async versions for non-blocking I/O.

import asyncio
from guidedmind import Client

async def main():
    client = Client(api_key="your_api_key")
    
    # Async RAG search
    response = await client.asearch(
        query="How does authentication work?",
        limit=10,
        threshold=0.75
    )
    
    # Async short memory
    records = await client.memory.short.aget_records(session_id="session-123")
    
    # Async long memory
    memories = await client.memory.long.search(
        query="user preferences",
        limit=5
    )
    
    # Async document upload
    upload_response = await client.documents.aupload_and_process(
        file_path="doc.pdf"
    )

asyncio.run(main())

Context Manager

The SDK supports context managers for automatic resource cleanup.

from guidedmind import Client

# Synchronous context manager
with Client(api_key="your_api_key") as client:
    response = client.search(query="What is RAG?")
    print(response.results)

# Async context manager
import asyncio

async def main():
    async with Client(api_key="your_api_key") as client:
        response = await client.asearch(query="What is RAG?")
        print(response.results)

asyncio.run(main())

Integration with AI Frameworks

LangChain Integration

from langchain.vectorstores import BaseVectorStore
from guidedmind import Client

class GuidedMindVectorStore(BaseVectorStore):
    def __init__(self, client: Client):
        self.client = client
    
    def similarity_search(self, query: str, k: int = 4):
        response = self.client.search(query=query, limit=k)
        return [result.content for result in response.results]

# Usage
client = Client(api_key="your_api_key")
vectorstore = GuidedMindVectorStore(client)
docs = vectorstore.similarity_search("microservices architecture", k=5)

LlamaIndex Integration

from llama_index.core.base.response.schema import Response
from guidedmind import Client

class GuidedMindRetriever:
    def __init__(self, client: Client):
        self.client = client
    
    def retrieve(self, query: str, top_k: int = 5):
        response = self.client.search(query=query, limit=top_k)
        return [result.content for result in response.results]

# Usage
client = Client(api_key="your_api_key")
retriever = GuidedMindRetriever(client)
context = retriever.retrieve("API authentication", top_k=3)

API Reference

Client

The main entry point for the SDK.

Constructor

Client(
    api_key: Optional[str] = None,
    base_url: str = "https://api.guidedmind.ai",
    timeout: float = 30.0,
    max_retries: int = 3
)

Methods

DocumentsClient

Accessed via client.documents.

ShortMemoryClient

Accessed via client.memory.short.

LongMemoryClient

Accessed via client.memory.long.

Search Methods

Error Handling

The SDK provides custom exceptions for different error scenarios:

from guidedmind import Client, APIError, AuthenticationError, RateLimitError

client = Client(api_key="your_api_key")

try:
    response = client.search(query="What is RAG?")
except AuthenticationError as e:
    # 401/403 errors
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    # 429 errors
    print(f"Rate limit exceeded: {e}")
except APIError as e:
    # Other API errors
    print(f"API error {e.status_code}: {e}")

Security

API Key Management

DO:

• Use environment variables for API keys (GUIDEDMIND_API_KEY)
• Store keys in secret management services (AWS Secrets Manager, HashiCorp Vault)
• Use .env files with proper .gitignore
• Rotate keys regularly

DON'T:

• Hardcode API keys in source code
• Commit API keys to version control
• Log API keys (the SDK automatically redacts them)

# ✅ GOOD
from guidedmind import Client
import os

client = Client()  # Uses GUIDEDMIND_API_KEY env var
# or
client = Client(api_key=os.environ.get("GUIDEDMIND_API_KEY"))

# ❌ BAD
client = Client(api_key="12345678_...")  # Never hardcode!

Security Features

• ✅ API key validation - Validates key format before use
• ✅ API key redaction - Automatically redacts keys in logs and errors
• ✅ HTTPS enforcement - Requires TLS 1.2+ connections
• ✅ Input validation - Validates all user inputs
• ✅ Structured logging - Logs without sensitive data
• ✅ Secure error handling - Error messages don't leak sensitive info

Configuration

Logging

import logging
from guidedmind import Client

# Enable debug logging
logging.getLogger("guidedmind").setLevel(logging.DEBUG)
logging.basicConfig(
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    level=logging.INFO
)

client = Client(api_key="your_api_key")

Custom Timeout

client = Client(
    api_key="your_api_key",
    timeout=60.0  # 60 second timeout
)

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://github.com/guidedmind/guidedmind-rag-sdk-python#readme
• Issues: https://github.com/guidedmind/guidedmind-rag-sdk-python/issues
• Email: support@guidedmind.com