@mastra/pg 0.1.6-alpha.1 → 0.1.6-alpha.3

package/.turbo/turbo-build.log

@@ -1,18 +1,23 @@
 
-> @mastra/pg@0.1.6-alpha.1 build /home/runner/work/mastra/mastra/stores/pg
-> tsup src/index.ts --format esm --experimental-dts --clean --treeshake
+> @mastra/pg@0.1.6-alpha.3 build /home/runner/work/mastra/mastra/stores/pg
+> tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.3.6
 TSC Build start
-TSC ⚡️ Build success in 10385ms
+TSC ⚡️ Build success in 11801ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.7.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/pg/dist/_tsup-dts-rollup.d.ts
-DTS ⚡️ Build success in 5525ms
+Analysis will use the bundled TypeScript version 5.7.3
+Writing package typings: /home/runner/work/mastra/mastra/stores/pg/dist/_tsup-dts-rollup.d.cts
+DTS ⚡️ Build success in 12369ms
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js 32.82 KB
-ESM ⚡️ Build success in 642ms
+CJS Build start
+ESM dist/index.js 33.20 KB
+ESM ⚡️ Build success in 1143ms
+CJS dist/index.cjs 33.60 KB
+CJS ⚡️ Build success in 1147ms

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @mastra/pg
 
+## 0.1.6-alpha.3
+
+### Patch Changes
+
+- 0fd78ac: Update vector store functions to use object params
+- fd14a3f: Updating filter location from @mastra/core/filter to @mastra/core/vector/filter
+- 4d4e1e1: Updated vector tests and pinecone
+- bb4f447: Add support for commonjs
+- Updated dependencies [0fd78ac]
+- Updated dependencies [0d25b75]
+- Updated dependencies [fd14a3f]
+- Updated dependencies [3f369a2]
+- Updated dependencies [4d4e1e1]
+- Updated dependencies [bb4f447]
+  - @mastra/core@0.4.3-alpha.3
+
+## 0.1.6-alpha.2
+
+### Patch Changes
+
+- 5325d6a: A bug fix earlier today unmasked that the next/prev settings for PG semantic recall were swapped
+- Updated dependencies [2512a93]
+- Updated dependencies [e62de74]
+  - @mastra/core@0.4.3-alpha.2
+
 ## 0.1.6-alpha.1
 
 ### Patch Changes

package/README.md

@@ -23,24 +23,28 @@ import { PgVector } from '@mastra/pg';
 const vectorStore = new PgVector('postgresql://user:pass@localhost:5432/db');
 
 // Create a new table with vector support
-await vectorStore.createIndex('my_vectors', 1536, 'cosine');
+await vectorStore.createIndex({
+  indexName: 'my_vectors',
+  dimension: 1536,
+  metric: 'cosine',
+});
 
 // Add vectors
-const ids = await vectorStore.upsert(
-  'my_vectors',
-  [[0.1, 0.2, ...], [0.3, 0.4, ...]],
-  [{ text: 'doc1' }, { text: 'doc2' }]
-);
+const ids = await vectorStore.upsert({
+  indexName: 'my_vectors',
+  vectors: [[0.1, 0.2, ...], [0.3, 0.4, ...]],
+  metadata: [{ text: 'doc1' }, { text: 'doc2' }],
+});
 
 // Query vectors
-const results = await vectorStore.query(
-  'my_vectors',
-  [0.1, 0.2, ...],
-  10,              // topK
-  { text: 'doc1' }, // filter
-  false,           // includeVector
-  0.5              // minScore
-);
+const results = await vectorStore.query({
+  indexName: 'my_vectors',
+  queryVector: [0.1, 0.2, ...],
+  topK: 10, // topK
+  filter: { text: 'doc1' }, // filter
+  includeVector: false, // includeVector
+  minScore: 0.5, // minScore
+});
 
 // Clean up
 await vectorStore.disconnect();
@@ -137,9 +141,10 @@ Example filter:
 
 ## Vector Store Methods
 
-- `createIndex(indexName, dimension, metric?)`: Create a new table with vector support
-- `upsert(indexName, vectors, metadata?, ids?)`: Add or update vectors
-- `query(indexName, queryVector, topK?, filter?, includeVector?, minScore?)`: Search for similar vectors
+- `createIndex({indexName, dimension, metric?, indexConfig?, defineIndex?})`: Create a new table with vector support
+- `upsert({indexName, vectors, metadata?, ids?})`: Add or update vectors
+- `query({indexName, queryVector, topK?, filter?, includeVector?, minScore?})`: Search for similar vectors
+- `defineIndex({indexName, metric?, indexConfig?})`: Define an index
 - `listIndexes()`: List all vector-enabled tables
 - `describeIndex(indexName)`: Get table statistics
 - `deleteIndex(indexName)`: Delete a table

