@positronic/template-new-project 0.0.76 → 0.0.78

package/template/src/brain.ts

@@ -0,0 +1,73 @@
+import { createBrain } from '@positronic/core';
+import { components } from './components/index.js';
+
+/**
+ * Project-level brain function with pre-configured components.
+ *
+ * All brains in your project should import from this file:
+ *
+ * ```typescript
+ * import { brain } from '../brain.js';
+ *
+ * export default brain('my-brain')
+ *   .step('Do something', ({ state }) => ({ ...state, done: true }));
+ * ```
+ *
+ * ## Prompt steps with tool-calling loops
+ *
+ * Use `.prompt()` with a `loop` property to run an LLM with tools:
+ *
+ * ```typescript
+ * import { generatePage, waitForWebhook } from '@positronic/core';
+ *
+ * export default brain('my-brain')
+ *   .prompt('Do Work', ({ state }) => ({
+ *     system: 'You are a helpful assistant',
+ *     message: `Help the user with: <%= '${state.task}' %>`,
+ *     outputSchema: z.object({ result: z.string() }),
+ *     loop: {
+ *       tools: { generatePage, waitForWebhook },
+ *     },
+ *   }));
+ * ```
+ *
+ * Without `loop`, `.prompt()` makes a single LLM call for structured output.
+ * With `loop`, the LLM calls tools iteratively until it calls the auto-generated
+ * 'done' tool with data matching the outputSchema.
+ *
+ * ## Adding plugins
+ *
+ * Plugins provide services, tools, and event adapters to brains.
+ * Configure them in createBrain or per-brain with .withPlugin():
+ *
+ * ```typescript
+ * import { createBrain } from '@positronic/core';
+ * import { components } from './components/index.js';
+ * import { mem0 } from '@positronic/mem0';
+ *
+ * export const brain = createBrain({
+ *   plugins: [mem0.setup({ apiKey: process.env.MEM0_API_KEY! })],
+ *   components,
+ * });
+ * ```
+ *
+ * Then plugin services are available in all brain steps under the plugin name:
+ *
+ * ```typescript
+ * export default brain('my-brain')
+ *   .step('Remember', async ({ mem0 }) => {
+ *     const prefs = await mem0.search('user preferences');
+ *     return { preferences: prefs };
+ *   });
+ * ```
+ *
+ * Or declare multiple plugins upfront:
+ *
+ * ```typescript
+ * brain({ title: 'my-brain', plugins: { slack, mem0 } })
+ *   .step('Go', ({ slack, mem0 }) => { ... });
+ * ```
+ */
+export const brain = createBrain({
+  components,
+});

package/template/src/brains/hello.ts

