@pylonsync/functions 0.4.19 → 0.4.21

package/dist/index.d.ts

@@ -24,4 +24,4 @@ export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunne
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, MemberRow, Workflows, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, } from "./types";

package/dist/types.d.ts

@@ -128,6 +128,32 @@ export interface DbReader {
      * entities without a `search:` config (`SEARCH_NOT_CONFIGURED`).
      */
     search(entity: string, query: Record<string, unknown>): Promise<SearchResult>;
+    /**
+     * Exact k-nearest-neighbor search over a `field.vector(dims)` field.
+     * Cosine similarity by default (`metric: "dot" | "l2"` to change);
+     * hits come back best-first with the full row on `doc` (vector
+     * fields stripped — re-fetch by id if you need the embedding).
+     *
+     * Available wherever `ctx.db` is — queries and mutations. Actions
+     * have no `ctx.db`: embed there, then `ctx.runQuery` a query that
+     * searches with the vector.
+     *
+     * ```ts
+     * // In a query: the vector arrives as an arg (an action embedded it).
+     * const { hits } = await ctx.db.vectorSearch("Doc", {
+     *   field: "embedding",
+     *   vector,
+     *   limit: 5,
+     *   filter: { status: "published" },   // equality / IN pre-filter
+     * });
+     * ```
+     *
+     * Exact scan, not ANN: every non-NULL embedding is scored. Fine to
+     * ~100k rows per entity; past that, a dedicated vector store wins.
+     * Throws `VECTOR_FIELD_NOT_FOUND` when `field` isn't a vector field
+     * and `INVALID_QUERY` on dimension mismatch or bad filters.
+     */
+    vectorSearch(entity: string, query: VectorSearchQuery): Promise<VectorSearchResult>;
     /**
      * Cursor-paginated list. Pass `cursor` from a previous page's `nextCursor`
      * to continue; pass `null` for the first page.
@@ -165,6 +191,32 @@ export interface SearchResult<T = Record<string, unknown>> {
     /** Milliseconds spent in the search engine. */
     tookMs: number;
 }
