@positronic/template-new-project 0.0.56 → 0.0.58

package/index.js

@@ -53,10 +53,10 @@ module.exports = {
   ],
   setup: async ctx => {
     const devRootPath = process.env.POSITRONIC_LOCAL_PATH;
-    let coreVersion = '^0.0.56';
-    let cloudflareVersion = '^0.0.56';
-    let clientVercelVersion = '^0.0.56';
-    let genUIComponentsVersion = '^0.0.56';
+    let coreVersion = '^0.0.58';
+    let cloudflareVersion = '^0.0.58';
+    let clientVercelVersion = '^0.0.58';
+    let genUIComponentsVersion = '^0.0.58';
 
     // Map backend selection to package names
     const backendPackageMap = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/template-new-project",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "publishConfig": {
     "access": "public"
   },

package/template/brain.ts

@@ -59,6 +59,29 @@ import { components } from './components/index.js';
  *   },
  * }));
  * ```
+ *
+ * To add memory (long-term storage with semantic search):
+ *
+ * ```typescript
+ * import { createBrain, defaultTools } from '@positronic/core';
+ * import { createMem0Provider, createMem0Tools } from '@positronic/mem0';
+ * import { components } from './components/index.js';
+ *
+ * const memory = createMem0Provider({
+ *   apiKey: process.env.MEM0_API_KEY!,
+ * });
+ *
+ * export const brain = createBrain({
+ *   components,
+ *   defaultTools,
+ *   memory, // All brains now have access to memory
+ * });
+ *
+ * // Memory tools (rememberFact, recallMemories) can be added to agents:
+ * const memoryTools = createMem0Tools();
+ * ```
+ *
+ * See docs/memory-guide.md for more details on memory configuration.
  */
 export const brain = createBrain({
   components,

package/template/brains/hello.ts

@@ -1,33 +1,44 @@
 import { brain } from '../brain.js';
+import { z } from 'zod';
 
 /**
- * A simple agent brain that demonstrates the default tools.
+ * A simple agent brain that demonstrates the default tools and outputSchema.
  *
  * This brain uses only a system prompt and tools - no explicit user prompt needed.
  * When prompt is omitted, the agent automatically starts with "Begin."
  *
+ * The outputSchema ensures the agent returns structured data that gets stored
+ * in state.welcome - making it available for subsequent steps.
+ *
  * This brain:
  * 1. Uses generateUI to create a form asking for the user's name
  * 2. Waits for the user to submit the form
- * 3. Uses consoleLog to log a personalized greeting
- * 4. Uses done to complete with a welcome message
+ * 3. Completes with a structured welcome message (via outputSchema)
+ * 4. The follow-up step logs the greeting, demonstrating type inference
  *
  * Run with: px brain run hello
  */
-export default brain('hello', ({ tools }) => ({
-  system: `You are a friendly greeter for the Positronic framework.
-Your job is to welcome new users and make them feel excited about building AI workflows.
+export default brain('hello', {
+  system: `
+You are a friendly greeter for the Positronic framework.
 
-When you start:
-1. Use generateUI to create a simple, welcoming form that asks for the user's name
-   (use a friendly title and a single text input)
-2. After receiving their name, use consoleLog to log a warm, personalized greeting
-3. Use done to complete with an encouraging message about what they can build
+Your job is to welcome new users and make them feel excited about building AI workflows.
 
-You have access to these tools:
-- generateUI: Create a form to collect the user's name
-- consoleLog: Log messages to the console
-- done: Complete the greeting with a final message`,
+You have access to a few different tools. Use these tools to greet the user and ask them for their name.
 
-  tools,
-}));
+Once you have the user's name send them a personalized greeting!
+`,
+  outputSchema: {
+    schema: z.object({
+      userName: z.string().describe('The name the user provided'),
+      greeting: z.string().describe('A personalized welcome message for the user'),
+    }),
+    name: 'welcome' as const,
+  },
+})
+  .step('Log Welcome', ({ state }) => {
+    // TypeScript knows state.welcome has userName and greeting
+    console.log('\n✨ ' + state.welcome.greeting);
+    console.log('   Welcome aboard, ' + state.welcome.userName + '!\n');
+    return state;
+  });

package/template/docs/brain-dsl-guide.md

@@ -908,7 +908,9 @@ brain('Research Assistant')
 - `system: string` - System prompt for the agent
 - `prompt: string | ((state) => string)` - User prompt (can be a function)
 - `tools: Record<string, ToolDefinition>` - Tools available to the agent
+- `outputSchema: { schema, name }` - Structured output schema (see below)
 - `maxTokens: number` - Maximum tokens for the agent response
+- `maxIterations: number` - Maximum agent loop iterations (default: 100)
 
 ### Tool Definition
 
@@ -917,6 +919,42 @@ Each tool requires:
 - `inputSchema: ZodSchema` - Zod schema for the tool's input
 - `execute: (input) => Promise<any>` - Function to execute when the tool is called
 
+### Agent Output Schema
+
+Use `outputSchema` to get structured, typed output from agent steps. This generates a terminal tool that the agent must call to complete, ensuring the output matches your schema:
+
+```typescript
+brain('Entity Extractor')
+  .brain('Extract Entities', {
+    system: 'You are an entity extraction assistant.',
+    prompt: 'Extract all people and organizations from the provided text.',
+    outputSchema: {
+      schema: z.object({
+        people: z.array(z.string()).describe('Names of people mentioned'),
+        organizations: z.array(z.string()).describe('Organization names'),
+        confidence: z.number().min(0).max(1).describe('Confidence score'),
+      }),
+      name: 'entities' as const,  // Use 'as const' for type inference
+    },
+  })
+  .step('Use Extracted Data', ({ state }) => {
+    // TypeScript knows state.entities has people, organizations, and confidence
+    console.log('Found ' + state.entities.people.length + ' people');
+    console.log('Found ' + state.entities.organizations.length + ' organizations');
+    return {
+      ...state,
+      summary: 'Extracted ' + state.entities.people.length + ' people and ' +
+               state.entities.organizations.length + ' organizations',
+    };
+  });
+```
+
+Key points about `outputSchema`:
+- The agent automatically gets a `done` tool that uses your schema
+- The result is stored under `state[name]` (e.g., `state.entities`)
+- Full TypeScript type inference flows to subsequent steps
+- Use `as const` on the name for proper type narrowing
+
 ## Environment and Pages Service
 
 ### The `env` Parameter

package/template/package.json

@@ -7,7 +7,7 @@
   "scripts": {
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "typecheck": "tsc --noEmit",
-    "build:components": "node esbuild.config.mjs"
+    "build:components": "node .positronic/esbuild.config.mjs"
   },
   "keywords": [],
   "author": "",

package/template/runner.ts

@@ -2,6 +2,30 @@ import { BrainRunner } from '@positronic/core';
 import { VercelClient } from '@positronic/client-vercel';
 import { google } from '@ai-sdk/google';
 
+/**
+ * The BrainRunner executes brains with the configured client and adapters.
+ *
+ * To add memory (automatic conversation indexing with Mem0):
+ *
+ * ```typescript
+ * import { createMem0Provider, createMem0Adapter } from '@positronic/mem0';
+ *
+ * const provider = createMem0Provider({
+ *   apiKey: process.env.MEM0_API_KEY!,
+ * });
+ *
+ * const memoryAdapter = createMem0Adapter({ provider });
+ *
+ * export const runner = new BrainRunner({
+ *   adapters: [memoryAdapter],
+ *   client: new VercelClient(google('gemini-3-pro-preview')),
+ *   resources: {},
+ * });
+ * ```
+ *
+ * The adapter automatically indexes all agent conversations to memory.
+ * See docs/memory-guide.md for more details.
+ */
 export const runner = new BrainRunner({
   adapters: [],
   client: new VercelClient(google('gemini-3-pro-preview')),