@a24z/pixeltable-sdk

Official JavaScript/TypeScript SDK for Pixeltable API.

Installation

npm install @a24z/pixeltable-sdk
# or
yarn add @a24z/pixeltable-sdk
# or
bun add @a24z/pixeltable-sdk

Quick Start

import PixeltableClient from '@a24z/pixeltable-sdk';

const client = new PixeltableClient({
  baseUrl: 'http://localhost:8000/api/v1', // Optional, this is the default
  apiKey: 'pxt_live_your_api_key_here' // Optional, but recommended for production
});

// Check API health
const health = await client.health();
console.log(health); // { status: 'healthy' }

// List all tables
const tables = await client.listTables();
console.log(tables); // ['table1', 'table2', ...]

// Create a new table
await client.createTable('my_table', {
  columns: {
    id: 'int',
    name: 'string',
    score: 'float',
    is_active: 'bool'
  }
});

// Get table information
const tableInfo = await client.getTable('my_table');
console.log(tableInfo);
// {
//   name: 'my_table',
//   column_count: 4,
//   columns: [
//     { name: 'id', type: 'int', is_computed: false },
//     { name: 'name', type: 'string', is_computed: false },
//     ...
//   ]
// }

// Drop a table
await client.dropTable('my_table');

🚀 Embeddings & Vector Search (New in v0.4.0)

Generate Embeddings

// Generate a single embedding
const embedding = await client.embeddings.generateEmbedding(
  'React component organization patterns'
);
console.log(embedding); // Float32Array with 384 dimensions

// Generate embeddings for multiple texts (batch)
const embeddings = await client.embeddings.generateEmbeddings([
  'How to use React hooks',
  'TypeScript best practices',
  'CSS Grid layout guide'
]);
console.log(embeddings.length); // 3 embeddings

// List available models
const models = await client.embeddings.listModels();
console.log(models);
// [
//   { id: 'sentence-transformers/all-MiniLM-L6-v2', dimensions: 384, ... },
//   { id: 'openai/text-embedding-ada-002', dimensions: 1536, ... }
// ]

// Preload a model for optimal performance
await client.embeddings.preloadModel('sentence-transformers/all-MiniLM-L6-v2');

// Monitor cache performance
const stats = await client.embeddings.getCacheStats();
console.log(`Cache hit rate: ${stats.hit_rate * 100}%`);

Similarity Search

// Simple similarity search
const results = await client.search.search('code_layouts', 
  'React hooks best practices',
  {
    column: 'teaches_embedding',
    limit: 10,
    threshold: 0.7,
    metric: 'cosine'
  }
);

// Search with filters (Alexandria pattern)
const filteredResults = await client.search.search('code_layouts',
  'TypeScript component patterns',
  {
    column: 'teaches_embedding',
    limit: 5,
    filters: [
      { column: 'quality_score', operator: '>=', value: 8 },
      { column: 'language', operator: '=', value: 'TypeScript' }
    ]
  }
);

// Fluent search builder API
const fluentResults = await client.search
  .similarity('code_layouts', 'React state management')
  .inColumn('teaches_embedding')
  .where({ column: 'quality_score', operator: '>=', value: 7 })
  .where({ column: 'language', operator: '=', value: 'JavaScript' })
  .threshold(0.6)
  .limit(20)
  .withScores(true)
  .execute();

// Hybrid search (combines vector + text search)
const hybridResults = await client.search.hybridSearch('code_layouts',
  'useEffect cleanup patterns',
  {
    embeddingColumn: 'teaches_embedding',
    textColumns: ['title', 'description', 'tags'],
    limit: 15,
    alpha: 0.7  // 70% weight to vector search, 30% to text
  }
);

// Search with pre-computed embedding
const embedding = await client.embeddings.generateEmbedding('my query');
const embeddingResults = await client.search.search('my_table',
  embedding,  // Pass Float32Array directly
  {
    column: 'embedding_column',
    limit: 10
  }
);

Performance Characteristics

• Embedding Generation: <100ms for cached embeddings
• Similarity Search: <200ms P95 latency for 10k documents
• Batch Processing: Up to 100 texts per request
• Cache Hit Rate: >70% with LRU eviction
• Concurrent Users: 100+ without degradation

Authentication & Security

// Create an API key for production use
const { api_key, key_info } = await client.createAPIKey({
  name: 'Production API Key',
  permissions: [
    { resource: 'tables', actions: ['read', 'write', 'create', 'delete'] },
    { resource: 'data', actions: ['read', 'write'] }
  ],
  expires_at: '2025-12-31T23:59:59Z' // Optional expiration
});

// IMPORTANT: Save the api_key securely - it won't be shown again!
console.log('Save this key:', api_key);

