@mindstudio-ai/agent 0.1.86 → 0.1.88

package/llms.txt

@@ -8,7 +8,7 @@ This file is the complete API reference. No other documentation is needed to use
 
 There are 150+ actions available. Do NOT try to read or load them all at once. Follow this discovery flow:
 
-1. **Identify yourself** — Call `changeName` to set your display name (use your name or whatever your user calls you). If you have a profile picture or icon, call `uploadFile` to upload it, then `changeProfilePicture` with the returned URL. This helps users identify your requests in their logs.
+1. **Identify yourself** — Call `changeName` to set your display name (use your name or whatever your user calls you). If you have a profile picture, pass its public image URL to `changeProfilePicture`. This helps users identify your requests in their logs.
 2. **Ask** — Use `mindstudio ask "your question"` (CLI) or the `ask` MCP tool for SDK guidance. It knows every action, model, and connector and returns working TypeScript code with real model IDs and config options. Examples: `mindstudio ask "generate an image with FLUX"`, `mindstudio ask "what models support vision?"`, `mindstudio ask "how do I send a Slack message?"`.
 3. **Browse** — For manual discovery, call `listActions` (MCP tool) or `mindstudio list-actions --summary` (CLI) to get a compact `{ action: description }` map of everything available (~3k tokens). Call `mindstudio info <action>` (CLI) for parameter details.
 4. **Call it** — Invoke the action with the required parameters. All actions share the same calling convention (see below).
@@ -303,7 +303,7 @@ Convert each page of a PDF document into a PNG image.
 - Output: `{ imageUrls: string[] }`
 
 #### createDataSource
-Create a new empty vector data source for the current app.
+Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Create a new empty vector data source for the current app.
 - Creates a new data source (vector database) associated with the current app version.
 - The data source is created empty — use the "Upload Data Source Document" block to add documents.
 - Returns the new data source ID which can be used in subsequent blocks.
@@ -319,7 +319,7 @@ Create a draft email in the connected Gmail account.
 - Output: `{ draftId: string }`
 
 #### deleteDataSource
-Delete a vector data source from the current app.
+Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Delete a vector data source from the current app.
 - Soft-deletes a data source (vector database) by marking it as deleted.
 - The Milvus partition is cleaned up asynchronously by a background cron job.
 - The data source must belong to the current app version.
@@ -327,7 +327,7 @@ Delete a vector data source from the current app.
 - Output: `unknown`
 
 #### deleteDataSourceDocument
-Delete a single document from a data source.
+Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Delete a single document from a data source.
 - Soft-deletes a document by marking it as deleted.
 - Requires both the data source ID and document ID.
 - After deletion, reloads vectors into Milvus so the data source reflects the change immediately.
@@ -422,7 +422,7 @@ Download a file from a URL and extract its text content. Supports PDFs (includin
 - Output: `{ text: string | string[] }`
 
 #### fetchDataSourceDocument
-Fetch the full extracted text contents of a document in a data source.
+Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Fetch the full extracted text contents of a document in a data source.
 - Loads a document by ID and returns its full extracted text content.
 - The document must have been successfully processed (status "done").
 - Also returns document metadata (name, summary, word count).
@@ -557,7 +557,7 @@ Insert b-roll clips into a base video at a timecode, optionally with an xfade tr
 - Output: `{ videoUrl: string }`
 
 #### listDataSources
-List all data sources for the current app.
+Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. List all data sources for the current app.
 - Returns metadata for every data source associated with the current app version.
 - Each entry includes the data source ID, name, description, status, and document list.
 - Input: `object`
@@ -659,7 +659,7 @@ when parameterize is false.
 - Output: `{ rows: unknown[], changes: number }`
 
 #### queryDataSource
-Search a vector data source (RAG) and return relevant document chunks.
+Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Search a vector data source (RAG) and return relevant document chunks.
 - Queries a vectorized data source and returns the most relevant chunks.
 - Useful for retrieval-augmented generation (RAG) workflows.
 - Input: `{ dataSourceId: string, query: string, maxResults: number }`
@@ -958,7 +958,7 @@ Add or remove labels on Gmail messages, identified by message IDs or a search qu
 - Output: `{ updatedMessageIds: string[] }`
 
 #### uploadDataSourceDocument
-Upload a file into an existing data source from a URL or raw text content.
+Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Upload a file into an existing data source from a URL or raw text content.
 - If "file" is a single URL, the file is downloaded from that URL and uploaded.
 - If "file" is any other string, a .txt document is created from that content and uploaded.
 - The block waits (polls) for processing to complete before transitioning, up to 5 minutes.
@@ -1791,7 +1791,7 @@ await mindstudio.changeProfilePicture('https://example.com/avatar.png');
 ```
 
 #### `uploadFile(content, options)`
-Upload a file to the MindStudio CDN. Gets a signed upload URL, PUTs the file content, and returns the permanent public URL.
+**Deprecated for app file storage** — use the `files` store below (`files.defineStore(...).put(...)`): private by default, app-scoped, and served on the app's own domain. `uploadFile` uploads to the shared account media CDN and remains only for account-level assets (e.g. an agent avatar for `changeProfilePicture`). Gets a signed upload URL, PUTs the file content, and returns the permanent public URL.
 
 ```typescript
 import { readFileSync } from 'fs';
@@ -1856,9 +1856,17 @@ const context = results.map((r) => r.text).join(String.fromCharCode(10, 10));
 // add a document (background — poll documents() for status)
 await Policies.add(buffer, { filename: 'policy.pdf', contentType: 'application/pdf' });
 const docs = await Policies.documents();
+
+// introspection — what is in the corpus, and how one document was split
+const { chunkCount, pipeline } = await Policies.stats();  // counts + the config actually in effect
+const chunks = await Policies.chunks(docs[0].id);       // why a document does or doesn't match
 ```
 
-`SearchHit`: `{ score, text, citation: { documentId, filename, pageNumber, headingPath, boundingBox?, url } }`. `citation.url` is a stable on-domain link to the source document — drop it in an `<a href>`.
+`SearchHit`: `{ score, text, citation: { documentId, filename, pageNumber, chunkIndex, headingPath, boundingBox?, url } }`. `citation.url` is a stable on-domain link to the source document — drop it in an `<a href>`. `(documentId, chunkIndex)` is a chunk's stable identity — key an eval set on that, not on `text`.
+
+Also on each hit: `retrievalRank`/`retrievalScore` (position before reranking — compare with the final position to see what reranking did). Two opt-in search options for debugging: `explain: true` adds `explain.{dense,lexical,matchedVia}` so you can see which half of hybrid found a hit, and `expand: 1` adds `neighbors.{before,after}` for surrounding context. Neither changes the results or their order.
+
+Search is deterministic for a fixed corpus and configuration — same query, same order — so regression checks are meaningful. `search()` also returns `latencyMs`.
 
 Supported: pdf, docx, pptx, xlsx, odt, rtf, epub, images, txt, md, json, csv, html.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/agent",
-  "version": "0.1.86",
+  "version": "0.1.88",
   "description": "TypeScript SDK for MindStudio direct step execution",
   "type": "module",
   "main": "./dist/index.js",