alchemy 0.2.5 → 0.3.1

package/src/ai/document.ts

@@ -1,15 +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 {
-  type ModelConfig,
-  createClient,
-  getModelId,
-  getModelOptions,
-} from "./client";
+import { createModel, withRateLimitRetry, type ModelConfig } from "./client";
 
 /**
  * Properties for creating or updating a Document
@@ -21,9 +15,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
@@ -40,7 +35,27 @@ 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
+   * The default system prompt instructs the model to return a single markdown document inside ```md fences
+   * @default "You are a technical documentation writer. Create a single markdown document based on the user's requirements. Your response MUST include only a single markdown document inside ```md fences. Do not include any other text, explanations, or multiple code blocks."
+   */
+  system?: string;
 
   /**
    * OpenAI API key to use for generating content
@@ -52,6 +67,21 @@ export interface DocumentProps {
    * Model configuration
    */
   model?: ModelConfig;
+
+  /**
+   * 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.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;
 }
 
 /**
@@ -63,6 +93,11 @@ export interface Document extends DocumentProps, Resource<"docs::Document"> {
    */
   content: string;
 
+  /**
+   * Updated message history with the document response appended
+   */
+  messages: CoreMessage[];
+
   /**
    * Time at which the document was created
    */
@@ -72,48 +107,101 @@ 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;
 }
 
+/**
+ * Default system prompt for markdown document generation
+ */
+const DEFAULT_MD_SYSTEM_PROMPT =
+  "You are a technical documentation writer. Create a single markdown document based on the user's requirements. Your response MUST include only a single markdown document inside ```md fences. Do not include any other text, explanations, or multiple code blocks.";
+
 /**
  * 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",
  *   prompt: await alchemy`
  *     Generate API documentation based on these source files:
  *     ${alchemy.file("src/api.ts")}
  *     ${alchemy.file("src/types.ts")}
- *   `
- *   // The above will automatically append the file contents as code blocks:
- *   //
- *   // Generate API documentation based on these source files:
- *   // [api.ts](src/api.ts)
- *   // [types.ts](src/types.ts)
- *   //
- *   // // src/api.ts
- *   // ```ts
- *   // ... contents of api.ts ...
- *   // ```
- *   //
- *   // // src/types.ts
- *   // ```ts
- *   // ... contents of types.ts ...
- *   // ```
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @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
+ * // Use alchemy template literals with file collections and temperature control
  * const modelDocs = await Document("models", {
+ *   title: "Data Models",
  *   path: "./docs/models.md",
  *   prompt: await alchemy`
  *     Write documentation for these data models:
  *     ${alchemy.files("src/models/user.ts", "src/models/post.ts")}
- *   `
- *   // This creates a prompt with all files appended as code blocks,
- *   // automatically handling syntax highlighting based on file extensions
+ *   `,
+ *   temperature: 0.2 // Lower temperature for more deterministic output
+ * });
+ *
+ * @example
+ * // Advanced model configuration with custom provider options and custom system prompt
+ * const techDocs = await Document("tech-specs", {
+ *   title: "Technical Specifications",
+ *   path: "./docs/tech-specs.md",
+ *   prompt: await alchemy`
+ *     Create detailed technical specifications based on these requirements:
+ *     ${alchemy.file("requirements/system.md")}
+ *   `,
+ *   system: "You are an expert technical writer specializing in system specifications. Create a single markdown document inside ```md fences with no additional text.",
+ *   model: {
+ *     id: "o3-mini",
+ *     provider: "openai",
+ *     options: {
+ *       reasoningEffort: "high"
+ *     }
+ *   },
+ *   temperature: 0.1
  * });
  */
 export const Document = Resource(
@@ -121,45 +209,135 @@ 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();
     }
 
-    // Initialize OpenAI compatible provider using shared client
-    const provider = createClient(props);
+    // Use provided system prompt or default
+    const system = props.system || DEFAULT_MD_SYSTEM_PROMPT;
 
-    // Generate content
-    const { text } = await generateText({
-      model: provider(getModelId(props)),
-      prompt: props.prompt,
-      ...getModelOptions(props),
+    // 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 }),
+      });
     });
 
-    // Write content to file
-    await fs.writeFile(props.path, text);
+    // Extract and validate markdown content
+    let { content, error } = extractMarkdownContent(text);
 
-    // Get file stats for timestamps
-    const stats = await fs.stat(props.path);
+    // 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.`;
 
