@positronic/core 0.0.1 → 0.0.3

package/src/dsl/constants.ts

@@ -1,11 +1,11 @@
-export const WORKFLOW_EVENTS = {
-  START: 'workflow:start',
-  RESTART: 'workflow:restart',
+export const BRAIN_EVENTS = {
+  START: 'brain:start',
+  RESTART: 'brain:restart',
   STEP_START: 'step:start',
   STEP_COMPLETE: 'step:complete',
   STEP_STATUS: 'step:status',
-  ERROR: 'workflow:error',
-  COMPLETE: 'workflow:complete',
+  ERROR: 'brain:error',
+  COMPLETE: 'brain:complete',
 } as const;
 
 export const STATUS = {
@@ -13,4 +13,4 @@ export const STATUS = {
   RUNNING: 'running',
   COMPLETE: 'complete',
   ERROR: 'error',
-} as const;
+} as const;

package/src/dsl/json-patch.ts

@@ -1,13 +1,15 @@
 import pkg from 'fast-json-patch';
 const { compare, applyPatch } = pkg;
-import { JsonPatch, State } from './types';
+import { JsonPatch, State } from './types.js';
+
+export type { JsonPatch };
 
 /**
  * Creates a JSON Patch that describes the changes needed to transform prevState into nextState.
  */
 export function createPatch(prevState: State, nextState: State): JsonPatch {
   // Filter out non-standard operations and ensure type safety
-  return compare(prevState, nextState).filter(op =>
+  return compare(prevState, nextState).filter((op) =>
     ['add', 'remove', 'replace', 'move', 'copy', 'test'].includes(op.op)
   ) as JsonPatch;
 }
@@ -16,12 +18,25 @@ export function createPatch(prevState: State, nextState: State): JsonPatch {
  * Applies one or more JSON Patches to a state object and returns the resulting state.
  * If multiple patches are provided, they are applied in sequence.
  */
-export function applyPatches(state: State, patches: JsonPatch | JsonPatch[]): State {
-  const patchArray = Array.isArray(patches[0]) ? patches as JsonPatch[] : [patches as JsonPatch];
+export function applyPatches(
+  state: State,
+  patches: JsonPatch | JsonPatch[]
+): State {
+  const patchArray = Array.isArray(patches[0])
+    ? (patches as JsonPatch[])
+    : [patches as JsonPatch];
 
   // Apply patches in sequence, creating a new state object each time
-  return patchArray.reduce((currentState, patch) => {
-    const { newDocument } = applyPatch(currentState, patch as any[], true, false);
-    return newDocument;
-  }, { ...state });
-}
+  return patchArray.reduce(
+    (currentState, patch) => {
+      const { newDocument } = applyPatch(
+        currentState,
+        patch as any[],
+        true,
+        false
+      );
+      return newDocument;
+    },
+    { ...state }
+  );
+}

package/src/dsl/types.ts

@@ -10,4 +10,4 @@ export type JsonPatch = {
   path: string;
   value?: JsonValue;
   from?: string;
-}[];
+}[];

package/src/index.ts

@@ -1,22 +1,36 @@
-export { Workflow, workflow } from "./dsl/workflow";
-export { WorkflowRunner } from "./dsl/workflow-runner";
-export { createExtension } from "./dsl/extensions";
-export { STATUS, WORKFLOW_EVENTS } from "./dsl/constants";
-export { Adapter } from "./adapters/types";
+export { Brain, brain } from './dsl/brain.js';
+export { BrainRunner } from './dsl/brain-runner.js';
+export { STATUS, BRAIN_EVENTS } from './dsl/constants.js';
+export type { Adapter } from './adapters/types.js';
 export type {
-  WorkflowEvent,
+  BrainEvent,
   SerializedStep,
   InitialRunParams,
   RerunParams,
-  WorkflowStartEvent,
-  WorkflowCompleteEvent,
-  WorkflowErrorEvent,
+  BrainStartEvent,
+  BrainCompleteEvent,
+  BrainErrorEvent,
   StepStatusEvent,
   StepStartedEvent,
-  StepCompletedEvent
-} from "./dsl/workflow";
-export type { PromptClient, ResponseModel } from "./clients/types";
-export type { State } from "./dsl/types";
-export type { FileStore } from "./file-stores/types";
-export { createPatch, applyPatches } from "./dsl/json-patch";
-export { LocalFileStore } from "./file-stores/local-file-store";
+  StepCompletedEvent,
+  BrainStructure,
+  BrainFactory,
+} from './dsl/brain.js';
+export type { ObjectGenerator, Message } from './clients/types.js';
+export type { State } from './dsl/types.js';
+export { createPatch, applyPatches } from './dsl/json-patch.js';
+
+// Only needed for development to ensure that zod version numbers are the same, it's a peer
+// dependency so when not using file://..path/to/package links the version numbers
+// will match just fine if the user has the same version of zod installed.
+// NOTE: Not 100% sure this is still needed - worth re-evaluating if we can remove this.
+export { z } from 'zod';
+
+export type { ResourceLoader } from './resources/resource-loader.js';
+export { createResources, type Resources } from './resources/resources.js';
+export type {
+  Manifest as ResourceManifest,
+  Entry as ResourceEntry,
+  ResourceType,
+} from './resources/resources.js';
+export { RESOURCE_TYPES } from './resources/resources.js';

package/src/resources/resource-loader.ts

@@ -0,0 +1,8 @@
+export interface ResourceLoader {
+  load(resourceName: string, type?: 'text'): Promise<string>;
+  load(resourceName: string, type: 'binary'): Promise<Buffer>;
+  load(
+    resourceName: string,
+    type?: 'text' | 'binary'
+  ): Promise<string | Buffer>;
+}

package/src/resources/resources.ts

@@ -0,0 +1,267 @@
+import { ResourceLoader } from './resource-loader.js';
+
+// Runtime array of valid resource types
+export const RESOURCE_TYPES = ['text', 'binary'] as const;
+export type ResourceType = (typeof RESOURCE_TYPES)[number];
+
+export interface Entry {
+  type: ResourceType;
+  path: string; // File path - used during build process
+  key: string; // R2 object key (original filename with path)
+}
+
+export interface Manifest {
+  [key: string]: ManifestEntry;
+}
+
+type ManifestEntry = Entry | Manifest;
+
+interface Resource {
+  load: () => Promise<string | Buffer>;
+  loadText: () => Promise<string>;
+  loadBinary: () => Promise<Buffer>;
+}
+
+export interface Resources {
+  [key: string]: Resource | Resources;
+}
+
+function isResourceEntry(entry: ManifestEntry): entry is Entry {
+  return typeof (entry as Entry).type === 'string';
+}
+
+export function createResources<M extends Manifest>(
+  loader: ResourceLoader,
+  initialManifest: M
+) {
+  // Helper function to find a resource entry by path in the manifest
+  function findResourceByPath(manifest: Manifest, path: string): Entry | null {
+    const parts = path.split('/');
+
+    let current: Manifest | Entry = manifest;
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      if (isResourceEntry(current)) {
+        // We hit a resource entry before consuming all parts
+        return null;
+      }
+
+      const currentManifest = current as Manifest;
+      const next = currentManifest[part];
+      if (!next) {
+        // If exact match not found and this is the last part, try without extension
+        if (i === parts.length - 1) {
+          const partWithoutExt = part.replace(/\.[^/.]+$/, '');
+          const currentManifest = current as Manifest; // We know it's a Manifest since we checked isResourceEntry above
+          const matches = Object.keys(currentManifest).filter((key) => {
+            const keyWithoutExt = key.replace(/\.[^/.]+$/, '');
+            return (
+              keyWithoutExt === partWithoutExt &&
+              isResourceEntry(currentManifest[key])
+            );
+          });
+
+          if (matches.length === 1) {
+            return currentManifest[matches[0]] as Entry;
+          } else if (matches.length > 1) {
+            throw new Error(
+              `Ambiguous resource path '${path}': found ${matches.join(
+                ', '
+              )}. ` + `Please specify the full filename with extension.`
+            );
+          }
+        }
+        return null;
+      }
+
+      if (i === parts.length - 1 && isResourceEntry(next)) {
+        // Found the resource
+        return next;
+      }
+
+      current = next as Manifest;
+    }
+
+    return null;
+  }
+
+  function createProxiedResources(manifestNode: Manifest): Resources {
+    // Create methods that will be shared across all instances
+    const loadText = async (path: string): Promise<string> => {
+      const entry = findResourceByPath(manifestNode, path);
+      if (!entry) {
+        throw new Error(`Resource not found: ${path}`);
+      }
+      if (entry.type !== 'text') {
+        throw new Error(
+          `Resource "${path}" is of type "${entry.type}", but was accessed with loadText().`
+        );
+      }
+      return loader.load(entry.key, 'text');
+    };
+
+    const loadBinary = async (path: string) => {
+      const entry = findResourceByPath(manifestNode, path);
+      if (!entry) {
+        throw new Error(`Resource not found: ${path}`);
+      }
+      if (entry.type !== 'binary') {
+        throw new Error(
+          `Resource "${path}" is of type "${entry.type}", but was accessed with loadBinary().`
+        );
+      }
+      return loader.load(entry.key, 'binary');
+    };
+
+    const resultProxy: Resources = new Proxy({} as Resources, {
+      get: (target, prop, receiver): any => {
+        if (prop === 'loadText') {
+          return loadText;
+        }
+        if (prop === 'loadBinary') {
+          return loadBinary;
+        }
+
+        // Handle dynamic resource properties
+        if (typeof prop !== 'string') {
+          return Reflect.get(target, prop, receiver);
+        }
+
+        // Check if the property exists directly (with extension)
+        if (prop in manifestNode) {
+          const manifestEntry = manifestNode[prop];
+
+          if (isResourceEntry(manifestEntry)) {
+            const { key, type } = manifestEntry;
+            const apiObject: Resource = {
+              load: () =>
+                manifestEntry.type === 'text'
+                  ? loader.load(key, 'text')
+                  : loader.load(key, 'binary'),
+              loadText: () => {
+                if (type !== 'text') {
+                  throw new Error(
+                    `Resource "${prop}" is of type "${type}", but was accessed with loadText().`
+                  );
+                }
+                return loader.load(key, 'text');
+              },
+              loadBinary: () => {
+                if (type !== 'binary') {
+                  throw new Error(
+                    `Resource "${prop}" is of type "${type}", but was accessed with loadBinary().`
+                  );
+                }
+                return loader.load(key, 'binary');
+              },
+            };
+            return apiObject;
+          } else {
+            // manifestEntry is a nested Manifest
+            const nestedResources = createProxiedResources(
+              manifestEntry as Manifest
+            );
+            return nestedResources;
+          }
+        }
+
+        // If not found directly, check for files without extension
+        // Find all keys that match when extension is removed
+        const matches = Object.keys(manifestNode).filter((key) => {
+          const keyWithoutExt = key.replace(/\.[^/.]+$/, '');
+          return keyWithoutExt === prop && isResourceEntry(manifestNode[key]);
+        });
+
+        if (matches.length === 0) {
+          // No matches - might be a nested directory
+          if (prop in manifestNode && !isResourceEntry(manifestNode[prop])) {
+            return createProxiedResources(manifestNode[prop] as Manifest);
+          }
+          return undefined;
+        }
+
+        if (matches.length === 1) {
+          // Single match - return it
+          const manifestEntry = manifestNode[matches[0]] as Entry;
+          const { key, type } = manifestEntry;
+          const apiObject: Resource = {
+            load: () =>
+              type === 'text'
+                ? loader.load(key, 'text')
+                : loader.load(key, 'binary'),
+            loadText: () => {
+              if (type !== 'text') {
+                throw new Error(
+                  `Resource "${matches[0]}" is of type "${type}", but was accessed with loadText().`
+                );
+              }
+              return loader.load(key, 'text');
+            },
+            loadBinary: () => {
+              if (type !== 'binary') {
+                throw new Error(
+                  `Resource "${matches[0]}" is of type "${type}", but was accessed with loadBinary().`
+                );
+              }
+              return loader.load(key, 'binary');
+            },
+          };
+          return apiObject;
+        }
+
+        // Multiple matches - throw helpful error
+        throw new Error(
+          `Ambiguous resource name '${prop}': found ${matches.join(', ')}. ` +
+            `Please use resources.loadText('${matches[0]}') or resources.loadBinary('${matches[1]}') instead.`
+        );
+      },
+      has: (target, prop): boolean => {
+        // Check for special methods
+        if (prop === 'loadText' || prop === 'loadBinary') {
+          return true;
+        }
+        // Then check manifest
+        if (typeof prop === 'string') {
+          return prop in manifestNode;
+        }
+        return Reflect.has(target, prop);
+      },
+      ownKeys: (target): string[] => {
+        // Combine special methods with manifest keys
+        return ['loadText', 'loadBinary', ...Object.keys(manifestNode)];
+      },
+      getOwnPropertyDescriptor: (
+        target,
+        prop
+      ): PropertyDescriptor | undefined => {
+        if (prop === 'loadText' || prop === 'loadBinary') {
+          return {
+            value: prop === 'loadText' ? loadText : loadBinary,
+            writable: false,
+            enumerable: true,
+            configurable: true,
+          };
+        }
+
+        if (typeof prop === 'string' && prop in manifestNode) {
+          const value: Resource | Resources | undefined =
+            resultProxy[prop as keyof Resources];
+          if (value === undefined) {
+            return undefined;
+          }
+          return {
+            value,
+            writable: false,
+            enumerable: true,
+            configurable: true,
+          };
+        }
+        return Reflect.getOwnPropertyDescriptor(target, prop);
+      },
+    });
+
+    return resultProxy;
+  }
+
+  return createProxiedResources(initialManifest);
+}

