alchemy 0.3.0 → 0.4.0

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(),
   });
 });

package/src/ai/document.ts

@@ -1,11 +1,9 @@
-import { generateText } from "ai";
-import fs from "node:fs/promises";
-import path from "node:path";
+import { generateText, 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 { ignore } from "../util/ignore";
-import { type ModelConfig, createModel } from "./client";
+import { createModel, withRateLimitRetry, type ModelConfig } from "./client";
 
 /**
  * Properties for creating or updating a Document
@@ -13,13 +11,16 @@ import { type ModelConfig, createModel } from "./client";
 export interface DocumentProps {
   /**
    * Title of the document
+   *
+   * @default id
    */
-  title: string;
+  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
@@ -36,7 +37,19 @@ 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
@@ -64,17 +77,40 @@ 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;
+
+  /**
+   * Freeze the document after creation (do not re-generate on updates)
+   * @default false
+   */
+  freeze?: boolean;
 }
 
 /**
  * A markdown document that can be created, updated, and deleted
  */
 export interface Document extends DocumentProps, Resource<"docs::Document"> {
+  /**
+   * The title of the document
+   */
+  title: string;
+
   /**
    * Content of the document
    */
   content: string;
 
+  /**
+   * Updated message history with the document response appended
+   */
+  messages: CoreMessage[];
+
   /**
    * Time at which the document was created
    */
@@ -84,6 +120,11 @@ 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;
 }
 
 /**
@@ -97,7 +138,22 @@ const DEFAULT_MD_SYSTEM_PROMPT =
  * 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",
@@ -113,6 +169,23 @@ const DEFAULT_MD_SYSTEM_PROMPT =
  * });
  *
  * @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",
@@ -149,84 +222,104 @@ export const Document = Resource(
   async function (
     this: Context<Document>,
     id: string,
-    props: DocumentProps,
+    props: DocumentProps
   ): Promise<Document> {
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    // Validate that either prompt or messages are provided
+    if (!props.prompt && !props.messages) {
+      throw new Error("Either prompt or messages must be provided");
+    }
 
+    // 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();
     }
 
+    if (this.phase === "update" && props.freeze) {
+      if (props.path) {
+        const filePath = props.path;
+        const fileId = `${id}-file`;
+
+        await StaticTextFile(fileId, filePath, this.output!.content);
+      }
+      return this(this.output);
+    }
+
     // Use provided system prompt or default
     const system = props.system || DEFAULT_MD_SYSTEM_PROMPT;
 
-    // Generate initial content
-    const { text } = await generateText({
-      model: createModel(props),
-      prompt: props.prompt,
-      system,
-      providerOptions: props.model?.options,
-      ...(props.temperature === undefined
-        ? {}
-        : // some models error if you provide it (rather than ignoring it)
-          { temperature: props.temperature }),
+    // Generate initial content with rate limit retry
+    const { text } = await withRateLimitRetry(async () => {
+      return generateText({
+        model: createModel(props),
+        ...(props.messages
+          ? { messages: props.messages }
+          : { prompt: props.prompt! }),
+        system,
+        maxTokens: props.maxTokens || 8192,
+        providerOptions: props.model?.options,
+        ...(props.temperature === undefined
+          ? {}
+          : // some models error if you provide it (rather than ignoring it)
+            { temperature: props.temperature }),
+      });
     });
 
     // Extract and validate markdown content
-    let { content, error } = await extractMarkdownContent(text);
+    let { content, error } = extractMarkdownContent(text);
 
     // Re-prompt if there are validation errors
     if (error) {
       const errorSystem = `${system}\n\nERROR: ${error}\n\nPlease try again and ensure your response contains exactly one markdown document inside \`\`\`md fences.`;
 
-      const { text: retryText } = await generateText({
-        model: createModel(props),
-        prompt: props.prompt,
-        system: errorSystem,
-        providerOptions: props.model?.options,
-        ...(props.temperature === undefined
-          ? {}
-          : { temperature: props.temperature }),
+      const { text: retryText } = await withRateLimitRetry(async () => {
+        return generateText({
+          model: createModel(props),
+          ...(props.messages
+            ? { messages: props.messages }
+            : { prompt: props.prompt! }),
+          system: errorSystem,
+          providerOptions: props.model?.options,
+          ...(props.temperature === undefined
+            ? {}
+            : { temperature: props.temperature }),
+        });
       });
 
-      const retryResult = await extractMarkdownContent(retryText);
+      const retryResult = extractMarkdownContent(retryText);
 
       if (retryResult.error) {
         throw new Error(
-          `Failed to generate valid markdown content: ${retryResult.error}`,
+          `Failed to generate valid markdown content: ${retryResult.error}\n${retryText}`
         );
       }
 
       content = retryResult.content;
     }
 
-    if (this.phase === "update" && props.path !== this.props.path) {
-      await ignore("ENOENT", () => fs.unlink(this.props.path));
-    }
+    // Create result object
+    const result: Partial<Document> = {
+      ...props,
+      content,
+      messages: [
+        ...(props.messages || [{ role: "user", content: props.prompt! }]),
+        { role: "assistant", content },
+      ],
+      createdAt: this.output?.createdAt || Date.now(),
+      updatedAt: Date.now(),
+      title: props.title || id,
+    };
 
-    // Write content to file
-    await fs.writeFile(props.path, content);
+    // Write file if path is provided
+    if (props.path) {
+      const filePath = props.path;
+      const fileId = `${id}-file`;
 
-    // Get file stats for timestamps
-    const stats = await fs.stat(props.path);
+      result.file = await StaticTextFile(fileId, filePath, content);
+    }
 
     // Return the resource
-    return this({
-      ...props,
-      content: content,
-      createdAt: stats.birthtimeMs,
-      updatedAt: stats.mtimeMs,
-    });
-  },
+    return this(result as Document);
+  }
 );
 
 /**
@@ -236,13 +329,14 @@ export const Document = Resource(
  * @param text The text to extract markdown content from
  * @returns The extracted markdown content or error message
  */
