moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-supabase/modules/edge-functions.md

@@ -0,0 +1,371 @@
+---
+name: edge-functions
+description: Serverless Deno functions at the edge with authentication and rate limiting
+parent-skill: moai-platform-supabase
+version: 1.0.0
+updated: 2026-01-06
+---
+
+# Edge Functions Module
+
+## Overview
+
+Supabase Edge Functions are serverless functions running on the Deno runtime at the edge, providing low-latency responses globally.
+
+## Basic Edge Function
+
+### Function Structure
+
+```typescript
+// supabase/functions/api/index.ts
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type'
+}
+
+serve(async (req) => {
+  // Handle CORS preflight
+  if (req.method === 'OPTIONS') {
+    return new Response('ok', { headers: corsHeaders })
+  }
+
+  try {
+    const supabase = createClient(
+      Deno.env.get('SUPABASE_URL')!,
+      Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+    )
+
+    // Process request
+    const body = await req.json()
+
+    return new Response(
+      JSON.stringify({ success: true, data: body }),
+      { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+    )
+  } catch (error) {
+    return new Response(
+      JSON.stringify({ error: error.message }),
+      { status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+    )
+  }
+})
+```
+
+## Authentication
+
+### JWT Token Verification
+
+```typescript
+serve(async (req) => {
+  if (req.method === 'OPTIONS') {
+    return new Response('ok', { headers: corsHeaders })
+  }
+
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  )
+
+  // Verify JWT token
+  const authHeader = req.headers.get('authorization')
+  if (!authHeader) {
+    return new Response(
+      JSON.stringify({ error: 'Unauthorized' }),
+      { status: 401, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+    )
+  }
+
+  const { data: { user }, error } = await supabase.auth.getUser(
+    authHeader.replace('Bearer ', '')
+  )
+
+  if (error || !user) {
+    return new Response(
+      JSON.stringify({ error: 'Invalid token' }),
+      { status: 401, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+    )
+  }
+
+  // User is authenticated, proceed with request
+  return new Response(
+    JSON.stringify({ success: true, user_id: user.id }),
+    { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+  )
+})
+```
+
+### Using User Context Client
+
+Create a client that inherits user permissions:
+
+```typescript
+serve(async (req) => {
+  const authHeader = req.headers.get('authorization')!
+
+  // Client with user's permissions (respects RLS)
+  const supabaseUser = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_ANON_KEY')!,
+    { global: { headers: { Authorization: authHeader } } }
+  )
+
+  // This query respects RLS policies
+  const { data, error } = await supabaseUser
+    .from('projects')
+    .select('*')
+
+  return new Response(JSON.stringify({ data }))
+})
+```
+
+## Rate Limiting
+
+### Database-Based Rate Limiting
+
+```sql
+-- Rate limits table
+CREATE TABLE rate_limits (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  identifier TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_rate_limits_lookup ON rate_limits(identifier, created_at);
+```
+
+### Rate Limit Function
+
+```typescript
+async function checkRateLimit(
+  supabase: SupabaseClient,
+  identifier: string,
+  limit: number,
+  windowSeconds: number
+): Promise<boolean> {
+  const windowStart = new Date(Date.now() - windowSeconds * 1000).toISOString()
+
+  const { count } = await supabase
+    .from('rate_limits')
+    .select('*', { count: 'exact', head: true })
+    .eq('identifier', identifier)
+    .gte('created_at', windowStart)
+
+  if (count && count >= limit) {
+    return false
+  }
+
+  await supabase.from('rate_limits').insert({ identifier })
+  return true
+}
+```
+
+### Usage in Edge Function
+
+```typescript
+serve(async (req) => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  )
+
+  // Get client identifier (IP or user ID)
+  const identifier = req.headers.get('x-forwarded-for') || 'anonymous'
+
+  // 100 requests per minute
+  const allowed = await checkRateLimit(supabase, identifier, 100, 60)
+
+  if (!allowed) {
+    return new Response(
+      JSON.stringify({ error: 'Rate limit exceeded' }),
+      { status: 429, headers: corsHeaders }
+    )
+  }
+
+  // Process request...
+})
+```
+
+## External API Integration
+
+### Webhook Handler
+
+```typescript
+serve(async (req) => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  )
+
+  // Verify webhook signature
+  const signature = req.headers.get('x-webhook-signature')
+  const body = await req.text()
+
+  const expectedSignature = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(body + Deno.env.get('WEBHOOK_SECRET'))
+  )
+
+  if (!verifySignature(signature, expectedSignature)) {
+    return new Response('Invalid signature', { status: 401 })
+  }
+
+  const payload = JSON.parse(body)
+
+  // Process webhook
+  await supabase.from('webhook_events').insert({
+    type: payload.type,
+    data: payload.data,
+    processed: false
+  })
+
+  return new Response('OK', { status: 200 })
+})
+```
+
+### External API Call
+
+```typescript
+serve(async (req) => {
+  const { query } = await req.json()
+
+  // Call external API
+  const response = await fetch('https://api.openai.com/v1/embeddings', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${Deno.env.get('OPENAI_API_KEY')}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      model: 'text-embedding-ada-002',
+      input: query
+    })
+  })
+
+  const data = await response.json()
+
+  return new Response(
+    JSON.stringify({ embedding: data.data[0].embedding }),
+    { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+  )
+})
+```
+
+## Error Handling
+
+### Structured Error Response
+
+```typescript
+interface ErrorResponse {
+  error: string
+  code: string
+  details?: unknown
+}
+
+function errorResponse(
+  message: string,
+  code: string,
+  status: number,
+  details?: unknown
+): Response {
+  const body: ErrorResponse = { error: message, code, details }
+  return new Response(
+    JSON.stringify(body),
+    { status, headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
+  )
+}
+
+serve(async (req) => {
+  try {
+    // ... processing
+  } catch (error) {
+    if (error instanceof AuthError) {
+      return errorResponse('Authentication failed', 'AUTH_ERROR', 401)
+    }
+    if (error instanceof ValidationError) {
+      return errorResponse('Invalid input', 'VALIDATION_ERROR', 400, error.details)
+    }
+    console.error('Unexpected error:', error)
+    return errorResponse('Internal server error', 'INTERNAL_ERROR', 500)
+  }
+})
+```
+
+## Deployment
+
+### Local Development
+
+```bash
+supabase functions serve api --env-file .env.local
+```
+
+### Deploy Function
+
+```bash
+supabase functions deploy api
+```
+
+### Set Secrets
+
+```bash
+supabase secrets set OPENAI_API_KEY=sk-xxx
+supabase secrets set WEBHOOK_SECRET=whsec-xxx
+```
+
+### List Functions
+
+```bash
+supabase functions list
+```
+
+## Best Practices
+
+### Cold Start Optimization
+
+Keep imports minimal at the top level:
+
+```typescript
+// Good: Import only what's needed
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+
+// Bad: Heavy imports at top level increase cold start
+// import { everything } from 'large-library'
+```
+
+### Response Streaming
+
+Stream large responses:
+
+```typescript
+serve(async (req) => {
+  const stream = new ReadableStream({
+    async start(controller) {
+      for (let i = 0; i < 10; i++) {
+        await new Promise(r => setTimeout(r, 100))
+        controller.enqueue(new TextEncoder().encode(`data: ${i}\n\n`))
+      }
+      controller.close()
+    }
+  })
+
+  return new Response(stream, {
+    headers: { 'Content-Type': 'text/event-stream' }
+  })
+})
+```
+
+## Context7 Query Examples
+
+For latest Edge Functions documentation:
+
+Topic: "edge functions deno runtime"
+Topic: "supabase functions deploy secrets"
+Topic: "edge functions cors authentication"
+
+---
+
+Related Modules:
+- auth-integration.md - Authentication patterns
+- typescript-patterns.md - Client invocation