-    // Return the resource
-    return this({
+      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 = extractMarkdownContent(retryText);
+
+      if (retryResult.error) {
+        throw new Error(
+          `Failed to generate valid markdown content: ${retryResult.error}`
+        );
+      }
+
+      content = retryResult.content;
+    }
+
+    // Create result object
+    const result: Partial<Document> = {
       ...props,
-      content: text,
-      createdAt: stats.birthtimeMs,
-      updatedAt: stats.mtimeMs,
-    });
-  },
+      content,
+      messages: [
+        ...(props.messages || [{ role: "user", content: props.prompt! }]),
+        { role: "assistant", content },
+      ],
+      createdAt: this.output?.createdAt || Date.now(),
+      updatedAt: Date.now(),
+    };
+
+    // Write file if path is provided
+    if (props.path) {
+      const filePath = props.path;
+      const fileId = `${id}-file`;
+
+      result.file = await StaticTextFile(fileId, filePath, content);
+    }
+
+    // Return the resource
+    return this(result as Document);
+  }
 );
+
+/**
+ * Extracts markdown content from between ```md fences
+ * Validates that exactly one markdown code block exists
+ *
+ * @param text The text to extract markdown content from
+ * @returns The extracted markdown content or error message
+ */
+function extractMarkdownContent(text: string): {
+  content: string;
+  error?: string;
+} {
+  const lines = text.split("\n");
+  const startIdx = lines.findIndex((line) => line.trim() === "```md");
+
+  if (startIdx === -1) {
+    return {
+      content: "",
+      error:
+        "No markdown code block found in the response. Please include your markdown content within ```md fences.",
+    };
+  }
+
+  const rest = lines.slice(startIdx + 1);
+  const endRelativeIdx = rest
+    .map((line) => line.trim() === "```")
+    .lastIndexOf(true);
+
+  if (endRelativeIdx === -1) {
+    return {
+      content: "",
+      error: "Markdown block was not closed properly.",
+    };
+  }
+
+  const endIdx = startIdx + 1 + endRelativeIdx;
+
+  const content = lines
+    .slice(startIdx + 1, endIdx)
+    .join("\n")
+    .trim();
+
+  return { content };
+}

package/src/ai/html-file.ts

