alchemy 0.1.1 → 0.1.3

package/src/{components/agent → markdown}/requirements.ts

@@ -1,17 +1,29 @@
-import { generateText } from "ai";
-import { mkdir, unlink, writeFile } from "fs/promises";
+import { mkdir, writeFile } from "fs/promises";
 import { dirname } from "path";
 import { z } from "zod";
-import { Agent } from "./agent";
-import { resolveModel } from "./model";
-import { scrapeWebPage } from "./scrape";
+import {
+  FileContext,
+  ModelId,
+  dependenciesAsMessages,
+  generateText,
+  resolveModel,
+} from "../agent";
+import { rm } from "../fs";
+import { type Context, Resource } from "../resource";
+
+export const ReasoningEffort = z.enum(["low", "medium", "high"]);
 
 export const RequirementsInput = z.object({
   /**
    * The ID of the model to use for generating requirements documentation
    * @default "gpt-4o"
    */
-  modelId: z.string().optional(),
+  modelId: ModelId.optional(),
+
+  /**
+   * The effort to put into reasoning about the requirements
+   */
+  reasoningEffort: ReasoningEffort.optional(),
 
   /**
    * List of requirements to document and analyze
@@ -19,9 +31,9 @@ export const RequirementsInput = z.object({
   requirements: z.array(z.string()),
 
   /**
-   * One-line summary of the requirements document
+   * List of dependencies for the requirements document
    */
-  title: z.string(),
+  dependencies: z.array(FileContext).optional(),
 
   /**
    * Temperature setting for model generation (higher = more creative, lower = more focused)
@@ -32,7 +44,7 @@ export const RequirementsInput = z.object({
   /**
    * File path where the requirements document should be written
    */
-  path: z.string(),
+  file: z.string().optional(),
 });
 
 export const RequirementsOutput = z.object({
@@ -42,33 +54,44 @@ export const RequirementsOutput = z.object({
   content: z.string(),
 });
 
-export type RequirementsInput = z.infer<typeof RequirementsInput>;
+export interface RequirementsInput extends z.infer<typeof RequirementsInput> {}
 export type RequirementsOutput = z.infer<typeof RequirementsOutput>;
 
-export class Requirements extends Agent(
+export class Requirements extends Resource(
   "code::Requirements",
-  {
-    description:
-      "This Agent is responsible for writing and refining a detailed requirements document from a list of requirements.",
-    input: RequirementsInput,
-    output: RequirementsOutput,
-  },
-  async (ctx, input) => {
+  async (ctx: Context<RequirementsOutput>, props: RequirementsInput) => {
     if (ctx.event === "delete") {
-      await unlink(input.path);
+      if (props.file) {
+        await rm(props.file);
+      }
       return;
     }
 
+    if (props.file) {
+      console.log(
+        ctx.event === "create" ? "Designing" : "Revising",
+        "requirements",
+        props.file,
+      );
+    }
+
     // Get the appropriate model based on the ID
-    const { model } = await resolveModel(input.modelId ?? "gpt-4o");
+    const model = await resolveModel(props.modelId ?? "gpt-4o");
 
     // Generate the requirements document
     const { text } = await generateText({
       model,
-      temperature: input.temperature ?? 0.7,
+      temperature: props.temperature ?? 0.7,
       maxSteps: 3, // Allow multiple steps for potential tool usage
+      providerOptions: props.reasoningEffort
+        ? {
+            openai: {
+              reasoningEffort: props.reasoningEffort,
+            },
+          }
+        : undefined,
       tools: {
-        scrapeWebPage,
+        // scrapeWebPage,
       },
       messages: [
         {
@@ -76,14 +99,13 @@ export class Requirements extends Agent(
           content:
             "You are a helpful assistant that creates markdown documents from requirements. You can use the scrapeWebPage tool to get additional requirements from relevant URLs if needed.",
         },
+        ...dependenciesAsMessages(props.dependencies ?? []),
         {
           role: "user",
           content: `Please analyze the following system requirements and create a comprehensive, unambiguous markdown document that covers all aspects:
 
-Title: ${input.title}
-
 Requirements:
-${input.requirements.map((req) => `- ${req}`).join("\n")}
+${props.requirements.map((req) => `- ${req}`).join("\n")}
 
 Guidelines:
 1. Make explicit decisions for any ambiguous requirements - do not leave open questions
@@ -98,11 +120,13 @@ Include technical considerations and implementation details, ensuring every requ
       ],
     });
 
-    // Ensure the directory exists
-    await mkdir(dirname(input.path), { recursive: true });
+    if (props.file) {
+      // Ensure the directory exists
+      await mkdir(dirname(props.file), { recursive: true });
 
-    // Write the requirements to the file
-    await writeFile(input.path, text);
+      // Write the requirements to the file
+      await writeFile(props.file, text);
+    }
 
     return {
       content: text,

package/src/output.ts

@@ -1,5 +1,11 @@
 export type Eval<U> = U extends Output<infer V> ? Eval<V> : U;
 
+export function isOutput<T>(value: any): value is Output<T> {
+  return (
+    value && typeof value === "object" && typeof value.apply === "function"
+  );
+}
+
 export type Outputs<P extends readonly any[]> = P extends [
   infer First,
   ...infer Rest,

package/src/resource.ts

@@ -1,6 +1,10 @@
-import { deletions, nodes, providers } from "./global";
-import type { Inputs } from "./input";
+import { alchemize } from "./alchemize";
+import { type ApplyOptions, apply } from "./apply";
+import type { DestroyOptions } from "./destroy";
+import { defaultStateStore, deletions, providers } from "./global";
+import type { Inputs, Input as input } from "./input";
 import { Output } from "./output";
+import { Scope as IScope, getScope, pushScope } from "./scope";
 import type { State, StateStore } from "./state";
 
 export type ResourceID = string;
@@ -12,6 +16,8 @@ export const Input = Symbol.for("Input");
 export const Value = Symbol.for("Value");
 export const Apply = Symbol.for("Apply");
 export const Provide = Symbol.for("Provide");
+export const Scope = Symbol.for("Scope");
+export const Options = Symbol.for("Options");
 
 // properties that pierce through the Proxy
 const OrthogonalProperties = [
@@ -21,8 +27,17 @@ const OrthogonalProperties = [
   Value,
   Apply,
   Provide,
+  Scope,
+  Options,
 ] as const;
 
+export interface ProviderOptions {
+  /**
+   * If true, the resource will be updated even if the inputs have not changed.
+   */
+  alwaysUpdate: boolean;
+}
+
 export type Resource<In extends any[] = any[], Out = any> = {
   [ResourceID]: string;
   [Provider]: Provider<any, any[], any>;
@@ -30,11 +45,14 @@ export type Resource<In extends any[] = any[], Out = any> = {
   [Value]?: Out;
   [Apply]: <O>(value: Out) => O;
   [Provide]: (value: Out) => void;
+  [Options]: ProviderOptions;
 } & Output<Out>;
 
-export type Context<Outputs> = {
+export interface BaseContext {
+  quiet: boolean;
   stage: string;
   resourceID: ResourceID;
+  scope: IScope;
   get<T>(key: string): Promise<T | undefined>;
   set<T>(key: string, value: T): Promise<void>;
   delete<T>(key: string): Promise<T | undefined>;
@@ -43,15 +61,26 @@ export type Context<Outputs> = {
    * This will cause the resource to be deleted at the end of the stack's CREATE phase.
    */
   replace(): void;
-} & (
-  | {
-      event: "create";
-    }
-  | {
-      event: "update" | "delete";
-      output: Outputs;
-    }
-);
+}
+
+export interface CreateContext extends BaseContext {
+  event: "create";
+}
+
+export interface UpdateContext<Outputs> extends BaseContext {
+  event: "update";
+  output: Outputs;
+}
+
+export interface DeleteContext<Outputs> extends BaseContext {
+  event: "delete";
+  output: Outputs;
+}
+
+export type Context<Outputs> =
+  | CreateContext
+  | UpdateContext<Outputs>
+  | DeleteContext<Outputs>;
 
 export type Provider<
   Type extends ResourceType = ResourceType,
@@ -65,16 +94,19 @@ export type Provider<
     deps: Set<ResourceID>,
     inputs: Inputs<In>,
     stateStore: StateStore,
+    options: ApplyOptions,
   ): Promise<Awaited<Out>>;
   delete(
     stage: string,
+    scope: IScope | undefined,
     resourceID: ResourceID,
     state: State,
     inputs: Inputs<In>,
+    options: DestroyOptions,
   ): Promise<void>;
 } & (new (
   id: string,
-  ...inputs: Inputs<In>
+  ...inputs: [...Inputs<In>, ...any[]]
 ) => Resource<In, Out>);
 
 export function isResource(value: any): value is Resource {
@@ -87,41 +119,88 @@ export function Resource<
   Out,
 >(
   type: Type,
-  func: (ctx: Context<Out>, ...args: Args) => Promise<Out | void> | Out | void,
+  options: Partial<ProviderOptions>,
+  func: (
+    ctx: Context<Out>,
+    ...args: Args
+  ) => Promise<input<Out> | void> | input<Out> | void,
+): Provider<Type, Args, Awaited<Out>>;
+
+export function Resource<
+  const Type extends ResourceType,
+  Args extends any[],
+  Out,
+>(
+  type: Type,
+  func: (
+    ctx: Context<Out>,
+    ...args: Args
+  ) => Promise<input<Out> | void> | input<Out> | void,
+): Provider<Type, Args, Awaited<Out>>;
+
+export function Resource<
+  const Type extends ResourceType,
+  Args extends any[],
+  Out,
+>(
+  type: Type,
+  ...args:
+    | [
+        Partial<ProviderOptions>,
+        (
+          ctx: Context<Out>,
+          ...args: Args
+        ) => Promise<input<Out> | void> | input<Out> | void,
+      ]
+    | [
+        (
+          ctx: Context<Out>,
+          ...args: Args
+        ) => Promise<input<Out> | void> | input<Out> | void,
+      ]
 ): Provider<Type, Args, Awaited<Out>> {
   if (providers.has(type)) {
     throw new Error(`Resource ${type} already exists`);
   }
+  const [options, func] = args.length === 2 ? args : [undefined, args[0]];
 
   interface Resource {
     [ResourceID]: ResourceID;
     [Provider]: Provider<Type, Args, Out>;
     [Input]: Inputs<Args>;
     [Value]?: Out;
+    [Scope]: IScope;
+    [Options]: ProviderOptions;
   }
 
   class Resource {
     static readonly type = type;
 
     constructor(id: ResourceID, ...input: Inputs<Args>) {
+      const scope = getScope();
       const node = {
         provider: Resource,
         resource: this,
       } as const;
-      if (nodes.has(id)) {
+
+      if (scope.nodes.has(id)) {
         // TODO(sam): do we want to throw?
         // it's kind of awesome that you can re-create a resource and call apply
         // console.warn(`Resource ${id} already exists in the stack: ${stack.id}`);
       }
-      nodes.set(id, node as any);
+      scope.nodes.set(id, node as any);
 
       this[ResourceID] = id;
       this[Provider] = Resource as any;
       this[Input] = input;
       this[Value] = undefined;
+      this[Scope] = scope;
       this[Provide] = (value: Out) => {
         this[Value] = value;
       };
+      this[Options] = {
+        alwaysUpdate: options?.alwaysUpdate ?? false,
+      };
 
       return new Proxy(this, {
         // TODO(sam): this won't work for the sub-class (class Table extends Resource)
@@ -175,14 +254,12 @@ export function Resource<
       deps: Set<ResourceID>,
       inputs: Args,
       stateStore: StateStore,
+      options: ApplyOptions,
     ): Promise<Awaited<Out | void>> {
       // const stack = resource[ResourceStack];
       const resourceID = resource[ResourceID];
 
-      let resourceState: State | undefined = await stateStore.get(
-        stage,
-        resourceID,
-      );
+      let resourceState: State | undefined = await stateStore.get(resourceID);
       if (resourceState === undefined) {
         resourceState = {
           provider: type,
@@ -192,20 +269,28 @@ export function Resource<
           deps: [...deps],
           inputs,
         };
-        await stateStore.set(stage, resourceID, resourceState);
+        await stateStore.set(resourceID, resourceState);
       }
 
+      const resourceFQN = `${resource[Scope].getScopePath(stage)}/${resourceID}`;
+
       // Skip update if inputs haven't changed and resource is in a stable state
       if (
-        (resourceState.status === "created" ||
-          resourceState.status === "updated") &&
-        JSON.stringify(resourceState.inputs) === JSON.stringify(inputs)
+        resourceState.status === "created" ||
+        resourceState.status === "updated"
       ) {
-        console.log(`Skip:    ${resourceID} (no changes)`);
-        if (resourceState.output !== undefined) {
-          resource[Provide](resourceState.output);
+        if (
+          JSON.stringify(resourceState.inputs) === JSON.stringify(inputs) &&
+          !resource[Options].alwaysUpdate
+        ) {
+          if (!options?.quiet) {
+            console.log(`Skip:    ${resourceFQN} (no changes)`);
+          }
+          if (resourceState.output !== undefined) {
+            resource[Provide](resourceState.output);
+          }
+          return resourceState.output;
         }
-        return resourceState.output;
       }
 
       const event = resourceState.status === "creating" ? "create" : "update";
@@ -213,78 +298,122 @@ export function Resource<
       resourceState.oldInputs = resourceState.inputs;
       resourceState.inputs = inputs;
 
-      console.log(
-        `${event === "create" ? "Create" : "Update"}:  ${resourceID}`,
-      );
+      if (!options?.quiet) {
+        console.log(
+          `${event === "create" ? "Create" : "Update"}:  ${resourceFQN}`,
+        );
+      }
 
-      await stateStore.set(stage, resourceID, resourceState);
+      await stateStore.set(resourceID, resourceState);
 
       let isReplaced = false;
 
-      const result = await func(
-        {
-          stage,
-          resourceID,
-          event,
-          output: resourceState.output,
-          replace: () => {
-            if (isReplaced) {
-              console.warn(
-                `Resource ${type} ${resourceID} is already marked as REPLACE`,
-              );
-              return;
-            }
-            isReplaced = true;
-            deletions.push({
-              id: resourceID,
-              data: {
-                ...resourceState!.data,
+      const quiet = options.quiet ?? false;
+
+      const evaluated = await pushScope(
+        resource[Scope],
+        resourceID,
+        async () => {
+          const result = await func(
+            {
+              stage,
+              resourceID,
+              event,
+              scope: getScope(),
+              output: resourceState.output,
+              replace: () => {
+                if (isReplaced) {
+                  console.warn(
+                    `Resource ${type} ${resourceFQN} is already marked as REPLACE`,
+                  );
+                  return;
+                }
+                isReplaced = true;
+                deletions.push({
+                  id: resourceID,
+                  data: {
+                    ...resourceState!.data,
+                  },
+                  inputs: inputs,
+                });
               },
-              inputs: inputs,
-            });
-          },
-          get: (key) => resourceState!.data[key],
-          set: async (key, value) => {
-            resourceState!.data[key] = value;
-            await stateStore.set(stage, resourceID, resourceState!);
-          },
-          delete: async (key) => {
-            const value = resourceState!.data[key];
-            delete resourceState!.data[key];
-            await stateStore.set(stage, resourceID, resourceState!);
-            return value;
-          },
+              get: (key) => resourceState!.data[key],
+              set: async (key, value) => {
+                resourceState!.data[key] = value;
+                await stateStore.set(resourceID, resourceState!);
+              },
+              delete: async (key) => {
+                const value = resourceState!.data[key];
+                delete resourceState!.data[key];
+                await stateStore.set(resourceID, resourceState!);
+                return value;
+              },
+              quiet,
+            },
+            ...inputs,
+          );
+
+          if (result === undefined) {
+            return undefined;
+          }
+
+          const evaluated = await apply(result as Out, {
+            stage,
+            scope: getScope(),
+            quiet,
+          });
+
+          return evaluated;
         },
-        ...inputs,
       );
 
-      console.log(
-        `${event === "create" ? "Created" : "Updated"}: ${resourceID}`,
-      );
-      await stateStore.set(stage, resourceID, {
+      if (!options?.quiet) {
+        console.log(
+          `${event === "create" ? "Created" : "Updated"}: ${resourceFQN}`,
+        );
+      }
+      await stateStore.set(resourceID, {
         provider: type,
         data: resourceState.data,
         status: event === "create" ? "created" : "updated",
-        output: result,
+        output: evaluated,
         inputs,
         deps: [...deps],
       });
-      if (result !== undefined) {
-        resource[Provide](result);
+      if (evaluated !== undefined) {
+        resource[Provide](evaluated);
       }
-      return result;
+      return evaluated;
     }
 
     static async delete(
       stage: string,
+      scope: IScope,
       resourceID: ResourceID,
       state: State,
       inputs: Args,
+      options: DestroyOptions,
     ) {
-      console.log(`Delete:  ${resourceID}`);
+      const resourceFQN = `${scope.getScopePath(stage)}/${resourceID}`;
+      const nestedScope = new IScope(resourceID, scope);
+
+      await alchemize({
+        mode: "destroy",
+        stage,
+        scope: nestedScope,
+        // TODO(sam): should use the appropriate state store
+        stateStore: defaultStateStore,
+        quiet: options.quiet,
+      });
+
+      if (!options?.quiet) {
+        console.log(`Delete:  ${resourceFQN}`);
+      }
+
       await func(
         {
           stage,
+          scope,
           resourceID: resourceID,
           event: "delete",
           output: state.output,
@@ -302,10 +431,14 @@ export function Resource<
             delete state.data[key];
             return value;
           },
+          quiet: options.quiet ?? false,
         },
         ...inputs,
       );
-      console.log(`Deleted: ${resourceID}`);
+
+      if (!options?.quiet) {
+        console.log(`Deleted: ${resourceFQN}`);
+      }
     }
   }
   providers.set(type, Resource as any);

package/src/scope.ts

@@ -0,0 +1,56 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+import { rootScope } from "./global";
+import type { Provider, Resource, ResourceID } from "./resource";
+
+const scopeGlobal = new Map<string | null, Scope>();
+
+const scopeStorage = new AsyncLocalStorage<Scope>();
+
+export class Scope {
+  public readonly nodes = new Map<
+    ResourceID,
+    {
+      provider: Provider<any, any[], any>;
+      resource: Resource<any, any>;
+    }
+  >();
+
+  constructor(
+    public readonly scopeName: string | null = null,
+    public readonly parent: Scope | undefined = undefined,
+  ) {}
+
+  public getScopePath(root: string): string {
+    // First, compute the parent's scope path
+    const parentPath = this.parent ? this.parent.getScopePath(root) : root;
+    // Then join the current scope name (if any) onto the parent's path
+    return this.scopeName ? path.join(parentPath, this.scopeName) : parentPath;
+  }
+}
+
+export function getScope(): Scope {
+  return scopeStorage.getStore() ?? rootScope;
+}
+
+export function withScope<T>(
+  scope: Scope,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  return scopeStorage.run(scope, async () => {
+    try {
+      return await fn();
+    } catch (error) {
+      throw error;
+    }
+  });
+}
+
+export function pushScope<T>(
+  parent: Scope,
+  scopeName: string,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  const newScope = new Scope(scopeName, parent);
+  return withScope(newScope, fn);
+}

package/src/slug.ts

@@ -0,0 +1,3 @@
+export function slugify(str: string) {
+  return str.replaceAll("/", "_");
+}