alchemy 0.3.0 → 0.3.1

package/lib/ai/approve.d.ts

@@ -0,0 +1,99 @@
+import type { CoreMessage } from "ai";
+/**
+ * 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;
+/**
+ * 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 declare function Approve(id: string, props: ApproveProps): Promise<ApprovalResult>;

package/lib/ai/approve.js

@@ -0,0 +1,76 @@
+import { type } from "arktype";
+import { Data } from "./data";
+/**
+ * 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, props) {
+    // Create messages array if not provided
+    const messages = props.messages ||
+        (props.content && props.prompt
+            ? [
+                {
+                    role: "user",
+                    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/lib/ai/astro-file.js

@@ -1,9 +1,7 @@
 import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
 import prettier from "prettier";
+import { StaticAstroFile } from "../fs/static-astro-file";
 import { Resource } from "../resource";
-import { ignore } from "../util/ignore";
 import { createModel } from "./client";
 /**
  * Default system prompt for Astro file generation
@@ -72,18 +70,8 @@ const DEFAULT_ASTRO_SYSTEM_PROMPT = "You are an Astro component generator. Creat
  * });
  */
 export const AstroFile = Resource("ai::AstroFile", async function (id, props) {
-    // 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) {
-            // Ignore if file doesn't exist
-            if (error.code !== "ENOENT") {
-                throw error;
-            }
-        }
         return this.destroy();
     }
     // Use provided system prompt or default
@@ -132,19 +120,14 @@ export const AstroFile = Resource("ai::AstroFile", async function (id, props) {
         // If Prettier formatting fails, just use the unformatted code
         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(),
     });
 });
 /**

package/lib/ai/client.d.ts

@@ -41,3 +41,10 @@ export interface ClientConfig {
  * Creates an OpenAI-compatible client with the given configuration
  */
 export declare function createModel(config: ClientConfig): import("ai").LanguageModelV1;
+/**
+ * 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 declare function withRateLimitRetry<T>(fn: () => Promise<T>): Promise<T>;

package/lib/ai/client.js

@@ -11,3 +11,48 @@ export function createModel(config) {
         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(fn) {
+    let retryCount = 0;
+    let lastError = null;
+    let startTime = Date.now();
+    while (true) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            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/lib/ai/css-file.js

@@ -1,8 +1,6 @@
 import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
+import { StaticCSSFile } from "../fs/static-css-file";
 import { Resource } from "../resource";
-import { ignore } from "../util/ignore";
 import { createModel } from "./client";
 /**
  * Default system prompt for CSS file generation
@@ -71,18 +69,8 @@ const DEFAULT_CSS_SYSTEM_PROMPT = "You are a CSS code generator. Create CSS code
  * });
  */
 export const CSSFile = Resource("ai::CSSFile", async function (id, props) {
-    // 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) {
-            // Ignore if file doesn't exist
-            if (error.code !== "ENOENT") {
-                throw error;
-            }
-        }
         return this.destroy();
     }
     // Use provided system prompt or default
@@ -117,19 +105,14 @@ export const CSSFile = Resource("ai::CSSFile", async function (id, props) {
         }
         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(),
     });
 });
 /**

package/lib/ai/data.d.ts

@@ -1,3 +1,4 @@
+import { type CoreMessage } from "ai";
 import type { JsonSchema, Type, type } from "arktype";
 import type { Context } from "../context";
 import { Resource } from "../resource";
@@ -20,7 +21,12 @@ 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
      * @example
@@ -58,6 +64,10 @@ export interface Data<T> extends Resource<"ai::Object"> {
      * The generated content, typed according to the provided schema
      */
     object: T;
+    /**
+     * Updated message history with the AI's response appended
+     */
+    messages: CoreMessage[];
     /**
      * Time at which the content was generated
      */
@@ -114,28 +124,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 declare const Data: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | (<const T extends Type<any, any>>(this: Context<Data<any>>, id: string, props: DataProps<T>) => Promise<Data<type.infer<T>>>);

package/lib/ai/data.js

