@positronic/template-new-project 0.0.67 → 0.0.68

package/index.js

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

package/package.json

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

package/template/.positronic/src/index.ts

@@ -6,6 +6,7 @@ import {
   BrainRunnerDO,
   MonitorDO,
   ScheduleDO,
+  GovernorDO,
   PositronicManifest,
 } from "@positronic/cloudflare";
 // Import the generated manifests - NOTE the .js extension for runtime compatibility
@@ -37,4 +38,4 @@ export default {
   fetch: app.fetch,
 } satisfies ExportedHandler<Env>;
 
-export { BrainRunnerDO, MonitorDO, ScheduleDO };
+export { BrainRunnerDO, MonitorDO, ScheduleDO, GovernorDO };

package/template/.positronic/wrangler.jsonc

@@ -13,13 +13,18 @@
     {
       "tag": "v1",
       "new_sqlite_classes": ["BrainRunnerDO", "MonitorDO", "ScheduleDO"]
+    },
+    {
+      "tag": "v2",
+      "new_sqlite_classes": ["GovernorDO"]
     }
   ],
   "durable_objects": {
     "bindings": [
       { "name": "BRAIN_RUNNER_DO", "class_name": "BrainRunnerDO" },
       { "name": "MONITOR_DO", "class_name": "MonitorDO" },
-      { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" }
+      { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" },
+      { "name": "GOVERNOR_DO", "class_name": "GovernorDO" }
     ]
   },
   "r2_buckets": [
@@ -59,7 +64,8 @@
         "bindings": [
           { "name": "BRAIN_RUNNER_DO", "class_name": "BrainRunnerDO" },
           { "name": "MONITOR_DO", "class_name": "MonitorDO" },
-          { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" }
+          { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" },
+          { "name": "GOVERNOR_DO", "class_name": "GovernorDO" }
         ]
       },
       "r2_buckets": [

package/template/brains/example.ts

@@ -7,7 +7,7 @@ const exampleBrain = brain('example')
     topic: 'AI workflows',
   }))
   .step('Generate greeting', async ({ state, client }) => {
-    const result = await client.generateObject({
+    const { object } = await client.generateObject({
       schema: z.object({
         greeting: z.string(),
         funFact: z.string(),
@@ -18,8 +18,8 @@ const exampleBrain = brain('example')
     });
     return {
       ...state,
-      greeting: result.greeting,
-      funFact: result.funFact,
+      greeting: object.greeting,
+      funFact: object.funFact,
     };
   })
   .step('Finish', ({ state }) => ({

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

@@ -135,6 +135,41 @@ Key points about prompt steps:
 - You can optionally provide a transform function as the third parameter
 - Type inference works throughout - TypeScript knows about your schema types
 
+#### Per-Step Client Overrides
+
+You can use a different AI model for a specific prompt step by passing a `client` option. This is useful when some steps need a cheaper model for simple tasks and others need a more capable model for complex reasoning:
+
+```typescript
+import { createAnthropicClient } from '@positronic/client-anthropic';
+
+const fastModel = createAnthropicClient({ model: 'claude-haiku-4-5-20251001' });
+const smartModel = createAnthropicClient({ model: 'claude-sonnet-4-5-20250929' });
+
+brain('Multi-Model Brain')
+  .prompt('Quick summary', {
+    template: ({ document }) => `Summarize this briefly: <%= '${document}' %>`,
+    outputSchema: {
+      schema: z.object({ summary: z.string() }),
+      name: 'quickSummary' as const,
+    },
+    client: fastModel,  // Use a fast, cheap model for summarization
+  })
+  .prompt('Deep analysis', {
+    template: ({ quickSummary }) =>
+      `Analyze the implications of this summary: <%= '${quickSummary.summary}' %>`,
+    outputSchema: {
+      schema: z.object({
+        insights: z.array(z.string()),
+        risks: z.array(z.string()),
+      }),
+      name: 'analysis' as const,
+    },
+    client: smartModel,  // Use a more capable model for analysis
+  });
+```
+
+When deployed to Cloudflare, rate limiting is applied automatically to all clients — including per-step overrides — through the Governor system. Brain authors don't need to worry about rate limiting.
+
 ### 3. Nested Brains
 
 Compose complex workflows from smaller brains:
@@ -733,13 +768,31 @@ for await (const event of brain.run({ client })) {
 
 ## Resources
 
-Access loaded resources with type-safe API:
+Resources are files in your project's `/resources` directory that brains can access at runtime. They provide a type-safe way to load text and binary content.
+
+### Adding Resources
+
+Place files in the `/resources` directory:
+
+```
+resources/
+├── config.json
+├── prompts/
+│   ├── customerSupport.md
+│   └── codeReview.md
+└── data/
+    └── records.csv
+```
+
+### Accessing Resources
+
+Access resources using dot notation that matches the file structure:
 
 ```typescript
 brain('Resource Example').step('Load Data', async ({ resources }) => {
-  const config = await resources.config.loadText();
-  const data = await resources.data.records.loadText();
-  return { config: JSON.parse(config), data };
+  const config = await resources.config.load();
+  const template = await resources.prompts.customerSupport.load();
+  return { config: JSON.parse(config), template };
 });
 ```
 
@@ -748,7 +801,7 @@ Resources are also available in prompt templates:
 ```typescript
 brain('Template Example').prompt('Generate Content', {
   template: async (state, resources) => {
-    const template = await resources.prompts.customerSupport.loadText();
+    const template = await resources.prompts.customerSupport.load();
     return template.replace('{{issue}}', state.issue);
   },
   outputSchema: {
@@ -758,6 +811,52 @@ brain('Template Example').prompt('Generate Content', {
 });
 ```
 
+### Resource Methods
+
+Each resource has a single `load()` method that returns the appropriate type:
+
+- `TextResource.load()` - Returns `Promise<string>` (for text files like `.md`, `.json`, `.txt`)
+- `BinaryResource.load()` - Returns `Promise<Buffer>` (for binary files like images)
+
+The resource type is determined automatically based on file content detection when you run `px resources types`.
+
+### File Naming and Property Access
+
+The resource name you use in code must be a valid JavaScript identifier. The system strips file extensions automatically, so `config.json` is accessed as `resources.config`.
+
+**Important**: Resource filenames must be valid JS identifiers (after extension stripping) to be accessible via dot notation. This means:
+
+```
+resources/
+├── myPrompt.md          ✅  → resources.myPrompt.load()
+├── config.json          ✅  → resources.config.load()
+├── reference-material.md  ❌  → "reference-material" has a hyphen, not a valid identifier
+├── referenceMaterial.md   ✅  → resources.referenceMaterial.load()
+```
+
+Use camelCase or single-word names for your resource files. Avoid hyphens, spaces, or other characters that aren't valid in JavaScript identifiers.
+
+You can also access resources by their full filename (including extension) using bracket notation:
+
+```typescript
+const content = await resources['config.json'].load();
+```
+
+### Type Generation
+
+Run `px resources types` to generate a `resources.d.ts` file in your project root. This provides TypeScript type safety for your resources — your editor will autocomplete resource names and flag typos.
+
+The generated types distinguish between `TextResource` and `BinaryResource` based on file content detection, so `load()` returns the correct type (`string` or `Buffer`).
+
+### Path-Based Access
+
+You can also load resources by path string at any level of the resource tree:
+
+```typescript
+const content = await resources.loadText('prompts/customerSupport.md');
+const binary = await resources.loadBinary('images/logo.png');
+```
+
 ## Organizing Complex Prompts
 
 When prompts become more than a sentence or two, extract them into separate files for better maintainability:
@@ -797,7 +896,7 @@ interface FilterPromptState {
 export const aiFilterPrompt = {
   template: async (state: FilterPromptState, resources: Resources) => {
     // Load a prompt template from resources
-    const template = await resources.prompts.hnFilter.loadText();
+    const template = await resources.prompts.hnFilter.load();
 
     // Build the prompt with state data
     const articleList = state.articles
@@ -885,6 +984,8 @@ brain('Batch Processor')
 - `concurrency: number` - Maximum number of items processed in parallel (default: 10)
 - `error: (item, error) => Response` - Fallback function when a request fails
 
+Batch prompts also support per-step `client` overrides (see Prompt Steps above), so you can use a different model for batch processing.
+
 ### Result Format
 
 The result is stored as an array of `[item, response]` tuples, preserving the relationship between each input item and its generated response.
@@ -1373,7 +1474,7 @@ const completeBrain = brain({
   .prompt('Generate Plan', {
     template: async (state, resources) => {
       // Load a template from resources
-      const template = await resources.templates.projectPlan.loadText();
+      const template = await resources.templates.projectPlan.load();
       return template.replace('{{context}}', 'software project');
     },
     outputSchema: {

package/template/runner.ts

@@ -26,8 +26,10 @@ import { google } from '@ai-sdk/google';
  * The adapter automatically indexes all agent conversations to memory.
  * See docs/memory-guide.md for more details.
  */
+const client = new VercelClient(google('gemini-3-pro-preview'));
+
 export const runner = new BrainRunner({
   adapters: [],
-  client: new VercelClient(google('gemini-3-pro-preview')),
+  client,
   resources: {},
-});
+});