package/dist/_tsup-dts-rollup.d.cts

@@ -0,0 +1,329 @@
+import type { ArrayOperator } from '@mastra/core/vector/filter';
+import { BaseFilterTranslator } from '@mastra/core/vector/filter';
+import type { BasicOperator } from '@mastra/core/vector/filter';
+import type { CreateIndexParams } from '@mastra/core/vector';
+import type { ElementOperator } from '@mastra/core/vector/filter';
+import type { EvalRow } from '@mastra/core/storage';
+import type { IndexStats } from '@mastra/core/vector';
+import type { LogicalOperator } from '@mastra/core/vector/filter';
+import { MastraStorage } from '@mastra/core/storage';
+import { MastraVector } from '@mastra/core/vector';
+import type { MessageType } from '@mastra/core/memory';
+import type { NumericOperator } from '@mastra/core/vector/filter';
+import type { OperatorSupport } from '@mastra/core/vector/filter';
+import type { ParamsToArgs } from '@mastra/core/vector';
+import type { QueryResult } from '@mastra/core/vector';
+import type { QueryVectorParams } from '@mastra/core/vector';
+import type { RegexOperator } from '@mastra/core/vector/filter';
+import type { StorageColumn } from '@mastra/core/storage';
+import type { StorageGetMessagesArg } from '@mastra/core/storage';
+import type { StorageThreadType } from '@mastra/core/memory';
+import type { TABLE_NAMES } from '@mastra/core/storage';
+import type { UpsertVectorParams } from '@mastra/core/vector';
+import type { VectorFilter } from '@mastra/core/vector/filter';
+import type { WorkflowRunState } from '@mastra/core/workflows';
+
+export declare const baseTestConfigs: {
+    smokeTests: {
+        dimension: number;
+        size: number;
+        k: number;
+        queryCount: number;
+    }[];
+    '64': {
+        dimension: number;
+        size: number;
+        k: number;
+        queryCount: number;
+    }[];
+    '384': {
+        dimension: number;
+        size: number;
+        k: number;
+        queryCount: number;
+    }[];
+    '1024': {
+        dimension: number;
+        size: number;
+        k: number;
+        queryCount: number;
+    }[];
+    stressTests: {
+        dimension: number;
+        size: number;
+        k: number;
+        queryCount: number;
+    }[];
+};
+
+export declare function buildFilterQuery(filter: VectorFilter, minScore: number): FilterResult;
+
+export declare const calculateRecall: (actual: number[], expected: number[], k: number) => number;
+
+export declare const calculateTimeout: (dimension: number, size: number, k: number) => number;
+
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+
+export declare const FILTER_OPERATORS: Record<string, OperatorFn>;
+
+declare type FilterOperator = {
+    sql: string;
+    needsValue: boolean;
+    transformValue?: (value: any) => any;
+};
+
+export declare interface FilterResult {
+    sql: string;
+    values: any[];
+}
+
+export declare const findNearestBruteForce: (query: number[], vectors: number[][], k: number) => number[];
+
+export declare const formatTable: (data: any[], columns: string[]) => string;
+
+export declare const generateClusteredVectors: (count: number, dim: number, numClusters?: number) => number[][];
+
+export declare const generateRandomVectors: (count: number, dim: number) => number[][];
+
+export declare const generateSkewedVectors: (count: number, dim: number) => number[][];
+
+export declare const getHNSWConfig: (indexConfig: IndexConfig) => {
+    m: number;
+    efConstruction: number;
+};
+
+export declare function getIndexDescription({ type, hnsw, }: {
+    type: IndexType;
+    hnsw: {
+        m: number;
+        efConstruction: number;
+    };
+}): string;
+
+export declare const getListCount: (indexConfig: IndexConfig, size: number) => number | undefined;
+
+export declare function getSearchEf(k: number, m: number): {
+    default: number;
+    lower: number;
+    higher: number;
+};
+
+export declare const groupBy: <T, K extends keyof T>(array: T[], key: K | ((item: T) => string), reducer?: (group: T[]) => any) => Record<string, any>;
+
+export declare const handleKey: (key: string) => string;
+
+declare interface HNSWConfig {
+    m?: number;
+    efConstruction?: number;
+}
+
+export declare interface IndexConfig {
+    type?: IndexType;
+    ivf?: IVFConfig;
+    hnsw?: HNSWConfig;
+}
+
+export declare type IndexType = 'ivfflat' | 'hnsw' | 'flat';
+
+declare interface IVFConfig {
+    lists?: number;
+}
+
+export declare function measureLatency<T>(fn: () => Promise<T>): Promise<[number, T]>;
+
+declare type OperatorFn = (key: string, paramIndex: number, value?: any) => FilterOperator;
+
+export declare type OperatorType = BasicOperator | NumericOperator | ArrayOperator | ElementOperator | LogicalOperator | '$contains' | Exclude<RegexOperator, '$options'>;
+
+declare interface PgCreateIndexParams extends CreateIndexParams {
+    indexConfig?: IndexConfig;
+    buildIndex?: boolean;
+}
+
+declare interface PgDefineIndexParams {
+    indexName: string;
+    metric: 'cosine' | 'euclidean' | 'dotproduct';
+    indexConfig: IndexConfig;
+}
+
+/**
+ * Translates MongoDB-style filters to PG compatible filters.
+ *
+ * Key differences from MongoDB:
+ *
+ * Logical Operators ($and, $or, $nor):
+ * - Can be used at the top level or nested within fields
+ * - Can take either a single condition or an array of conditions
+ *
+ */
+export declare class PGFilterTranslator extends BaseFilterTranslator {
+    protected getSupportedOperators(): OperatorSupport;
+    translate(filter?: VectorFilter): VectorFilter;
+    private translateNode;
+    private translateRegexPattern;
+}
+
+declare interface PGIndexStats extends IndexStats {
+    type: IndexType;
+    config: {
+        m?: number;
+        efConstruction?: number;
+        lists?: number;
+        probes?: number;
+    };
+}
+export { PGIndexStats }
+export { PGIndexStats as PGIndexStats_alias_1 }
+
+declare interface PgQueryVectorParams extends QueryVectorParams {
+    minScore?: number;
+    /**
+     * HNSW search parameter. Controls the size of the dynamic candidate
+     * list during search. Higher values improve accuracy at the cost of speed.
+     */
+    ef?: number;
+    /**
+     * IVFFlat probe parameter. Number of cells to visit during search.
+     * Higher values improve accuracy at the cost of speed.
+     */
+    probes?: number;
+}
+
+declare class PgVector extends MastraVector {
+    private pool;
+    private indexCache;
+    constructor(connectionString: string);
+    transformFilter(filter?: VectorFilter): VectorFilter;
+    getIndexInfo(indexName: string): Promise<PGIndexStats>;
+    query(...args: ParamsToArgs<PgQueryVectorParams>): Promise<QueryResult[]>;
+    upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]>;
+    createIndex(...args: ParamsToArgs<PgCreateIndexParams>): Promise<void>;
+    /**
+     * @deprecated This function is deprecated. Use buildIndex instead
+     */
+    defineIndex(indexName: string, metric: "cosine" | "euclidean" | "dotproduct" | undefined, indexConfig: IndexConfig): Promise<void>;
+    buildIndex(...args: ParamsToArgs<PgDefineIndexParams>): Promise<void>;
+    listIndexes(): Promise<string[]>;
+    describeIndex(indexName: string): Promise<PGIndexStats>;
+    deleteIndex(indexName: string): Promise<void>;
+    truncateIndex(indexName: string): Promise<void>;
+    disconnect(): Promise<void>;
+}
+export { PgVector }
+export { PgVector as PgVector_alias_1 }
+
+declare type PostgresConfig = {
+    host: string;
+    port: number;
+    database: string;
+    user: string;
+    password: string;
+} | {
+    connectionString: string;
+};
+export { PostgresConfig }
+export { PostgresConfig as PostgresConfig_alias_1 }
+
+declare class PostgresStore extends MastraStorage {
+    private db;
+    private pgp;
+    constructor(config: PostgresConfig);
+    getEvalsByAgentName(_agentName: string, _type?: 'test' | 'live'): Promise<EvalRow[]>;
+    batchInsert({ tableName, records }: {
+        tableName: TABLE_NAMES;
+        records: Record<string, any>[];
+    }): Promise<void>;
+    getTraces({ name, scope, page, perPage, attributes, }: {
+        name?: string;
+        scope?: string;
+        page: number;
+        perPage: number;
+        attributes?: Record<string, string>;
+    }): Promise<any[]>;
+    createTable({ tableName, schema, }: {
+        tableName: TABLE_NAMES;
+        schema: Record<string, StorageColumn>;
+    }): Promise<void>;
+    clearTable({ tableName }: {
+        tableName: TABLE_NAMES;
+    }): Promise<void>;
+    insert({ tableName, record }: {
+        tableName: TABLE_NAMES;
+        record: Record<string, any>;
+    }): Promise<void>;
+    load<R>({ tableName, keys }: {
+        tableName: TABLE_NAMES;
+        keys: Record<string, string>;
+    }): Promise<R | null>;
+    getThreadById({ threadId }: {
+        threadId: string;
+    }): Promise<StorageThreadType | null>;
+    getThreadsByResourceId({ resourceId }: {
+        resourceId: string;
+    }): Promise<StorageThreadType[]>;
+    saveThread({ thread }: {
+        thread: StorageThreadType;
+    }): Promise<StorageThreadType>;
+    updateThread({ id, title, metadata, }: {
+        id: string;
+        title: string;
+        metadata: Record<string, unknown>;
+    }): Promise<StorageThreadType>;
+    deleteThread({ threadId }: {
+        threadId: string;
+    }): Promise<void>;
+    getMessages<T = unknown>({ threadId, selectBy }: StorageGetMessagesArg): Promise<T>;
+    saveMessages({ messages }: {
+        messages: MessageType[];
+    }): Promise<MessageType[]>;
+    persistWorkflowSnapshot({ workflowName, runId, snapshot, }: {
+        workflowName: string;
+        runId: string;
+        snapshot: WorkflowRunState;
+    }): Promise<void>;
+    loadWorkflowSnapshot({ workflowName, runId, }: {
+        workflowName: string;
+        runId: string;
+    }): Promise<WorkflowRunState | null>;
+    close(): Promise<void>;
+}
+export { PostgresStore }
+export { PostgresStore as PostgresStore_alias_1 }
+
+export declare interface TestConfig {
+    dimension: number;
+    size: number;
+    k: number;
+    queryCount: number;
+}
+
+export declare interface TestResult {
+    distribution: string;
+    dimension: number;
+    type: IndexType;
+    size: number;
+    k?: number;
+    metrics: {
+        recall?: number;
+        minRecall?: number;
+        maxRecall?: number;
+        latency?: {
+            p50: number;
+            p95: number;
+            lists?: number;
+            vectorsPerList?: number;
+            m?: number;
+            ef?: number;
+        };
+        clustering?: {
+            numLists?: number;
+            avgVectorsPerList?: number;
+            recommendedLists?: number;
+            distribution?: string;
+        };
+    };
+}
+
+export declare function warmupQuery(vectorDB: PgVector, indexName: string, dimension: number, k: number): Promise<void>;
+
+export { }

