Skip to content

AI_INTEGRATION_GUIDE.md

Latest commit

 

History

History
804 lines (642 loc) · 15.6 KB

AI_INTEGRATION_GUIDE.md

File metadata and controls

804 lines (642 loc) · 15.6 KB

AI Integration Guide

Complete guide to building AI-powered ObjectStack applications

Table of Contents

  1. Introduction
  2. AI Protocols Overview
  3. Getting Started
  4. Building AI Agents
  5. Implementing RAG
  6. Natural Language Queries
  7. Model Registry
  8. Production Best Practices
  9. Example Applications

Introduction

ObjectStack provides a comprehensive AI protocol suite enabling you to build intelligent, context-aware applications. This guide covers all AI capabilities from RAG pipelines to natural language query processing.

What You Can Build

  • Intelligent Assistants: Context-aware chatbots with function calling
  • Natural Language Interfaces: Query data using plain English
  • Code Generators: Generate ObjectStack apps from descriptions
  • Smart Automation: AI-powered workflows and decision making

AI Protocols Overview

ObjectStack includes four core AI protocols:

1. Agent Protocol (@objectstack/spec/ai/agent)

Define autonomous AI agents with:

  • Model configuration
  • Function calling (tools)
  • Knowledge base access (RAG)
  • Access control

2. Model Registry Protocol (@objectstack/spec/ai/model-registry)

Centralized LLM management:

  • Model configurations
  • Prompt templates
  • Fallback handling
  • Health monitoring

3. RAG Pipeline Protocol (@objectstack/spec/ai/rag-pipeline)

Retrieval-Augmented Generation:

  • Vector store configuration
  • Embedding models
  • Chunking strategies
  • Retrieval methods (similarity, MMR, hybrid)

4. Natural Language Query Protocol (@objectstack/spec/ai/nlq)

Transform natural language to ObjectQL:

  • Intent detection
  • Entity recognition
  • Timeframe parsing
  • Field mapping

Getting Started

Installation

npm install @objectstack/spec

Basic Agent

import { Agent } from '@objectstack/spec';

const myAgent: Agent = {
  name: 'my_assistant',
  label: 'My AI Assistant',
  role: 'Customer Support Specialist',
  instructions: 'You are a helpful assistant.',
  
  model: {
    provider: 'openai',
    model: 'gpt-4-turbo-preview',
    temperature: 0.7,
  },
  
  active: true,
};

Building AI Agents

Agent Components

1. Identity & Role

const agent: Agent = {
  name: 'support_agent',        // snake_case identifier
  label: 'Support Agent',        // Display name
  avatar: '/avatars/bot.png',    // Optional avatar
  role: 'Customer Support',      // Agent persona
};

2. Instructions (System Prompt)

instructions: `You are an experienced customer support agent.

Your responsibilities:
- Answer questions professionally
- Create support tickets when needed
- Escalate complex issues

Always be polite and solution-oriented.`

3. Model Configuration

model: {
  provider: 'openai',
  model: 'gpt-4-turbo-preview',
  temperature: 0.7,      // Creativity (0-2)
  maxTokens: 2048,       // Response length
  topP: 0.9,             // Nucleus sampling
}

4. Tools (Function Calling)

tools: [
  {
    type: 'action',
    name: 'create_ticket',
    description: 'Create a new support ticket',
  },
  {
    type: 'query',
    name: 'search_tickets',
    description: 'Search existing tickets',
  },
  {
    type: 'vector_search',
    name: 'kb_search',
    description: 'Search knowledge base',
  },
  {
    type: 'flow',
    name: 'escalate_to_human',
    description: 'Transfer to human agent',
  },
]

5. Knowledge Base (RAG)

knowledge: {
  topics: ['product_docs', 'faq', 'troubleshooting'],
  indexes: ['support_kb_v2'],
}

6. Access Control

access: ['support_team', 'customers'],
active: true,

Advanced Agent Example

import { Agent } from '@objectstack/spec';

