HeliosDB AI Integration Guide

HeliosDB AI Integration Guide

Building AI-Powered Applications with HeliosDB

HeliosDB provides native AI capabilities designed for seamless integration with AI applications, chatbots, agents, and large language models (LLMs).

---

Overview

HeliosDB’s AI-first architecture includes:

• Native Vector Storage - HNSW indexes for semantic search
• Automatic Embeddings - Generate embeddings on insert
• Hybrid Search - Combine semantic and keyword search
• RAG Support - Built-in retrieval-augmented generation patterns
• LLM-Friendly API - Designed for AI agent consumption

---

Quick Start for AI Applications

1. Create an AI-Ready Database

curl -X POST https://api.heliosdb.io/v1/databases \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-ai-app",
    "tier": "developer",
    "features": ["vector", "embeddings"]
  }'

2. Create a Knowledge Base Table

CREATE TABLE knowledge_base (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    metadata JSONB DEFAULT '{}',
    embedding VECTOR(1536) GENERATED ALWAYS AS (
        helios_embed('openai/text-embedding-3-small', content)
    ) STORED,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX knowledge_base_embedding_idx ON knowledge_base
    USING hnsw (embedding vector_cosine_ops);

3. Add Documents

curl -X POST https://my-ai-app.heliosdb.io/api/v1/sql \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "INSERT INTO knowledge_base (title, content, metadata) VALUES ($1, $2, $3)",
    "params": [
      "Getting Started Guide",
      "HeliosDB is a universal database platform that supports multiple protocols...",
      {"category": "documentation", "version": "7.0"}
    ]
  }'

4. Semantic Search

curl -X POST https://my-ai-app.heliosdb.io/api/v1/vectors/search \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "knowledge_base",
    "embedding_column": "embedding",
    "query": "how do I connect to the database?",
    "limit": 5,
    "threshold": 0.7,
    "return_columns": ["id", "title", "content", "metadata"]
  }'

---

Integration Patterns

Pattern 1: RAG (Retrieval-Augmented Generation)

Use HeliosDB as the retrieval layer for RAG applications:

import openai
import requests

HELIOS_TOKEN = "hdb_live_xxx"
HELIOS_DB = "my-ai-app.heliosdb.io"

def retrieve_context(query: str, limit: int = 5) -> list:
    """Retrieve relevant documents from HeliosDB."""
    response = requests.post(
        f"https://{HELIOS_DB}/api/v1/vectors/search",
        headers={"Authorization": f"Bearer {HELIOS_TOKEN}"},
        json={
            "table": "knowledge_base",
            "embedding_column": "embedding",
            "query": query,
            "limit": limit,
            "threshold": 0.6
        }
    )
    return response.json()["data"]["results"]

def generate_response(query: str) -> str:
    """Generate response using RAG."""
    # Step 1: Retrieve relevant context
    context_docs = retrieve_context(query)

    # Step 2: Build prompt with context
    context = "\n\n".join([doc["content"] for doc in context_docs])

    prompt = f"""Answer the question based on the following context.

Context:
{context}

Question: {query}

Answer:"""

    # Step 3: Generate with LLM
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )

    return response.choices[0].message.content

# Usage
answer = generate_response("How do I create a database branch?")
print(answer)

Pattern 2: Conversational Memory

Store conversation history for context-aware AI:

-- Conversation storage
CREATE TABLE conversations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id UUID NOT NULL,
    role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
    content TEXT NOT NULL,
    embedding VECTOR(1536) GENERATED ALWAYS AS (
        helios_embed('openai/text-embedding-3-small', content)
    ) STORED,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX conversations_session_idx ON conversations(session_id, created_at);
CREATE INDEX conversations_embedding_idx ON conversations USING hnsw (embedding vector_cosine_ops);

class ConversationMemory:
    def __init__(self, session_id: str):
        self.session_id = session_id

    def add_message(self, role: str, content: str, metadata: dict = None):
        """Add a message to conversation history."""
        requests.post(
            f"https://{HELIOS_DB}/api/v1/sql",
            headers={"Authorization": f"Bearer {HELIOS_TOKEN}"},
            json={
                "query": """
                    INSERT INTO conversations (session_id, role, content, metadata)
                    VALUES ($1, $2, $3, $4)
                """,
                "params": [self.session_id, role, content, metadata or {}]
            }
        )

    def get_recent_history(self, limit: int = 20) -> list:
        """Get recent conversation history."""
        response = requests.post(
            f"https://{HELIOS_DB}/api/v1/sql",
            headers={"Authorization": f"Bearer {HELIOS_TOKEN}"},
            json={
                "query": """
                    SELECT role, content, created_at
                    FROM conversations
                    WHERE session_id = $1
                    ORDER BY created_at DESC
                    LIMIT $2
                """,
                "params": [self.session_id, limit]
            }
        )
        return response.json()["data"]["rows"]

    def search_similar(self, query: str, limit: int = 5) -> list:
        """Search for similar past conversations."""
        response = requests.post(
            f"https://{HELIOS_DB}/api/v1/vectors/search",
            headers={"Authorization": f"Bearer {HELIOS_TOKEN}"},
            json={
                "table": "conversations",
                "embedding_column": "embedding",
                "query": query,
                "limit": limit,
                "filters": {"session_id": self.session_id}
            }
        )
        return response.json()["data"]["results"]

