@positronic/template-new-project 0.0.8 → 0.0.9

package/index.js

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

package/package.json

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

package/template/CLAUDE.md

@@ -26,7 +26,7 @@ This is a Positronic project - an AI-powered framework for building and running
 
 ### Testing & Building
 
-- `npm test` - Run tests (uses Jest with @positronic/core/testing utilities)
+- `npm test` - Run tests (uses Jest with local test utilities)
 - `npm run build` - Build the project
 - `npm run dev` - Start development mode with hot reload
 

package/template/brain.ts

@@ -1,4 +1,4 @@
-import { brain as coreBrain, type BrainFunction } from '@positronic/core';
+import { brain as coreBrain, type BrainFactory } from '@positronic/core';
 
 /**
  * Base brain factory for this project.
@@ -11,7 +11,7 @@ import { brain as coreBrain, type BrainFunction } from '@positronic/core';
  * 2. Create service instances
  * 3. Call .withServices() on the brain before returning it
  * 
- * Example:
+ * Example with services:
  * ```typescript
  * interface ProjectServices {
  *   logger: {
@@ -23,7 +23,7 @@ import { brain as coreBrain, type BrainFunction } from '@positronic/core';
  *   };
  * }
  * 
- * export const brain: BrainFunction = (brainConfig) => {
+ * export const brain: BrainFactory = (brainConfig) => {
  *   return coreBrain(brainConfig)
  *     .withServices({
  *       logger: {
@@ -43,16 +43,29 @@ import { brain as coreBrain, type BrainFunction } from '@positronic/core';
  * Then in your brain files (in the brains/ directory):
  * ```typescript
  * import { brain } from '../brain.js';
+ * import { z } from 'zod';
+ * 
+ * const optionsSchema = z.object({
+ *   environment: z.string().default('prod'),
+ *   verbose: z.string().default('false')
+ * });
  * 
  * export default brain('My Brain')
- *   .step('Use Services', async ({ logger, api }) => {
- *     logger.info('Fetching data...');
- *     const data = await api.fetch('/users');
+ *   .withOptionsSchema(optionsSchema)
+ *   .step('Use Services', async ({ state, options, logger, api }) => {
+ *     if (options.verbose === 'true') {
+ *       logger.info('Fetching data...');
+ *     }
+ *     const endpoint = options.environment === 'dev' ? '/users/test' : '/users';
+ *     const data = await api.fetch(endpoint);
  *     return { users: data };
  *   });
  * ```
+ * 
+ * Run with custom options from CLI:
+ * px brain run my-brain -o environment=dev -o verbose=true
  */
