ai-database 0.0.0-development → 0.1.0

package/README.md

@@ -1,72 +1,114 @@
 # ai-database
 
-[![npm version](https://badge.fury.io/js/ai-database.svg)](https://badge.fury.io/js/ai-database)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-AI-native database abstraction with hybrid vector search capabilities for synthetic data, tool-calling, and RAG applications.
-
-## Features
-- Hybrid vector search optimized for AI workloads
-- Synthetic data generation and management
-- Tool-calling interface compatible with major AI SDKs
-- Built-in support for RAG (Retrieval Augmented Generation)
-- Seamless integration with mdxdb for document storage
+Direct interface to Payload CMS with database.do compatibility.
 
 ## Installation
+
 ```bash
 npm install ai-database
 # or
-pnpm add ai-database
-# or
 yarn add ai-database
+# or
+pnpm add ai-database
 ```
 
-## Quick Start
+## Usage
+
+### Node.js Environment
+
 ```typescript
-import { createDatabase } from 'ai-database'
+import { getPayload } from 'payload'
+import config from '@payload-config'
+import { DB } from 'ai-database'
+
+// Initialize with Payload instance
+const payload = await getPayload({ config })
+const db = DB({ payload })
 
-// Initialize database with vector search capabilities
-const db = createDatabase({
-  namespace: 'my-app',
-  vectorSearch: true
+// Use the same interface as database.do
+const posts = await db.posts.find({
+  where: { status: 'published' },
+  limit: 10,
 })
 
-// Store documents with embeddings
-await db.collection('documents').store({
-  content: 'Example document',
-  embeddings: [0.1, 0.2, 0.3]
+const post = await db.posts.findOne('post-123')
+```
+
+### Edge Environment
+
+```typescript
+import { DB } from 'ai-database'
+
+// Initialize with REST API URL
+const db = DB({
+  apiUrl: 'https://your-payload-api.com/api',
+  apiKey: 'your-api-key',
 })
 
-// Perform hybrid search
-const results = await db.collection('documents').search({
-  query: 'example',
-  vector: [0.1, 0.2, 0.3],
-  threshold: 0.8
+// Use the same interface as database.do
+const posts = await db.posts.find({
+  where: { status: 'published' },
+  limit: 10,
 })
+
+const post = await db.posts.findOne('post-123')
+```
+
+### Generating Embeddings
+
+```typescript
+import { generateEmbedding, calculateSimilarity } from 'ai-database'
+
+// Generate embeddings for text
+const result = await generateEmbedding('Text to embed')
+
+if (result.success) {
+  console.log('Embedding:', result.embedding)
+  console.log('Model used:', result.model)
+
+  // Calculate similarity between two embeddings
+  const embedding1 = result.embedding[0]
+  const embedding2 = await generateEmbedding('Similar text').then((r) => r.embedding?.[0])
+
+  if (embedding1 && embedding2) {
+    const similarity = calculateSimilarity(embedding1, embedding2)
+    console.log('Similarity score:', similarity)
+  }
+}
 ```
 
-## Tool Integration
-ai-database exports AI-compatible tools that work with any LLM supporting function calling:
+## API
+
+The API is compatible with `database.do`, providing the same methods for each collection:
+
+- `find(options?)`: Find documents in the collection
+- `findOne(id)`: Find a single document by ID
+- `create(data)`: Create a new document
+- `update(id, data)`: Update an existing document
+- `delete(id)`: Delete a document
+- `search(query, options?)`: Search for documents
+
+## Environment-specific Adapters
+
+For more control over environment-specific initialization:
 
 ```typescript
-import { tools } from 'ai-database'
+import { createNodeClient, createEdgeClient } from 'ai-database/adapters'
+
+// Node.js
+const nodeDb = createNodeClient({ payload })
 
-// Use with any AI SDK (Vercel AI, LangChain, etc)
-const searchTool = tools.vectorSearch({
-  collection: 'documents',
-  namespace: 'my-app'
+// Edge
+const edgeDb = createEdgeClient({
+  apiUrl: 'https://your-payload-api.com/api',
 })
 ```
 
-## Integration with AI Primitives
-ai-database is designed to work seamlessly with other AI Primitives packages:
+## Embedding Functions
 
-- **ai-functions**: Provides database operations as callable AI functions
-- **ai-workflows**: Enables database integration in AI workflow definitions
-- **ai-agents**: Offers database access tools for AI agents
+- `generateEmbedding(text, options?)`: Generate embeddings for text using the AI SDK
+- `calculateSimilarity(embedding1, embedding2)`: Calculate cosine similarity between two embeddings
 
-## API Reference
-[API documentation link]
+## License
 
-## Dependencies
-Built on top of [mdxdb](https://github.com/ai-primitives/mdxdb) for robust document storage and vector search capabilities.
+MIT

package/dist/index.d.mts

@@ -0,0 +1,195 @@
+import { ListResponse } from 'apis.do/types';
+export { ClientOptions, ErrorResponse, ListResponse, QueryParams } from 'apis.do/types';
+
+/**
+ * Types for ai-database package
+ */
+
+/**
+ * Options for embedding generation
+ */
+interface EmbeddingOptions {
+    /** Embedding model to use (defaults to openai:text-embedding-3-small) */
+    model?: string;
+    /** Additional options for the embedding model */
+    [key: string]: any;
+}
+/**
+ * Result of embedding generation
+ */
+interface EmbeddingResult {
+    /** Generated embedding vectors */
+    embedding: number[][] | null;
+    /** Model used for embedding generation */
+    model: string;
+    /** Whether the embedding generation was successful */
+    success: boolean;
+    /** Error message if embedding generation failed */
+    error?: string;
+}
+/**
+ * Generic collection data type
+ */
+type CollectionData = Record<string, any>;
+/**
+ * Query options for database operations
+ */
+interface QueryOptions {
+    /** Filter criteria */
+    where?: Record<string, any>;
+    /** Sorting options (field:direction) */
+    sort?: string | string[];
+    /** Number of results per page */
+    limit?: number;
+    /** Page number for pagination */
+    page?: number;
+    /** Fields to include in the result */
+    select?: string | string[];
+    /** Relations to populate */
+    populate?: string | string[];
+}
+/**
+ * Methods available for each collection
+ * @template T Document type for the collection
+ */
+interface CollectionMethods<T = CollectionData> {
+    /** Find documents in the collection */
+    find: (options?: QueryOptions) => Promise<ListResponse<T>>;
+    /** Find a single document by ID */
+    findOne: (id: string) => Promise<T>;
+    /** Create a new document */
+    create: (data: Partial<T>) => Promise<T>;
+    /** Update an existing document */
+    update: (id: string, data: Partial<T>) => Promise<T>;
+    /** Delete a document */
+    delete: (id: string) => Promise<T>;
+    /** Search for documents */
+    search: (query: string, options?: QueryOptions) => Promise<ListResponse<T>>;
+}
+/**
+ * Database client interface
+ */
+interface DatabaseClientType {
+    /** Dynamic access to any collection */
+    [collection: string]: CollectionMethods;
+}
+/**
+ * Payload instance interface defining the minimum required methods
+ */
+interface PayloadInstance {
+    find?: (options: any) => Promise<any>;
+    findByID?: (options: any) => Promise<any>;
+    create?: (options: any) => Promise<any>;
+    update?: (options: any) => Promise<any>;
+    delete?: (options: any) => Promise<any>;
+    db?: any;
+    [key: string]: any;
+}
+/**
+ * Configuration for REST API-based Payload client
+ */
+interface RestClientConfig {
+    apiUrl: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    fetchOptions?: RequestInit;
+}
+/**
+ * Options for DB initialization
+ */
+interface DBOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    payload?: PayloadInstance;
+    apiUrl?: string;
+    headers?: Record<string, string>;
+    fetchOptions?: RequestInit;
+    [collection: string]: any;
+}
+/**
+ * Collection handler options
+ */
+interface CollectionHandlerOptions {
+    payload: PayloadInstance;
+    collectionName: string;
+}
+
+/**
+ * Node.js adapter for ai-database
+ */
+
+/**
+ * Creates a database client for Node.js environments
+ * @param options Configuration options
+ * @returns Database client instance
+ * @example
+ * import { getPayload } from 'payload'
+ * import config from '@payload-config'
+ * import { createNodeClient } from 'ai-database/adapters'
+ *
+ * const payload = await getPayload({ config })
+ * const db = createNodeClient({ payload })
+ */
+declare const createNodeClient: (options?: DBOptions) => DatabaseClientType;
+
+/**
+ * Edge runtime adapter for ai-database
+ */
+
+/**
+ * Creates a database client for Edge runtime environments
+ * @param options Configuration options (must include apiUrl)
+ * @returns Database client instance
+ * @example
+ * import { createEdgeClient } from 'ai-database/adapters'
+ *
+ * const db = createEdgeClient({
+ *   apiUrl: 'https://your-payload-api.com/api',
+ *   apiKey: 'your-api-key'
+ * })
+ */
+declare const createEdgeClient: (options?: DBOptions) => DatabaseClientType;
+
+/**
+ * Embedding functionality for ai-database
+ * Uses OpenAI API directly for generating embeddings
+ */
+
+/**
+ * Generate embeddings for text using OpenAI API
+ * @param text Text to generate embeddings for
+ * @param options Embedding options
+ * @returns Promise resolving to embedding result
+ */
+declare function generateEmbedding(text: string | string[], options?: EmbeddingOptions): Promise<EmbeddingResult>;
+/**
+ * Calculate cosine similarity between two embeddings
+ * @param embedding1 First embedding vector
+ * @param embedding2 Second embedding vector
+ * @returns Cosine similarity score (0-1)
+ */
+declare function calculateSimilarity(embedding1: number[], embedding2: number[]): number;
+
+/**
+ * ai-database
+ * Direct interface to Payload CMS with database.do compatibility
+ */
+
+/**
+ * Creates a database client with the provided options
+ * @param options Configuration options for the database client
+ * @returns A proxy-based database client that provides collection-based access
+ * @example
+ * const db = DB({ payload }) // Node.js with Payload instance
+ * const db = DB({ apiUrl: 'https://api.example.com' }) // Edge with REST API
+ */
+declare const DB: (options?: DBOptions) => DatabaseClientType;
+/**
+ * Default database client instance
+ * Note: This will attempt to use a global Payload instance if available,
+ * otherwise it will throw an error. In most cases, you should use the DB
+ * function directly with explicit options.
+ */
+declare const db: DatabaseClientType;
+
+export { type CollectionData, type CollectionHandlerOptions, type CollectionMethods, DB, type DBOptions, type DatabaseClientType, type EmbeddingOptions, type EmbeddingResult, type PayloadInstance, type QueryOptions, type RestClientConfig, calculateSimilarity, createEdgeClient, createNodeClient, db, DB as default, generateEmbedding };

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+import { ListResponse } from 'apis.do/types';
+export { ClientOptions, ErrorResponse, ListResponse, QueryParams } from 'apis.do/types';
+
+/**
+ * Types for ai-database package
+ */
+
+/**
+ * Options for embedding generation
+ */
+interface EmbeddingOptions {
+    /** Embedding model to use (defaults to openai:text-embedding-3-small) */
+    model?: string;
+    /** Additional options for the embedding model */
+    [key: string]: any;
+}
+/**
+ * Result of embedding generation
+ */
+interface EmbeddingResult {
+    /** Generated embedding vectors */
+    embedding: number[][] | null;
+    /** Model used for embedding generation */
+    model: string;
+    /** Whether the embedding generation was successful */
+    success: boolean;
+    /** Error message if embedding generation failed */
+    error?: string;
+}
+/**
+ * Generic collection data type
+ */
+type CollectionData = Record<string, any>;
+/**
+ * Query options for database operations
+ */
+interface QueryOptions {
+    /** Filter criteria */
+    where?: Record<string, any>;
+    /** Sorting options (field:direction) */
+    sort?: string | string[];
+    /** Number of results per page */
+    limit?: number;
+    /** Page number for pagination */
+    page?: number;
+    /** Fields to include in the result */
+    select?: string | string[];
+    /** Relations to populate */
+    populate?: string | string[];
+}
+/**
+ * Methods available for each collection
+ * @template T Document type for the collection
+ */
+interface CollectionMethods<T = CollectionData> {
+    /** Find documents in the collection */
+    find: (options?: QueryOptions) => Promise<ListResponse<T>>;
+    /** Find a single document by ID */
+    findOne: (id: string) => Promise<T>;
+    /** Create a new document */
+    create: (data: Partial<T>) => Promise<T>;
+    /** Update an existing document */
+    update: (id: string, data: Partial<T>) => Promise<T>;
+    /** Delete a document */
+    delete: (id: string) => Promise<T>;
+    /** Search for documents */
+    search: (query: string, options?: QueryOptions) => Promise<ListResponse<T>>;
+}
+/**
+ * Database client interface
+ */
+interface DatabaseClientType {
+    /** Dynamic access to any collection */
+    [collection: string]: CollectionMethods;
+}
+/**
+ * Payload instance interface defining the minimum required methods
+ */
+interface PayloadInstance {
+    find?: (options: any) => Promise<any>;
+    findByID?: (options: any) => Promise<any>;
+    create?: (options: any) => Promise<any>;
+    update?: (options: any) => Promise<any>;
+    delete?: (options: any) => Promise<any>;
+    db?: any;
+    [key: string]: any;
+}
+/**
+ * Configuration for REST API-based Payload client
+ */
+interface RestClientConfig {
+    apiUrl: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    fetchOptions?: RequestInit;
+}
+/**
+ * Options for DB initialization
+ */
+interface DBOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    payload?: PayloadInstance;
+    apiUrl?: string;
+    headers?: Record<string, string>;
+    fetchOptions?: RequestInit;
+    [collection: string]: any;
+}
+/**
+ * Collection handler options
+ */
+interface CollectionHandlerOptions {
+    payload: PayloadInstance;
+    collectionName: string;
+}
+
+/**
+ * Node.js adapter for ai-database
+ */
+
+/**
+ * Creates a database client for Node.js environments
+ * @param options Configuration options
+ * @returns Database client instance
+ * @example
+ * import { getPayload } from 'payload'
+ * import config from '@payload-config'
+ * import { createNodeClient } from 'ai-database/adapters'
+ *
+ * const payload = await getPayload({ config })
+ * const db = createNodeClient({ payload })
+ */
+declare const createNodeClient: (options?: DBOptions) => DatabaseClientType;
+
+/**
+ * Edge runtime adapter for ai-database
+ */
+
+/**
+ * Creates a database client for Edge runtime environments
+ * @param options Configuration options (must include apiUrl)
+ * @returns Database client instance
+ * @example
+ * import { createEdgeClient } from 'ai-database/adapters'
+ *
+ * const db = createEdgeClient({
+ *   apiUrl: 'https://your-payload-api.com/api',
+ *   apiKey: 'your-api-key'
+ * })
+ */
+declare const createEdgeClient: (options?: DBOptions) => DatabaseClientType;
+
+/**
+ * Embedding functionality for ai-database
+ * Uses OpenAI API directly for generating embeddings
+ */
+
+/**
+ * Generate embeddings for text using OpenAI API
+ * @param text Text to generate embeddings for
+ * @param options Embedding options
+ * @returns Promise resolving to embedding result
+ */
+declare function generateEmbedding(text: string | string[], options?: EmbeddingOptions): Promise<EmbeddingResult>;
+/**
+ * Calculate cosine similarity between two embeddings
+ * @param embedding1 First embedding vector
+ * @param embedding2 Second embedding vector
+ * @returns Cosine similarity score (0-1)
+ */
+declare function calculateSimilarity(embedding1: number[], embedding2: number[]): number;
+
+/**
+ * ai-database
+ * Direct interface to Payload CMS with database.do compatibility
+ */
+
+/**
+ * Creates a database client with the provided options
+ * @param options Configuration options for the database client
+ * @returns A proxy-based database client that provides collection-based access
+ * @example
+ * const db = DB({ payload }) // Node.js with Payload instance
+ * const db = DB({ apiUrl: 'https://api.example.com' }) // Edge with REST API
+ */
+declare const DB: (options?: DBOptions) => DatabaseClientType;
+/**
+ * Default database client instance
+ * Note: This will attempt to use a global Payload instance if available,
+ * otherwise it will throw an error. In most cases, you should use the DB
+ * function directly with explicit options.
+ */
+declare const db: DatabaseClientType;
+
+export { type CollectionData, type CollectionHandlerOptions, type CollectionMethods, DB, type DBOptions, type DatabaseClientType, type EmbeddingOptions, type EmbeddingResult, type PayloadInstance, type QueryOptions, type RestClientConfig, calculateSimilarity, createEdgeClient, createNodeClient, db, DB as default, generateEmbedding };