@@ -53,34 +53,35 @@ import { createModel } from "./client";
  * });
  *
  * @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 (id, props) {
     if (this.phase === "delete") {
         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),
@@ -90,16 +91,26 @@ export const Data = Resource("ai::Object", async function (id, props) {
         providerOptions: props.model?.options,
         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",
+            content: responseText,
+        },
+    ];
+    // Return the resource with typed content and updated messages
     return this({
         type: props.schema,
         object: object,
+        messages: updatedMessages,
         createdAt: Date.now(),
     });
 });

package/lib/ai/document.d.ts

@@ -1,4 +1,6 @@
+import { type CoreMessage } from "ai";
 import type { Context } from "../context";
+import { StaticTextFile } from "../fs/static-text-file";
 import { Resource } from "../resource";
 import type { Secret } from "../secret";
 import { type ModelConfig } from "./client";
@@ -11,9 +13,10 @@ export interface DocumentProps {
      */
     title: string;
     /**
-     * Path to the markdown document
+     * Optional path to the markdown document
+     * If provided, document will be written to this path
      */
-    path: string;
+    path?: string;
     /**
      * Base URL for the OpenAI API
      * @default 'https://api.openai.com/v1'
@@ -28,7 +31,18 @@ export interface DocumentProps {
      *   ${alchemy.file("src/api.ts")}
      * `
      */
-    prompt: string;
+    prompt?: string;
+    /**
+     * Message history for conversation-based generation
+     * If provided, this will be used instead of the prompt
+     * @example
+     * messages: [
+     *   { role: "user", content: "Generate API documentation for this file" },
+     *   { role: "assistant", content: "I'll create detailed API docs. What file should I document?" },
+     *   { role: "user", content: "Please document src/api.ts" }
+     * ]
+     */
+    messages?: CoreMessage[];
     /**
      * System prompt for the model
      * This is used to provide instructions to the model about how to format the response
@@ -52,6 +66,12 @@ export interface DocumentProps {
      * @default 0.7
      */
     temperature?: number;
+    /**
+     * Maximum number of tokens to generate.
+     * Higher values allow for longer documents but may increase cost and generation time.
+     * @default 10000
+     */
+    maxTokens?: number;
 }
 /**
  * A markdown document that can be created, updated, and deleted
@@ -61,6 +81,10 @@ export interface Document extends DocumentProps, Resource<"docs::Document"> {
      * Content of the document
      */
     content: string;
+    /**
+     * Updated message history with the document response appended
+     */
+    messages: CoreMessage[];
     /**
      * Time at which the document was created
      */
@@ -69,13 +93,32 @@ export interface Document extends DocumentProps, Resource<"docs::Document"> {
      * Time at which the document was last updated
      */
     updatedAt: number;
+    /**
+     * File resource if path was provided
+     */
+    file?: StaticTextFile;
 }
 /**
  * Resource for managing AI-generated markdown documents using the Vercel AI SDK.
  * Supports powerful context handling through the alchemy template literal tag.
  *
  * @example
- * // Create a document using alchemy template literals for context
+ * // Create an in-memory document (no file created)
+ * const apiDocs = await Document("api-docs", {
+ *   title: "API Documentation",
+ *   prompt: await alchemy`
+ *     Generate API documentation based on these source files:
+ *     ${alchemy.file("src/api.ts")}
+ *     ${alchemy.file("src/types.ts")}
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Create a document and write it to disk
  * const apiDocs = await Document("api-docs", {
  *   title: "API Documentation",
  *   path: "./docs/api.md",
@@ -91,6 +134,23 @@ export interface Document extends DocumentProps, Resource<"docs::Document"> {
  * });
  *
  * @example
+ * // Use message history for iterative document generation
+ * const apiDocs = await Document("api-docs", {
+ *   title: "API Documentation",
+ *   path: "./docs/api.md",
+ *   messages: [
+ *     { role: "user", content: "Create API documentation for these files" },
+ *     { role: "assistant", content: "I'll help you create API documentation. Please provide the files." },
+ *     { role: "user", content: "Here are the files: [file contents]" }
+ *   ],
+ *   system: "You are a technical documentation writer. Generate clear and concise API documentation.",
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
  * // Use alchemy template literals with file collections and temperature control
  * const modelDocs = await Document("models", {
  *   title: "Data Models",