moai_adk/templates/.claude/skills/moai-platform-supabase/modules/postgresql-pgvector.md

@@ -0,0 +1,231 @@
+---
+name: postgresql-pgvector
+description: PostgreSQL 16 with pgvector extension for AI embeddings and semantic search
+parent-skill: moai-platform-supabase
+version: 1.0.0
+updated: 2026-01-06
+---
+
+# PostgreSQL 16 + pgvector Module
+
+## Overview
+
+PostgreSQL 16 with pgvector extension enables AI-powered semantic search through vector embeddings storage and similarity search operations.
+
+## Extension Setup
+
+Enable required extensions for vector operations:
+
+```sql
+-- Enable required extensions
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+## Embeddings Table Schema
+
+Create a table optimized for storing AI embeddings:
+
+```sql
+CREATE TABLE documents (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  content TEXT NOT NULL,
+  embedding vector(1536),  -- OpenAI ada-002 dimensions
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+### Common Embedding Dimensions
+
+- OpenAI ada-002: 1536 dimensions
+- OpenAI text-embedding-3-small: 1536 dimensions
+- OpenAI text-embedding-3-large: 3072 dimensions
+- Cohere embed-english-v3.0: 1024 dimensions
+- Google PaLM: 768 dimensions
+
+## Index Strategies
+
+### HNSW Index (Recommended)
+
+HNSW (Hierarchical Navigable Small World) provides fast approximate nearest neighbor search:
+
+```sql
+CREATE INDEX idx_documents_embedding ON documents
+USING hnsw (embedding vector_cosine_ops)
+WITH (m = 16, ef_construction = 64);
+```
+
+Parameters:
+- m: Maximum number of connections per layer (default 16, higher = more accurate but slower)
+- ef_construction: Size of dynamic candidate list during construction (default 64)
+
+### IVFFlat Index (Large Datasets)
+
+IVFFlat is better for datasets with millions of rows:
+
+```sql
+CREATE INDEX idx_documents_ivf ON documents
+USING ivfflat (embedding vector_cosine_ops)
+WITH (lists = 100);
+```
+
+Guidelines for lists parameter:
+- Less than 1M rows: lists = rows / 1000
+- More than 1M rows: lists = sqrt(rows)
+
+## Distance Operations
+
+Available distance operators:
+
+- `<->` - Euclidean distance (L2)
+- `<#>` - Negative inner product
+- `<=>` - Cosine distance
+
+For normalized embeddings, cosine distance is recommended.
+
+## Semantic Search Function
+
+Basic semantic search with threshold and limit:
+
+```sql
+CREATE OR REPLACE FUNCTION search_documents(
+  query_embedding vector(1536),
+  match_threshold FLOAT DEFAULT 0.8,
+  match_count INT DEFAULT 10
+) RETURNS TABLE (id UUID, content TEXT, similarity FLOAT)
+LANGUAGE plpgsql AS $$
+BEGIN
+  RETURN QUERY SELECT d.id, d.content,
+    1 - (d.embedding <=> query_embedding) AS similarity
+  FROM documents d
+  WHERE 1 - (d.embedding <=> query_embedding) > match_threshold
+  ORDER BY d.embedding <=> query_embedding
+  LIMIT match_count;
+END; $$;
+```
+
+### Usage Example
+
+```sql
+SELECT * FROM search_documents(
+  '[0.1, 0.2, ...]'::vector(1536),
+  0.75,
+  20
+);
+```
+
+## Hybrid Search
+
+Combine vector similarity with full-text search for better results:
+
+```sql
+CREATE OR REPLACE FUNCTION hybrid_search(
+  query_text TEXT,
+  query_embedding vector(1536),
+  match_count INT DEFAULT 10,
+  full_text_weight FLOAT DEFAULT 0.3,
+  semantic_weight FLOAT DEFAULT 0.7
+) RETURNS TABLE (id UUID, content TEXT, score FLOAT) AS $$
+BEGIN
+  RETURN QUERY
+  WITH semantic AS (
+    SELECT e.id, e.content, 1 - (e.embedding <=> query_embedding) AS similarity
+    FROM documents e ORDER BY e.embedding <=> query_embedding LIMIT match_count * 2
+  ),
+  full_text AS (
+    SELECT e.id, e.content,
+      ts_rank(to_tsvector('english', e.content), plainto_tsquery('english', query_text)) AS rank
+    FROM documents e
+    WHERE to_tsvector('english', e.content) @@ plainto_tsquery('english', query_text)
+    LIMIT match_count * 2
+  )
+  SELECT COALESCE(s.id, f.id), COALESCE(s.content, f.content),
+    (COALESCE(s.similarity, 0) * semantic_weight + COALESCE(f.rank, 0) * full_text_weight)
+  FROM semantic s FULL OUTER JOIN full_text f ON s.id = f.id
+  ORDER BY 3 DESC LIMIT match_count;
+END; $$ LANGUAGE plpgsql;
+```
+
+## Full-Text Search Index
+
+Add GIN index for efficient full-text search:
+
+```sql
+CREATE INDEX idx_documents_content_fts ON documents
+USING gin(to_tsvector('english', content));
+```
+
+## Performance Optimization
+
+### Query Performance
+
+Set appropriate ef_search for HNSW queries:
+
+```sql
+SET hnsw.ef_search = 100;  -- Higher = more accurate, slower
+```
+
+### Batch Insertions
+
+Use COPY or multi-row INSERT for bulk embeddings:
+
+```sql
+INSERT INTO documents (content, embedding, metadata)
+VALUES
+  ('Content 1', '[...]'::vector(1536), '{"source": "doc1"}'),
+  ('Content 2', '[...]'::vector(1536), '{"source": "doc2"}'),
+  ('Content 3', '[...]'::vector(1536), '{"source": "doc3"}');
+```
+
+### Index Maintenance
+
+Reindex after large bulk insertions:
+
+```sql
+REINDEX INDEX CONCURRENTLY idx_documents_embedding;
+```
+
+## Metadata Filtering
+
+Combine vector search with JSONB metadata filters:
+
+```sql
+CREATE OR REPLACE FUNCTION search_with_filters(
+  query_embedding vector(1536),
+  filter_metadata JSONB,
+  match_count INT DEFAULT 10
+) RETURNS TABLE (id UUID, content TEXT, similarity FLOAT) AS $$
+BEGIN
+  RETURN QUERY SELECT d.id, d.content,
+    1 - (d.embedding <=> query_embedding) AS similarity
+  FROM documents d
+  WHERE d.metadata @> filter_metadata
+  ORDER BY d.embedding <=> query_embedding
+  LIMIT match_count;
+END; $$;
+```
+
+### Usage with Filters
+
+```sql
+SELECT * FROM search_with_filters(
+  '[0.1, 0.2, ...]'::vector(1536),
+  '{"category": "technical", "language": "en"}'::jsonb,
+  10
+);
+```
+
+## Context7 Query Examples
+
+For latest pgvector documentation:
+
+Topic: "pgvector extension indexes hnsw ivfflat"
+Topic: "vector similarity search operators"
+Topic: "postgresql full-text search tsvector"
+
+---
+
+Related Modules:
+- row-level-security.md - Secure vector data access
+- typescript-patterns.md - Client-side search implementation