Pattern 3: AI Agent Tool Use

HeliosDB as a tool for AI agents:

# Tool definition for Claude, GPT-4, etc.
HELIOS_TOOLS = [
    {
        "name": "query_database",
        "description": "Execute a SQL query against the HeliosDB database to retrieve or modify data.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "SQL query to execute. Use $1, $2 for parameters."
                },
                "params": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "Query parameters (optional)"
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "semantic_search",
        "description": "Search for documents semantically similar to the query.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Natural language search query"
                },
                "table": {
                    "type": "string",
                    "description": "Table to search in"
                },
                "limit": {
                    "type": "integer",
                    "description": "Maximum results to return"
                }
            },
            "required": ["query", "table"]
        }
    },
    {
        "name": "create_branch",
        "description": "Create an isolated database branch for safe experimentation.",
        "input_schema": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Branch name"
                },
                "from": {
                    "type": "string",
                    "description": "Source branch (default: main)"
                }
            },
            "required": ["name"]
        }
    }
]

def execute_tool(tool_name: str, tool_input: dict) -> dict:
    """Execute a HeliosDB tool."""

    if tool_name == "query_database":
        response = requests.post(
            f"https://{HELIOS_DB}/api/v1/sql",
            headers={"Authorization": f"Bearer {HELIOS_TOKEN}"},
            json={
                "query": tool_input["query"],
                "params": tool_input.get("params", [])
            }
        )
        return response.json()

    elif tool_name == "semantic_search":
        response = requests.post(
            f"https://{HELIOS_DB}/api/v1/vectors/search",
            headers={"Authorization": f"Bearer {HELIOS_TOKEN}"},
            json={
                "table": tool_input["table"],
                "embedding_column": "embedding",
                "query": tool_input["query"],
                "limit": tool_input.get("limit", 10)
            }
        )
        return response.json()

    elif tool_name == "create_branch":
        response = requests.post(
            f"https://{HELIOS_DB}/api/v1/branches",
            headers={"Authorization": f"Bearer {HELIOS_TOKEN}"},
            json={
                "name": tool_input["name"],
                "from": tool_input.get("from", "main")
            }
        )
        return response.json()

    return {"error": f"Unknown tool: {tool_name}"}

Pattern 4: Structured Output Parsing

Store and query structured AI outputs:

-- Store structured LLM outputs
CREATE TABLE ai_outputs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    prompt TEXT NOT NULL,
    raw_output TEXT NOT NULL,
    structured_output JSONB,
    model TEXT NOT NULL,
    tokens_used INTEGER,
    latency_ms INTEGER,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Query specific structured fields
SELECT
    structured_output->>'sentiment' as sentiment,
    structured_output->>'confidence' as confidence,
    COUNT(*) as count
FROM ai_outputs
WHERE structured_output->>'category' = 'customer_feedback'
GROUP BY sentiment, confidence;

---

Embedding Models

HeliosDB supports multiple embedding models:

Model	Dimensions	Use Case
openai/text-embedding-3-small	1536	General purpose, cost-effective
openai/text-embedding-3-large	3072	Highest accuracy
openai/text-embedding-ada-002	1536	Legacy support
cohere/embed-english-v3.0	1024	English-optimized
cohere/embed-multilingual-v3.0	1024	Multi-language
voyage/voyage-large-2	1536	Long documents
helios/local-small	384	Local, no external API
helios/local-large	768	Local, better accuracy

Configure model per column:

-- High accuracy column
ALTER TABLE documents ADD COLUMN embedding_large VECTOR(3072)
    GENERATED ALWAYS AS (
        helios_embed('openai/text-embedding-3-large', content)
    ) STORED;

-- Cost-effective column
ALTER TABLE documents ADD COLUMN embedding_small VECTOR(1536)
    GENERATED ALWAYS AS (
        helios_embed('openai/text-embedding-3-small', content)
    ) STORED;

---

Hybrid Search

Combine semantic and keyword search:

-- Hybrid search function
SELECT
    id,
    title,
    content,
    -- Combine semantic similarity and BM25 keyword score
    (0.7 * (1 - (embedding <-> $1))) +
    (0.3 * ts_rank(to_tsvector('english', content), plainto_tsquery('english', $2)))
    AS combined_score
FROM knowledge_base
WHERE
    -- Semantic filter
    embedding <-> $1 < 0.5
    -- Keyword filter
    AND to_tsvector('english', content) @@ plainto_tsquery('english', $2)
ORDER BY combined_score DESC
LIMIT 10;

Via API:

curl -X POST https://my-ai-app.heliosdb.io/api/v1/vectors/hybrid-search \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "knowledge_base",
    "query": "database connection pooling",
    "semantic_weight": 0.7,
    "keyword_weight": 0.3,
    "limit": 10
  }'

---

Multimodal Search

Search across text, images, and other modalities:

-- Multimodal content table
CREATE TABLE content (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    content_type TEXT NOT NULL CHECK (content_type IN ('text', 'image', 'audio', 'video')),
    title TEXT,
    raw_content BYTEA,
    text_content TEXT,
    -- Unified embedding space for all modalities
    embedding VECTOR(1536) GENERATED ALWAYS AS (
        CASE content_type
            WHEN 'text' THEN helios_embed('openai/text-embedding-3-small', text_content)
            WHEN 'image' THEN helios_embed_image('clip-vit-base-patch32', raw_content)
            WHEN 'audio' THEN helios_embed_audio('whisper-base', raw_content)
            ELSE helios_embed('openai/text-embedding-3-small', title)
        END
    ) STORED
);

-- Search across all modalities with text query
SELECT * FROM content
WHERE embedding <-> helios_embed('openai/text-embedding-3-small', 'sunset over mountains')
ORDER BY embedding <-> helios_embed('openai/text-embedding-3-small', 'sunset over mountains')
LIMIT 10;

---

Performance Optimization

Index Tuning

-- HNSW index with custom parameters
CREATE INDEX ON knowledge_base USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

-- Set search parameters
SET hnsw.ef_search = 100;  -- Higher = more accurate, slower

Batch Operations

# Batch insert for efficiency
curl -X POST https://my-ai-app.heliosdb.io/api/v1/sql/batch \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "statements": [
      {"query": "INSERT INTO knowledge_base (title, content) VALUES ($1, $2)", "params": ["Doc 1", "Content 1"]},
      {"query": "INSERT INTO knowledge_base (title, content) VALUES ($1, $2)", "params": ["Doc 2", "Content 2"]},
      {"query": "INSERT INTO knowledge_base (title, content) VALUES ($1, $2)", "params": ["Doc 3", "Content 3"]}
    ],
    "transaction": true
  }'

Caching

-- Enable query result caching for repeated searches
SET helios.result_cache = 'on';
SET helios.result_cache_ttl = '5 minutes';

---

LangChain Integration

from langchain.vectorstores import HeliosDB
from langchain.embeddings import OpenAIEmbeddings

# Initialize HeliosDB vector store
vectorstore = HeliosDB(
    connection_string=f"postgresql://default:{HELIOS_TOKEN}@{HELIOS_DB}:5432/main",
    table_name="knowledge_base",
    embedding=OpenAIEmbeddings()
)

# Add documents
vectorstore.add_texts(
    texts=["Document 1 content", "Document 2 content"],
    metadatas=[{"source": "file1"}, {"source": "file2"}]
)

# Similarity search
results = vectorstore.similarity_search("query text", k=5)

---

LlamaIndex Integration

from llama_index import VectorStoreIndex, SimpleDirectoryReader
from llama_index.vector_stores import HeliosDBVectorStore

# Initialize vector store
vector_store = HeliosDBVectorStore(
    host=HELIOS_DB,
    port=5432,
    user="default",
    password=HELIOS_TOKEN,
    database="main",
    table_name="knowledge_base"
)

# Create index
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(
    documents,
    vector_store=vector_store
)

# Query
query_engine = index.as_query_engine()
response = query_engine.query("What is HeliosDB?")

---

Best Practices

1. Chunking Strategy

def chunk_document(content: str, chunk_size: int = 1000, overlap: int = 200) -> list:
    """Split document into overlapping chunks."""
    chunks = []
    start = 0
    while start < len(content):
        end = start + chunk_size
        chunk = content[start:end]
        chunks.append({
            "content": chunk,
            "start_index": start,
            "end_index": end
        })
        start += chunk_size - overlap
    return chunks

2. Metadata Enrichment

-- Store rich metadata for filtering
INSERT INTO knowledge_base (title, content, metadata) VALUES (
    'API Guide',
    'The HeliosDB API provides...',
    '{
        "category": "documentation",
        "language": "en",
        "version": "7.0",
        "last_updated": "2025-12-16",
        "author": "engineering",
        "tags": ["api", "rest", "authentication"]
    }'
);

-- Filter by metadata in searches
SELECT * FROM knowledge_base
WHERE metadata->>'category' = 'documentation'
  AND embedding <-> $1 < 0.5
ORDER BY embedding <-> $1
LIMIT 10;

3. Freshness Tracking

-- Track document freshness
ALTER TABLE knowledge_base ADD COLUMN freshness_score FLOAT
    GENERATED ALWAYS AS (
        1.0 / (1.0 + EXTRACT(EPOCH FROM (NOW() - created_at)) / 86400)
    ) STORED;

-- Boost recent documents
SELECT *,
       (1 - (embedding <-> $1)) * 0.8 + freshness_score * 0.2 AS score
FROM knowledge_base
ORDER BY score DESC
LIMIT 10;

---

Rate Limits for AI Operations

Operation	Free	Developer	Team	Enterprise
Embedding generations/min	10	100	1,000	Unlimited
Vector searches/min	60	600	6,000	Unlimited
Batch embeddings/request	10	100	1,000	10,000

---

Next Steps

• API Reference - Complete API documentation
• Free Tier Guide - Get started free
• Authentication - Secure your integration

---

HeliosDB: The AI-native database for intelligent applications.