alchemy 0.3.0 → 0.3.1

package/src/ai/approve.ts

@@ -0,0 +1,163 @@
+import type { CoreMessage } from "ai";
+import { type } from "arktype";
+import { Data } from "./data";
+
+/**
+ * Properties for approving or denying content
+ */
+export interface ApproveProps {
+  /**
+   * Content to be reviewed
+   * Use alchemy template literals to include file context:
+   * @example
+   * content: await alchemy`
+   *   Review this code:
+   *   ${alchemy.file("src/api.ts")}
+   * `
+   *
+   * Required unless messages are provided
+   */
+  content?: string;
+
+  /**
+   * Prompt for the approval decision
+   * This should include specific criteria for approval or denial
+   * @example
+   * prompt: "Approve this code if it follows security best practices and has proper error handling."
+   *
+   * Required unless messages are provided
+   */
+  prompt?: string;
+
+  /**
+   * System prompt for the model
+   * This is used to provide instructions to the model about how to make the decision
+   */
+  system?: string;
+
+  /**
+   * Message history for the conversation
+   * If provided, this will be used instead of the prompt and content
+   */
+  messages?: CoreMessage[];
+
+  /**
+   * Temperature for controlling randomness in generation.
+   * Higher values (e.g., 0.8) make output more random,
+   * lower values (e.g., 0.2) make it more deterministic.
+   * @default 0.2 (lower for more consistent decisions)
+   */
+  temperature?: number;
+}
+
+/**
+ * Result of the approval process
+ */
+export interface ApprovalResult {
+  /**
+   * Whether the content was approved
+   */
+  approved: boolean;
+
+  /**
+   * Explanation for the decision
+   */
+  explanation: string;
+
+  /**
+   * Suggestions for improvement if denied
+   */
+  suggestions?: string[];
+
+  /**
+   * Updated message history with the approval response appended
+   */
+  messages: CoreMessage[];
+}
+
+export type Approve = ApprovalResult;
+
+/**
+ * Default system prompt for approval decisions
+ */
+const DEFAULT_APPROVE_SYSTEM_PROMPT = `You are an expert content reviewer tasked with approving or denying content based on specific criteria.
+
+Your role is to:
+1. Carefully evaluate the content against the provided criteria
+2. Make a clear decision to approve or deny the content
+3. Provide a detailed explanation for your decision
+4. If denying, offer specific suggestions for improvement
+
+Be objective, thorough, and fair in your assessment.`;
+
+/**
+ * Approves or denies content based on a prompt or message history
+ *
+ * @example
+ * // Approve or deny a code file
+ * const result = await Approve("code-approval", {
+ *   content: await alchemy`
+ *     Review this API implementation:
+ *     ${alchemy.file("src/api.ts")}
+ *   `,
+ *   prompt: "Approve this code if it follows security best practices and has proper error handling."
+ * });
+ *
+ * if (result.approved) {
+ *   console.log("Content approved:", result.explanation);
+ * } else {
+ *   console.log("Content denied:", result.explanation);
+ *   console.log("Suggestions:", result.suggestions);
+ * }
+ *
+ * @example
+ * // Approve or deny using message history
+ * const result = await Approve("doc-approval-with-history", {
+ *   content: "This is the content to review",
+ *   prompt: "Approve this documentation if it is clear and accurate",
+ *   messages: [
+ *     { role: "user", content: "Can you review this documentation?" },
+ *     { role: "assistant", content: "Yes, I'd be happy to review it." },
+ *     { role: "user", content: "Please check for clarity and accuracy." }
+ *   ]
+ * });
+ */
+export async function Approve(
+  id: string,
+  props: ApproveProps
+): Promise<ApprovalResult> {
+  // Create messages array if not provided
+  const messages =
+    props.messages ||
+    (props.content && props.prompt
+      ? [
+          {
+            role: "user" as const,
+            content: `${props.content}\n\n${props.prompt}`,
+          },
+        ]
+      : []);
+
+  if (messages.length === 0) {
+    throw new Error(
+      "Either messages or both content and prompt must be provided"
+    );
+  }
+
+  const data = await Data(id, {
+    schema: type({
+      approved: "boolean",
+      explanation: "string",
+      suggestions: "string[]?",
+    }),
+    messages,
+    system: props.system || DEFAULT_APPROVE_SYSTEM_PROMPT,
+    temperature: props.temperature ?? 0.2,
+  });
+
+  // Return the result with updated messages from Data
+  return {
+    ...data.object,
+    messages: data.messages,
+  };
+}

package/src/ai/astro-file.ts

@@ -1,11 +1,9 @@
 import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
 import prettier from "prettier";
 import type { Context } from "../context";
+import { StaticAstroFile } from "../fs/static-astro-file";
 import { Resource } from "../resource";
 import type { Secret } from "../secret";