-async function extractMarkdownContent(
-  text: string,
-): Promise<{ content: string; error?: string }> {
-  const mdCodeRegex = /```md\s*([\s\S]*?)```/g;
-  const matches = Array.from(text.matchAll(mdCodeRegex));
+function extractMarkdownContent(text: string): {
+  content: string;
+  error?: string;
+} {
+  const lines = text.split("\n");
+  const startIdx = lines.findIndex((line) => line.trim() === "```md");
 
-  if (matches.length === 0) {
+  if (startIdx === -1) {
     return {
       content: "",
       error:
@@ -250,13 +344,24 @@ async function extractMarkdownContent(
     };
   }
 
-  if (matches.length > 1) {
+  const rest = lines.slice(startIdx + 1);
+  const endRelativeIdx = rest
+    .map((line) => line.trim() === "```")
+    .lastIndexOf(true);
+
+  if (endRelativeIdx === -1) {
     return {
       content: "",
-      error:
-        "Multiple markdown code blocks found in the response. Please provide exactly one markdown block within ```md fences.",
+      error: "Markdown block was not closed properly.",
     };
   }
 
-  return { content: matches[0][1].trim() };
+  const endIdx = startIdx + 1 + endRelativeIdx;
+
+  const content = lines
+    .slice(startIdx + 1, endIdx)
+    .join("\n")
+    .trim();
+
+  return { content };
 }

package/src/ai/html-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 { StaticHTMLFile } from "../fs/static-html-file";
 import { Resource } from "../resource";
 import type { Secret } from "../secret";
-import { ignore } from "../util/ignore";
 import { type ModelConfig, createModel } from "./client";
 
 /**
@@ -151,20 +149,10 @@ export const HTMLFile = Resource(
   async function (
     this: Context<HTMLFile>,
     id: string,
-    props: HTMLFileProps,
+    props: HTMLFileProps
   ): Promise<HTMLFile> {
-    // 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();
     }
 
@@ -203,31 +191,24 @@ export const HTMLFile = Resource(
 
       if (retryResult.error) {
         throw new Error(
-          `Failed to generate valid HTML code: ${retryResult.error}`,
+          `Failed to generate valid HTML code: ${retryResult.error}`
         );
       }
 
       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 StaticHTMLFile to create/update the file
+    const file = await StaticHTMLFile("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(),
     });
-  },
+  }
 );
 
 /**
@@ -238,7 +219,7 @@ export const HTMLFile = Resource(
  * @returns The extracted HTML code or error message
  */
 async function extractHTMLCode(
-  text: string,
+  text: string
 ): Promise<{ code: string; error?: string }> {
   const htmlCodeRegex = /```html\s*([\s\S]*?)```/g;
   const matches = Array.from(text.matchAll(htmlCodeRegex));