+/** Request shape for [`DbReader.vectorSearch`]. */
+export interface VectorSearchQuery {
+    /** The `vector(dims)` field to search. */
+    field: string;
+    /** Query embedding; length must equal the field's declared dims. */
+    vector: number[];
+    /** Max hits. Default 10, capped at 200. */
+    limit?: number;
+    /** Similarity metric. Default "cosine" (higher = closer);
+     *  "dot" (higher = closer); "l2" (Euclidean distance, lower = closer). */
+    metric?: "cosine" | "dot" | "l2";
+    /** Equality pre-filter applied in SQL before scoring. A plain value
+     *  means equality; an array means SQL `IN`; `null` means IS NULL. */
+    filter?: Record<string, unknown>;
+}
+/** Result shape for [`DbReader.vectorSearch`]. */
+export interface VectorSearchResult<T = Record<string, unknown>> {
+    /** Best-first hits for the chosen metric. */
+    hits: Array<{
+        id: string;
+        score: number;
+        doc: T;
+    }>;
+    /** Milliseconds spent scanning + scoring. */
+    tookMs: number;
+}
 export interface DbWriter extends DbReader {
     /**
      * Escape hatch — same shape as [`DbReader.unsafe`] but with the
@@ -339,6 +391,34 @@ export interface Llm {
      * `complete` would refuse.
      */
     stream(request: LlmCompleteRequest, onEvent: (event: LlmStreamEvent) => void): Promise<LlmCompleteResponse>;
+    /**
+     * Batch-embed texts via the configured embeddings provider. One
+     * embedding per input, in input order. Pair with a
+     * `field.vector(dims)` field and `ctx.db.vectorSearch` for
+     * retrieval. From an action (which has no `ctx.db`), store via a
+     * mutation:
+     *
+     * ```ts
+     * const [vec] = await ctx.llm.embed([doc.body]);
+     * await ctx.runMutation("saveEmbedding", { docId: doc.id, embedding: vec });
+     * ```
+     *
+     * The embeddings provider is a separate axis from chat: with
+     * `OPENAI_API_KEY` set it defaults to OpenAI
+     * `text-embedding-3-small` (1536 dims) even when chat runs
+     * Anthropic; `PYLON_EMBEDDINGS_PROVIDER=voyage` + `VOYAGE_API_KEY`
+     * selects Voyage `voyage-3.5` (1024 dims).
+     * `PYLON_EMBEDDINGS_MODEL` overrides the model.
+     *
+     * Not available in queries (reactive re-runs would re-bill the
+     * provider) — embed in a mutation/action and store the vector.
+     * Errors carry `err.code`: `EMBEDDINGS_NOT_CONFIGURED`,
+     * `PROVIDER_HTTP_<code>`, `PROVIDER_UNREACHABLE`,
+     * `INVALID_REQUEST`.
+     */
+    embed(input: string[], opts?: {
+        model?: string;
+    }): Promise<number[][]>;
 }
 /**
  * One event from an in-flight {@link Llm.stream} call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.4.19",
+  "version": "0.4.21",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -63,6 +63,10 @@ export type {
   RequireMemberOptions,
   MemberRow,
   Workflows,
+  VectorSearchQuery,
+  VectorSearchResult,
+  SearchResult,
+  PaginationResult,
   // LLM + realtime surfaces. A handler writing an agent tool loop
   // builds its own message array and branches on stream events, so
   // these have to be nameable from app code.

package/src/runtime-vector.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Wire-shape tests for the vector surfaces (runtime.ts):
+ *
+ *   1. `ctx.db.vectorSearch` emits `{type:"db", op:"vector_search"}`
+ *      frames with the query on `data` and the unsafe_op / ssr_read
+ *      flags the Rust policy gate keys on.
+ *   2. `ctx.llm.embed` emits `{type:"llm_embed", request:{input,model}}`
+ *      with an op_id so concurrent embeds demux.
+ *
+ * Same child-process harness as runtime-db.test.ts — runtime.ts runs
+ * main() on import, so the builders are exercised in a probe script
+ * whose emitted NDJSON frames are the assertion target.
+ */
+import { expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+
+const SCRIPT = `
+import { buildDbReader, buildLlm } from ${JSON.stringify(RUNTIME)};
+
+const reader = buildDbReader("c_r");
+const llm = buildLlm("c_l");
+
+// No host replies — don't await; the emitted frames are the target.
+reader.vectorSearch("Doc", {
+  field: "embedding",
+  vector: [1, 0, 0],
+  limit: 5,
+  metric: "l2",
+  filter: { kind: "a" },
+}).catch(() => {});
+reader.unsafe.vectorSearch("Doc", { field: "embedding", vector: [1] }).catch(() => {});
+llm.embed(["hello", "world"], { model: "text-embedding-3-large" }).catch(() => {});
+
+setTimeout(() => process.exit(0), 300);
+`;
+
+test("vectorSearch + llm.embed emit the exact wire shapes the host parses", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-vec-"));
+  const scriptPath = join(dir, "probe.ts");
+  writeFileSync(scriptPath, SCRIPT);
+
+  const proc = Bun.spawn(["bun", scriptPath], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout] = await Promise.all([
+    new Response(proc.stdout).text(),
+    proc.exited,
+  ]);
+
+  const frames = stdout
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as Record<string, any>);
+
+  const vs = frames.filter((f) => f.type === "db" && f.op === "vector_search");
+  expect(vs.length).toBe(2);
+  const safe = vs.find((f) => f.unsafe_op === false)!;
+  expect(safe).toMatchObject({
+    entity: "Doc",
+    ssr_read: false,
+    data: {
+      field: "embedding",
+      vector: [1, 0, 0],
+      limit: 5,
+      metric: "l2",
+      filter: { kind: "a" },
+    },
+  });
+  expect(safe.op_id).toBeDefined();
+  const unsafe = vs.find((f) => f.unsafe_op === true)!;
+  expect(unsafe.data.field).toBe("embedding");
+
+  const embed = frames.find((f) => f.type === "llm_embed")!;
+  expect(embed).toBeDefined();
+  expect(embed.call_id).toBe("c_l");
+  expect(embed.op_id).toBeDefined();
+  expect(embed.request).toMatchObject({
+    input: ["hello", "world"],
+    model: "text-embedding-3-large",
+  });
+});

package/src/runtime.ts

@@ -689,6 +689,16 @@ function buildReaderOps(
         ssr_read: ssrRead,
       })) as any;
     },
+    async vectorSearch(entity, query) {
+      return (await rpcDb(callId, {
+        type: "db",
+        op: "vector_search",
+        entity,
+        data: query,
+        unsafe_op: unsafeOp,
+        ssr_read: ssrRead,
+      })) as any;
+    },
   };
 }
 
@@ -915,6 +925,18 @@ export function buildLlm(callId: string): Llm {
         (event) => onEvent(event as LlmStreamEvent),
       )) as LlmCompleteResponse;
     },
+
+    async embed(
+      input: string[],
+      opts?: { model?: string },
+    ): Promise<number[][]> {
+      // op_id-keyed rpc so concurrent embeds in one handler demux.
+      const resp = (await rpcDb(callId, {
+        type: "llm_embed",
+        request: { input, model: opts?.model },
+      })) as { embeddings: number[][] };
+      return resp.embeddings;
+    },
   };
 }
 

