@positronic/template-new-project 0.0.75 → 0.0.76

package/index.js

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

package/package.json

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

package/template/CLAUDE.md

@@ -12,6 +12,7 @@ This is a Positronic project - an AI-powered framework for building and running
 - **`/webhooks`** - Webhook definitions for external integrations (auto-discovered)
 - **`/resources`** - Files and documents that brains can access via the resource system
 - **`/tests`** - Test files for brains (kept separate to avoid deployment issues)
+- **`/utils`** - Shared utilities (e.g., `bottleneck` for rate limiting)
 - **`/docs`** - Documentation including brain testing guide
 - **`/runner.ts`** - The main entry point for running brains locally
 - **`/positronic.config.json`** - Project configuration

package/template/brain.ts

@@ -18,6 +18,10 @@ import { components } from './components/index.js';
  * - 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

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

@@ -773,6 +773,39 @@ export const brain = createBrain({
 
 All brains created with this factory will have access to the configured services, tools, components, and store.
 
+#### Typing Initial State and Options
+
+By default, the first `.step()` establishes the state type and inference flows from there. But when a brain receives its initial state from outside — via `initialState` in `.run()`, from the CLI, or from a parent brain — the first step's `state` parameter is untyped.
+
+You can provide type parameters to `brain()` to type the initial state and options:
+
+```typescript
+// brain<TOptions, TState>(title)
+// Both parameters are optional and default to {} and object respectively.
+
+// Type just the initial state (pass {} for options)
+const myBrain = brain<{}, { userId: string; email: string }>('process-user')
+  .step('Greet', ({ state }) => {
+    // state.userId and state.email are correctly typed
+    return { ...state, greeting: 'Hello ' + state.email };
+  });
+
+// Type both options and initial state
+const myBrain = brain<{ verbose: boolean }, { count: number }>('counter')
+  .step('Process', ({ state, options }) => {
+    if (options.verbose) console.log('Count:', state.count);
+    return { ...state, doubled: state.count * 2 };
+  });
+```
+
+This is useful in several situations:
+
+- **Brains run with `initialState`**: When calling `.run({ initialState: { ... } })` or passing initial state from the CLI
+- **Sub-brains**: When a parent brain provides initial state via `.brain()` or iterate's `initialState` option
+- **Any brain where the first step receives rather than creates state**
+
+Existing `brain('title')` calls without type parameters continue to work unchanged.
+
 ## Running Brains
 
 ### Basic Execution
@@ -1042,12 +1075,16 @@ Extract prompts to separate files when:
 - The prompt might be reused in other brains
 - You want to test the prompt logic separately
 
-## Batch Prompt Mode
+## Iterating Over Items
 
-When you need to run the same prompt over multiple items, use batch mode with the `over` option:
+When you need to run the same prompt, brain, or agent over multiple items, use the `over` option.
+
+### Prompt Iterate
+
+Run the same prompt once per item in a list:
 
 ```typescript
-brain('Batch Processor')
+brain('Item Processor')
   .step('Initialize', () => ({
     items: [
       { id: 1, title: 'First item' },
@@ -1062,31 +1099,132 @@ brain('Batch Processor')
       name: 'summaries' as const
     }
   }, {
-    over: (state) => state.items,  // Array to iterate over
-    concurrency: 10,               // Parallel requests (default: 10)
-    error: (item, error) => ({ summary: 'Failed to summarize' })  // Fallback on error
+    over: ({ state }) => state.items,
+    error: (item, error) => ({ summary: 'Failed to summarize' })
   })
   .step('Process Results', ({ state }) => ({
     ...state,
-    // summaries is [item, response][] - array of tuples
-    processedSummaries: state.summaries.map(([item, response]) => ({
+    // summaries is an IterateResult — use .values, .items, .entries, .filter(), .map()
+    processedSummaries: state.summaries.map((item, response) => ({
       id: item.id,
       summary: response.summary
     }))
   }));
 ```
 
-### Batch Options
+Prompt iterate also supports per-step `client` overrides (see Prompt Steps above), so you can use a different model for processing.
 
-- `over: (state) => T[]` - Function returning the array to iterate over
-- `concurrency: number` - Maximum number of items processed in parallel (default: 10)
-- `error: (item, error) => Response` - Fallback function when a request fails
+### Brain Iterate
 
-Batch prompts also support per-step `client` overrides (see Prompt Steps above), so you can use a different model for batch processing.
+Run a nested brain once per item:
+
+```typescript
+const processBrain = brain('Process Item')
+  .step('Transform', ({ state }) => ({
+    ...state,
+    result: state.value * 2,
+  }));
+
+brain('Process All Items')
+  .step('Initialize', () => ({
+    items: [{ value: 1 }, { value: 2 }, { value: 3 }]
+  }))
+  .brain('Process Each', processBrain, {
+    over: ({ state }) => state.items,
+    initialState: (item) => ({ value: item.value }),
+    outputKey: 'results' as const,
+    error: (item, error) => ({ value: item.value, failed: true }),
+  })
+  .step('Use Results', ({ state }) => ({
+    ...state,
+    // results is an IterateResult — use .values to get just the results
+    totals: state.results.values.map(result => result.result),
+  }));
+```
+
+### Agent Iterate
+
+Run an agent config once per item. The `configFn` receives the item as its first argument:
+
+```typescript
+brain('Research Topics')
+  .step('Initialize', () => ({
+    topics: [{ name: 'AI' }, { name: 'Robotics' }]
+  }))
+  .brain('Research Each', (item, { state, tools }) => ({
+    system: 'You are a research assistant.',
+    prompt: `Research this topic: <%= '${item.name}' %>`,
+    tools: {
+      search: tools.search,
+    },
+    outputSchema: {
+      schema: z.object({ summary: z.string() }),
+      name: 'research' as const,
+    },
+  }), {
+    over: ({ state }) => state.topics,
+    outputKey: 'results' as const,
+  })
+  .step('Use Results', ({ state }) => ({
+    ...state,
+    // results is an IterateResult — use .values to get just the results
+    summaries: state.results.values.map(result => result.summary),
+  }));
+```
+
+### Iterate Options
+
+All iterate variants share these options:
+
+- `over: (context) => T[] | Promise<T[]>` - Function returning the array to iterate over. Receives the full step context (`{ state, options, client, resources, services, ... }`) — the same context object that step actions receive. Most commonly you'll destructure just `{ state }`, but you can access options, services, or any other context field. Can be async.
+- `error: (item, error) => Result | null` - Fallback when an item fails. Return `null` to skip the item entirely.
+
+Brain and agent iterate also require:
+
+- `outputKey: string` - Key under which results are stored in state (use `as const` for type inference)
+
+Brain iterate additionally requires:
+
+- `initialState: (item, outerState) => State` - Function to create the inner brain's initial state from each item
+
+#### Accessing options and services in `over`
+
+Since `over` receives the full step context, you can use options or services to determine which items to iterate over:
+
+```typescript
+brain('Dynamic Processor')
+  .withOptionsSchema(z.object({ category: z.string() }))
+  .step('Load items', () => ({
+    items: [
+      { id: 1, category: 'a' },
+      { id: 2, category: 'b' },
+      { id: 3, category: 'a' },
+    ]
+  }))
+  .prompt('Process', {
+    template: (item) => `Process item <%= '${item.id}' %>`,
+    outputSchema: {
+      schema: z.object({ result: z.string() }),
+      name: 'results' as const,
+    },
+  }, {
+    over: ({ state, options }) => state.items.filter(i => i.category === options.category),
+  })
+```
 
 ### Result Format
 
-The result is stored as an array of `[item, response]` tuples, preserving the relationship between each input item and its generated response.
+By default, results are stored as an `IterateResult` — a collection that wraps `[item, result]` pairs and provides a richer API than raw tuples:
+
+- **`.items`** — array of all input items
+- **`.values`** — array of all results
+- **`.entries`** — array of `[item, result]` tuples
+- **`.length`** — number of results
+- **`.filter((item, result) => boolean)`** — returns a new `IterateResult` with only matching pairs
+- **`.map((item, result) => value)`** — maps over both item and result, returns a plain array
+- **`for...of`** — iterates as `[item, result]` tuples (backward compatible with destructuring)
+
+For prompts, the key comes from `outputSchema.name`. For brain and agent iterate, it comes from `outputKey`.
 
 ## Agent Steps
 

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

@@ -6,6 +6,40 @@ This document contains helpful tips and patterns for AI agents working with Posi
 
 Run `npm run typecheck` frequently as you make changes to ensure your TypeScript code compiles correctly. This will catch type errors early and help maintain code quality.
 
+## Prefer Type Inference
+
+Never add explicit type annotations unless `npm run typecheck` tells you to. TypeScript's inference is very strong — especially within the Brain DSL chain — and explicit types add noise without value.
+
+Start by writing code with no annotations. If `typecheck` fails, add the minimum annotation or cast needed to fix it.
+
+```typescript
+// ❌ DON'T DO THIS - explicit types on callback parameters
+.filter(([_, result]: [any, any]) => result !== null)
+.map((pr: any) => pr.author)
+.map((n: string) => n.trim())
+error: (thread: any, error: any) => { ... }
+
+// ✅ DO THIS - let inference work
+.filter(([_, result]) => result !== null)
+.map(pr => pr.author)
+.map(n => n.trim())
+error: (thread, error) => { ... }
+```
+
+This also applies to variable declarations and function parameters:
+
+```typescript
+// ❌ DON'T DO THIS
+const names: string[] = options.notify.split(',');
+template: (state: any) => { ... }
+
+// ✅ DO THIS
+const names = options.notify.split(',');
+template: (state) => { ... }
+```
+
+If you genuinely need a cast to fix a type error, prefer the narrowest cast possible and add it only after seeing the error.
+
 ## Running the Development Server
 
 When you need to run a development server, use the `--log-file` option to capture server output. **Important**: Always place the server log file in the `/tmp` directory so it gets cleaned up automatically by the operating system.
@@ -125,6 +159,145 @@ Key rules:
 - Optional title as second argument: `.guard(predicate, 'Check condition')`
 - See `/docs/brain-dsl-guide.md` for more details
 
+**Guards vs exceptions**: Use guards for conditions that are an expected part of the brain's flow — like "no audio URL was found" after a discovery step. Guards are documented in the DSL and show up when viewing the brain's steps. Reserve `throw` for truly unexpected errors. If a missing value is a normal possible outcome of a previous step, handle it with a guard, not an exception.
+
+```typescript
+// ❌ DON'T DO THIS - throwing for an expected outcome
+.step('Transcribe', async ({ state }) => {
+    if (!state.discovery.audioUrl) {
+      throw new Error('No audio URL found');
+    }
+    const transcript = await whisper.transcribe(state.discovery.audioUrl);
+    return { ...state, transcript };
+  })
+
+// ✅ DO THIS - guard for expected flow, keep the step focused
+.guard(({ state: { discovery } }) => !!discovery.audioUrl, 'Has audio URL')
+.step('Transcribe', async ({ state: { discovery } }) => {
+    const transcript = await whisper.transcribe(discovery.audioUrl!);
+    return { ...state, transcript };
+  })
+```
+
+## Destructure State in Steps
+
+Always destructure properties off of `state` rather than accessing them through `state.property`. This applies to steps, prompt templates, brain callbacks, and guards — anywhere state is accessed.
+
+```typescript
+// ❌ DON'T DO THIS - accessing properties through state
+.brain('Find data', ({ state }) => ({
+    prompt: `Process <%= '${state.user.name}' %> from <%= '${state.user.email}' %>`,
+  }))
+
+// ✅ DO THIS - destructure in the parameter when state itself isn't needed
+.brain('Find data', ({ state: { user } }) => ({
+    prompt: `Process <%= '${user.name}' %> from <%= '${user.email}' %>`,
+  }))
+```
+
+The same applies to prompt templates:
+
+```typescript
+// ❌ DON'T DO THIS
+template: (state) => `Hello <%= '${state.user.name}' %>, your order <%= '${state.order.id}' %> is ready.`,
+
+// ✅ DO THIS
+template: ({ user, order }) => `Hello <%= '${user.name}' %>, your order <%= '${order.id}' %> is ready.`,
+```
+
+When you still need `state` (e.g. for `...state` in the return value), destructure in the function body instead:
+
+```typescript
+// ❌ DON'T DO THIS
+.step('Format', ({ state }) => ({
+    ...state,
+    summary: `<%= '${state.title}' %> by <%= '${state.author}' %>`,
+  }))
+
+// ✅ DO THIS - destructure in the body when you also need ...state
+.step('Format', ({ state }) => {
+    const { title, author } = state;
+    return {
+      ...state,
+      summary: `<%= '${title}' %> by <%= '${author}' %>`,
+    };
+  })
+```
+
+## State Shape
+
+### Each step should have one clear purpose, and add one thing to state
+
+Don't let steps do multiple unrelated things. Each step should have a clear name that describes its single purpose, and it should add one key to state. If a step produces multiple data points, namespace them under a single key.
+
+```typescript
+// ❌ DON'T DO THIS - step does too much and adds multiple keys
+.step('Process', async ({ state }) => ({
+    ...state,
+    transcript: await transcribe(state.audioUrl),
+    episodeTitle: state.discovery.episodeTitle,
+    podcastName: state.podcast.source,
+    podcastUrl: state.podcast.url,
+  }))
+
+// ✅ DO THIS - step has one purpose, adds one thing
+.step('Transcribe', async ({ state }) => {
+    const { discovery } = state;
+    const transcript = await whisper.transcribe(discovery.audioUrl!);
+    return { ...state, transcript };
+  })
+```
+
+Previous steps already namespace their results on state (e.g. `state.discovery`, `state.podcast`). Don't copy their fields to the top level — it duplicates data and makes it unclear which version is canonical.
+
+### Reshape state at phase boundaries
+
+As steps build up state, it can accumulate intermediate artifacts. At major phase transitions in a brain — like going from "gathering data" to "analyzing it" — reshape state to a clean form for the next phase. Return only what the next phase needs instead of spreading everything forward.
+
+The smell to watch for: if you're reading a brain and can't quickly answer "what's the canonical version of X on state?" then state needs reshaping.
+
+```typescript
+// After a data-gathering phase, clean up for analysis
+.step('Prepare for analysis', ({ state }) => {
+    const { discovery, transcript, podcast } = state;
+    // Only carry forward what the analysis phase needs
+    return { podcast, discovery, transcript };
+  })
+```
+
+## Iterate Results
+
+Iterate steps produce an `IterateResult` — use its properties and methods to access results cleanly:
+
+```typescript
+// Access just the results
+state.results.values.map(r => r.summary)
+
+// Access just the input items
+state.results.items
+
+// Filter by both item and result
+state.results.filter((item, r) => r.isImportant).items
+
+// Map over both item and result
+state.results.map((item, r) => ({ id: item.id, summary: r.summary }))
+
+// Tuple destructuring still works (backward compatible)
+for (const [item, result] of state.results) { ... }
+```
+
+Use `.values` for simple extraction, `.filter()` for correlated filtering, and `.map()` when you need both item and result:
+
+```typescript
+.step('Process', ({ state }) => ({
+    ...state,
+    important: state.results.filter((item, r) => r.score > 0.8).items,
+    summaries: state.results.values.map(r => r.summary),
+  }))
+```
+
+**Name the `outputKey` after the content.** If results contain analyses, use `outputKey: 'analyses' as const`, not `outputKey: 'processedItems' as const`.
+
 ## Brain DSL Type Inference
 
 The Brain DSL has very strong type inference capabilities. **Important**: You should NOT explicitly specify types on the state object as it flows through steps. The types are automatically inferred from the previous step.
@@ -287,6 +460,86 @@ export const brain = createBrain({
 
 This keeps your service implementations separate from your brain logic and makes them easier to test and maintain.
 
+## Rate Limiting with bottleneck
+
+Most external APIs have rate limits. The `utils/bottleneck.ts` utility creates a simple rate limiter you can wrap around any async call.
+
+### Basic Usage
+
+```typescript
+import { bottleneck } from '../utils/bottleneck.js';
+
+// Create a limiter — exactly one rate unit is required
+const limit = bottleneck({ rpm: 60 }); // 60 requests per minute
+
+// Wrap any async call with the limiter
+const result = await limit(() => api.fetchData(id));
+```
+
+### Config Options
+
+Pass exactly one of these (TypeScript enforces this):
+
+- `rps` — requests per second
+- `rpm` — requests per minute
+- `rph` — requests per hour
+- `rpd` — requests per day
+
+```typescript
+const fast = bottleneck({ rps: 10 });   // 10 per second
+const slow = bottleneck({ rpd: 1000 }); // 1000 per day
+```
+
+### Wrapping a Service
+
+Create one limiter per API and wrap all calls through it:
+
+```typescript
+// services/github.ts
+import { bottleneck } from '../utils/bottleneck.js';
+
+const limit = bottleneck({ rps: 10 });
+
+async function getRepo(owner: string, repo: string) {
+  return limit(() =>
+    fetch('https://api.github.com/repos/' + owner + '/' + repo)
+      .then(r => r.json())
+  );
+}
+
+async function listIssues(owner: string, repo: string) {
+  return limit(() =>
+    fetch('https://api.github.com/repos/' + owner + '/' + repo + '/issues')
+      .then(r => r.json())
+  );
+}
+
+export default { getRepo, listIssues };
+```
+
+### Using with Iterate
+
+When iterating over items, wrap the API call inside the step callback:
+
+```typescript
+import { bottleneck } from '../utils/bottleneck.js';
+
+const limit = bottleneck({ rpm: 60 });
+
+brain('process-items')
+  .step('Init', ({ state }) => ({ items: state.items }))
+  .step('Fetch details', async ({ state }) => {
+    const details = await Promise.all(
+      state.items.map(item => limit(() => api.getDetail(item.id)))
+    );
+    return { ...state, details };
+  });
+```
+
+### When Creating Services
+
+When building a new service that wraps an external API, research the API's rate limits and add a bottleneck upfront. It's much easier to add rate limiting from the start than to debug 429 errors later.
+
 ## Brain Options Usage
 
 When creating brains that need runtime configuration, use the options schema pattern:
@@ -309,14 +562,14 @@ const alertBrain = brain('Alert System')
   }))
   .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 };
   });
 ```
@@ -528,4 +781,4 @@ export default feedbackBrain;
 - Let TypeScript infer types - don't add explicit type annotations
 - Don't catch errors unless it's part of the workflow logic
 - Run `npm run typecheck` frequently to catch type errors early
-- Stop the server when done: `px server -k` (default server) or `kill $(cat .positronic-server.pid)`
+- Stop the server when done: `px server -k` (default server) or `kill $(cat .positronic-server.pid)`

package/template/utils/bottleneck.ts

@@ -0,0 +1,26 @@
+type BottleneckConfig =
+  | { rps: number; rpm?: never; rph?: never; rpd?: never }
+  | { rpm: number; rps?: never; rph?: never; rpd?: never }
+  | { rph: number; rps?: never; rpm?: never; rpd?: never }
+  | { rpd: number; rps?: never; rpm?: never; rph?: never };
+
+export function bottleneck(config: BottleneckConfig) {
+  const interval = configToInterval(config);
+  let next = 0;
+
+  return async <T>(fn: () => Promise<T>): Promise<T> => {
+    const now = Date.now();
+    const delay = Math.max(0, next - now);
+    next = Math.max(now, next) + interval;
+    if (delay > 0) await new Promise<void>((r) => setTimeout(r, delay));
+    return fn();
+  };
+}
+
+function configToInterval(config: BottleneckConfig) {
+  if ('rps' in config && config.rps !== undefined) return 1000 / config.rps;
+  if ('rpm' in config && config.rpm !== undefined) return 60_000 / config.rpm;
+  if ('rph' in config && config.rph !== undefined) return 3_600_000 / config.rph;
+  if ('rpd' in config && config.rpd !== undefined) return 86_400_000 / config.rpd;
+  return 0;
+}