@@ -0,0 +1,244 @@
+import { generateText } from "ai";
+import type { Context } from "../context";
+import { StaticHTMLFile } from "../fs/static-html-file";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { type ModelConfig, createModel } from "./client";
+
+/**
+ * Properties for creating or updating an HTMLFile
+ */
+export interface HTMLFileProps {
+  /**
+   * Path to the HTML file
+   */
+  path: string;
+
+  /**
+   * Base URL for the OpenAI API
+   * @default 'https://api.openai.com/v1'
+   */
+  baseURL?: string;
+
+  /**
+   * Prompt for generating content
+   * Use alchemy template literals to include file context:
+   * @example
+   * prompt: await alchemy`
+   *   Generate an HTML page using:
+   *   ${alchemy.file("src/templates/base.html")}
+   * `
+   */
+  prompt: string;
+
+  /**
+   * System prompt for the model
+   * This is used to provide instructions to the model about how to format the response
+   * The default system prompt instructs the model to return HTML code inside ```html fences
+   * @default "You are an HTML code generator. Create HTML code based on the user's requirements. Your response MUST include only HTML code inside ```html fences. Do not include any other text, explanations, or multiple code blocks."
+   */
+  system?: string;
+
+  /**
+   * OpenAI API key to use for generating content
+   * If not provided, will use OPENAI_API_KEY environment variable
+   */
+  apiKey?: Secret;
+
+  /**
+   * Model configuration
+   */
+  model?: ModelConfig;
+
+  /**
+   * 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.7
+   */
+  temperature?: number;
+}
+
+/**
+ * An HTML file that can be created, updated, and deleted
+ */
+export interface HTMLFile extends HTMLFileProps, Resource<"ai::HTMLFile"> {
+  /**
+   * Content of the HTML file
+   */
+  content: string;
+
+  /**
+   * Time at which the file was created
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the file was last updated
+   */
+  updatedAt: number;
+}
+
+/**
+ * Default system prompt for HTML file generation
+ */
+const DEFAULT_HTML_SYSTEM_PROMPT =
+  "You are an HTML code generator. Create HTML code based on the user's requirements. Your response MUST include only HTML code inside ```html fences. Do not include any other text, explanations, or multiple code blocks.";
+
+/**
+ * Resource for generating HTML files using AI models.
+ * Extracts HTML code from between ```html fences and validates the response.
+ *
+ * @example
+ * // Create a simple landing page
+ * const landingPage = await HTMLFile("landing-page", {
+ *   path: "./public/index.html",
+ *   prompt: await alchemy`
+ *     Generate a modern landing page for a SaaS product with:
+ *     - Hero section with headline and call-to-action
+ *     - Features section with 3 key features
+ *     - Pricing section with 3 tiers
+ *     - Testimonials section with 2 customer quotes
+ *     - Contact form and footer
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate an HTML email template
+ * const emailTemplate = await HTMLFile("welcome-email", {
+ *   path: "./emails/welcome.html",
+ *   prompt: await alchemy`
+ *     Create an HTML email template for welcoming new users to our platform.
+ *     The email should include:
+ *     - Company logo and branding
+ *     - Personalized welcome message (use {{name}} placeholder)
+ *     - Three steps to get started
+ *     - Support contact information
+ *     - Unsubscribe footer
+ *
+ *     Make sure it's responsive and works in all major email clients.
+ *   `,
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Generate an HTML component with custom system prompt
+ * const navComponent = await HTMLFile("navigation", {
+ *   path: "./components/nav.html",
+ *   prompt: await alchemy`
+ *     Create a responsive navigation component with:
+ *     - Logo in the left corner
+ *     - Navigation links: Home, Products, Services, About, Contact
+ *     - Mobile hamburger menu that expands/collapses
+ *     - Login/signup buttons on the right side
+ *     - Dark/light mode toggle
+ *   `,
+ *   system: "You are an expert HTML/CSS developer specializing in responsive components. Create a single HTML file inside ```html fences with no additional text. Use modern HTML5 semantic elements and inline CSS if needed.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export const HTMLFile = Resource(
+  "ai::HTMLFile",
+  async function (
+    this: Context<HTMLFile>,
+    id: string,
+    props: HTMLFileProps
+  ): Promise<HTMLFile> {
+    // Handle deletion phase
+    if (this.phase === "delete") {
+      return this.destroy();
+    }
+
+    // Use provided system prompt or default
+    const system = props.system || DEFAULT_HTML_SYSTEM_PROMPT;
+
+    // Generate initial content
+    const { text } = await generateText({
+      model: createModel(props),
+      prompt: props.prompt,
+      system,
+      providerOptions: props.model?.options,
+      ...(props.temperature === undefined
+        ? {}
+        : { temperature: props.temperature }),
+    });
+
+    // Extract and validate HTML code
+    let { code, error } = await extractHTMLCode(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 HTML code block inside \`\`\`html 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 retryResult = await extractHTMLCode(retryText);
+
+      if (retryResult.error) {
+        throw new Error(
+          `Failed to generate valid HTML code: ${retryResult.error}`
+        );
+      }
+
+      code = retryResult.code;
+    }
+
+    // Use StaticHTMLFile to create/update the file
+    const file = await StaticHTMLFile("file", props.path, code);
+
+    // Return the resource
+    return this({
+      ...props,
+      content: file.content,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+  }
+);
+
+/**
+ * Extracts HTML code from between ```html fences
+ * Validates that exactly one HTML code block exists
+ *
+ * @param text The text to extract HTML code from
+ * @returns The extracted HTML code or error message
+ */
+async function extractHTMLCode(
+  text: string
+): Promise<{ code: string; error?: string }> {
+  const htmlCodeRegex = /```html\s*([\s\S]*?)```/g;
+  const matches = Array.from(text.matchAll(htmlCodeRegex));
+
+  if (matches.length === 0) {
+    return {
+      code: "",
+      error:
+        "No HTML code block found in the response. Please include your code within ```html fences.",
+    };
+  }
+
+  if (matches.length > 1) {
+    return {
+      code: "",
+      error:
+        "Multiple HTML code blocks found in the response. Please provide exactly one code block within ```html fences.",
+    };
+  }
+
+  return { code: matches[0][1].trim() };
+}

package/src/ai/index.ts

@@ -1,3 +1,12 @@
+export * from "./approve";
 export * from "./ark";
+export * from "./astro-file";
+export * from "./css-file";
 export * from "./data";
 export * from "./document";
+export * from "./html-file";
+export * from "./json-file";
+export * from "./review";
+export * from "./typescript-file";
+export * from "./vue-file";
+export * from "./yaml-file";