package/src/test-utils.ts

@@ -0,0 +1,254 @@
+import type { ObjectGenerator, Message } from './clients/types.js';
+import { z } from 'zod';
+import { jest } from '@jest/globals';
+import type { Adapter } from './adapters/types.js';
+import type { BrainEvent, Brain } from './dsl/brain.js';
+import type { State } from './dsl/types.js';
+import { BRAIN_EVENTS } from './dsl/constants.js';
+import { applyPatches } from './dsl/json-patch.js';
+import { BrainRunner } from './dsl/brain-runner.js';
+import type { Resources } from './resources/resources.js';
+
+/**
+ * Mock implementation of ObjectGenerator for testing
+ */
+export class MockObjectGenerator implements ObjectGenerator {
+  private generateObjectMock: jest.Mock<any>;
+  private calls: Array<{
+    params: Parameters<ObjectGenerator['generateObject']>[0];
+    timestamp: Date;
+  }> = [];
+
+  constructor() {
+    this.generateObjectMock = jest.fn();
+  }
+
+  async generateObject<T extends z.AnyZodObject>(
+    params: Parameters<ObjectGenerator['generateObject']>[0]
+  ): Promise<z.infer<T>> {
+    this.calls.push({ params, timestamp: new Date() });
+    return this.generateObjectMock(params) as Promise<z.infer<T>>;
+  }
+
+  /**
+   * Mock a response for the next generateObject call
+   */
+  mockNextResponse<T>(response: T): void {
+    this.generateObjectMock.mockResolvedValueOnce(response as any);
+  }
+
+  /**
+   * Mock multiple responses in sequence
+   */
+  mockResponses(...responses: any[]): void {
+    responses.forEach((response) => {
+      this.generateObjectMock.mockResolvedValueOnce(response as any);
+    });
+  }
+
+  /**
+   * Mock an error for the next generateObject call
+   */
+  mockNextError(error: Error | string): void {
+    const errorObj = typeof error === 'string' ? new Error(error) : error;
+    this.generateObjectMock.mockRejectedValueOnce(errorObj as any);
+  }
+
+  /**
+   * Get the underlying jest.Mock for advanced mocking scenarios
+   */
+  get mock(): jest.Mock<any> {
+    return this.generateObjectMock;
+  }
+
+  /**
+   * Clear all mocks and call history
+   */
+  clear(): void {
+    this.generateObjectMock.mockClear();
+    this.calls = [];
+  }
+
+  /**
+   * Reset mock to initial state
+   */
+  reset(): void {
+    this.generateObjectMock.mockReset();
+    this.calls = [];
+  }
+
+  /**
+   * Get all calls made to generateObject
+   */
+  getCalls() {
+    return this.calls;
+  }
+
+  /**
+   * Get the last call made to generateObject
+   */
+  getLastCall() {
+    return this.calls[this.calls.length - 1];
+  }
+
+  /**
+   * Assert that generateObject was called with specific parameters
+   */
+  expectCalledWith(expected: {
+    prompt?: string | ((actual: string) => boolean);
+    schemaName?: string;
+    messages?: Message[];
+    system?: string;
+  }): void {
+    const lastCall = this.getLastCall();
+    if (!lastCall) {
+      throw new Error('No calls made to generateObject');
+    }
+
+    if (expected.prompt !== undefined) {
+      if (typeof expected.prompt === 'function') {
+        expect(expected.prompt(lastCall.params.prompt || '')).toBe(true);
+      } else {
+        expect(lastCall.params.prompt).toBe(expected.prompt);
+      }
+    }
+
+    if (expected.schemaName !== undefined) {
+      expect(lastCall.params.schemaName).toBe(expected.schemaName);
+    }
+
+    if (expected.messages !== undefined) {
+      expect(lastCall.params.messages).toEqual(expected.messages);
+    }
+
+    if (expected.system !== undefined) {
+      expect(lastCall.params.system).toBe(expected.system);
+    }
+  }
+
+  /**
+   * Assert that generateObject was called N times
+   */
+  expectCallCount(count: number): void {
+    expect(this.generateObjectMock).toHaveBeenCalledTimes(count);
+  }
+}
+
+/**
+ * Creates a mock client for testing brains
+ */
+export function createMockClient(): MockObjectGenerator {
+  return new MockObjectGenerator();
+}
+
+/**
+ * Test adapter that collects brain execution results
+ */
+class TestAdapter<TState extends State = State> implements Adapter {
+  private stepTitles: string[] = [];
+  private currentState: TState;
+  private completed = false;
+  private error: Error | null = null;
+
+  constructor(private initialState: TState) {
+    this.currentState = { ...initialState };
+  }
+
+  async dispatch(event: BrainEvent): Promise<void> {
+    switch (event.type) {
+      case BRAIN_EVENTS.STEP_COMPLETE:
+        this.stepTitles.push(event.stepTitle);
+        if (event.patch && event.patch.length > 0) {
+          this.currentState = applyPatches(this.currentState, event.patch) as TState;
+        }
+        break;
+      case BRAIN_EVENTS.COMPLETE:
+        this.completed = true;
+        break;
+      case BRAIN_EVENTS.ERROR:
+        this.error = event.error;
+        break;
+    }
+  }
+
+  getExecutedSteps(): string[] {
+    return [...this.stepTitles];
+  }
+
+  getFinalState(): TState {
+    return { ...this.currentState };
+  }
+
+  isCompleted(): boolean {
+    return this.completed;
+  }
+
+  getError(): Error | null {
+    return this.error;
+  }
+}
+
+/**
+ * Test runner options
+ */
+export interface TestRunnerOptions<TState extends State = State> {
+  client?: ObjectGenerator;
+  resources?: Resources;
+  initialState?: TState;
+}
+
+/**
+ * Result of running a brain test
+ */
+export interface TestRunResult<TState extends State = State> {
+  finalState: TState;
+  steps: string[];
+  error: Error | null;
+  completed: boolean;
+}
+
+/**
+ * Runs a brain with test utilities and returns collected data
+ */
+export async function runBrainTest<
+  TOptions extends object = {},
+  TState extends State = {}
+>(
+  brain: Brain<TOptions, TState, any>,
+  options: TestRunnerOptions<TState> & { brainOptions?: TOptions } = {}
+): Promise<TestRunResult<TState>> {
+  const {
+    client = createMockClient(),
+    resources,
+    initialState = {} as TState,
+    brainOptions,
+  } = options;
+
+  // Create test adapter
+  const testAdapter = new TestAdapter<TState>(initialState);
+
+  // Create brain runner with test adapter
+  const runner = new BrainRunner({
+    adapters: [testAdapter],
+    client,
+    resources,
+  });
+
+  try {
+    // Run the brain
+    await runner.run(brain, {
+      initialState,
+      options: brainOptions,
+    });
+  } catch (error) {
+    // Brain might throw after emitting ERROR event
+    // This is expected behavior, so we don't re-throw
+  }
+
+  return {
+    finalState: testAdapter.getFinalState(),
+    steps: testAdapter.getExecutedSteps(),
+    error: testAdapter.getError(),
+    completed: testAdapter.isCompleted(),
+  };
+}