package/dist/_tsup-dts-rollup.d.ts

@@ -1,22 +1,26 @@
-import type { ArrayOperator } from '@mastra/core/filter';
-import { BaseFilterTranslator } from '@mastra/core/filter';
-import type { BasicOperator } from '@mastra/core/filter';
-import type { ElementOperator } from '@mastra/core/filter';
+import type { ArrayOperator } from '@mastra/core/vector/filter';
+import { BaseFilterTranslator } from '@mastra/core/vector/filter';
+import type { BasicOperator } from '@mastra/core/vector/filter';
+import type { CreateIndexParams } from '@mastra/core/vector';
+import type { ElementOperator } from '@mastra/core/vector/filter';
 import type { EvalRow } from '@mastra/core/storage';
-import type { Filter } from '@mastra/core/filter';
 import type { IndexStats } from '@mastra/core/vector';
-import type { LogicalOperator } from '@mastra/core/filter';
+import type { LogicalOperator } from '@mastra/core/vector/filter';
 import { MastraStorage } from '@mastra/core/storage';
 import { MastraVector } from '@mastra/core/vector';
 import type { MessageType } from '@mastra/core/memory';
-import type { NumericOperator } from '@mastra/core/filter';
-import type { OperatorSupport } from '@mastra/core/filter';
+import type { NumericOperator } from '@mastra/core/vector/filter';
+import type { OperatorSupport } from '@mastra/core/vector/filter';
+import type { ParamsToArgs } from '@mastra/core/vector';
 import type { QueryResult } from '@mastra/core/vector';
