{"_id":"@a24z/pixeltable-sdk","_rev":"4-aadd6011e4336bc05638c97cc62a2db4","name":"@a24z/pixeltable-sdk","dist-tags":{"latest":"0.4.2"},"versions":{"0.1.0":{"name":"@a24z/pixeltable-sdk","version":"0.1.0","keywords":["pixeltable","api","sdk","client","typescript","javascript","ai","data"],"author":{"name":"Pixeltable, Inc."},"license":"Apache-2.0","_id":"@a24z/pixeltable-sdk@0.1.0","maintainers":[{"name":"principal-ai","email":"principle@principlemd.com"}],"homepage":"https://github.com/a24z-ai/pixeltable#readme","bugs":{"url":"https://github.com/a24z-ai/pixeltable/issues"},"dist":{"shasum":"830c88842e73864f65b24dc15a13e559b2cdefcb","tarball":"https://registry.npmjs.org/@a24z/pixeltable-sdk/-/pixeltable-sdk-0.1.0.tgz","fileCount":6,"integrity":"sha512-AbQIL1wLOcWZpYqzCE6kCRCaanb9MK3WEDbLZxqZpMhiQ5LEgrvpsugsPxagRcD718dQJ6mrTV8UG+1EkyVaZQ==","signatures":[{"sig":"MEQCIGUWB1sIwiaXpUD+aD/OEk+2gcdvn5o/H21VXJv4cWPCAiBMgLv9dvkgYDm2GXyBxj4FfPypUjAOPv2FqWJmB155qQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51946},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"f9970871c7bed01ba5e8d9b8ab1d9f7d2334f216","scripts":{"dev":"bun run --watch src/index.ts","lint":"bun run typecheck","test":"bun test","build":"bun run build:clean && bun run build:js && bun run build:types","build:js":"bun build ./src/index.ts --outdir ./dist --format esm --minify && bun build ./src/index.ts --outdir ./dist --format cjs","typecheck":"tsc --noEmit","build:clean":"rm -rf dist","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist","generate-types":"bun run scripts/generate-types.ts","prepublishOnly":"bun run lint && bun run test && bun run build"},"_npmUser":{"name":"principal-ai","email":"principle@principlemd.com"},"repository":{"url":"git+https://github.com/a24z-ai/pixeltable.git","type":"git","directory":"js-sdk"},"_npmVersion":"10.9.2","description":"JavaScript/TypeScript SDK for Pixeltable API","directories":{},"_nodeVersion":"23.11.0","dependencies":{},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pixeltable-sdk_0.1.0_1757535734496_0.039484421838960726","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@a24z/pixeltable-sdk","version":"0.4.0","keywords":["pixeltable","api","sdk","client","typescript","javascript","ai","data","embeddings","vector-search","similarity-search","semantic-search"],"author":{"name":"Pixeltable, Inc."},"license":"Apache-2.0","_id":"@a24z/pixeltable-sdk@0.4.0","maintainers":[{"name":"principal-ai","email":"principle@principlemd.com"}],"homepage":"https://github.com/a24z-ai/pixeltable#readme","bugs":{"url":"https://github.com/a24z-ai/pixeltable/issues"},"dist":{"shasum":"49cb18e032a7b1eb1ed579f4a0de8c5199b38ec5","tarball":"https://registry.npmjs.org/@a24z/pixeltable-sdk/-/pixeltable-sdk-0.4.0.tgz","fileCount":10,"integrity":"sha512-OGmzyWJnzep6T53v8R4L2eGK++wg8aXtsVkEzZClDhw/lJjGUaV+jNOmbVbL1zyNgbfZYKZDJt7IkOZ/mC+f8g==","signatures":[{"sig":"MEUCIQCVenhqj32u8ljsQ8IzZmCffbkd3VsZwfVyK3hCQHkedwIgCrGazDdKuXFflbmmc18zP6K/Iby+bj36eG59LYyhLMI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106209},"main":"./dist/index.js","types":"./dist/src/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"eb9b9c1c834467f2881abda95dab1ed46e783bc8","scripts":{"dev":"bun run --watch src/index.ts","lint":"bun run typecheck","test":"bun test","build":"bun run build:clean && bun run build:js && bun run build:types","build:js":"bun build ./src/index.ts --format esm --minify --outfile dist/index.mjs && bun build ./src/index.ts --format cjs --outfile dist/index.js","typecheck":"tsc --noEmit","build:clean":"rm -rf dist","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist","generate-types":"bun run scripts/generate-types.ts","prepublishOnly":"bun run lint && bun run test && bun run build"},"_npmUser":{"name":"principal-ai","email":"principle@principlemd.com"},"repository":{"url":"git+https://github.com/a24z-ai/pixeltable.git","type":"git","directory":"js-sdk"},"_npmVersion":"10.9.2","description":"JavaScript/TypeScript SDK for Pixeltable API with embeddings and search","directories":{},"_nodeVersion":"23.11.0","dependencies":{},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pixeltable-sdk_0.4.0_1757572052866_0.050636238750193296","host":"s3://npm-registry-packages-npm-production"}},"0.4.1":{"name":"@a24z/pixeltable-sdk","version":"0.4.1","keywords":["pixeltable","api","sdk","client","typescript","javascript","ai","data","embeddings","vector-search","similarity-search","semantic-search"],"author":{"name":"Pixeltable, Inc."},"license":"Apache-2.0","_id":"@a24z/pixeltable-sdk@0.4.1","maintainers":[{"name":"principal-ai","email":"principle@principlemd.com"}],"homepage":"https://github.com/a24z-ai/pixeltable#readme","bugs":{"url":"https://github.com/a24z-ai/pixeltable/issues"},"dist":{"shasum":"26c9a30d15b03b99e9d60222a9be296e5feb7c69","tarball":"https://registry.npmjs.org/@a24z/pixeltable-sdk/-/pixeltable-sdk-0.4.1.tgz","fileCount":10,"integrity":"sha512-7z04jXMfA/hdBHEl4u+sp4gIemjxBt0MTyPKpeeRqs4x0qKJ8H0+xRNLEtQFlw1sH1w+MFqldn8MK1FfUEe6EQ==","signatures":[{"sig":"MEYCIQDmeRObAolFDQSpgOJlJhIFyF264aRj/y82rqJb78d4qgIhAIdnrk23AmpfdmOP/iK3erlvc3j9eZQypS8TbGxRXuH4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":106209},"main":"./dist/index.js","types":"./dist/src/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"eb9b9c1c834467f2881abda95dab1ed46e783bc8","scripts":{"dev":"bun run --watch src/index.ts","lint":"bun run typecheck","test":"bun test","build":"bun run build:clean && bun run build:js && bun run build:types","build:js":"bun build ./src/index.ts --format esm --minify --outfile dist/index.mjs && bun build ./src/index.ts --format cjs --outfile dist/index.js","typecheck":"tsc --noEmit","build:clean":"rm -rf dist","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist","generate-types":"bun run scripts/generate-types.ts","prepublishOnly":"bun run lint && bun run test && bun run build"},"_npmUser":{"name":"principal-ai","email":"principle@principlemd.com"},"repository":{"url":"git+https://github.com/a24z-ai/pixeltable.git","type":"git","directory":"js-sdk"},"_npmVersion":"10.9.2","description":"JavaScript/TypeScript SDK for Pixeltable API with embeddings and search","directories":{},"_nodeVersion":"23.11.0","dependencies":{},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pixeltable-sdk_0.4.1_1757572285671_0.32232605960474126","host":"s3://npm-registry-packages-npm-production"}},"0.4.2":{"name":"@a24z/pixeltable-sdk","version":"0.4.2","description":"JavaScript/TypeScript SDK for Pixeltable API with embeddings and search","author":{"name":"Pixeltable, Inc."},"license":"Apache-2.0","homepage":"https://github.com/a24z-ai/pixeltable#readme","repository":{"type":"git","url":"git+https://github.com/a24z-ai/pixeltable.git","directory":"js-sdk"},"bugs":{"url":"https://github.com/a24z-ai/pixeltable/issues"},"keywords":["pixeltable","api","sdk","client","typescript","javascript","ai","data","embeddings","vector-search","similarity-search","semantic-search"],"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/src/index.d.ts","exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"bun run build:clean && bun run build:js && bun run build:types","build:clean":"rm -rf dist","build:js":"bun build ./src/index.ts --format esm --minify --outfile dist/index.mjs && bun build ./src/index.ts --format cjs --outfile dist/index.js","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist","dev":"bun run --watch src/index.ts","test":"bun test","typecheck":"tsc --noEmit","lint":"bun run typecheck","prepublishOnly":"bun run lint && bun run test && bun run build","generate-types":"bun run scripts/generate-types.ts"},"dependencies":{},"devDependencies":{"@types/bun":"latest","typescript":"^5.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"engines":{"node":">=18.0.0"},"_id":"@a24z/pixeltable-sdk@0.4.2","gitHead":"eb9b9c1c834467f2881abda95dab1ed46e783bc8","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-NZQZxQenzaTztplOIcK2gJQIi/3lLJRk2EM7oCgeDXoNB1hOBLJUyydpbGAeCYvq/Rj0z2yHyRtjkfjaZAffLQ==","shasum":"80b8e96ab5d58148b3ae9b0c7a9f3f137dd92a07","tarball":"https://registry.npmjs.org/@a24z/pixeltable-sdk/-/pixeltable-sdk-0.4.2.tgz","fileCount":10,"unpackedSize":106380,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAHpiy6XAD6RxPf4ti3++5oSYQCsc7e5BYgJeI4hxQwCAiEAjXBh+/wac26JAX6vaKDMHogo2RfTxkTLikVJ/kEfVuk="}]},"_npmUser":{"name":"fernando-ram-lugo","email":"principle@principlemd.com"},"directories":{},"maintainers":[{"name":"fernando-ram-lugo","email":"principle@principlemd.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pixeltable-sdk_0.4.2_1758497135111_0.6493572098359901"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-10T20:22:14.343Z","modified":"2025-09-21T23:25:35.592Z","0.1.0":"2025-09-10T20:22:14.702Z","0.4.0":"2025-09-11T06:27:33.077Z","0.4.1":"2025-09-11T06:31:25.848Z","0.4.2":"2025-09-21T23:25:35.311Z"},"bugs":{"url":"https://github.com/a24z-ai/pixeltable/issues"},"author":{"name":"Pixeltable, Inc."},"license":"Apache-2.0","homepage":"https://github.com/a24z-ai/pixeltable#readme","keywords":["pixeltable","api","sdk","client","typescript","javascript","ai","data","embeddings","vector-search","similarity-search","semantic-search"],"repository":{"type":"git","url":"git+https://github.com/a24z-ai/pixeltable.git","directory":"js-sdk"},"description":"JavaScript/TypeScript SDK for Pixeltable API with embeddings and search","maintainers":[{"name":"fernando-ram-lugo","email":"principle@principlemd.com"}],"readme":"# @a24z/pixeltable-sdk\n\nOfficial JavaScript/TypeScript SDK for Pixeltable API.\n\n## Installation\n\n```bash\nnpm install @a24z/pixeltable-sdk\n# or\nyarn add @a24z/pixeltable-sdk\n# or\nbun add @a24z/pixeltable-sdk\n```\n\n## Quick Start\n\n```typescript\nimport PixeltableClient from '@a24z/pixeltable-sdk';\n\nconst client = new PixeltableClient({\n  baseUrl: 'http://localhost:8000/api/v1', // Optional, this is the default\n  apiKey: 'pxt_live_your_api_key_here' // Optional, but recommended for production\n});\n\n// Check API health\nconst health = await client.health();\nconsole.log(health); // { status: 'healthy' }\n\n// List all tables\nconst tables = await client.listTables();\nconsole.log(tables); // ['table1', 'table2', ...]\n\n// Create a new table\nawait client.createTable('my_table', {\n  columns: {\n    id: 'int',\n    name: 'string',\n    score: 'float',\n    is_active: 'bool'\n  }\n});\n\n// Get table information\nconst tableInfo = await client.getTable('my_table');\nconsole.log(tableInfo);\n// {\n//   name: 'my_table',\n//   column_count: 4,\n//   columns: [\n//     { name: 'id', type: 'int', is_computed: false },\n//     { name: 'name', type: 'string', is_computed: false },\n//     ...\n//   ]\n// }\n\n// Drop a table\nawait client.dropTable('my_table');\n```\n\n## 🚀 Embeddings & Vector Search (New in v0.4.0)\n\n### Generate Embeddings\n\n```typescript\n// Generate a single embedding\nconst embedding = await client.embeddings.generateEmbedding(\n  'React component organization patterns'\n);\nconsole.log(embedding); // Float32Array with 384 dimensions\n\n// Generate embeddings for multiple texts (batch)\nconst embeddings = await client.embeddings.generateEmbeddings([\n  'How to use React hooks',\n  'TypeScript best practices',\n  'CSS Grid layout guide'\n]);\nconsole.log(embeddings.length); // 3 embeddings\n\n// List available models\nconst models = await client.embeddings.listModels();\nconsole.log(models);\n// [\n//   { id: 'sentence-transformers/all-MiniLM-L6-v2', dimensions: 384, ... },\n//   { id: 'openai/text-embedding-ada-002', dimensions: 1536, ... }\n// ]\n\n// Preload a model for optimal performance\nawait client.embeddings.preloadModel('sentence-transformers/all-MiniLM-L6-v2');\n\n// Monitor cache performance\nconst stats = await client.embeddings.getCacheStats();\nconsole.log(`Cache hit rate: ${stats.hit_rate * 100}%`);\n```\n\n### Similarity Search\n\n```typescript\n// Simple similarity search\nconst results = await client.search.search('code_layouts', \n  'React hooks best practices',\n  {\n    column: 'teaches_embedding',\n    limit: 10,\n    threshold: 0.7,\n    metric: 'cosine'\n  }\n);\n\n// Search with filters (Alexandria pattern)\nconst filteredResults = await client.search.search('code_layouts',\n  'TypeScript component patterns',\n  {\n    column: 'teaches_embedding',\n    limit: 5,\n    filters: [\n      { column: 'quality_score', operator: '>=', value: 8 },\n      { column: 'language', operator: '=', value: 'TypeScript' }\n    ]\n  }\n);\n\n// Fluent search builder API\nconst fluentResults = await client.search\n  .similarity('code_layouts', 'React state management')\n  .inColumn('teaches_embedding')\n  .where({ column: 'quality_score', operator: '>=', value: 7 })\n  .where({ column: 'language', operator: '=', value: 'JavaScript' })\n  .threshold(0.6)\n  .limit(20)\n  .withScores(true)\n  .execute();\n\n// Hybrid search (combines vector + text search)\nconst hybridResults = await client.search.hybridSearch('code_layouts',\n  'useEffect cleanup patterns',\n  {\n    embeddingColumn: 'teaches_embedding',\n    textColumns: ['title', 'description', 'tags'],\n    limit: 15,\n    alpha: 0.7  // 70% weight to vector search, 30% to text\n  }\n);\n\n// Search with pre-computed embedding\nconst embedding = await client.embeddings.generateEmbedding('my query');\nconst embeddingResults = await client.search.search('my_table',\n  embedding,  // Pass Float32Array directly\n  {\n    column: 'embedding_column',\n    limit: 10\n  }\n);\n```\n\n### Performance Characteristics\n\n- **Embedding Generation**: <100ms for cached embeddings\n- **Similarity Search**: <200ms P95 latency for 10k documents\n- **Batch Processing**: Up to 100 texts per request\n- **Cache Hit Rate**: >70% with LRU eviction\n- **Concurrent Users**: 100+ without degradation\n\n## Authentication & Security\n\n```typescript\n// Create an API key for production use\nconst { api_key, key_info } = await client.createAPIKey({\n  name: 'Production API Key',\n  permissions: [\n    { resource: 'tables', actions: ['read', 'write', 'create', 'delete'] },\n    { resource: 'data', actions: ['read', 'write'] }\n  ],\n  expires_at: '2025-12-31T23:59:59Z' // Optional expiration\n});\n\n// IMPORTANT: Save the api_key securely - it won't be shown again!\nconsole.log('Save this key:', api_key);\n\n// Use the API key in a new client\nconst authenticatedClient = new PixeltableClient({\n  apiKey: api_key\n});\n\n// Verify authentication\nconst auth = await authenticatedClient.verifyAuth();\nconsole.log('Authenticated with permissions:', auth.permissions);\n\n// Manage API keys\nconst keys = await client.listAPIKeys();\nconst stats = await client.getAPIKeyUsage(key_info.id, 24); // Last 24 hours\nawait client.rotateAPIKey(key_info.id); // Rotate for security\nawait client.revokeAPIKey(key_info.id); // Revoke when no longer needed\n```\n\n## Data Operations\n\n```typescript\n// Insert data\nawait client.insertRow('my_table', {\n  id: 1,\n  name: 'John Doe',\n  score: 95.5,\n  is_active: true\n});\n\nawait client.insertRows('my_table', {\n  rows: [\n    { id: 2, name: 'Jane', score: 88.0 },\n    { id: 3, name: 'Bob', score: 92.3 }\n  ]\n});\n\n// Query data\nconst results = await client.query('my_table', {\n  select: ['name', 'score'],\n  where: [\n    { column: 'score', operator: '>=', value: 90 },\n    { column: 'is_active', operator: '=', value: true }\n  ],\n  order_by: [{ column: 'score', direction: 'desc' }],\n  limit: 10\n});\n\n// Update data\nawait client.updateRows('my_table', {\n  where: [{ column: 'score', operator: '<', value: 60 }],\n  set: { is_active: false }\n});\n\n// Delete data\nawait client.deleteRows('my_table', {\n  where: [{ column: 'is_active', operator: '=', value: false }]\n});\n\n// Count rows\nconst count = await client.countRows('my_table');\nconsole.log(`Total rows: ${count.row_count}`);\n```\n\n## API Reference\n\n### Embeddings API\n\n#### `client.embeddings.generateEmbedding(text, model?, options?)`\nGenerate an embedding for a single text.\n- Returns: `Promise<Float32Array>`\n\n#### `client.embeddings.generateEmbeddings(texts, model?, options?)`\nGenerate embeddings for multiple texts (batch).\n- Returns: `Promise<Float32Array[]>`\n\n#### `client.embeddings.listModels()`\nList all available embedding models.\n- Returns: `Promise<EmbeddingModel[]>`\n\n#### `client.embeddings.preloadModel(modelId)`\nPreload a model into memory for faster inference.\n- Returns: `Promise<void>`\n\n#### `client.embeddings.getCacheStats()`\nGet embedding cache statistics.\n- Returns: `Promise<CacheStatsResponse>`\n\n#### `client.embeddings.clearCache()`\nClear the embedding cache.\n- Returns: `Promise<void>`\n\n### Search API\n\n#### `client.search.search(tableName, query, options)`\nPerform similarity search on a table.\n- `query`: Text string or Float32Array embedding\n- `options.column`: Embedding column to search\n- `options.limit`: Maximum results (default: 10)\n- `options.threshold`: Minimum similarity score\n- `options.filters`: SQL-like filter conditions\n- `options.metric`: Distance metric (cosine, euclidean, inner_product)\n- Returns: `Promise<SearchResult[]>`\n\n#### `client.search.hybridSearch(tableName, query, options)`\nPerform hybrid search combining vector and text search.\n- Returns: `Promise<SearchResult[]>`\n\n#### `client.search.similarity(tableName, query)`\nCreate a fluent search builder for intuitive queries.\n- Returns: `SearchBuilder`\n\n### Core API\n\n#### `new PixeltableClient(config?)`\nCreates a new Pixeltable client instance.\n- `config.baseUrl`: API base URL (default: `http://localhost:8000/api/v1`)\n- `config.apiKey`: API key for authentication\n\n#### Table Operations\n- `client.listTables()`: List all tables\n- `client.createTable(name, schema)`: Create a new table\n- `client.getTable(name)`: Get table information\n- `client.dropTable(name)`: Delete a table\n\n#### Data Operations\n- `client.insertRow(tableName, data)`: Insert single row\n- `client.insertRows(tableName, request)`: Insert multiple rows\n- `client.query(tableName, request)`: Advanced query with filters\n- `client.updateRows(tableName, request)`: Update rows\n- `client.deleteRows(tableName, request)`: Delete rows\n- `client.countRows(tableName)`: Count rows\n\n#### Authentication Operations\n- `client.createAPIKey(request)`: Create API key\n- `client.listAPIKeys()`: List API keys\n- `client.getAPIKey(keyId)`: Get API key info\n- `client.revokeAPIKey(keyId)`: Revoke API key\n- `client.verifyAuth()`: Verify authentication\n\n## TypeScript Support\n\nThis SDK is written in TypeScript and provides full type definitions out of the box.\n\n```typescript\nimport PixeltableClient, { \n  TableSchema, \n  TableInfo,\n  EmbeddingModel,\n  SearchResult,\n  WhereClause\n} from '@a24z/pixeltable-sdk';\n\n// All types are fully typed\nconst schema: TableSchema = {\n  columns: {\n    id: 'int',\n    name: 'string',\n    content_embedding: 'array'  // For embedding columns\n  }\n};\n\nconst searchOptions: SimilaritySearchOptions = {\n  column: 'content_embedding',\n  limit: 10,\n  threshold: 0.7,\n  metric: 'cosine'\n};\n```\n\n## Requirements\n\n- Node.js >= 18.0.0\n- Pixeltable API server running (see [main repository](https://github.com/a24z-ai/pixeltable))\n\n## Development\n\n```bash\n# Install dependencies\nbun install\n\n# Run tests\nbun test\n\n# Type check\nbun run typecheck\n\n# Build\nbun run build\n\n# Generate types from API\nbun run generate-types\n```\n\n## License\n\nApache-2.0\n\n## Contributing\n\nSee the [main repository](https://github.com/a24z-ai/pixeltable) for contribution guidelines.","readmeFilename":"README.md"}