-import { ignore } from "../util/ignore";
 import { type ModelConfig, createModel } from "./client";
 
 /**
@@ -161,20 +159,10 @@ export const AstroFile = Resource(
   async function (
     this: Context<AstroFile>,
     id: string,
-    props: AstroFileProps,
+    props: AstroFileProps
   ): Promise<AstroFile> {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
-
+    // Handle deletion phase
     if (this.phase === "delete") {
-      try {
-        await fs.unlink(props.path);
-      } catch (error: any) {
-        // Ignore if file doesn't exist
-        if (error.code !== "ENOENT") {
-          throw error;
-        }
-      }
       return this.destroy();
     }
 
@@ -213,7 +201,7 @@ export const AstroFile = Resource(
 
       if (retryResult.error) {
         throw new Error(
-          `Failed to generate valid Astro code: ${retryResult.error}`,
+          `Failed to generate valid Astro code: ${retryResult.error}`
         );
       }
 
@@ -235,24 +223,17 @@ export const AstroFile = Resource(
       console.warn("Failed to format Astro code with Prettier:", error);
     }
 
-    if (this.phase === "update" && props.path !== this.props.path) {
-      await ignore("ENOENT", () => fs.unlink(this.props.path));
-    }
-
-    // Write content to file
-    await fs.writeFile(props.path, code);
-
-    // Get file stats for timestamps
-    const stats = await fs.stat(props.path);
+    // Use StaticAstroFile to create/update the file
+    const file = await StaticAstroFile("file", props.path, code);
 
     // Return the resource
     return this({
       ...props,
-      content: code,
-      createdAt: stats.birthtimeMs,
-      updatedAt: stats.mtimeMs,
+      content: file.content,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
     });
-  },
+  }
 );
 
 /**
@@ -263,7 +244,7 @@ export const AstroFile = Resource(
  * @returns The extracted Astro code or error message
  */
 async function extractAstroCode(
-  text: string,
+  text: string
 ): Promise<{ code: string; error?: string }> {
   const astroCodeRegex = /```astro\s*([\s\S]*?)```/g;
   const matches = Array.from(text.matchAll(astroCodeRegex));

package/src/ai/client.ts

@@ -56,3 +56,62 @@ export function createModel(config: ClientConfig) {
     return openai(config.model?.id ?? "gpt-4o");
   }
 }
+
+/**
+ * Maximum time to retry in milliseconds (5 minutes)
+ */
+const MAX_RETRY_TIME = 5 * 60 * 1000;
+
+/**
+ * Initial delay between retries in milliseconds
+ */
+const INITIAL_RETRY_DELAY = 1000;
+
+/**
+ * Maximum number of retries
+ */
+const MAX_RETRIES = 10;
+
+/**
+ * Handles rate limiting with exponential backoff
+ * @param fn Function to retry
+ * @returns Result of the function
+ * @throws Error if max retries or time is exceeded
+ */
+export async function withRateLimitRetry<T>(fn: () => Promise<T>): Promise<T> {
+  let retryCount = 0;
+  let lastError: Error | null = null;
+  let startTime = Date.now();
+
+  while (true) {
+    try {
+      return await fn();
+    } catch (error: any) {
+      lastError = error;
+
+      console.log("retry error", error);
+
+      // Check if we should retry
+      const isRateLimit = error.statusCode === 429;
+      const timeElapsed = Date.now() - startTime;
+      const shouldRetry =
+        isRateLimit && retryCount < MAX_RETRIES && timeElapsed < MAX_RETRY_TIME;
+
+      if (!shouldRetry) {
+        throw error;
+      }
+
+      // Calculate delay with exponential backoff
+      const delay = Math.min(
+        INITIAL_RETRY_DELAY * Math.pow(2, retryCount),
+        MAX_RETRY_TIME - timeElapsed
+      );
+
+      console.log(`Retrying in ${delay}ms`);
+
+      // Wait before retrying
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      retryCount++;
+    }
+  }
+}

package/src/ai/css-file.ts

@@ -1,10 +1,8 @@
 import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
 import type { Context } from "../context";
+import { StaticCSSFile } from "../fs/static-css-file";
 import { Resource } from "../resource";
 import type { Secret } from "../secret";