export const DataAnalystAgent: Agent = {
  name: 'data_analyst_ai',
  label: 'AI Data Analyst',
  avatar: '/avatars/analyst.png',
  role: 'Business Intelligence Analyst',
  
  instructions: `You are a data analyst helping users understand business metrics.

Skills:
- Interpret natural language questions about data
- Generate ObjectQL queries
- Create visualizations
- Provide actionable insights

Be precise, data-driven, and clear.`,
  
  model: {
    provider: 'openai',
    model: 'gpt-4',
    temperature: 0.3,  // Lower for precision
    maxTokens: 4096,
  },
  
  tools: [
    {
      type: 'query',
      name: 'execute_objectql',
      description: 'Execute ObjectQL queries on data',
    },
    {
      type: 'action',
      name: 'create_dashboard',
      description: 'Generate dashboard from metrics',
    },
    {
      type: 'action',
      name: 'generate_chart',
      description: 'Create visualizations',
    },
  ],
  
  knowledge: {
    topics: ['sql_guides', 'metrics_definitions'],
    indexes: ['analytics_kb'],
  },
  
  access: ['analysts', 'executives', 'managers'],
  active: true,
};

Implementing RAG

Why RAG?

RAG (Retrieval-Augmented Generation) enables AI to:

  • Access up-to-date information
  • Reduce hallucinations
  • Provide source citations
  • Scale beyond context windows

RAG Pipeline Configuration

import { RAGPipelineConfig } from '@objectstack/spec';

const myRAG: RAGPipelineConfig = {
  name: 'knowledge_base',
  label: 'Knowledge Base RAG',
  description: 'RAG for product documentation',
  
  // 1. Embedding Model
  embedding: {
    provider: 'openai',
    model: 'text-embedding-3-large',
    dimensions: 3072,
    batchSize: 100,
  },
  
  // 2. Vector Store
  vectorStore: {
    provider: 'pinecone',
    indexName: 'kb-prod',
    namespace: 'v2',
    dimensions: 3072,
    metric: 'cosine',
  },
  
  // 3. Chunking Strategy
  chunking: {
    type: 'markdown',
    maxChunkSize: 1000,
    respectHeaders: true,
    respectCodeBlocks: true,
  },
  
  // 4. Retrieval Method
  retrieval: {
    type: 'mmr',         // Maximal Marginal Relevance
    topK: 5,
    fetchK: 20,
    lambda: 0.7,         // Balance relevance vs diversity
  },
  
  // 5. Optional Reranking
  reranking: {
    enabled: true,
    model: 'rerank-english-v3.0',
    provider: 'cohere',
    topK: 3,
  },
  
  // 6. Document Loaders
  loaders: [
    {
      type: 'directory',
      source: '/docs',
      fileTypes: ['.md', '.txt', '.pdf'],
      recursive: true,
    },
  ],
  
  maxContextTokens: 6000,
  enableCache: true,
  cacheTTL: 3600,
};

Chunking Strategies

Fixed Size

chunking: {
  type: 'fixed',
  chunkSize: 512,
  chunkOverlap: 50,
  unit: 'tokens',
}

Semantic Chunking

chunking: {
  type: 'semantic',
  minChunkSize: 100,
  maxChunkSize: 1000,
}

Recursive Text Splitting

chunking: {
  type: 'recursive',
  separators: ['\n\n', '\n', '. ', ' '],
  chunkSize: 1000,
  chunkOverlap: 100,
}

Markdown-Aware

chunking: {
  type: 'markdown',
  maxChunkSize: 1500,
  respectHeaders: true,
  respectCodeBlocks: true,
}

Retrieval Methods

Similarity Search

retrieval: {
  type: 'similarity',
  topK: 5,
  scoreThreshold: 0.7,
}

MMR (Diverse Results)

retrieval: {
  type: 'mmr',
  topK: 5,
  fetchK: 20,
  lambda: 0.5,  // 0=diverse, 1=relevant
}

Hybrid (Vector + Keyword)

retrieval: {
  type: 'hybrid',
  topK: 10,
  vectorWeight: 0.7,
  keywordWeight: 0.3,
}

Querying RAG

import { RAGQueryRequest } from '@objectstack/spec';

