@mindstudio-ai/agent 0.1.85 → 0.1.87

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).
@@ -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';
@@ -1840,3 +1840,38 @@ return token;
 import { platform } from '@mindstudio-ai/interface';
 const { url } = await platform.upload(token, file, { onProgress });
 ```
+
+#### `dataSources` — searchable document corpora (RAG)
+
+Declare a data source at module scope and import the handle. The platform owns parsing, chunking, embedding, storage and tenant isolation; every hit returns a citation.
+```typescript
+import { dataSources } from '@mindstudio-ai/agent';
+export const Policies = dataSources.defineDataSource('policies');
+
+// search
+const { results } = await Policies.search('what are the payment terms?', { topK: 5 });
+// options: topK (default 5, max 50), scoreThreshold, rerank, hybrid — the last two default on
+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, 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.
+
+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. Only reconfiguring the source makes a re-add do work again, and that is an explicit owner-triggered migration, never a side effect of a deploy.
+
+`rerank` and `hybrid` are free to change and take effect on the next search. How documents are chunked and embedded is configured on the corpus itself with `mindstudio-prod datasources config` — not in code — and changing it on a populated source is rejected rather than silently rebuilding.
+
+**A data source is live and shared.** Unlike database tables there is no dev copy and no per-release isolation: adding or removing a document changes what the deployed app retrieves, immediately. Scenarios never reset a data source, and re-ingesting a large corpus costs real money.

package/package.json

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