-import { ignore } from "../util/ignore";
 import { type ModelConfig, createModel } from "./client";
 
 /**
@@ -154,20 +152,10 @@ export const CSSFile = Resource(
   async function (
     this: Context<CSSFile>,
     id: string,
-    props: CSSFileProps,
+    props: CSSFileProps
   ): Promise<CSSFile> {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
-
+    // Handle deletion phase
     if (this.phase === "delete") {
-      try {
-        await fs.unlink(props.path);
-      } catch (error: any) {
-        // Ignore if file doesn't exist
-        if (error.code !== "ENOENT") {
-          throw error;
-        }
-      }
       return this.destroy();
     }
 
@@ -206,31 +194,24 @@ export const CSSFile = Resource(
 
       if (retryResult.error) {
         throw new Error(
-          `Failed to generate valid CSS code: ${retryResult.error}\n${retryText}`,
+          `Failed to generate valid CSS code: ${retryResult.error}\n${retryText}`
         );
       }
 
       code = retryResult.code;
     }
 
-    if (this.phase === "update" && props.path !== this.props.path) {
-      await ignore("ENOENT", () => fs.unlink(this.props.path));
-    }
-
-    // Write content to file
-    await fs.writeFile(props.path, code);
-
-    // Get file stats for timestamps
-    const stats = await fs.stat(props.path);
+    // Use StaticCSSFile to create/update the file
+    const file = await StaticCSSFile("file", props.path, code);
 
     // Return the resource
     return this({
       ...props,
-      content: code,
-      createdAt: stats.birthtimeMs,
-      updatedAt: stats.mtimeMs,
+      content: file.content,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
     });
-  },
+  }
 );
 
 /**
@@ -241,7 +222,7 @@ export const CSSFile = Resource(
  * @returns The extracted CSS code or error message
  */
 async function extractCSSCode(
-  text: string,
+  text: string
 ): Promise<{ code: string; error?: string }> {
   const cssCodeRegex = /```css\s*([\s\S]*?)```/g;
   const matches = Array.from(text.matchAll(cssCodeRegex));

package/src/ai/data.ts

@@ -1,10 +1,10 @@
-import { generateObject } from "ai";
+import { generateObject, type CoreMessage } from "ai";
 import type { JsonSchema, Type, type } from "arktype";
 import type { Context } from "../context";
 import { Resource } from "../resource";
 import type { Secret } from "../secret";
 import { ark } from "./ark";
-import { type ModelConfig, createModel } from "./client";
+import { createModel, type ModelConfig } from "./client";
 
 /**
  * Properties for creating or updating an AI Object
@@ -24,7 +24,13 @@ export interface DataProps<T extends Type<any, any>> {
    *   ${alchemy.file("src/data.ts")}
    * `
    */
-  prompt: string;
+  prompt?: string;
+
+  /**
+   * Message history for the conversation
+   * If provided, this will be used instead of the prompt
+   */
+  messages?: CoreMessage[];
 
   /**
    * System prompt to guide the AI's behavior
@@ -70,6 +76,11 @@ export interface Data<T> extends Resource<"ai::Object"> {
    */
   object: T;
 
+  /**
+   * Updated message history with the AI's response appended
+   */
+  messages: CoreMessage[];
+
   /**
    * Time at which the content was generated
    */
@@ -127,28 +138,23 @@ export interface Data<T> extends Resource<"ai::Object"> {
  * });
  *
  * @example
- * // Using specific model configuration with advanced options
- * const analysisSchema = type({
- *   insights: "string[]",
- *   recommendations: "string[]",
- *   risk: "'low'|'medium'|'high'"
+ * // Using message history for iterative generation
+ * const feedbackSchema = type({
+ *   rating: "number",
+ *   positives: "string[]",
+ *   improvements: "string[]",
+ *   summary: "string"
  * });
  *
- * const analysis = await Data("code-analysis", {
- *   schema: analysisSchema,
- *   prompt: await alchemy`
- *     Analyze this code for security issues:
- *     ${alchemy.file("src/auth/login.ts")}
- *   `,
- *   system: "You are a security expert specializing in code analysis",
- *   model: {
- *     id: "o3-mini",
- *     provider: "openai",
- *     options: {
- *       reasoningEffort: "high"
- *     }
- *   },
- *   temperature: 0.1
+ * const feedback = await Data("product-feedback", {
+ *   schema: feedbackSchema,
+ *   messages: [
+ *     { role: "user", content: "I'd like feedback on my product design" },
+ *     { role: "assistant", content: "I'd be happy to provide feedback. What's your product?" },
+ *     { role: "user", content: "It's a new smart home device that..." }
+ *   ],
+ *   system: "You are a product design expert providing structured feedback",
+ *   temperature: 0.3
  * });
  */
 export const Data = Resource("ai::Object", async function <
@@ -160,6 +166,14 @@ export const Data = Resource("ai::Object", async function <
     return this.destroy();
   }
 
+  // Validate that either prompt or messages is provided
+  if (!props.prompt && !props.messages) {
+    throw new Error("Either prompt or messages must be provided");
+  }
+
+  // Create messages array if only prompt is provided
+  const messages = props.messages || [{ role: "user", content: props.prompt! }];
+
   // Generate structured output using generateObject
   const { object } = await generateObject({
     model: createModel(props),
@@ -170,17 +184,28 @@ export const Data = Resource("ai::Object", async function <
     system:
       props.system ||
       "You are an AI assistant tasked with generating structured content.",
-    prompt: props.prompt,
+    messages,
     ...(props.temperature === undefined
       ? {}
       : // some models error if you provide it (rather than ignoring it)
         { temperature: props.temperature }),
   });
 
-  // Return the resource with typed content
+  // Create updated message history with the structured response
+  const responseText = JSON.stringify(object);
+  const updatedMessages = [
+    ...messages,
+    {
+      role: "assistant" as const,
+      content: responseText,
+    },
+  ];
+
+  // Return the resource with typed content and updated messages
   return this({
     type: props.schema,
     object: object,
+    messages: updatedMessages,
     createdAt: Date.now(),
   });
 });