@xano-sdk/vector 1.0.0

package/dist/index.js

@@ -0,0 +1,1429 @@
+// src/options.ts
+var CHUNK_STRATEGIES = [
+  "fixed",
+  "paragraph",
+  "sentence",
+  "markdown",
+  "custom"
+];
+var DOCUMENT_STATUSES = [
+  "pending",
+  "indexing",
+  "indexed",
+  "failed"
+];
+var GEMINI_EMBEDDING_DIMENSIONS = 768;
+var DEFAULT_GEMINI_MODEL = "gemini-embedding-2";
+var DEFAULT_API_KEY_ENV = "GEMINI_API_KEY";
+var DEFAULT_CHUNK_SIZE = 500;
+var DEFAULT_CHUNK_OVERLAP = 50;
+var DEFAULT_SEARCH_LIMIT = 10;
+var DEFAULT_SEARCH_THRESHOLD = 0;
+var DEFAULT_STRATEGY = "paragraph";
+var DEFAULT_NAMES = {
+  document: "vector_document",
+  chunk: "vector_chunk",
+  embedFn: "vector/generate_embedding",
+  chunkFn: "vector/chunk_text",
+  ingestFn: "vector/ingest_document",
+  searchFn: "vector/search_vectors",
+  searchTool: "vector_search",
+  apiGroup: "Vector"
+};
+var CANONICAL_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function inferTableKeyType(table3) {
+  if (!table3 || typeof table3 === "string") return "int";
+  if (table3.idType === "uuid") return "uuid";
+  return "int";
+}
+function resolveOptions(opts = {}) {
+  const authenticated = opts.authenticated ?? opts.authTable !== void 0;
+  if (authenticated && opts.authTable === void 0) {
+    throw new Error(
+      "resolveOptions: `authTable` is required when `authenticated` is true."
+    );
+  }
+  const userIdType = opts.userIdType ?? inferTableKeyType(opts.authTable);
+  if (userIdType !== "int" && userIdType !== "uuid") {
+    throw new Error(
+      `resolveOptions: \`userIdType\` must be "int" or "uuid", got "${userIdType}".`
+    );
+  }
+  const model = opts.model ?? DEFAULT_GEMINI_MODEL;
+  if (typeof model !== "string" || !model.trim()) {
+    throw new Error("resolveOptions: `model` must be a non-empty string.");
+  }
+  const apiKeyEnv = opts.apiKeyEnv ?? DEFAULT_API_KEY_ENV;
+  if (typeof apiKeyEnv !== "string" || !apiKeyEnv.trim()) {
+    throw new Error("resolveOptions: `apiKeyEnv` must be a non-empty string.");
+  }
+  const defaultStrategy = opts.defaultStrategy ?? DEFAULT_STRATEGY;
+  if (!CHUNK_STRATEGIES.includes(defaultStrategy)) {
+    throw new Error(
+      `resolveOptions: \`defaultStrategy\` must be one of [${CHUNK_STRATEGIES.join(", ")}], got "${defaultStrategy}".`
+    );
+  }
+  const defaultChunkSize = opts.defaultChunkSize ?? DEFAULT_CHUNK_SIZE;
+  if (typeof defaultChunkSize !== "number" || !Number.isInteger(defaultChunkSize) || defaultChunkSize < 20 || defaultChunkSize > 1e4) {
+    throw new Error(
+      `resolveOptions: \`defaultChunkSize\` must be an integer between 20 and 10000, got ${defaultChunkSize}.`
+    );
+  }
+  const defaultChunkOverlap = opts.defaultChunkOverlap ?? DEFAULT_CHUNK_OVERLAP;
+  if (typeof defaultChunkOverlap !== "number" || !Number.isInteger(defaultChunkOverlap) || defaultChunkOverlap < 0 || defaultChunkOverlap >= defaultChunkSize) {
+    throw new Error(
+      `resolveOptions: \`defaultChunkOverlap\` must be an integer >= 0 and < defaultChunkSize, got ${defaultChunkOverlap}.`
+    );
+  }
+  const searchLimit = opts.searchLimit ?? DEFAULT_SEARCH_LIMIT;
+  if (typeof searchLimit !== "number" || !Number.isInteger(searchLimit) || searchLimit < 1 || searchLimit > 100) {
+    throw new Error(
+      `resolveOptions: \`searchLimit\` must be an integer between 1 and 100, got ${searchLimit}.`
+    );
+  }
+  const searchThreshold = opts.searchThreshold ?? DEFAULT_SEARCH_THRESHOLD;
+  if (typeof searchThreshold !== "number" || searchThreshold < 0 || searchThreshold > 1) {
+    throw new Error(
+      `resolveOptions: \`searchThreshold\` must be a number between 0.0 and 1.0, got ${searchThreshold}.`
+    );
+  }
+  const taskTypeDocument = opts.taskTypeDocument ?? "RETRIEVAL_DOCUMENT";
+  const taskTypeQuery = opts.taskTypeQuery ?? "RETRIEVAL_QUERY";
+  const citationFormat = opts.citationFormat ?? "markdown";
+  if (opts.names) {
+    for (const [k, v] of Object.entries(opts.names)) {
+      if (typeof v !== "string" || !v.trim()) {
+        throw new Error(`resolveOptions: names.${k} must be a non-empty string.`);
+      }
+    }
+  }
+  let routePrefix = opts.routePrefix ?? "vector";
+  if (opts.canonical !== void 0) {
+    const trimmed = opts.canonical.trim();
+    if (!trimmed || !CANONICAL_PATTERN.test(trimmed)) {
+      throw new Error(
+        `resolveOptions: \`canonical\` must match ${CANONICAL_PATTERN}, got "${opts.canonical}".`
+      );
+    }
+    routePrefix = trimmed;
+  }
+  routePrefix = routePrefix.replace(/^\/+|\/+$/g, "");
+  const names = {
+    document: opts.names?.document ?? (opts.canonical ? `${opts.canonical}_document` : DEFAULT_NAMES.document),
+    chunk: opts.names?.chunk ?? (opts.canonical ? `${opts.canonical}_chunk` : DEFAULT_NAMES.chunk),
+    embedFn: opts.names?.embedFn ?? (opts.canonical ? `${opts.canonical}/generate_embedding` : DEFAULT_NAMES.embedFn),
+    chunkFn: opts.names?.chunkFn ?? (opts.canonical ? `${opts.canonical}/chunk_text` : DEFAULT_NAMES.chunkFn),
+    ingestFn: opts.names?.ingestFn ?? (opts.canonical ? `${opts.canonical}/ingest_document` : DEFAULT_NAMES.ingestFn),
+    searchFn: opts.names?.searchFn ?? (opts.canonical ? `${opts.canonical}/search_vectors` : DEFAULT_NAMES.searchFn),
+    searchTool: opts.names?.searchTool ?? DEFAULT_NAMES.searchTool,
+    apiGroup: opts.names?.apiGroup ?? (opts.canonical ? `Vector (${opts.canonical})` : DEFAULT_NAMES.apiGroup)
+  };
+  const tags = opts.tags ?? ["vector", "ai", "search"];
+  return {
+    authTable: opts.authTable,
+    authenticated,
+    userIdType,
+    model,
+    apiKeyEnv,
+    dimensions: GEMINI_EMBEDDING_DIMENSIONS,
+    defaultStrategy,
+    defaultChunkSize,
+    defaultChunkOverlap,
+    searchLimit,
+    searchThreshold,
+    taskTypeDocument,
+    taskTypeQuery,
+    citationFormat,
+    routePrefix,
+    canonical: opts.canonical,
+    names,
+    tags
+  };
+}
+
+// src/tables/document.ts
+import { table, f } from "@xano/sdk";
+function documentTable(opts) {
+  const schema = {
+    title: f.text({
+      required: true,
+      methods: ["trim", "min:1"],
+      description: "Human-readable title or filename for the document."
+    }),
+    content: f.text({
+      required: false,
+      description: "Raw textual content of the document."
+    }),
+    media_data: f.text({
+      required: false,
+      description: "Base64-encoded media data for multimodal documents (image, audio, video)."
+    }),
+    mime_type: f.text({
+      default: "text/plain",
+      description: "MIME type (e.g. text/markdown, image/png, image/jpeg, audio/mp3, video/mp4)."
+    }),
+    metadata: f.json({
+      description: "Arbitrary structured metadata (tags, author, source URL, dimensions, etc.)."
+    }),
+    status: f.enum(DOCUMENT_STATUSES, {
+      default: "pending",
+      description: "Current indexing lifecycle status: pending, indexing, indexed, or failed."
+    }),
+    chunk_count: f.int({
+      default: 0,
+      description: "Total number of vector chunks generated from this document."
+    }),
+    strategy: f.enum(CHUNK_STRATEGIES, {
+      default: opts.defaultStrategy,
+      description: "Chunking strategy used during indexing."
+    }),
+    chunk_size: f.int({
+      default: opts.defaultChunkSize,
+      description: "Target character chunk size used during indexing."
+    }),
+    chunk_overlap: f.int({
+      default: opts.defaultChunkOverlap,
+      description: "Chunk character overlap used during indexing."
+    }),
+    error_message: f.text({
+      description: "Error description if status is failed."
+    })
+  };
+  if (opts.authenticated && opts.authTable) {
+    schema.user_id = f.tableRef(opts.authTable, {
+      required: false,
+      description: "The user who owns or uploaded this document."
+    });
+  }
+  const indexes = [
+    {
+      type: "btree",
+      fields: [{ name: "status", op: "asc" }]
+    }
+  ];
+  if (opts.authenticated && opts.authTable) {
+    indexes.push({
+      type: "btree",
+      fields: [{ name: "user_id", op: "asc" }]
+    });
+  }
+  return table({
+    name: opts.names.document,
+    description: "Source documents and media assets managed by the vector pipeline.",
+    auth: false,
+    useXdo: true,
+    tags: opts.tags,
+    schema,
+    index: indexes
+  });
+}
+var PUBLIC_DOCUMENT_FIELDS = [
+  "id",
+  "created_at",
+  "title",
+  "content",
+  "media_data",
+  "mime_type",
+  "metadata",
+  "status",
+  "chunk_count",
+  "strategy",
+  "chunk_size",
+  "chunk_overlap",
+  "error_message"
+];
+
+// src/tables/chunk.ts
+import { table as table2, f as f2 } from "@xano/sdk";
+function chunkTable(opts, document) {
+  return table2({
+    name: opts.names.chunk,
+    description: "Document chunks and multimodal embeddings for semantic vector search.",
+    auth: false,
+    useXdo: true,
+    tags: opts.tags,
+    schema: {
+      document_id: f2.tableRef(document, {
+        required: true,
+        description: "The document this chunk was generated from."
+      }),
+      document_title: f2.text({
+        required: false,
+        description: "Title of the parent document."
+      }),
+      chunk_index: f2.int({
+        required: true,
+        description: "0-based sequence index of the chunk within the document."
+      }),
+      content: f2.text({
+        required: false,
+        description: "The text content or caption of this chunk."
+      }),
+      mime_type: f2.text({
+        default: "text/plain",
+        description: "MIME type of the chunk content (e.g. text/plain, image/png, audio/mp3)."
+      }),
+      embedding: f2.vector(GEMINI_EMBEDDING_DIMENSIONS, {
+        description: "Google Gemini 768-dimensional multimodal vector embedding."
+      }),
+      metadata: f2.json({
+        description: "Metadata specific to this chunk (e.g. section title, timestamps, bounding box)."
+      }),
+      char_count: f2.int({
+        default: 0,
+        description: "Character length of the text content."
+      })
+    },
+    index: [
+      {
+        type: "vector",
+        fields: [{ name: "embedding", op: "vector_cosine_ops" }]
+      },
+      {
+        type: "btree",
+        fields: [
+          { name: "document_id", op: "asc" },
+          { name: "chunk_index", op: "asc" }
+        ]
+      }
+    ]
+  });
+}
+var PUBLIC_CHUNK_FIELDS = [
+  "id",
+  "created_at",
+  "document_id",
+  "document_title",
+  "chunk_index",
+  "content",
+  "mime_type",
+  "metadata",
+  "char_count"
+];
+
+// src/functions/embed.ts
+import {
+  defineFunction,
+  input,
+  s,
+  setVar,
+  c,
+  inp,
+  ref,
+  expr,
+  or,
+  obj,
+  env,
+  withFilters,
+  fl
+} from "@xano/sdk";
+var BUILD_PARTS_LAMBDA_JS = `
+const parts = [];
+const textVal = String($var.raw_text || "").trim();
+const mediaVal = String($var.raw_media || "").trim();
+const mimeVal = String($var.raw_mime || "image/png").trim();
+const modelId = String($var.model_identifier || "models/gemini-embedding-2");
+const taskTypeVal = String($var.raw_task_type || "").trim();
+
+if (textVal) {
+  parts.push({ text: textVal });
+}
+if (mediaVal) {
+  parts.push({
+    inlineData: {
+      mimeType: mimeVal,
+      data: mediaVal,
+    },
+  });
+}
+
+const req = {
+  model: modelId,
+  content: { parts },
+  outputDimensionality: 768,
+};
+
+if (taskTypeVal) {
+  req.taskType = taskTypeVal;
+}
+
+return req;
+`.trim();
+function generateEmbeddingFn(opts) {
+  return defineFunction({
+    name: opts.names.embedFn,
+    description: "Generates a 768-dimensional multimodal vector embedding for text, images, audio, or video using Google Gemini Embeddings 2.",
+    tags: opts.tags,
+    input: {
+      text: input.text({
+        required: false,
+        description: "Text content to generate a vector embedding for."
+      }),
+      media_data: input.text({
+        required: false,
+        description: "Base64-encoded media data (image, audio, or video bytes)."
+      }),
+      mime_type: input.text({
+        default: "text/plain",
+        description: "MIME type for media data (e.g. image/png, image/jpeg, audio/mp3, video/mp4)."
+      }),
+      task_type: input.text({
+        required: false,
+        description: "Gemini embedding task type (RETRIEVAL_DOCUMENT, RETRIEVAL_QUERY, SEMANTIC_SIMILARITY, etc.)."
+      }),
+      model: input.text({
+        default: opts.model,
+        description: "Google Gemini embedding model name (default: gemini-embedding-2)."
+      }),
+      api_key: input.text({
+        required: false,
+        description: "Optional Google API key override. If omitted, uses the configured environment variable."
+      })
+    },
+    stack: [
+      setVar("raw_text", inp("text")),
+      setVar("raw_media", inp("media_data")),
+      setVar("raw_mime", inp("mime_type")),
+      setVar("raw_task_type", inp("task_type")),
+      s.precondition({
+        expr: or(
+          expr(ref("raw_text"), "!=", c.text("")),
+          expr(ref("raw_media"), "!=", c.text(""))
+        ),
+        error_type: "badrequest",
+        error: c.text("generate_embedding: at least one of `text` or `media_data` must be provided.")
+      }),
+      setVar(
+        "active_key",
+        withFilters(inp("api_key"), [fl.first_notempty(env(opts.apiKeyEnv))])
+      ),
+      s.precondition({
+        expr: expr(ref("active_key"), "!=", c.text("")),
+        error_type: "badrequest",
+        error: c.text(
+          `generate_embedding: missing Gemini API key. Set \`${opts.apiKeyEnv}\` in your environment or pass \`api_key\` explicitly.`
+        )
+      }),
+      setVar(
+        "endpoint_url",
+        withFilters(c.text("https://generativelanguage.googleapis.com/v1beta/models/"), [
+          fl.concat(inp("model")),
+          fl.concat(c.text(":embedContent?key=")),
+          fl.concat(ref("active_key"))
+        ])
+      ),
+      setVar(
+        "model_identifier",
+        withFilters(c.text("models/"), [fl.concat(inp("model"))])
+      ),
+      s.lambda({
+        as: "request_body",
+        code: c.text(BUILD_PARTS_LAMBDA_JS)
+      }),
+      s.api.request({
+        url: ref("endpoint_url"),
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        params: ref("request_body"),
+        as: "gemini_res"
+      }),
+      s.precondition({
+        expr: expr(ref("gemini_res.response.status"), "=", c.int(200)),
+        error_type: "badrequest",
+        error: withFilters(c.text("Gemini API error: "), [
+          fl.concat(ref("gemini_res.response.status")),
+          fl.concat(c.text(" - ")),
+          fl.concat(ref("gemini_res.response.result.error.message"))
+        ])
+      }),
+      setVar(
+        "embedding_values",
+        ref("gemini_res.response.result.embedding.values")
+      )
+    ],
+    response: obj({
+      embedding: ref("embedding_values"),
+      dimensions: c.int(GEMINI_EMBEDDING_DIMENSIONS)
+    }),
+    responseShape: {}
+  });
+}
+
+// src/functions/chunk.ts
+import {
+  defineFunction as defineFunction2,
+  input as input2,
+  s as s2,
+  setVar as setVar2,
+  c as c2,
+  inp as inp2,
+  ref as ref2,
+  obj as obj2,
+  withFilters as withFilters2,
+  fl as fl2
+} from "@xano/sdk";
+var CHUNKER_LAMBDA_JS = `
+const rawContent = String($var.raw_text || "").trim();
+const strat = String($var.active_strategy || "paragraph");
+const sizeLimit = Math.max(20, Number($var.target_size) || 500);
+const overlapSize = Math.max(0, Math.min(sizeLimit - 1, Number($var.target_overlap) || 50));
+
+if (!rawContent) {
+  return [];
+}
+
+const chunkList = [];
+
+const buildChunk = (chunkIndex, textSegment, extraMeta = {}) => ({
+  index: chunkIndex,
+  content: textSegment.trim(),
+  char_count: textSegment.trim().length,
+  metadata: { strategy: strat, ...extraMeta },
+});
+
+if (strat === "fixed") {
+  const stepSize = Math.max(1, sizeLimit - overlapSize);
+  let currentIdx = 0;
+  for (let charPos = 0; charPos < rawContent.length; charPos += stepSize) {
+    const segment = rawContent.slice(charPos, charPos + sizeLimit);
+    if (segment.trim().length > 0) {
+      chunkList.push(buildChunk(currentIdx++, segment, { start_char: charPos, end_char: charPos + segment.length }));
+    }
+  }
+} else if (strat === "sentence") {
+  const sentenceList = rawContent.split(/(?<=[.?!])\\s+/);
+  let currentAccumulator = "";
+  let currentIdx = 0;
+  for (const singleSentence of sentenceList) {
+    const trimmedSentence = singleSentence.trim();
+    if (!trimmedSentence) continue;
+    if (currentAccumulator && (currentAccumulator.length + 1 + trimmedSentence.length > sizeLimit)) {
+      chunkList.push(buildChunk(currentIdx++, currentAccumulator));
+      if (overlapSize > 0 && currentAccumulator.length > overlapSize) {
+        currentAccumulator = currentAccumulator.slice(currentAccumulator.length - overlapSize).trim() + " " + trimmedSentence;
+      } else {
+        currentAccumulator = trimmedSentence;
+      }
+    } else {
+      currentAccumulator = currentAccumulator ? currentAccumulator + " " + trimmedSentence : trimmedSentence;
+    }
+  }
+  if (currentAccumulator.trim().length > 0) {
+    chunkList.push(buildChunk(currentIdx++, currentAccumulator));
+  }
+} else if (strat === "markdown") {
+  const sectionList = rawContent.split(/(?=(?:^|\\n)#{1,6}\\s+)/);
+  let currentIdx = 0;
+  for (const singleSection of sectionList) {
+    const trimmedSection = singleSection.trim();
+    if (!trimmedSection) continue;
+    const headerMatch = trimmedSection.match(/^#{1,6}\\s+(.+)$/m);
+    const headerTitle = headerMatch ? headerMatch[1] : "";
+    if (trimmedSection.length <= sizeLimit) {
+      chunkList.push(buildChunk(currentIdx++, trimmedSection, { header: headerTitle }));
+    } else {
+      const stepSize = Math.max(1, sizeLimit - overlapSize);
+      for (let charPos = 0; charPos < trimmedSection.length; charPos += stepSize) {
+        const segment = trimmedSection.slice(charPos, charPos + sizeLimit);
+        if (segment.trim().length > 0) {
+          chunkList.push(buildChunk(currentIdx++, segment, { header: headerTitle, start_char: charPos }));
+        }
+      }
+    }
+  }
+} else if (strat === "custom") {
+  const customBlocks = rawContent.split(/\\n\\n+/);
+  let currentIdx = 0;
+  for (const customBlock of customBlocks) {
+    const trimmedBlock = customBlock.trim();
+    if (trimmedBlock.length > 0) {
+      chunkList.push(buildChunk(currentIdx++, trimmedBlock));
+    }
+  }
+} else {
+  const paragraphList = rawContent.split(/\\n\\s*\\n+/);
+  let currentAccumulator = "";
+  let currentIdx = 0;
+  for (const singleParagraph of paragraphList) {
+    const trimmedParagraph = singleParagraph.trim();
+    if (!trimmedParagraph) continue;
+    if (currentAccumulator && (currentAccumulator.length + 2 + trimmedParagraph.length > sizeLimit)) {
+      chunkList.push(buildChunk(currentIdx++, currentAccumulator));
+      if (overlapSize > 0 && currentAccumulator.length > overlapSize) {
+        currentAccumulator = currentAccumulator.slice(currentAccumulator.length - overlapSize).trim() + "\\n\\n" + trimmedParagraph;
+      } else {
+        currentAccumulator = trimmedParagraph;
+      }
+    } else {
+      currentAccumulator = currentAccumulator ? currentAccumulator + "\\n\\n" + trimmedParagraph : trimmedParagraph;
+    }
+  }
+  if (currentAccumulator.trim().length > 0) {
+    chunkList.push(buildChunk(currentIdx++, currentAccumulator));
+  }
+}
+
+return chunkList;
+`.trim();
+function chunkTextFn(opts) {
+  return defineFunction2({
+    name: opts.names.chunkFn,
+    description: "Segments input text into structured chunks based on the chosen strategy (fixed, paragraph, sentence, markdown, custom).",
+    tags: opts.tags,
+    input: {
+      content: input2.text({
+        required: false,
+        description: "The raw text content to segment into chunks."
+      }),
+      strategy: input2.enum(CHUNK_STRATEGIES, {
+        default: opts.defaultStrategy,
+        description: "Chunking algorithm: fixed, paragraph, sentence, markdown, or custom."
+      }),
+      chunk_size: input2.int({
+        default: opts.defaultChunkSize,
+        description: "Target maximum character count per chunk."
+      }),
+      chunk_overlap: input2.int({
+        default: opts.defaultChunkOverlap,
+        description: "Character overlap preserved between consecutive chunks."
+      })
+    },
+    stack: [
+      setVar2("target_size", inp2("chunk_size")),
+      setVar2("target_overlap", inp2("chunk_overlap")),
+      setVar2("active_strategy", inp2("strategy")),
+      setVar2("raw_text", inp2("content")),
+      s2.lambda({
+        as: "chunks",
+        code: c2.text(CHUNKER_LAMBDA_JS)
+      })
+    ],
+    response: obj2({
+      chunks: ref2("chunks"),
+      count: withFilters2(ref2("chunks"), [fl2.count()])
+    }),
+    responseShape: {}
+  });
+}
+
+// src/functions/ingest.ts
+import {
+  defineFunction as defineFunction3,
+  input as input3,
+  s as s3,
+  setVar as setVar3,
+  c as c3,
+  inp as inp3,
+  ref as ref3,
+  col,
+  expr as expr2,
+  and,
+  obj as obj3,
+  withFilters as withFilters3,
+  fl as fl3
+} from "@xano/sdk";
+function ingestDocumentFn(opts, document, chunk, embedFn, chunkFn) {
+  return defineFunction3({
+    name: opts.names.ingestFn,
+    description: "Fetches a document/media record, chunks text (or processes media), generates Gemini embeddings, and saves chunks.",
+    tags: opts.tags,
+    input: {
+      document_id: input3.int({
+        required: true,
+        description: "The primary key ID of the document to ingest and index."
+      }),
+      api_key: input3.text({
+        required: false,
+        description: "Optional Google API key override."
+      })
+    },
+    stack: [
+      s3.db.get({
+        table: document,
+        fieldValue: inp3("document_id"),
+        as: "doc"
+      }),
+      s3.precondition({
+        expr: expr2(ref3("doc"), "!=", c3.null()),
+        error_type: "notfound",
+        error: c3.text("ingest_document: document not found.")
+      }),
+      s3.db.edit({
+        table: document,
+        fieldValue: ref3("doc.id"),
+        row: {
+          status: c3.text("indexing"),
+          error_message: c3.null()
+        }
+      }),
+      s3.db.bulk.delete({
+        table: chunk,
+        where: expr2(col("document_id"), "=", ref3("doc.id"))
+      }),
+      s3.conditional({
+        when: and(
+          expr2(ref3("doc.media_data"), "!=", c3.null()),
+          expr2(ref3("doc.media_data"), "!=", c3.text(""))
+        ),
+        then: [
+          setVar3(
+            "media_text_label",
+            withFilters3(ref3("doc.content"), [fl3.first_notempty(ref3("doc.title"))])
+          ),
+          s3.function.run({
+            fn: embedFn,
+            input: {
+              text: ref3("media_text_label"),
+              media_data: ref3("doc.media_data"),
+              mime_type: ref3("doc.mime_type"),
+              task_type: c3.text(opts.taskTypeDocument),
+              api_key: inp3("api_key")
+            },
+            as: "single_embed_res"
+          }),
+          s3.db.add({
+            table: chunk,
+            row: {
+              document_id: ref3("doc.id"),
+              document_title: ref3("doc.title"),
+              chunk_index: c3.int(0),
+              content: ref3("media_text_label"),
+              mime_type: ref3("doc.mime_type"),
+              embedding: ref3("single_embed_res.embedding"),
+              metadata: ref3("doc.metadata"),
+              char_count: c3.int(0)
+            }
+          }),
+          setVar3("final_chunk_count", c3.int(1))
+        ],
+        else: [
+          s3.function.run({
+            fn: chunkFn,
+            input: {
+              content: ref3("doc.content"),
+              strategy: ref3("doc.strategy"),
+              chunk_size: ref3("doc.chunk_size"),
+              chunk_overlap: ref3("doc.chunk_overlap")
+            },
+            as: "chunks_res"
+          }),
+          s3.foreach({
+            list: ref3("chunks_res.chunks"),
+            as: "item",
+            body: [
+              s3.function.run({
+                fn: embedFn,
+                input: {
+                  text: ref3("item.content"),
+                  task_type: c3.text(opts.taskTypeDocument),
+                  api_key: inp3("api_key")
+                },
+                as: "embed_res"
+              }),
+              s3.db.add({
+                table: chunk,
+                row: {
+                  document_id: ref3("doc.id"),
+                  document_title: ref3("doc.title"),
+                  chunk_index: ref3("item.index"),
+                  content: ref3("item.content"),
+                  mime_type: ref3("doc.mime_type"),
+                  embedding: ref3("embed_res.embedding"),
+                  metadata: ref3("item.metadata"),
+                  char_count: ref3("item.char_count")
+                }
+              })
+            ]
+          }),
+          setVar3("final_chunk_count", ref3("chunks_res.count"))
+        ]
+      }),
+      s3.db.edit({
+        table: document,
+        fieldValue: ref3("doc.id"),
+        row: {
+          status: c3.text("indexed"),
+          chunk_count: ref3("final_chunk_count"),
+          error_message: c3.null()
+        }
+      })
+    ],
+    response: obj3({
+      document_id: ref3("doc.id"),
+      status: c3.text("indexed"),
+      chunk_count: ref3("final_chunk_count")
+    }),
+    responseShape: {}
+  });
+}
+
+// src/functions/search.ts
+import {
+  defineFunction as defineFunction4,
+  input as input4,
+  s as s4,
+  setVar as setVar4,
+  c as c4,
+  inp as inp4,
+  ref as ref4,
+  expr as expr3,
+  or as or2,
+  obj as obj4,
+  withFilters as withFilters4,
+  fl as fl4
+} from "@xano/sdk";
+function searchVectorsFn(opts, chunk, embedFn) {
+  return defineFunction4({
+    name: opts.names.searchFn,
+    description: "Performs semantic similarity search over document chunks using Gemini 768-dim embeddings and pgvector.",
+    tags: opts.tags,
+    input: {
+      query: input4.text({
+        required: false,
+        description: "Natural language query string. If provided, embedded via Gemini."
+      }),
+      query_media_data: input4.text({
+        required: false,
+        description: "Base64-encoded media data for visual/audio/multimodal search queries."
+      }),
+      query_mime_type: input4.text({
+        default: "text/plain",
+        description: "MIME type for query media data (e.g. image/png, audio/mp3)."
+      }),
+      query_embedding: input4.vector(GEMINI_EMBEDDING_DIMENSIONS, {
+        required: false,
+        description: "Pre-computed 768-dimensional query vector embedding."
+      }),
+      limit: input4.int({
+        default: opts.searchLimit,
+        description: "Maximum number of search results to return."
+      }),
+      threshold: input4.decimal({
+        default: opts.searchThreshold,
+        description: "Minimum cosine similarity score threshold (0.0 to 1.0)."
+      }),
+      api_key: input4.text({
+        required: false,
+        description: "Optional Google API key override."
+      })
+    },
+    stack: [
+      setVar4("target_embedding", inp4("query_embedding")),
+      s4.conditional({
+        when: expr3(ref4("target_embedding"), "=", c4.null()),
+        then: [
+          s4.precondition({
+            expr: or2(
+              expr3(inp4("query"), "!=", c4.text("")),
+              expr3(inp4("query_media_data"), "!=", c4.text(""))
+            ),
+            error_type: "badrequest",
+            error: c4.text("search_vectors: either `query` text, `query_media_data`, or `query_embedding` vector must be provided.")
+          }),
+          s4.function.run({
+            fn: embedFn,
+            input: {
+              text: inp4("query"),
+              media_data: inp4("query_media_data"),
+              mime_type: inp4("query_mime_type"),
+              task_type: c4.text(opts.taskTypeQuery),
+              api_key: inp4("api_key")
+            },
+            as: "embed_query_res"
+          }),
+          setVar4("target_embedding", ref4("embed_query_res.embedding"))
+        ]
+      }),
+      s4.db.query({
+        table: chunk,
+        eval: [
+          {
+            name: "embedding",
+            as: "distance",
+            filters: [
+              {
+                name: "vector_cos_distance",
+                arg: [ref4("target_embedding")]
+              }
+            ]
+          }
+        ],
+        sort: [{ sortBy: "distance", dir: "asc" }],
+        paging: { per_page: inp4("limit") },
+        as: "hits"
+      })
+    ],
+    response: obj4({
+      results: ref4("hits.items"),
+      count: withFilters4(ref4("hits.items"), [fl4.count()])
+    }),
+    responseShape: {}
+  });
+}
+
+// src/tool/vector-search-tool.ts
+import { tool, input as input5, s as s5, inp as inp5, ref as ref5 } from "@xano/sdk";
+function vectorSearchTool(opts, searchFn) {
+  const citationGuide = opts.citationFormat === "markdown" ? " When citing or referencing any retrieved documents, images, audio, or files, format links to the document as `[Document Title](#doc-<document_id>)`." : opts.citationFormat === "numeric" ? " When citing or referencing any retrieved documents, cite the document as `(Document ID <document_id>)`." : "";
+  return tool({
+    name: opts.names.searchTool,
+    description: "Search the indexed document and media knowledge base using semantic vector similarity with Gemini multimodal embeddings.",
+    instructions: "Use this tool to search and retrieve facts, documentation, notes, specifications, images, and media files from the user's knowledge base to answer questions." + citationGuide,
+    tags: opts.tags,
+    input: {
+      query: input5.text({
+        required: false,
+        description: "Natural language search query to locate relevant context or media."
+      }),
+      media_data: input5.text({
+        required: false,
+        description: "Optional base64 media data for visual/audio search queries."
+      }),
+      mime_type: input5.text({
+        default: "text/plain",
+        description: "MIME type for media data if provided (e.g. image/png, audio/mp3)."
+      }),
+      limit: input5.int({
+        default: 5,
+        description: "Maximum number of relevant chunks to retrieve (default: 5)."
+      })
+    },
+    stack: [
+      s5.function.run({
+        fn: searchFn,
+        input: {
+          query: inp5("query"),
+          query_media_data: inp5("media_data"),
+          query_mime_type: inp5("mime_type"),
+          limit: inp5("limit")
+        },
+        as: "search_res"
+      })
+    ],
+    response: ref5("search_res.results")
+  });
+}
+
+// src/api/group.ts
+import { apiGroup } from "@xano/sdk";
+function vectorGroup(opts) {
+  return apiGroup({
+    name: opts.names.apiGroup,
+    canonical: opts.canonical,
+    description: "Vector embedding pipeline, document ingestion, and similarity search endpoints.",
+    tags: opts.tags
+  });
+}
+
+// src/api/documents.ts
+import {
+  query,
+  input as input6,
+  s as s6,
+  setVar as setVar5,
+  c as c5,
+  inp as inp6,
+  ref as ref6,
+  auth,
+  col as col2,
+  expr as expr4,
+  or as or3,
+  obj as obj5,
+  withFilters as withFilters5,
+  fl as fl5
+} from "@xano/sdk";
+function authWhere(opts) {
+  if (opts.authenticated && opts.authTable) {
+    return expr4(col2("user_id"), "=", auth("id"));
+  }
+  return void 0;
+}
+function documentQueries(opts, group, document, chunk, ingestFn) {
+  const prefix = opts.routePrefix;
+  const authGate = opts.authenticated ? opts.authTable : false;
+  const createEndpoint = query({
+    name: `${prefix}/documents/create`,
+    verb: "POST",
+    apiGroup: group,
+    auth: authGate,
+    description: "Create a new document or media asset and immediately chunk and index it.",
+    tags: opts.tags,
+    input: {
+      title: input6.text({
+        required: true,
+        description: "Title or filename for the document."
+      }),
+      content: input6.text({
+        required: false,
+        description: "Raw text content of the document."
+      }),
+      media_data: input6.text({
+        required: false,
+        description: "Base64-encoded media data (images, audio, video)."
+      }),
+      mime_type: input6.text({
+        default: "text/plain",
+        description: "MIME type (e.g. text/markdown, image/png, audio/mp3)."
+      }),
+      metadata: input6.json({
+        required: false,
+        description: "Arbitrary structured metadata."
+      }),
+      strategy: input6.enum(CHUNK_STRATEGIES, {
+        default: opts.defaultStrategy,
+        description: "Chunking algorithm for text content."
+      }),
+      chunk_size: input6.int({
+        default: opts.defaultChunkSize,
+        description: "Target maximum chunk size in characters."
+      }),
+      chunk_overlap: input6.int({
+        default: opts.defaultChunkOverlap,
+        description: "Chunk character overlap."
+      })
+    },
+    stack: [
+      s6.precondition({
+        expr: or3(
+          expr4(inp6("content"), "!=", c5.text("")),
+          expr4(inp6("media_data"), "!=", c5.text(""))
+        ),
+        error_type: "badrequest",
+        error: c5.text("create_document: either `content` text or `media_data` must be provided.")
+      }),
+      s6.db.add({
+        table: document,
+        row: {
+          title: inp6("title"),
+          content: inp6("content"),
+          media_data: inp6("media_data"),
+          mime_type: inp6("mime_type"),
+          metadata: inp6("metadata"),
+          status: c5.text("pending"),
+          chunk_count: c5.int(0),
+          strategy: inp6("strategy"),
+          chunk_size: inp6("chunk_size"),
+          chunk_overlap: inp6("chunk_overlap"),
+          ...opts.authenticated && opts.authTable ? { user_id: auth("id") } : {}
+        },
+        as: "created_doc"
+      }),
+      s6.function.run({
+        fn: ingestFn,
+        input: {
+          document_id: ref6("created_doc.id")
+        },
+        as: "ingest_res"
+      }),
+      s6.db.get({
+        table: document,
+        fieldValue: ref6("created_doc.id"),
+        as: "final_doc"
+      })
+    ],
+    response: obj5({
+      document: ref6("final_doc"),
+      chunk_count: ref6("ingest_res.chunk_count"),
+      status: ref6("ingest_res.status")
+    }),
+    responseShape: {}
+  });
+  const listEndpoint = query({
+    name: `${prefix}/documents`,
+    verb: "GET",
+    apiGroup: group,
+    auth: authGate,
+    description: "List uploaded documents and media assets with pagination.",
+    tags: opts.tags,
+    input: {
+      page: input6.int({
+        default: 1,
+        description: "Page number (1-based)."
+      }),
+      per_page: input6.int({
+        default: 20,
+        description: "Number of documents per page."
+      })
+    },
+    stack: [
+      s6.db.query({
+        table: document,
+        where: authWhere(opts),
+        sort: [{ sortBy: "created_at", dir: "desc" }],
+        paging: {
+          page: inp6("page"),
+          per_page: inp6("per_page")
+        },
+        as: "docs"
+      })
+    ],
+    response: ref6("docs"),
+    responseShape: {}
+  });
+  const getEndpoint = query({
+    name: `${prefix}/documents/{id}`,
+    verb: "GET",
+    apiGroup: group,
+    auth: authGate,
+    description: "Get a specific document record along with all its vector chunks.",
+    tags: opts.tags,
+    input: {
+      id: input6.int({
+        required: true,
+        description: "Document ID."
+      })
+    },
+    stack: [
+      s6.db.get({
+        table: document,
+        fieldValue: inp6("id"),
+        as: "doc"
+      }),
+      s6.precondition({
+        expr: expr4(ref6("doc"), "!=", c5.null()),
+        error_type: "notfound",
+        error: c5.text("Document not found.")
+      }),
+      ...opts.authenticated && opts.authTable ? [
+        s6.precondition({
+          expr: expr4(ref6("doc.user_id", { safe: true }), "=", auth("id")),
+          error_type: "notfound",
+          error: c5.text("Document not found.")
+        })
+      ] : [],
+      s6.db.query({
+        table: chunk,
+        where: expr4(col2("document_id"), "=", ref6("doc.id")),
+        sort: [{ sortBy: "chunk_index", dir: "asc" }],
+        as: "chunks"
+      })
+    ],
+    response: obj5({
+      document: ref6("doc"),
+      chunks: ref6("chunks")
+    }),
+    responseShape: {}
+  });
+  const deleteEndpoint = query({
+    name: `${prefix}/documents/{id}/delete`,
+    verb: "DELETE",
+    apiGroup: group,
+    auth: authGate,
+    description: "Delete a document and all of its associated vector chunks.",
+    tags: opts.tags,
+    input: {
+      id: input6.int({
+        required: true,
+        description: "Document ID to delete."
+      })
+    },
+    stack: [
+      s6.db.get({
+        table: document,
+        fieldValue: inp6("id"),
+        as: "doc"
+      }),
+      s6.precondition({
+        expr: expr4(ref6("doc"), "!=", c5.null()),
+        error_type: "notfound",
+        error: c5.text("Document not found.")
+      }),
+      ...opts.authenticated && opts.authTable ? [
+        s6.precondition({
+          expr: expr4(ref6("doc.user_id", { safe: true }), "=", auth("id")),
+          error_type: "notfound",
+          error: c5.text("Document not found.")
+        })
+      ] : [],
+      s6.db.bulk.delete({
+        table: chunk,
+        where: expr4(col2("document_id"), "=", ref6("doc.id"))
+      }),
+      s6.db.del({
+        table: document,
+        fieldValue: ref6("doc.id")
+      })
+    ],
+    response: obj5({
+      deleted: c5.bool(true),
+      id: ref6("doc.id")
+    }),
+    responseShape: {}
+  });
+  const reindexEndpoint = query({
+    name: `${prefix}/documents/{id}/reindex`,
+    verb: "POST",
+    apiGroup: group,
+    auth: authGate,
+    description: "Re-chunk and re-embed an existing document with updated chunking parameters.",
+    tags: opts.tags,
+    input: {
+      id: input6.int({
+        required: true,
+        description: "Document ID to reindex."
+      }),
+      strategy: input6.enum(CHUNK_STRATEGIES, {
+        required: false,
+        description: "New chunking algorithm (fixed, paragraph, sentence, markdown, custom)."
+      }),
+      chunk_size: input6.int({
+        required: false,
+        description: "Updated target chunk size."
+      }),
+      chunk_overlap: input6.int({
+        required: false,
+        description: "Updated chunk overlap."
+      })
+    },
+    stack: [
+      s6.db.get({
+        table: document,
+        fieldValue: inp6("id"),
+        as: "doc"
+      }),
+      s6.precondition({
+        expr: expr4(ref6("doc"), "!=", c5.null()),
+        error_type: "notfound",
+        error: c5.text("Document not found.")
+      }),
+      ...opts.authenticated && opts.authTable ? [
+        s6.precondition({
+          expr: expr4(ref6("doc.user_id", { safe: true }), "=", auth("id")),
+          error_type: "notfound",
+          error: c5.text("Document not found.")
+        })
+      ] : [],
+      setVar5(
+        "new_strategy",
+        withFilters5(inp6("strategy"), [fl5.first_notempty(ref6("doc.strategy"))])
+      ),
+      setVar5(
+        "new_size",
+        withFilters5(inp6("chunk_size"), [fl5.first_notempty(ref6("doc.chunk_size"))])
+      ),
+      setVar5(
+        "new_overlap",
+        withFilters5(inp6("chunk_overlap"), [fl5.first_notempty(ref6("doc.chunk_overlap"))])
+      ),
+      s6.db.edit({
+        table: document,
+        fieldValue: ref6("doc.id"),
+        row: {
+          strategy: ref6("new_strategy"),
+          chunk_size: ref6("new_size"),
+          chunk_overlap: ref6("new_overlap")
+        }
+      }),
+      s6.function.run({
+        fn: ingestFn,
+        input: {
+          document_id: ref6("doc.id")
+        },
+        as: "ingest_res"
+      })
+    ],
+    response: ref6("ingest_res"),
+    responseShape: {}
+  });
+  return {
+    create: createEndpoint,
+    createDocument: createEndpoint,
+    list: listEndpoint,
+    listDocuments: listEndpoint,
+    get: getEndpoint,
+    getDocument: getEndpoint,
+    delete: deleteEndpoint,
+    deleteDocument: deleteEndpoint,
+    reindex: reindexEndpoint,
+    reindexDocument: reindexEndpoint,
+    all: [
+      createEndpoint,
+      listEndpoint,
+      getEndpoint,
+      deleteEndpoint,
+      reindexEndpoint
+    ]
+  };
+}
+
+// src/api/search.ts
+import { query as query2, input as input7, s as s7, inp as inp7, ref as ref7, obj as obj6 } from "@xano/sdk";
+function searchQueries(opts, group, searchFn, embedFn) {
+  const prefix = opts.routePrefix;
+  const authGate = opts.authenticated ? opts.authTable : false;
+  const searchEndpoint = query2({
+    name: `${prefix}/search`,
+    verb: "POST",
+    apiGroup: group,
+    auth: authGate,
+    description: "Search document chunks and media using semantic similarity via 768-dim Gemini vector embeddings.",
+    tags: opts.tags,
+    input: {
+      query: input7.text({
+        required: false,
+        description: "Natural language query string."
+      }),
+      query_media_data: input7.text({
+        required: false,
+        description: "Base64-encoded media data for visual/audio search queries."
+      }),
+      query_mime_type: input7.text({
+        default: "text/plain",
+        description: "MIME type for media data if provided."
+      }),
+      query_embedding: input7.vector(GEMINI_EMBEDDING_DIMENSIONS, {
+        required: false,
+        description: "Pre-computed 768-dimensional query vector."
+      }),
+      limit: input7.int({
+        default: opts.searchLimit,
+        description: "Maximum number of search results to return."
+      }),
+      threshold: input7.decimal({
+        default: opts.searchThreshold,
+        description: "Minimum similarity threshold (0.0 to 1.0)."
+      })
+    },
+    stack: [
+      s7.function.run({
+        fn: searchFn,
+        input: {
+          query: inp7("query"),
+          query_media_data: inp7("query_media_data"),
+          query_mime_type: inp7("query_mime_type"),
+          query_embedding: inp7("query_embedding"),
+          limit: inp7("limit"),
+          threshold: inp7("threshold")
+        },
+        as: "search_res"
+      })
+    ],
+    response: obj6({
+      results: ref7("search_res.results"),
+      count: ref7("search_res.count")
+    }),
+    responseShape: {}
+  });
+  const embedEndpoint = query2({
+    name: `${prefix}/embed`,
+    verb: "POST",
+    apiGroup: group,
+    auth: authGate,
+    description: "Directly generates a 768-dimensional vector embedding for text or media using Google Gemini API.",
+    tags: opts.tags,
+    input: {
+      text: input7.text({
+        required: false,
+        description: "Text content to generate an embedding vector for."
+      }),
+      media_data: input7.text({
+        required: false,
+        description: "Base64 media data (image, audio, video)."
+      }),
+      mime_type: input7.text({
+        default: "text/plain",
+        description: "MIME type for media data if provided."
+      }),
+      model: input7.text({
+        default: opts.model,
+        description: "Google Gemini embedding model name."
+      })
+    },
+    stack: [
+      s7.function.run({
+        fn: embedFn,
+        input: {
+          text: inp7("text"),
+          media_data: inp7("media_data"),
+          mime_type: inp7("mime_type"),
+          model: inp7("model")
+        },
+        as: "embed_res"
+      })
+    ],
+    response: ref7("embed_res"),
+    responseShape: {}
+  });
+  return {
+    search: searchEndpoint,
+    embed: embedEndpoint,
+    all: [searchEndpoint, embedEndpoint]
+  };
+}
+
+// src/register.ts
+var installed = /* @__PURE__ */ new WeakSet();
+function createVector(opts = {}) {
+  const options = resolveOptions(opts);
+  const document = documentTable(options);
+  const chunk = chunkTable(options, document);
+  const embedFn = generateEmbeddingFn(options);
+  const chunkFn = chunkTextFn(options);
+  const ingestFn = ingestDocumentFn(options, document, chunk, embedFn, chunkFn);
+  const searchFn = searchVectorsFn(options, chunk, embedFn);
+  const searchTool = vectorSearchTool(options, searchFn);
+  const group = vectorGroup(options);
+  const documents = documentQueries(options, group, document, chunk, ingestFn);
+  const search = searchQueries(options, group, searchFn, embedFn);
+  return {
+    options,
+    document,
+    chunk,
+    embedFn,
+    chunkFn,
+    ingestFn,
+    searchFn,
+    searchTool,
+    group,
+    documents,
+    search,
+    queries: [...documents.all, ...search.all]
+  };
+}
+function registerVector(xano, opts = {}) {
+  if (installed.has(xano)) {
+    throw new Error(
+      'registerVector: already called on this Xano instance. Register the vector set once \u2014 a second registration duplicates every def, which the SDK cannot catch (the two sets are distinct objects sharing names) and which surfaces at export() as "Duplicate object guid \u2026 shared by \\"dbo/vector_document\\" and \\"dbo/vector_document\\"". To run TWO vector pipelines in one workspace, build the second with `createVector({ canonical, names: { searchTool } })` and register its defs yourself.'
+    );
+  }
+  const vec = createVector(opts);
+  xano.registerTables([vec.document, vec.chunk]).registerFunctions([
+    vec.embedFn,
+    vec.chunkFn,
+    vec.ingestFn,
+    vec.searchFn
+  ]).registerTools([vec.searchTool]).registerApiGroups([vec.group]).registerQueries(vec.queries);
+  installed.add(xano);
+  return { ...vec, xano };
+}
+export {
+  CHUNK_STRATEGIES,
+  DEFAULT_API_KEY_ENV,
+  DEFAULT_CHUNK_OVERLAP,
+  DEFAULT_CHUNK_SIZE,
+  DEFAULT_GEMINI_MODEL,
+  DEFAULT_NAMES,
+  DEFAULT_SEARCH_LIMIT,
+  DEFAULT_SEARCH_THRESHOLD,
+  DEFAULT_STRATEGY,
+  DOCUMENT_STATUSES,
+  GEMINI_EMBEDDING_DIMENSIONS,
+  PUBLIC_CHUNK_FIELDS,
+  PUBLIC_DOCUMENT_FIELDS,
+  chunkTable,
+  chunkTextFn,
+  createVector,
+  documentQueries,
+  documentTable,
+  generateEmbeddingFn,
+  ingestDocumentFn,
+  registerVector,
+  resolveOptions,
+  searchQueries,
+  searchVectorsFn,
+  vectorGroup,
+  vectorSearchTool
+};
+//# sourceMappingURL=index.js.map