@mindstudio-ai/agent 0.1.86 → 0.1.87

package/dist/index.d.ts

@@ -1508,6 +1508,16 @@ interface Citation {
     filename: string | null;
     /** 1-based. Null for formats with no pagination (plain text, html). */
     pageNumber: number | null;
+    /**
+     * Position within the document, 0-based.
+     *
+     * `(documentId, chunkIndex)` is the stable identity of a chunk — use it as
+     * the key for an eval set or a regression check rather than matching on
+     * `text`. Stable for as long as the corpus keeps its current configuration:
+     * re-chunking a source (a different chunk size, say) moves the boundaries and
+     * therefore renumbers, which is inherent rather than a wobble.
+     */
+    chunkIndex: number | null;
     /** Enclosing headings, outermost first. */
     headingPath: string[];
     /**
@@ -1527,12 +1537,49 @@ interface Citation {
      */
     url: string;
 }
+/** Where one retrieval branch put a hit, and what that branch scored it. */
+interface BranchPosition {
+    /** 0-based position within that branch's own results. */
+    rank: number;
+    score: number;
+}
+/**
+ * Which half of hybrid retrieval found a hit. Only present when `explain` was
+ * requested — see {@link SearchOptions.explain}.
+ */
+interface SearchExplain {
+    /** Semantic (embedding) retrieval. Null if this branch didn't find the hit. */
+    dense: BranchPosition | null;
+    /** Keyword/IDF retrieval. Null when `hybrid` is off, or if it didn't find it. */
+    lexical: BranchPosition | null;
+    matchedVia: 'dense' | 'lexical' | 'both';
+}
 interface SearchHit {
     /** Provider relevance score. Comparable within a response, not across them. */
     score: number;
     /** The matched chunk, prefixed with its heading path for context. */
     text: string;
     citation: Citation;
+    /**
+     * Where retrieval put this hit BEFORE reranking, and what it scored.
+     *
+     * With reranking on, `score` is the reranker's relevance score and this is
+     * the retriever's — different quantities, so they're kept apart rather than
+     * blended. Comparing `retrievalRank` with the hit's final position is how you
+     * see what reranking actually did ("retrieved 7th, reranked to 1st").
+     *
+     * Named for the stage rather than the method: it's a fused hybrid score when
+     * `hybrid` is on and a cosine similarity when it's off.
+     */
+    retrievalRank?: number;
+    retrievalScore?: number;
+    /** Only when `explain` was requested. */
+    explain?: SearchExplain;
+    /** Only when `expand` was requested. Outermost first, so `[...before, text, ...after]` reads in order. */
+    neighbors?: {
+        before: string[];
+        after: string[];
+    };
 }
 /**
  * Per-query overrides.
@@ -1566,6 +1613,23 @@ interface SearchOptions {
      * that an embedding model never learned. Rarely worth disabling.
      */
     hybrid?: boolean;
+    /**
+     * Report which branch found each hit, and where each ranked it.
+     *
+     * A debugging aid, off by default because it costs two extra round trips: a
+     * fused result carries one blended score, so the branches have to be asked
+     * separately. Results and their order are identical either way — this only
+     * adds {@link SearchHit.explain}.
+     */
+    explain?: boolean;
+    /**
+     * Also return this many chunks either side of each hit, in
+     * {@link SearchHit.neighbors} — for showing a passage in context. 0-2.
+     *
+     * `text` is untouched, so citations and highlighting still point at the
+     * chunk that actually matched.
+     */
+    expand?: number;
 }
 interface AddOptions {
     /**
@@ -1585,6 +1649,68 @@ interface DataSourceDocument {
     createdAt: string;
     ingestedAt: string | null;
 }
+/** One chunk exactly as it was indexed. See {@link DataSource.chunks}. */
+interface DataSourceChunk {
+    index: number;
+    text: string;
+    pageNumber: number;
+    headingPath: string[];
+    /**
+     * Offsets into the page's extracted markdown. Null for PDFs, which carry a
+     * `boundingBox` instead — there is no character stream to point into.
+     */
+    charStart: number | null;
+    charEnd: number | null;
+    boundingBox?: {
+        topLeftX: number;
+        topLeftY: number;
+        bottomRightX: number;
+        bottomRightY: number;
+    };
+    /** base64 of a Float32Array. Only when `vectors: true` was passed. */
+    vector?: string;
+}
+/** How a corpus was built and what is in it. See {@link DataSource.stats}. */
+interface DataSourceStats {
+    /** False for a source nothing has created yet — everything else reads zero. */
+    exists: boolean;
+    documentCount: number;
+    counts: {
+        total: number;
+        done: number;
+        processing: number;
+        error: number;
+    };
+    chunkCount: number;
+    /** Original document bytes, not index size. */
+    storageBytes: number;
+    lastIngestedAt: string | null;
+    /**
+     * The configuration these documents were actually built with — not the
+     * platform default, and not necessarily the newest. Changing it is an
+     * explicit, owner-triggered migration.
+     */
+    pipeline: {
+        version: number;
+        embeddingModelId: string;
+        dimensions: number;
+        chunking: {
+            strategy: string;
+            version: number;
+            maxChars: number;
+            minChars: number;
+            dropBlockTypes: string[];
+        };
+        contextual: {
+            enabled: boolean;
+            modelId: string | null;
+        };
+        images: {
+            describe: boolean;
+            modelId: string | null;
+        };
+    } | null;
+}
 /**
  * A typed handle to one data source. Lazy — nothing executes until a method is
  * awaited, so it's safe to `defineDataSource()` at module scope and import the
@@ -1602,10 +1728,39 @@ declare class DataSource {
      * 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.
      */
     search(query: string, options?: SearchOptions): Promise<{
         results: SearchHit[];
+        latencyMs: number;
     }>;
+    /**
+     * 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.
+     */
+    stats(): Promise<DataSourceStats>;
+    /**
+     * 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.
+     */
+    chunks(documentId: string, options?: {
+        vectors?: boolean;
+    }): Promise<DataSourceChunk[]>;
     /**
      * Add a document to the corpus.
      *
@@ -2300,6 +2455,12 @@ declare class MindStudioAgent$1 {
      *
      * 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`).
      */
     uploadFile(content: Buffer | Uint8Array, options: {
         extension: string;

package/dist/index.js

@@ -2128,17 +2128,54 @@ var DataSource = class {
    * 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 } = await this._call("search", {
+    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?.hybrid !== void 0 ? { hybrid: options.hybrid } : {},
+      ...options?.explain !== void 0 ? { explain: options.explain } : {},
+      ...options?.expand !== void 0 ? { expand: options.expand } : {}
     });
-    return { results: results ?? [] };
+    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.
@@ -5572,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}`;