package/src/types.ts

@@ -156,6 +156,36 @@ export interface DbReader {
     query: Record<string, unknown>
   ): Promise<SearchResult>;
 
+  /**
+   * Exact k-nearest-neighbor search over a `field.vector(dims)` field.
+   * Cosine similarity by default (`metric: "dot" | "l2"` to change);
+   * hits come back best-first with the full row on `doc` (vector
+   * fields stripped — re-fetch by id if you need the embedding).
+   *
+   * Available wherever `ctx.db` is — queries and mutations. Actions
+   * have no `ctx.db`: embed there, then `ctx.runQuery` a query that
+   * searches with the vector.
+   *
+   * ```ts
+   * // In a query: the vector arrives as an arg (an action embedded it).
+   * const { hits } = await ctx.db.vectorSearch("Doc", {
+   *   field: "embedding",
+   *   vector,
+   *   limit: 5,
+   *   filter: { status: "published" },   // equality / IN pre-filter
+   * });
+   * ```
+   *
+   * Exact scan, not ANN: every non-NULL embedding is scored. Fine to
+   * ~100k rows per entity; past that, a dedicated vector store wins.
+   * Throws `VECTOR_FIELD_NOT_FOUND` when `field` isn't a vector field
+   * and `INVALID_QUERY` on dimension mismatch or bad filters.
+   */
+  vectorSearch(
+    entity: string,
+    query: VectorSearchQuery
+  ): Promise<VectorSearchResult>;
+
   /**
    * Cursor-paginated list. Pass `cursor` from a previous page's `nextCursor`
    * to continue; pass `null` for the first page.
@@ -196,6 +226,30 @@ export interface SearchResult<T = Record<string, unknown>> {
   tookMs: number;
 }
 
+/** Request shape for [`DbReader.vectorSearch`]. */
+export interface VectorSearchQuery {
+  /** The `vector(dims)` field to search. */
+  field: string;
+  /** Query embedding; length must equal the field's declared dims. */
+  vector: number[];
+  /** Max hits. Default 10, capped at 200. */
+  limit?: number;
+  /** Similarity metric. Default "cosine" (higher = closer);
+   *  "dot" (higher = closer); "l2" (Euclidean distance, lower = closer). */
+  metric?: "cosine" | "dot" | "l2";
+  /** Equality pre-filter applied in SQL before scoring. A plain value
+   *  means equality; an array means SQL `IN`; `null` means IS NULL. */
+  filter?: Record<string, unknown>;
+}
+
+/** Result shape for [`DbReader.vectorSearch`]. */
+export interface VectorSearchResult<T = Record<string, unknown>> {
+  /** Best-first hits for the chosen metric. */
+  hits: Array<{ id: string; score: number; doc: T }>;
+  /** Milliseconds spent scanning + scoring. */
+  tookMs: number;
+}
+
 // ---------------------------------------------------------------------------
 // Database — write operations (extends read)
 // ---------------------------------------------------------------------------
@@ -422,6 +476,33 @@ export interface Llm {
     request: LlmCompleteRequest,
     onEvent: (event: LlmStreamEvent) => void,
   ): Promise<LlmCompleteResponse>;
+
+  /**
+   * Batch-embed texts via the configured embeddings provider. One
+   * embedding per input, in input order. Pair with a
+   * `field.vector(dims)` field and `ctx.db.vectorSearch` for
+   * retrieval. From an action (which has no `ctx.db`), store via a
+   * mutation:
+   *
+   * ```ts
+   * const [vec] = await ctx.llm.embed([doc.body]);
+   * await ctx.runMutation("saveEmbedding", { docId: doc.id, embedding: vec });
+   * ```
+   *
+   * The embeddings provider is a separate axis from chat: with
+   * `OPENAI_API_KEY` set it defaults to OpenAI
+   * `text-embedding-3-small` (1536 dims) even when chat runs
+   * Anthropic; `PYLON_EMBEDDINGS_PROVIDER=voyage` + `VOYAGE_API_KEY`
+   * selects Voyage `voyage-3.5` (1024 dims).
+   * `PYLON_EMBEDDINGS_MODEL` overrides the model.
+   *
+   * Not available in queries (reactive re-runs would re-bill the
+   * provider) — embed in a mutation/action and store the vector.
+   * Errors carry `err.code`: `EMBEDDINGS_NOT_CONFIGURED`,
+   * `PROVIDER_HTTP_<code>`, `PROVIDER_UNREACHABLE`,
+   * `INVALID_REQUEST`.
+   */
+  embed(input: string[], opts?: { model?: string }): Promise<number[][]>;
 }
 
 /**