@myvillage/cli 2.8.2 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.8.2",
+  "version": "2.10.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/agent-runtime/builtin-tools-registry.js

@@ -22,6 +22,14 @@ export const DATASET_APPEND_DESCRIPTION =
   'regression provide a numeric `target`. Data stays local; provenance ' +
   'is recorded automatically.';
 
+export const DATASET_READ_DESCRIPTION =
+  'Read a LOCAL dataset on this machine: its description, columns, labels, ' +
+  'row counts, and a page of its rows (newest working set by default, or a ' +
+  'frozen version). Filter by split or label and page with offset/limit. ' +
+  'Table rows come back keyed by column name; image and sound rows come back ' +
+  'as absolute file paths (which model_predict accepts). Read-only — use ' +
+  'dataset_append to add rows.';
+
 export const MODEL_PREDICT_DESCRIPTION =
   'Run a prediction with a LOCAL trained model on this machine. `input` is ' +
   'text (words models), the values of one table row as a list in column ' +
@@ -38,6 +46,12 @@ export const BUILTIN_TOOL_DEFS = [
     tier: 'villager',
     builtin: true,
   },
+  {
+    name: 'dataset_read',
+    description: DATASET_READ_DESCRIPTION,
+    tier: 'villager',
+    builtin: true,
+  },
   {
     name: 'model_predict',
     description: MODEL_PREDICT_DESCRIPTION,
@@ -45,3 +59,25 @@ export const BUILTIN_TOOL_DEFS = [
     builtin: true,
   },
 ];
+
+/** One line telling an agent what a local model is for and what it takes. */
+export function describeLocalModel(m) {
+  const f = m.featurization ?? {};
+  const modality = f.modality ?? m.modality;
+  let takes;
+  if (modality === 'image') takes = 'a local image file path (.jpg/.png)';
+  else if (modality === 'audio') takes = 'a local .wav file path';
+  else if (modality === 'text') takes = 'some writing';
+  else if (Array.isArray(f.columns)) {
+    takes = 'a table row with ' + f.columns.map((c) => `${JSON.stringify(c.name)} (${c.type})`).join(', ');
+  } else if (Array.isArray(m.featureNames) && m.featureNames.length) {
+    takes = 'a table row of numbers: ' + m.featureNames.map((n) => JSON.stringify(n)).join(', ');
+  } else {
+    takes = `a list of ${m.inputDim ?? 'some'} numbers`;
+  }
+  const gives =
+    m.taskType === 'classification' && Array.isArray(m.labels) && m.labels.length
+      ? `sorts it into: ${m.labels.join(', ')}`
+      : 'gives back a number';
+  return `- "${m.slug}" (${m.name}): takes ${takes}; ${gives}.`;
+}

package/src/agent-runtime/builtin-tools.js

@@ -10,16 +10,63 @@
  * `myvillage dataset append` command uses — so agents and humans write
  * identically. Raw data stays local; nothing leaves the machine.
  *
- * Tool contract mirrors @myvillage-studio/dataset-schema DATASET_APPEND_TOOL.
+ * `dataset_read` is its read side: it wraps readRows() so agents can look at
+ * what's been collected (to answer questions about it, avoid duplicate
+ * appends, or feed rows to model_predict). Also local-only.
+ *
+ * Tool contracts mirror @myvillage-studio/dataset-schema DATASET_APPEND_TOOL
+ * and DATASET_READ_TOOL.
  */
 import { tool } from 'ai';
 import { z } from 'zod';
-import { appendRows, datasetExists, readManifest, ingestAsset } from '../utils/dataset-workspace.js';
-import { DATASET_APPEND_DESCRIPTION, MODEL_PREDICT_DESCRIPTION } from './builtin-tools-registry.js';
+import {
+  appendRows,
+  datasetExists,
+  readManifest,
+  readRows,
+  ingestAsset,
+  getAssetPath,
+  listDatasets,
+} from '../utils/dataset-workspace.js';
+import {
+  DATASET_APPEND_DESCRIPTION,
+  DATASET_READ_DESCRIPTION,
+  MODEL_PREDICT_DESCRIPTION,
+} from './builtin-tools-registry.js';
 import { readToolsYaml } from '../utils/local-agent.js';
 
 export { BUILTIN_TOOL_DEFS } from './builtin-tools-registry.js';
 
