@mindstudio-ai/agent 0.1.85 → 0.1.87

package/dist/index.js

@@ -2112,6 +2112,133 @@ function createFiles(call) {
   };
 }
 
+// src/datasources/source.ts
+import { createHash as createHash2 } from "crypto";
+var DataSource = class {
+  constructor(_slug, _call) {
+    this._slug = _slug;
+    this._call = _call;
+  }
+  get name() {
+    return this._slug;
+  }
+  /**
+   * Search the corpus.
+   *
+   * Returns chunks ranked by relevance, each with a citation. Searching a
+   * source that doesn't exist yet returns no results rather than throwing —
+   * code may name a corpus the build hasn't populated.
+   *
+   * **Deterministic** for a fixed corpus and configuration: the same query
+   * returns the same hits in the same order, so it's safe to build an eval set
+   * or a regression check on top of it. There is no seed to set. Two things do
+   * legitimately move the results: adding or removing documents, and changing
+   * the corpus configuration — both of which you control.
+   */
+  async search(query, options) {
+    const { results, latencyMs } = await this._call("search", {
+      slug: this._slug,
+      query,
+      ...options?.topK !== void 0 ? { topK: options.topK } : {},
+      ...options?.scoreThreshold !== void 0 ? { scoreThreshold: options.scoreThreshold } : {},
+      ...options?.rerank !== void 0 ? { rerank: options.rerank } : {},
+      ...options?.hybrid !== void 0 ? { hybrid: options.hybrid } : {},
+      ...options?.explain !== void 0 ? { explain: options.explain } : {},
+      ...options?.expand !== void 0 ? { expand: options.expand } : {}
+    });
+    return { results: results ?? [], latencyMs: latencyMs ?? 0 };
+  }
+  /**
+   * What is in the corpus, and how it was built.
+   *
+   * Document and chunk counts, storage, and the embedding model and chunking
+   * settings actually in effect — which is not the same as the platform
+   * default, since a corpus keeps the configuration it was built with until
+   * someone migrates it.
+   */
+  async stats() {
+    return this._call("stats", { slug: this._slug });
+  }
+  /**
+   * Every chunk of one document, exactly as it was indexed.
+   *
+   * The direct answer to "why isn't this document coming back?" — search only
+   * shows you the chunks that surface, which is no help when none do. Reading
+   * how a document was actually split usually is.
+   *
+   * Pass `{ vectors: true }` to include each chunk's embedding. Large: roughly
+   * 8KB per chunk, so a 500-chunk document is several megabytes.
+   */
+  async chunks(documentId, options) {
+    const { chunks } = await this._call("chunks", {
+      slug: this._slug,
+      documentId,
+      ...options?.vectors ? { vectors: true } : {}
+    });
+    return chunks ?? [];
+  }
+  /**
+   * Add a document to the corpus.
+   *
+   * Returns as soon as the document is queued — extraction and embedding run
+   * in the background and take a while, so poll {@link documents} for status
+   * rather than assuming the content is searchable on return.
+   *
+   * **Adding the same bytes twice is free.** Documents are content-addressed,
+   * so a re-add is a no-op when this source has already processed those exact
+   * bytes under its current configuration. Reconfiguring the source is what
+   * makes a re-add do work again — and that is an explicit, owner-triggered
+   * migration, never something a deploy causes.
+   */
+  async add(content, options) {
+    const bytes = typeof content === "string" ? Buffer.from(content) : Buffer.from(content);
+    return this._call("add", {
+      slug: this._slug,
+      filename: options.filename,
+      ...options.contentType ? { contentType: options.contentType } : {},
+      body: bytes.toString("base64")
+    });
+  }
+  /** Every document in the corpus, with ingest status. */
+  async documents() {
+    const { documents } = await this._call("documents", { slug: this._slug });
+    return documents ?? [];
+  }
+  /** Remove a document and its vectors. */
+  async remove(documentId) {
+    await this._call("remove", { slug: this._slug, documentId });
+  }
+  /**
+   * Create the data source if it doesn't exist yet.
+   *
+   * Rarely needed — `add` and `search` both handle a missing source. Useful
+   * when you want it to exist (and appear in the dashboard) before any
+   * document has been added.
+   */
+  async ensure(name) {
+    await this._call("ensure", {
+      slug: this._slug,
+      ...name ? { name } : {}
+    });
+  }
+  /**
+   * @internal Content hash of some bytes, matching what the server computes.
+   * Exposed for callers that want to check whether they already added a file.
+   */
+  static contentHash(content) {
+    return createHash2("sha256").update(Buffer.from(content)).digest("hex");
+  }
+};
+
+// src/datasources/index.ts
+function createDataSources(call) {
+  return {
+    defineDataSource(name) {
+      return new DataSource(name, call);
+    }
+  };
+}
+
 // src/generated/metadata.ts
 var stepMetadata = {
   "activeCampaignAddNote": {
@@ -4126,6 +4253,7 @@ var MindStudioAgent = class {
   _db;
   /** @internal Cached Files namespace instance (lazy; no context hydration needed). */
   _files;
+  _dataSources;
   /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
   _authType;
   /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -5017,12 +5145,47 @@ var MindStudioAgent = class {
   get files() {
     return this._files ??= createFiles(this._filesRequest.bind(this));
   }
+  /**
+   * Searchable document corpora.
+   *
+   * @example
+   * ```ts
+   * const Policies = agent.dataSources.defineDataSource('policies');
+   * const { results } = await Policies.search('what are the payment terms?');
+   * ```
+   */
+  get dataSources() {
+    return this._dataSources ??= createDataSources(
+      this._dataSourcesRequest.bind(this)
+    );
+  }
   /**
    * @internal Transport for the `files` namespace — POST /_internal/v2/files/<op>
    * with the raw hook token (mirrors `_executeDbBatch`).
    */
   async _filesRequest(op, body) {
-    const url = `${this._currentHttpConfig.baseUrl}/_internal/v2/files/${op}`;
+    return this._brokeredRequest("files", op, body, {
+      fallbackMessage: "File operation failed",
+      fallbackCode: "file_error"
+    });
+  }
+  /**
+   * @internal Transport for the `dataSources` namespace —
+   * POST /_internal/v2/datasources/<op> with the raw hook token.
+   */
+  async _dataSourcesRequest(op, body) {
+    return this._brokeredRequest("datasources", op, body, {
+      fallbackMessage: "Data source operation failed",
+      fallbackCode: "data_source_error"
+    });
+  }
+  /**
+   * @internal Shared shape for the brokered `/_internal/v2/<ns>/<op>` data
+   * planes. Factored out rather than copied per namespace so error handling
+   * can't drift between them.
+   */
+  async _brokeredRequest(namespace, op, body, errors) {
+    const url = `${this._currentHttpConfig.baseUrl}/_internal/v2/${namespace}/${op}`;
     const res = await fetch(url, {
       method: "POST",
       headers: {
@@ -5044,8 +5207,8 @@ var MindStudioAgent = class {
     }
     if (!res.ok) {
       const rawMsg = json?.errorMessage ?? (typeof json?.error === "string" ? json.error : json?.error?.message);
-      const message = typeof rawMsg === "string" ? rawMsg : `File operation failed: ${res.status} ${res.statusText}`;
-      const code = json?.errorString ?? json?.code ?? "file_error";
+      const message = typeof rawMsg === "string" ? rawMsg : `${errors.fallbackMessage}: ${res.status} ${res.statusText}`;
+      const code = json?.errorString ?? json?.code ?? errors.fallbackCode;
       throw new MindStudioError(message, code, res.status);
     }
     return json;
@@ -5446,6 +5609,12 @@ var MindStudioAgent = class {
    *
    * Gets a presigned upload request from the API, POSTs the file as
    * multipart/form-data, and returns the permanent public URL.
+   *
+   * @deprecated For app file storage use the `files` store
+   * (`files.defineStore(...).put(...)`) — private by default, app-scoped, and
+   * served on the app's own domain. `uploadFile` uploads to the shared account
+   * media CDN; it remains only for account-level assets (e.g. an agent avatar
+   * passed to `changeProfilePicture`).
    */
   async uploadFile(content, options) {
     const filename = options.filename ?? `upload.${options.extension}`;
@@ -5726,6 +5895,16 @@ var files = new Proxy(
     }
   }
 );
+var dataSources = new Proxy(
+  {},
+  {
+    get(_, prop) {
+      const target = mindstudio.dataSources;
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  }
+);
 var stream = (data) => mindstudio.stream(data);
 var resolveUser = (userId) => mindstudio.resolveUser(userId);
 var reportIssue = (input) => mindstudio.reportIssue(input);
@@ -5739,6 +5918,7 @@ export {
   Roles,
   auth,
   blockTypeAliases,
+  dataSources,
   db,
   index_default as default,
   files,