// Use the API key in a new client
const authenticatedClient = new PixeltableClient({
  apiKey: api_key
});

// Verify authentication
const auth = await authenticatedClient.verifyAuth();
console.log('Authenticated with permissions:', auth.permissions);

// Manage API keys
const keys = await client.listAPIKeys();
const stats = await client.getAPIKeyUsage(key_info.id, 24); // Last 24 hours
await client.rotateAPIKey(key_info.id); // Rotate for security
await client.revokeAPIKey(key_info.id); // Revoke when no longer needed

Data Operations

// Insert data
await client.insertRow('my_table', {
  id: 1,
  name: 'John Doe',
  score: 95.5,
  is_active: true
});

await client.insertRows('my_table', {
  rows: [
    { id: 2, name: 'Jane', score: 88.0 },
    { id: 3, name: 'Bob', score: 92.3 }
  ]
});

// Query data
const results = await client.query('my_table', {
  select: ['name', 'score'],
  where: [
    { column: 'score', operator: '>=', value: 90 },
    { column: 'is_active', operator: '=', value: true }
  ],
  order_by: [{ column: 'score', direction: 'desc' }],
  limit: 10
});

// Update data
await client.updateRows('my_table', {
  where: [{ column: 'score', operator: '<', value: 60 }],
  set: { is_active: false }
});

// Delete data
await client.deleteRows('my_table', {
  where: [{ column: 'is_active', operator: '=', value: false }]
});

// Count rows
const count = await client.countRows('my_table');
console.log(`Total rows: ${count.row_count}`);

API Reference

Embeddings API

client.embeddings.generateEmbedding(text, model?, options?)

Generate an embedding for a single text.

• Returns: Promise<Float32Array>

client.embeddings.generateEmbeddings(texts, model?, options?)

Generate embeddings for multiple texts (batch).

• Returns: Promise<Float32Array[]>

client.embeddings.listModels()

List all available embedding models.

• Returns: Promise<EmbeddingModel[]>

client.embeddings.preloadModel(modelId)

Preload a model into memory for faster inference.

• Returns: Promise<void>

client.embeddings.getCacheStats()

Get embedding cache statistics.

• Returns: Promise<CacheStatsResponse>

client.embeddings.clearCache()

Clear the embedding cache.

• Returns: Promise<void>

Search API

client.search.search(tableName, query, options)

Perform similarity search on a table.

• query: Text string or Float32Array embedding
• options.column: Embedding column to search
• options.limit: Maximum results (default: 10)
• options.threshold: Minimum similarity score
• options.filters: SQL-like filter conditions
• options.metric: Distance metric (cosine, euclidean, inner_product)
• Returns: Promise<SearchResult[]>

client.search.hybridSearch(tableName, query, options)

Perform hybrid search combining vector and text search.

• Returns: Promise<SearchResult[]>

client.search.similarity(tableName, query)

Create a fluent search builder for intuitive queries.

• Returns: SearchBuilder

Core API

new PixeltableClient(config?)

Creates a new Pixeltable client instance.

• config.baseUrl: API base URL (default: http://localhost:8000/api/v1)
• config.apiKey: API key for authentication

Table Operations

• client.listTables(): List all tables
• client.createTable(name, schema): Create a new table
• client.getTable(name): Get table information
• client.dropTable(name): Delete a table

Data Operations

• client.insertRow(tableName, data): Insert single row
• client.insertRows(tableName, request): Insert multiple rows
• client.query(tableName, request): Advanced query with filters
• client.updateRows(tableName, request): Update rows
• client.deleteRows(tableName, request): Delete rows
• client.countRows(tableName): Count rows

Authentication Operations

• client.createAPIKey(request): Create API key
• client.listAPIKeys(): List API keys
• client.getAPIKey(keyId): Get API key info
• client.revokeAPIKey(keyId): Revoke API key
• client.verifyAuth(): Verify authentication

TypeScript Support

This SDK is written in TypeScript and provides full type definitions out of the box.

import PixeltableClient, { 
  TableSchema, 
  TableInfo,
  EmbeddingModel,
  SearchResult,
  WhereClause
} from '@a24z/pixeltable-sdk';

// All types are fully typed
const schema: TableSchema = {
  columns: {
    id: 'int',
    name: 'string',
    content_embedding: 'array'  // For embedding columns
  }
};

const searchOptions: SimilaritySearchOptions = {
  column: 'content_embedding',
  limit: 10,
  threshold: 0.7,
  metric: 'cosine'
};

Requirements

• Node.js >= 18.0.0
• Pixeltable API server running (see main repository)

Development

# Install dependencies
bun install

# Run tests
bun test

# Type check
bun run typecheck

# Build
bun run build

# Generate types from API
bun run generate-types

License

Apache-2.0

Contributing

See the main repository for contribution guidelines.