+const READ_DEFAULT_LIMIT = 50;
+const READ_MAX_LIMIT = 200;
+// Long text rows are clipped so one page can't blow out the model's context.
+const READ_MAX_TEXT_CHARS = 2000;
+
+/** Shape a stored row for the model: readable features, no internal noise. */
+function presentRow(slug, manifest, row) {
+  let features = row.features;
+  let truncated = false;
+  if (features && typeof features === 'object' && !Array.isArray(features) && features.path) {
+    // AssetRef → absolute path, the same form model_predict / dataset_append take
+    features = getAssetPath(slug, features.path);
+  } else if (
+    Array.isArray(features) &&
+    manifest.featureNames?.length === features.length
+  ) {
+    features = Object.fromEntries(manifest.featureNames.map((name, i) => [name, features[i]]));
+  } else if (typeof features === 'string' && features.length > READ_MAX_TEXT_CHARS) {
+    features = features.slice(0, READ_MAX_TEXT_CHARS);
+    truncated = true;
+  }
+  const out = { id: row.id, features, split: row.split };
+  if (truncated) out.truncated = true;
+  if (row.label != null) out.label = row.label;
+  if (row.target != null) out.target = row.target;
+  if (row.provenance?.source) out.source = row.provenance.source;
+  if (row.provenance?.ts) out.addedAt = row.provenance.ts;
+  return out;
+}
+
 /**
  * Gate built-ins by the SAME allowlist as the MyVillageOS platform server
  * (`allowed_tools` on whichever tools.yaml server points at a myvillageproject.ai
@@ -128,6 +175,77 @@ export function getBuiltinTools(agentName, config) {
       },
     }),
 
+    dataset_read: tool({
+      description: DATASET_READ_DESCRIPTION,
+      inputSchema: z.object({
+        datasetId: z.string().describe('Slug of the local dataset to read'),
+        version: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Frozen version number to read; omit for the current working set'),
+        split: z.enum(['train', 'val']).optional().describe('Only rows in this split'),
+        label: z.string().optional().describe('Only rows with this class label (classification datasets)'),
+        offset: z.number().int().min(0).optional().describe('Rows to skip (default 0)'),
+        limit: z
+          .number()
+          .int()
+          .min(0)
+          .max(READ_MAX_LIMIT)
+          .optional()
+          .describe(`Rows to return (default ${READ_DEFAULT_LIMIT}, max ${READ_MAX_LIMIT}; 0 = summary only)`),
+      }),
+      execute: async ({ datasetId, version, split, label, offset = 0, limit = READ_DEFAULT_LIMIT }) => {
+        const manifest = readManifest(datasetId);
+        if (!manifest) {
+          let available = [];
+          try {
+            available = listDatasets().map((d) => d.slug);
+          } catch { /* store unavailable */ }
+          return {
+            error:
+              `Dataset "${datasetId}" not found locally.` +
+              (available.length ? ` Available: ${available.join(', ')}.` : ' No local datasets exist yet.'),
+          };
+        }
+        if (version && !manifest.versions?.some((v) => v.version === version)) {
+          const known = (manifest.versions ?? []).map((v) => v.version);
+          return {
+            error:
+              `Dataset "${datasetId}" has no version ${version}.` +
+              (known.length ? ` Frozen versions: ${known.join(', ')}.` : ' It has no frozen versions yet.'),
+          };
+        }
+        try {
+          let rows = readRows(datasetId, { version, split });
+          if (label != null) rows = rows.filter((r) => r.label === label);
+          const page = rows.slice(offset, offset + limit);
+          return {
+            ok: true,
+            datasetId: manifest.slug,
+            name: manifest.name,
+            ...(manifest.description ? { description: manifest.description } : {}),
+            modality: manifest.modality,
+            taskType: manifest.taskType,
+            labels: manifest.labels ?? [],
+            ...(manifest.featureNames ? { columns: manifest.featureNames } : {}),
+            ...(manifest.featureTypes ? { columnTypes: manifest.featureTypes } : {}),
+            stats: manifest.stats,
+            versions: (manifest.versions ?? []).map((v) => ({ version: v.version, rowCount: v.rowCount, frozenAt: v.frozenAt })),
+            reading: version ? `version ${version}` : 'working set',
+            matchingRows: rows.length,
+            offset,
+            returned: page.length,
+            hasMore: offset + page.length < rows.length,
+            rows: page.map((r) => presentRow(datasetId, manifest, r)),
+          };
+        } catch (e) {
+          return { error: e.message };
+        }
+      },
+    }),
+
     model_predict: tool({
       description: MODEL_PREDICT_DESCRIPTION,
       inputSchema: z.object({

package/src/agent-runtime/context.js

@@ -13,6 +13,7 @@
 
 import { listDatasets } from '../utils/dataset-workspace.js';
 import { listModels } from '../utils/model-workspace.js';
+import { describeLocalModel } from './builtin-tools-registry.js';
 
 export async function gatherContext(agentConfig, lastCheckIn, recentActions = []) {
   const parts = [];
@@ -34,13 +35,14 @@ export async function gatherContext(agentConfig, lastCheckIn, recentActions = []
     }
   }
 
-  // Local Lab datasets & models, so the agent knows what it can append to /
-  // predict with (and the exact slugs to pass to dataset_append / model_predict).
+  // Local Lab datasets & models, so the agent knows what it can read / append
+  // to / predict with (and the exact slugs to pass to dataset_read /
+  // dataset_append / model_predict).
   // Local-only, synchronous file reads; tfjs is NOT loaded by listing models.
   try {
     const datasets = listDatasets();
     if (datasets.length > 0) {
-      parts.push('\nLocal datasets you can add to with dataset_append (use the slug as datasetId):');
+      parts.push('\nLocal datasets you can read with dataset_read or add to with dataset_append (use the slug as datasetId):');
       for (const d of datasets.slice(0, 25)) {
         parts.push(`- ${d.slug} — ${d.modality}/${d.taskType}, ${d.stats?.rowCount ?? 0} rows`);
       }
@@ -51,11 +53,8 @@ export async function gatherContext(agentConfig, lastCheckIn, recentActions = []
   try {
     const models = listModels();
     if (models.length > 0) {
-      parts.push('\nLocal models you can run with model_predict (use the slug as modelId):');
-      for (const m of models.slice(0, 25)) {
-        const labels = m.labels?.length ? ` → ${m.labels.join('/')}` : '';
-        parts.push(`- ${m.slug} — ${m.modality}/${m.taskType}${labels}`);
-      }
+      parts.push('\nLocal models you can run with model_predict (the quoted slug is the modelId). Use one whenever its job matches what you are doing:');
+      for (const m of models.slice(0, 25)) parts.push(describeLocalModel(m));
     }
   } catch {
     /* no local models / store unavailable — skip */

package/src/utils/agentic-templates.js

@@ -25,7 +25,7 @@ const TOOL_GROUPS = {
   villages: ['village_search', 'village_view', 'village_create', 'village_update'],
   moments: ['moment_create', 'moment_get', 'pulse_create', 'pulse_list'],
   villagers: ['villager_me', 'villager_search', 'villager_update', 'agent_list'],
-  meetings: ['recall_send_bot', 'recall_meeting_attendance'],
+  meetings: ['recall_send_bot', 'recall_list_sessions', 'recall_meeting_attendance'],
 };
 
 // ─── Agentic App Template (Next.js) ─────────────────────────────────────────
@@ -756,7 +756,7 @@ const TOOL_GROUPS = {
   villages: ['village_search', 'village_view', 'village_create', 'village_update'],
   moments: ['moment_create', 'moment_get', 'pulse_create', 'pulse_list'],
   villagers: ['villager_me', 'villager_search', 'villager_update', 'agent_list'],
-  meetings: ['recall_send_bot', 'recall_meeting_attendance'],
+  meetings: ['recall_send_bot', 'recall_list_sessions', 'recall_meeting_attendance'],
 };
 
 // Tool groups selected during project creation