-import type { RegexOperator } from '@mastra/core/filter';
+import type { QueryVectorParams } from '@mastra/core/vector';
+import type { RegexOperator } from '@mastra/core/vector/filter';
 import type { StorageColumn } from '@mastra/core/storage';
 import type { StorageGetMessagesArg } from '@mastra/core/storage';
 import type { StorageThreadType } from '@mastra/core/memory';
 import type { TABLE_NAMES } from '@mastra/core/storage';
+import type { UpsertVectorParams } from '@mastra/core/vector';
+import type { VectorFilter } from '@mastra/core/vector/filter';
 import type { WorkflowRunState } from '@mastra/core/workflows';
 
 export declare const baseTestConfigs: {
@@ -52,7 +56,7 @@ export declare const baseTestConfigs: {
     }[];
 };
 
-export declare function buildFilterQuery(filter: Filter, minScore: number): FilterResult;
+export declare function buildFilterQuery(filter: VectorFilter, minScore: number): FilterResult;
 
 export declare const calculateRecall: (actual: number[], expected: number[], k: number) => number;
 
@@ -131,6 +135,17 @@ declare type OperatorFn = (key: string, paramIndex: number, value?: any) => Filt
 
 export declare type OperatorType = BasicOperator | NumericOperator | ArrayOperator | ElementOperator | LogicalOperator | '$contains' | Exclude<RegexOperator, '$options'>;
 