-export const brain: BrainFunction = (brainConfig) => {
+export const brain: BrainFactory = (brainConfig) => {
   // For now, just return the core brain without any services.
   // Update this function to add your project-wide services.
   return coreBrain(brainConfig);

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

@@ -8,6 +8,31 @@ The Brain DSL provides a fluent, type-safe API for building stateful AI workflow
 
 **Note**: This project uses a custom brain function. Always import `brain` from `../brain.js`, not from `@positronic/core`. See positronic-guide.md for details.
 
+### Type Safety and Options
+
+The brain function provides full type safety through its fluent API. State types are automatically inferred as you build your brain, and options can be validated at runtime using schemas.
+
+For runtime options validation, use the `withOptionsSchema` method with a Zod schema:
+
+```typescript
+import { z } from 'zod';
+
+const optionsSchema = z.object({
+  environment: z.enum(['dev', 'staging', 'prod']),
+  verbose: z.boolean().default(false)
+});
+
+const myBrain = brain('My Brain')
+  .withOptionsSchema(optionsSchema)
+  .step('Process', ({ options }) => {
+    // options is fully typed based on the schema
+    if (options.verbose) {
+      console.log('Running in', options.environment);
+    }
+    return { status: 'complete' };
+  });
+```
+
 ## Basic Brain Structure
 
 ```typescript
@@ -57,7 +82,7 @@ brain('AI Education Assistant')
   }))
   .prompt('Generate explanation', {
     template: ({ topic, context }) =>
-      <%= "`${context}. Please provide a brief, beginner-friendly explanation of ${topic}.`" %>,
+      `<%= '${context}' %>. Please provide a brief, beginner-friendly explanation of <%= '${topic}' %>.`,
     outputSchema: {
       schema: z.object({
         explanation: z.string().describe('A clear explanation of the topic'),
@@ -72,7 +97,7 @@ brain('AI Education Assistant')
     formattedOutput: {
       topic: state.topic,
       explanation: state.topicExplanation.explanation || '',
-      summary: <%= "`This explanation covers ${state.topicExplanation.keyPoints?.length || 0} key points at a ${state.topicExplanation.difficulty || 'unknown'} level.`" %>,
+      summary: `This explanation covers <%= '${state.topicExplanation.keyPoints?.length || 0}' %> key points at a <%= '${state.topicExplanation.difficulty || \'unknown\'}' %> level.`,
       points: state.topicExplanation.keyPoints || [],
     },
   }))
@@ -80,7 +105,9 @@ brain('AI Education Assistant')
     'Generate follow-up questions',
     {
       template: ({ formattedOutput }) =>
-        <%= "`Based on this explanation about ${formattedOutput.topic}: \"${formattedOutput.explanation}\"\n        \n        Generate 3 thoughtful follow-up questions that a student might ask.`" %>,
+        `Based on this explanation about <%= '${formattedOutput.topic}' %>: "<%= '${formattedOutput.explanation}' %>"
+        
+        Generate 3 thoughtful follow-up questions that a student might ask.`,
       outputSchema: {
         schema: z.object({
           questions: z.array(z.string()).length(3).describe('Three follow-up questions'),
@@ -142,19 +169,144 @@ Each step receives these parameters:
 
 ## Configuration Methods
 
-### Default Options
+### Brain Options
+
+Options provide runtime configuration for your brains, allowing different behavior without changing code. They're perfect for settings like API endpoints, feature flags, output preferences, or channel identifiers.
 
-Set default options for all brain runs:
+#### Typing Options
+
+To use options in your brain, define a Zod schema with `withOptionsSchema`:
 
 ```typescript
-const configuredBrain = brain('My Brain')
-  .withOptions({ debug: true, temperature: 0.7 })
-  .step('Process', ({ state, options }) => {
-    if (options.debug) console.log('Processing...');
+import { z } from 'zod';
+
+// Define your options schema
+const notificationSchema = z.object({
+  slackChannel: z.string(),
+  priority: z.enum(['low', 'normal', 'high']),
+  includeTimestamp: z.boolean().default(true)
+});
+
+// Use withOptionsSchema to add runtime validation
+const notificationBrain = brain('Notification Brain')
+  .withOptionsSchema(notificationSchema)
+  .step('Send Alert', async ({ state, options, slack }) => {
+    // TypeScript knows the exact shape of options from the schema
+    const message = options.includeTimestamp 
+      ? `[<%= '${new Date().toISOString()}' %>] <%= '${state.alert}' %>`
+      : state.alert;
+    
+    await slack.post(options.slackChannel, {
+      text: message,
+      priority: options.priority  // Type-safe: must be 'low' | 'normal' | 'high'
+    });
+    
     return state;
   });
 ```
 
+The schema approach provides:
+- Runtime validation of options
+- Automatic TypeScript type inference
+- Clear error messages for invalid options
+- Support for default values in the schema
+
+#### Passing Options from Command Line
+
+Override default options when running brains from the CLI using the `-o` or `--options` flag:
+
+```bash
+# Single option
+px brain run my-brain -o debug=true
+
+# Multiple options
+px brain run my-brain -o slackChannel=#alerts -o temperature=0.9 -o verbose=true
+
+# Options with spaces or special characters (use quotes)
+px brain run my-brain -o "webhook=https://example.com/api?key=value"
+```
+
+Options are passed as simple key=value pairs and are available as strings in your brain.
+
+#### Options vs Services vs Initial State
+
+Understanding when to use each:
+
+- **Options**: Runtime configuration (channels, endpoints, feature flags)
+  - Override from CLI with `-o key=value`
+  - Don't change during execution
+  - Examples: `slackChannel`, `apiEndpoint`, `debugMode`
+
+- **Services**: External dependencies and side effects (clients, loggers, databases)
+  - Configure once with `.withServices()`
+  - Available in all steps
+  - Not serializable
+  - Examples: `slackClient`, `database`, `logger`
+
+- **Initial State**: Starting data for a specific run
+  - Pass to `brain.run()` or set via CLI/API
+  - Changes throughout execution
+  - Must be serializable
+  - Examples: `userId`, `orderData`, `inputText`
+
+#### Real-World Example
+
+```typescript
+// Define a brain that uses options for configuration
+const notificationSchema = z.object({
+  channel: z.string(),
+  priority: z.string().default('normal'),
+  includeDetails: z.string().default('false')
+});
+
+const notificationBrain = brain('Smart Notifier')
+  .withOptionsSchema(notificationSchema)
+  .withServices({ 
+    slack: slackClient,
+    email: emailClient 
+  })
+  .step('Process Alert', ({ state, options }) => ({
+    ...state,
+    formattedMessage: options.includeDetails === 'true'
+      ? `Alert: <%= '${state.message}' %> - Details: <%= '${state.details}' %>`
+      : `Alert: <%= '${state.message}' %>`,
+    isPriority: options.priority === 'high'
+  }))
+  .step('Send Notification', async ({ state, options, slack, email }) => {
+    // Use options to control behavior
+    if (state.isPriority) {
+      // High priority goes to email too
+      await email.send('admin@example.com', state.formattedMessage);
+    }
+    
+    // Always send to Slack channel from options
+    await slack.post(options.channel, state.formattedMessage);
+    
+    return { ...state, notified: true };
+  });
+
+// Run with custom options from CLI:
+// px brain run smart-notifier -o channel=#urgent -o priority=high -o includeDetails=true
+```
+
+#### Testing with Options
+
+```typescript
+// In your tests
+const result = await runBrainTest(notificationBrain, {
+  client: mockClient,
+  initialState: { message: 'System down', details: 'Database unreachable' },
+  options: { 
+    channel: '#test-channel',
+    priority: 'high',
+    includeDetails: true
+  }
+});
+
+expect(mockSlack.post).toHaveBeenCalledWith('#test-channel', expect.any(String));
+expect(mockEmail.send).toHaveBeenCalled(); // High priority triggers email
+```
+
 ### Service Injection
 
 The `withServices` method provides dependency injection for your brains, making external services available throughout the workflow while maintaining testability.
@@ -249,7 +401,7 @@ const analysisBrain = brain('Data Analysis')
     return { ...state, data };
   })
   .prompt('Analyze Data', {
-    template: ({ data }) => <%= "`Analyze this data: ${JSON.stringify(data)}`" %>,
+    template: ({ data }) => `Analyze this data: <%= '${JSON.stringify(data)}' %>`,
     outputSchema: {
       schema: z.object({
         insights: z.array(z.string()),
@@ -283,7 +435,7 @@ Services make testing easier by allowing you to inject mocks:
 
 ```typescript
 // In your test file
-import { createMockClient, runBrainTest } from '@positronic/core/testing';
+import { createMockClient, runBrainTest } from '../tests/test-utils.js';
 
 const mockLogger = {
   info: jest.fn(),
@@ -377,7 +529,7 @@ const typedBrain = brain('Typed Example')
     name: 'Test', // TypeScript knows state has 'count'
   }))
   .step('Use Both', ({ state }) => ({
-    message: <%= "`${state.name}: ${state.count}`" %>, // Both properties available
+    message: `<%= '${state.name}' %>: <%= '${state.count}' %>`, // Both properties available
   }));
 ```
 
@@ -482,7 +634,7 @@ export const aiFilterPrompt = {
 
     // Build the prompt with state data
     const articleList = state.articles
-      .map((a, i) => <%= "`${i + 1}. ${a.title} (score: ${a.score})`" %>)
+      .map((a, i) => `<%= '${i + 1}' %>. <%= '${a.title}' %> (score: <%= '${a.score}' %>)`)
       .join('\n');
 
     return template
@@ -546,7 +698,6 @@ const completeBrain = brain({
   title: 'Complete Example',
   description: 'Demonstrates all Brain DSL features',
 })
-  .withOptions({ temperature: 0.7 })
   .withServices<Services>({
     logger: console,
     analytics: {
@@ -574,11 +725,11 @@ const completeBrain = brain({
   },
   // Services available in reduce function too
   ({ state, response, logger }) => {
-    logger.log(<%= "`Plan generated with ${response.tasks.length} tasks`" %>);
+    logger.log(`Plan generated with <%= '${response.tasks.length}' %> tasks`);
     return { ...state, plan: response };
   })
   .step('Process Plan', ({ state, logger, analytics }) => {
-    logger.log(<%= "`Processing ${state.plan.tasks.length} tasks`" %>);
+    logger.log(`Processing <%= '${state.plan.tasks.length}' %> tasks`);
     analytics.track('plan_processed', {
       task_count: state.plan.tasks.length,
       duration: state.plan.duration

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

@@ -1,6 +1,14 @@
 # Brain Testing Guide
 
-This guide explains how to test Positronic brains using the testing utilities provided by `@positronic/core`.
+This guide explains how to test Positronic brains using the testing utilities in the `tests/test-utils.ts` file.
+
+## Test Organization
+
+All test files should be placed in the `tests/` directory at the root of your project. This keeps tests separate from your brain implementations and prevents them from being deployed with your application.
+
+Test files should follow the naming convention `<brain-name>.test.ts`. For example:
+- Brain file: `brains/customer-support.ts`
+- Test file: `tests/customer-support.test.ts`
 
 ## Testing Philosophy
 
@@ -16,8 +24,8 @@ Testing brains is about verifying they produce the correct outputs given specifi
 ## Quick Start
 
 ```typescript
-import { createMockClient, runBrainTest } from '@positronic/core';
-import yourBrain from './your-brain.js';
+import { createMockClient, runBrainTest } from '../tests/test-utils.js';
+import yourBrain from '../brains/your-brain.js';
 
 describe('your-brain', () => {
   it('should process user data and generate a report', async () => {

package/template/docs/positronic-guide.md

@@ -60,13 +60,10 @@ interface ProjectServices {
 }
 
 // Export the wrapped brain function
-export function brain<
-  TOptions extends object = object,
-  TState extends object = object
->(
+export function brain(
   brainConfig: string | { title: string; description?: string }
-): Brain<TOptions, TState, ProjectServices> {
-  return coreBrain<TOptions, TState, ProjectServices>(brainConfig)
+) {
+  return coreBrain(brainConfig)
     .withServices({
       logger: {
         info: (msg) => console.log(`[<%= '${new Date().toISOString()}' %>] INFO: <%= '${msg}' %>`),
@@ -127,7 +124,17 @@ See `/docs/brain-testing-guide.md` for detailed testing guidance.
 
 1. **Start the development server**: `px server -d`
 2. **Create or modify brains**: Always import from `./brain.js`
-3. **Test locally**: `px brain run <brain-name>`
+3. **Test locally**: 
+   ```bash
+   # Basic run
+   px brain run <brain-name>
+   
+   # Run with options
+   px brain run <brain-name> -o channel=#dev -o debug=true
+   
+   # Watch execution in real-time
+   px brain run <brain-name> --watch
+   ```
 4. **Run tests**: `npm test`
 5. **Deploy**: Backend-specific commands (e.g., `px deploy` for Cloudflare)
 

package/template/docs/tips-for-agents.md

@@ -202,10 +202,7 @@ import slack from './services/slack.js';
 import database from './services/database.js';
 import analytics from './services/analytics.js';
 
-export function brain<
-  TOptions extends object = object,
-  TState extends object = object
->(
+export function brain(
   brainConfig: string | { title: string; description?: string }
 ) {
   return coreBrain(brainConfig)
@@ -220,6 +217,45 @@ export function brain<
 
 This keeps your service implementations separate from your brain logic and makes them easier to test and maintain.
 
+## Brain Options Usage
+
+When creating brains that need runtime configuration, use the options schema pattern:
+
+```typescript
+import { z } from 'zod';
+
+// Good example - configurable brain with validated options
+const alertSchema = z.object({
+  slackChannel: z.string(),
+  emailEnabled: z.string().default('false'),
+  alertThreshold: z.string().default('10')
+});
+
+const alertBrain = brain('Alert System')
+  .withOptionsSchema(alertSchema)
+  .step('Check Threshold', ({ state, options }) => ({
+    ...state,
+    shouldAlert: state.errorCount > parseInt(options.alertThreshold)
+  }))
+  .step('Send Alerts', async ({ state, options, slack }) => {
+    if (!state.shouldAlert) return state;
+    
+    await slack.post(options.slackChannel, state.message);
+    
+    if (options.emailEnabled === 'true') {
+      // Note: CLI options come as strings
+      await email.send('admin@example.com', state.message);
+    }
+    
+    return { ...state, alerted: true };
+  });
+```
+
+Remember:
+- Options from CLI are always strings (even numbers and booleans)
+- Options are for configuration, not data
+- Document available options in comments above the brain
+
 ## Important: ESM Module Imports
 
 This project uses ES modules (ESM). **Always include the `.js` extension in your imports**, even when importing TypeScript files:
@@ -255,8 +291,8 @@ Start by following the brain testing guide (`/docs/brain-testing-guide.md`) and
 ```typescript
 // tests/my-new-brain.test.ts
 import { describe, it, expect } from '@jest/globals';
-import { createMockClient, runBrainTest } from '@positronic/core/testing';
-import myNewBrain from '../brains/my-new-brain';
+import { createMockClient, runBrainTest } from './test-utils.js';
+import myNewBrain from '../brains/my-new-brain.js';
 
 describe('MyNewBrain', () => {
   it('should process data and return expected result', async () => {
@@ -381,7 +417,7 @@ export default feedbackBrain;
 // Step 4: Add sentiment analysis step
   .prompt('Analyze sentiment', {
     template: ({ feedback }) =>
-      <%= "`Analyze the sentiment of this feedback: \"${feedback}\"`" %>,
+      <%= '\`Analyze the sentiment of this feedback: "${feedback}"\`' %>,
     outputSchema: {
       schema: z.object({
         sentiment: z.enum(['positive', 'neutral', 'negative']),
@@ -395,7 +431,7 @@ export default feedbackBrain;
 // Step 6: Add response generation
   .prompt('Generate response', {
     template: ({ sentimentAnalysis, feedback }) =>
-      <%= "`Generate a brief response to this ${sentimentAnalysis.sentiment} feedback: \"${feedback}\"`" %>,
+      <%= '\`Generate a brief response to this ${sentimentAnalysis.sentiment} feedback: "${feedback}"\`' %>,
     outputSchema: {
       schema: z.object({
         response: z.string()

package/template/tests/example.test.ts

@@ -1,4 +1,4 @@
-import { createMockClient, runBrainTest } from '@positronic/core/testing';
+import { createMockClient, runBrainTest } from './test-utils.js';
 import exampleBrain from '../brains/example.js';
 
 describe('example brain', () => {

package/template/tests/test-utils.ts

@@ -0,0 +1,81 @@
+import type { ObjectGenerator } from '@positronic/core';
+import type { BrainEvent } from '@positronic/core';
+import { BRAIN_EVENTS, applyPatches } from '@positronic/core';
+
+export interface MockClient extends ObjectGenerator {
+  mockResponses: (...responses: any[]) => void;
+  clearMocks: () => void;
+}
+
+export function createMockClient(): MockClient {
+  const responses: any[] = [];
+  let responseIndex = 0;
+
+  const generateObject = jest.fn(async () => {
+    if (responseIndex >= responses.length) {
+      throw new Error('No more mock responses available');
+    }
+    return responses[responseIndex++];
+  });
+
+  return {
+    generateObject,
+    mockResponses: (...newResponses: any[]) => {
+      responses.push(...newResponses);
+    },
+    clearMocks: () => {
+      responses.length = 0;
+      responseIndex = 0;
+      generateObject.mockClear();
+    },
+  };
+}
+
+export interface BrainTestResult<TState> {
+  completed: boolean;
+  error: Error | null;
+  finalState: TState;
+  events: BrainEvent<any>[];
+}
+
+export async function runBrainTest<TOptions extends object, TState extends object>(
+  brain: any,
+  options?: {
+    client?: ObjectGenerator;
+    initialState?: Partial<TState>;
+    resources?: any;
+  }
+): Promise<BrainTestResult<TState>> {
+  const events: BrainEvent<any>[] = [];
+  let finalState: any = options?.initialState || {};
+  let error: Error | null = null;
+  let completed = false;
+
+  try {
+    const runOptions = {
+      ...options,
+      state: options?.initialState,
+    };
+
+    for await (const event of brain.run(runOptions)) {
+      events.push(event);
+
+      if (event.type === BRAIN_EVENTS.STEP_COMPLETE) {
+        finalState = applyPatches(finalState, [event.patch]);
+      } else if (event.type === BRAIN_EVENTS.ERROR) {
+        error = new Error(event.error.message);
+      } else if (event.type === BRAIN_EVENTS.COMPLETE) {
+        completed = true;
+      }
+    }
+  } catch (err) {
+    error = err instanceof Error ? err : new Error(String(err));
+  }
+
+  return {
+    completed,
+    error,
+    finalState,
+    events,
+  };
+}