@@ -0,0 +1,46 @@
+import { brain } from '../brain.js';
+import { z } from 'zod';
+import { generatePage, waitForWebhook } from '@positronic/core';
+
+/**
+ * A simple brain that demonstrates .prompt() with a tool-calling loop.
+ *
+ * This brain:
+ * 1. Uses generatePage to create a form asking for the user's name
+ * 2. Waits for the user to submit the form
+ * 3. Completes with a structured welcome message (via the 'done' tool)
+ * 4. The follow-up step logs the greeting, demonstrating type inference
+ *
+ * The `loop` property on `.prompt()` enables tool-calling: the LLM calls
+ * tools iteratively until it calls the auto-generated 'done' tool with
+ * data matching the outputSchema. The result is spread onto state.
+ *
+ * Run with: px brain run hello
+ */
+export default brain('hello')
+  .prompt('Greet User', () => ({
+    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.
+
+Use the generatePage tool to create a form asking for the user's name.
+Once you have their name, call 'done' with a personalized greeting.
+`,
+    message: 'Begin.',
+    outputSchema: z.object({
+      userName: z.string().describe('The name the user provided'),
+      greeting: z
+        .string()
+        .describe('A personalized welcome message for the user'),
+    }),
+    loop: {
+      tools: { generatePage, waitForWebhook },
+    },
+  }))
+  .step('Log Welcome', ({ state }) => {
+    // TypeScript knows state has userName and greeting (spread from outputSchema)
+    console.log('\n✨ ' + state.greeting);
+    console.log('   Welcome aboard, ' + state.userName + '!\n');
+    return state;
+  });

package/template/{runner.ts → src/runner.ts}

@@ -38,24 +38,21 @@ import { google } from '@ai-sdk/google';
  *
  * ## Memory
  *
- * To add memory (automatic conversation indexing with Mem0):
+ * To add semantic memory via Mem0, use the mem0 plugin in your
+ * src/brain.ts file:
  *
  * ```typescript
- * import { createMem0Provider, createMem0Adapter } from '@positronic/mem0';
+ * import { createBrain } from '@positronic/core';
+ * import { mem0 } 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: {},
+ * export const brain = createBrain({
+ *   plugins: [mem0.setup({ apiKey: process.env.MEM0_API_KEY! })],
  * });
  * ```
  *
+ * Then use `mem0.search()` and `mem0.add()` in brain steps, or pass
+ * `mem0.tools` to a prompt loop for LLM-driven memory.
+ *
  * See docs/memory-guide.md for more details.
  */
 const client = new VercelClient(google('gemini-3-pro-preview'));

package/template/tests/example.test.ts

@@ -1,5 +1,5 @@
 import { createMockClient, runBrainTest } from './test-utils.js';
-import exampleBrain from '../brains/example.js';
+import exampleBrain from '../src/brains/example.js';
 
 describe('example brain', () => {
   it('should complete successfully with welcome messages', async () => {

package/template/tests/test-utils.ts

@@ -48,7 +48,6 @@ export interface BrainTestResult<TState> {
 export async function runBrainTest<
   TOptions extends object = object,
   TState extends object = object,
-  TServices extends object = object
 >(
   brain: any,
   params?: {
@@ -56,7 +55,6 @@ export async function runBrainTest<
     initialState?: Partial<TState>;
     resources?: any;
     options?: TOptions;
-    services?: TServices;
   }
 ): Promise<BrainTestResult<TState>> {
   const events: BrainEvent<any>[] = [];
@@ -72,8 +70,7 @@ export async function runBrainTest<
       options: params?.options,
     };
 
-    // If brain has services, we need to apply them first
-    const brainToRun = params?.services ? brain.withServices(params.services) : brain;
+    const brainToRun = brain;
 
     for await (const event of brainToRun.run(runOptions)) {
       events.push(event);

package/template/tsconfig.json

@@ -9,8 +9,10 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "outDir": "./dist",
-    "rootDir": "./"
+    "rootDir": "./",
+    "jsx": "react-jsx",
+    "jsxImportSource": "@positronic/core"
   },
-  "include": ["brains/**/*.ts", "resources.d.ts"],
+  "include": ["brains/**/*.ts", "brains/**/*.tsx", "resources.d.ts"],
   "exclude": ["node_modules", ".positronic"]
 }

package/template/brain.ts

@@ -1,96 +0,0 @@
-import { createBrain, defaultTools } from '@positronic/core';
-import { components } from './components/index.js';
-
-/**
- * Project-level brain function with pre-configured components and tools.
- *
- * All brains in your project should import from this file:
- *
- * ```typescript
- * import { brain } from '../brain.js';
- *
- * export default brain('my-brain')
- *   .step('Do something', ({ state }) => ({ ...state, done: true }));
- * ```
- *
- * Default tools available in agent steps:
- * - generateUI: Generate interactive UI components
- * - consoleLog: Log messages for debugging
- * - done: Complete the agent and return a result
- *
- * Tool configuration:
- * - `withTools({ ... })` — replaces the default tools entirely
- * - `withExtraTools({ ... })` — adds tools alongside the defaults
- *
- * To add services (e.g., Slack, Gmail, database clients):
- *
- * ```typescript
- * import { createBrain, defaultTools } from '@positronic/core';
- * import { components } from './components/index.js';
- * import slack from './services/slack.js';
- * import gmail from './services/gmail.js';
- *
- * export const brain = createBrain({
- *   services: { slack, gmail },
- *   components,
- *   defaultTools,
- * });
- * ```
- *
- * Then services are available in all brain steps:
- *
- * ```typescript
- * export default brain('notify')
- *   .step('Send alert', ({ slack }) => {
- *     slack.postMessage('#alerts', 'Something happened!');
- *     return { notified: true };
- *   });
- * ```
- *
- * You can also create agents directly with access to default tools:
- *
- * ```typescript
- * export default brain('my-agent', ({ slack, tools }) => ({
- *   system: 'You are a helpful assistant',
- *   prompt: 'Help the user with their request',
- *   tools: {
- *     ...tools, // includes generateUI, consoleLog, done
- *     notify: {
- *       description: 'Send a Slack notification',
- *       inputSchema: z.object({ message: z.string() }),
- *       execute: ({ message }) => slack.postMessage('#general', message),
- *     },
- *   },
- * }));
- * ```
- *
- * 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();
- * ```
- *
- * Memory is automatically scoped to the current user (via currentUser.name)
- * and the brain name. No need to pass userId manually.
- *
- * See docs/memory-guide.md for full details.
- */
-export const brain = createBrain({
-  components,
-  defaultTools,
-});

package/template/brains/hello.ts

@@ -1,44 +0,0 @@
-import { brain } from '../brain.js';
-import { z } from 'zod';
-
-/**
- * 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. 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', {
-  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.
-
-You have access to a few different tools. Use these tools to greet the user and ask them for their name.
-
-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;
-  });