+declare interface PgCreateIndexParams extends CreateIndexParams {
+    indexConfig?: IndexConfig;
+    buildIndex?: boolean;
+}
+
+declare interface PgDefineIndexParams {
+    indexName: string;
+    metric: 'cosine' | 'euclidean' | 'dotproduct';
+    indexConfig: IndexConfig;
+}
+
 /**
  * Translates MongoDB-style filters to PG compatible filters.
  *
@@ -143,7 +158,7 @@ export declare type OperatorType = BasicOperator | NumericOperator | ArrayOperat
  */
 export declare class PGFilterTranslator extends BaseFilterTranslator {
     protected getSupportedOperators(): OperatorSupport;
-    translate(filter: Filter): Filter;
+    translate(filter?: VectorFilter): VectorFilter;
     private translateNode;
     private translateRegexPattern;
 }
@@ -160,24 +175,34 @@ declare interface PGIndexStats extends IndexStats {
 export { PGIndexStats }
 export { PGIndexStats as PGIndexStats_alias_1 }
 
+declare interface PgQueryVectorParams extends QueryVectorParams {
+    minScore?: number;
+    /**
+     * HNSW search parameter. Controls the size of the dynamic candidate
+     * list during search. Higher values improve accuracy at the cost of speed.
+     */
+    ef?: number;
+    /**
+     * IVFFlat probe parameter. Number of cells to visit during search.
+     * Higher values improve accuracy at the cost of speed.
+     */
+    probes?: number;
+}
+
 declare class PgVector extends MastraVector {
     private pool;
     private indexCache;
     constructor(connectionString: string);
-    transformFilter(filter?: Filter): Filter;
+    transformFilter(filter?: VectorFilter): VectorFilter;
     getIndexInfo(indexName: string): Promise<PGIndexStats>;
-    query(indexName: string, queryVector: number[], topK?: number, filter?: Filter, includeVector?: boolean, minScore?: number, // Optional minimum score threshold
-    options?: {
-        ef?: number;
-        probes?: number;
-    }): Promise<QueryResult[]>;
-    upsert(indexName: string, vectors: number[][], metadata?: Record<string, any>[], ids?: string[]): Promise<string[]>;
-    createIndex(indexName: string, dimension: number, metric?: 'cosine' | 'euclidean' | 'dotproduct', indexConfig?: IndexConfig, defineIndex?: boolean): Promise<void>;
+    query(...args: ParamsToArgs<PgQueryVectorParams>): Promise<QueryResult[]>;
+    upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]>;
+    createIndex(...args: ParamsToArgs<PgCreateIndexParams>): Promise<void>;
     /**
      * @deprecated This function is deprecated. Use buildIndex instead
      */
     defineIndex(indexName: string, metric: "cosine" | "euclidean" | "dotproduct" | undefined, indexConfig: IndexConfig): Promise<void>;
-    buildIndex(indexName: string, metric: "cosine" | "euclidean" | "dotproduct" | undefined, indexConfig: IndexConfig): Promise<void>;
+    buildIndex(...args: ParamsToArgs<PgDefineIndexParams>): Promise<void>;
     listIndexes(): Promise<string[]>;
     describeIndex(indexName: string): Promise<PGIndexStats>;
     deleteIndex(indexName: string): Promise<void>;