const request: RAGQueryRequest = {
  query: 'How do I configure authentication?',
  pipelineName: 'knowledge_base',
  topK: 5,
  metadataFilters: {
    category: 'security',
  },
  includeMetadata: true,
  includeSources: true,
  executeQuery: false,  // Just retrieve, don't generate
};

Natural Language Queries

NLQ Configuration

import { NLQModelConfig } from '@objectstack/spec';

const nlqConfig: NLQModelConfig = {
  modelId: 'gpt-4-turbo',
  
  // Prompt Engineering
  systemPrompt: `Convert natural language to ObjectQL.
  Available objects: account, opportunity, task`,
  
  includeSchema: true,
  includeExamples: true,
  
  // Features
  enableIntentDetection: true,
  enableEntityRecognition: true,
  enableFuzzyMatching: true,
  enableTimeframeDetection: true,
  
  // Caching
  enableCaching: true,
  cacheTTL: 3600,
};

Field Synonyms

Help NLQ understand natural variations:

import { FieldSynonymConfig } from '@objectstack/spec';

const synonyms: FieldSynonymConfig[] = [
  {
    object: 'account',
    field: 'name',
    synonyms: [
      'customer name',
      'company name',
      'organization name',
      'account name',
    ],
    examples: [
      'show accounts by customer name',
      'find companies with name containing Acme',
    ],
  },
  {
    object: 'opportunity',
    field: 'amount',
    synonyms: [
      'value',
      'deal size',
      'revenue',
      'worth',
    ],
  },
];

Query Templates

Pre-built patterns for common queries:

import { QueryTemplate } from '@objectstack/spec';

const topNTemplate: QueryTemplate = {
  id: 'top-n-by-field',
  name: 'top_n_by_field',
  label: 'Top N Records',
  
  pattern: 'top {n} {object} by {field}',
  
  variables: [
    { name: 'n', type: 'value', required: true },
    { name: 'object', type: 'object', required: true },
    { name: 'field', type: 'field', required: true },
  ],
  
  astTemplate: {
    object: '{object}',
    sort: [{ field: '{field}', order: 'desc' }],
    limit: '{n}',
  },
  
  examples: [
    'top 10 accounts by revenue',
    'top 5 opportunities by amount',
  ],
};

Processing NLQ Requests

import { NLQRequest, NLQResponse } from '@objectstack/spec';

const request: NLQRequest = {
  query: 'show me all high priority tickets from last week',
  
  context: {
    userId: 'user-123',
    currentObject: 'ticket',
    defaultLimit: 100,
  },
  
  includeAlternatives: true,
  maxAlternatives: 3,
  minConfidence: 0.7,
  
  executeQuery: true,
  maxResults: 50,
};

// Response includes:
// - Parsed intent, entities, timeframe
// - Generated ObjectQL AST
// - Optional: Query results
// - Confidence scores
// - Alternative interpretations

Model Registry

Registry Configuration

import { ModelRegistry } from '@objectstack/spec';

const registry: ModelRegistry = {
  name: 'production_registry',
  
  models: {
    'gpt-4-turbo': {
      model: {
        id: 'gpt-4-turbo',
        name: 'GPT-4 Turbo',
        version: 'gpt-4-turbo-2024-04-09',
        provider: 'openai',
        
        capabilities: {
          textGeneration: true,
          functionCalling: true,
          reasoning: true,
        },
        
        limits: {
          maxTokens: 4096,
          contextWindow: 128000,
          rateLimit: {
            requestsPerMinute: 100,
          },
        },
        
        pricing: {
          inputCostPer1kTokens: 0.01,
          outputCostPer1kTokens: 0.03,
        },
      },
      
      status: 'active',
      priority: 10,
      fallbackModels: ['gpt-3.5-turbo'],
      
      healthCheck: {
        enabled: true,
        intervalSeconds: 300,
        status: 'healthy',
      },
    },
  },
  
  defaultModel: 'gpt-4-turbo',
  enableAutoFallback: true,
};

Prompt Templates

Reusable prompts with variables:

promptTemplates: {
  support_response: {
    id: 'support-v1',
    name: 'support_response',
    label: 'Support Response',
    
    system: 'You are a helpful support agent.',
    user: `Customer: {{customer_name}}
Question: {{question}}
Context: {{context}}`,
    
    variables: [
      { name: 'customer_name', type: 'string', required: true },
      { name: 'question', type: 'string', required: true },
      { name: 'context', type: 'string', required: false },
    ],
    
    modelId: 'gpt-4-turbo',
    temperature: 0.7,
    maxTokens: 2048,
    
    examples: [
      {
        input: {
          customer_name: 'John Doe',
          question: 'How do I reset my password?',
        },
        output: 'To reset your password...',
      },
    ],
  },
}

Production Best Practices

1. Model Selection

  • Reasoning tasks: GPT-4, Claude 3 Opus
  • Simple tasks: GPT-3.5, Claude 3 Haiku
  • Embeddings: text-embedding-3-large
  • Creative writing: Claude 3 Sonnet

2. Cost Optimization

  • Use smaller models for simple tasks
  • Enable caching for repeated queries
  • Batch embedding requests
  • Set appropriate token limits

3. Error Handling

{
  status: 'active',
  priority: 10,
  fallbackModels: ['backup-model'],
  healthCheck: {
    enabled: true,
    intervalSeconds: 300,
  },
}

4. Security

  • Store API keys in environment variables
  • Use access control on agents
  • Validate user inputs
  • Implement rate limiting
  • Monitor for abuse

5. Monitoring

Track:

  • Response times
  • Token usage
  • Error rates
  • User satisfaction
  • Cache hit rates

6. Testing

import { NLQTrainingExample } from '@objectstack/spec';

const trainingExamples: NLQTrainingExample[] = [
  {
    query: 'show all accounts created last month',
    expectedIntent: 'select',
    expectedObject: 'account',
    expectedAST: {
      object: 'account',
      filters: [['created_date', '>=', '2023-12-01']],
    },
  },
];

Example Applications

1. AI Support Assistant

View Example

Features:

  • RAG knowledge base
  • Ticket management
  • Escalation workflows
  • Customer satisfaction tracking

Architecture:

Customer → GPT-4 Agent → RAG (Pinecone) → Actions → ObjectQL

2. AI Data Analyst

View Example

Features:

  • Natural language queries
  • Auto-generate dashboards
  • Time-based analysis
  • Query templates

3. AI Code Generator

View Example

Features:

  • Generate ObjectStack apps
  • Schema validation
  • Best practices enforcement
  • RAG for documentation

4. AI Sales Assistant

View Example

Features:

  • Lead qualification
  • Email personalization
  • Competitive intelligence
  • Deal insights

FAQ

When should I use RAG vs fine-tuning?

Use RAG when:

  • Information changes frequently
  • You need source citations
  • Data is too large for context window
  • Privacy/compliance requirements

Use fine-tuning when:

  • Teaching specific writing style
  • Domain-specific terminology
  • Consistent behavior needed
  • Cost optimization for high volume

How do I handle low confidence queries?

if (response.parseResult.confidence < 0.7) {
  if (response.needsClarification) {
    // Ask user for clarification
    showSuggestions(response.suggestions);
  } else {
    // Show alternative interpretations
    showAlternatives(response.parseResult.alternatives);
  }
}

What vector database should I use?

  • Pinecone: Managed, easy to use
  • Weaviate: Open source, flexible
  • Qdrant: High performance, Rust-based
  • pgvector: PostgreSQL extension
  • Chroma: Local development

How do I optimize RAG performance?

  1. Use appropriate chunk sizes (500-1000 tokens)
  2. Enable reranking for accuracy
  3. Use MMR for diverse results
  4. Cache frequently accessed chunks
  5. Filter by metadata when possible
  6. Monitor retrieval metrics

Resources

Next Steps

  1. Start with a simple agent
  2. Add RAG for your knowledge base
  3. Implement natural language queries
  4. Deploy to production
  5. Monitor and optimize

Happy building! 🚀