alchemy 0.2.5 → 0.3.0

package/src/ai/css-file.ts

@@ -0,0 +1,266 @@
+import { generateText } from "ai";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { ignore } from "../util/ignore";
+import { type ModelConfig, createModel } from "./client";
+
+/**
+ * Properties for creating or updating a CSSFile
+ */
+export interface CSSFileProps {
+  /**
+   * Path to the CSS 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 CSS styles for:
+   *   ${alchemy.file("src/components/Button.jsx")}
+   * `
+   */
+  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 CSS code inside ```css fences
+   * @default "You are a CSS code generator. Create CSS code based on the user's requirements. Your response MUST include only CSS code inside ```css 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;
+}
+
+/**
+ * A CSS file that can be created, updated, and deleted
+ */
+export interface CSSFile extends CSSFileProps, Resource<"ai::CSSFile"> {
+  /**
+   * Content of the CSS 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 CSS file generation
+ */
+const DEFAULT_CSS_SYSTEM_PROMPT =
+  "You are a CSS code generator. Create CSS code based on the user's requirements. Your response MUST include only CSS code inside ```css fences. Do not include any other text, explanations, or multiple code blocks.";
+
+/**
+ * Resource for generating CSS files using AI models.
+ * Extracts CSS code from between ```css fences and validates the response.
+ *
+ * @example
+ * // Create styles for a website
+ * const mainStyles = await CSSFile("main-styles", {
+ *   path: "./public/css/main.css",
+ *   prompt: await alchemy`
+ *     Generate modern CSS styles for a company website with:
+ *     - Clean, minimalist design
+ *     - Primary color: #0062ff
+ *     - Secondary color: #6c757d
+ *     - Light gray background
+ *     - Responsive layout for mobile, tablet, and desktop
+ *     - Custom styles for buttons, cards, and navigation
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate CSS based on existing HTML
+ * const componentStyles = await CSSFile("component-styles", {
+ *   path: "./src/styles/component.css",
+ *   prompt: await alchemy`
+ *     Create CSS styles for this HTML component:
+ *     ${alchemy.file("src/components/Card.html")}
+ *
+ *     The styles should be:
+ *     - Modern and clean
+ *     - Include hover effects and transitions
+ *     - Support both light and dark themes
+ *     - Use CSS variables for colors and spacing
+ *   `,
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Generate CSS animation with custom system prompt
+ * const animationStyles = await CSSFile("animations", {
+ *   path: "./src/styles/animations.css",
+ *   prompt: await alchemy`
+ *     Create CSS animations for:
+ *     - Fade in/out
+ *     - Slide in from different directions
+ *     - Pulse effect
+ *     - Bounce effect
+ *     - Scale in/out
+ *     - Rotate
+ *
+ *     Each animation should be reusable via class names.
+ *   `,
+ *   system: "You are an expert CSS animator. Create a single CSS file inside ```css fences with no additional text. Use modern CSS animation techniques and include vendor prefixes where needed for browser compatibility.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   }
+ * });
+ */
+export const CSSFile = Resource(
+  "ai::CSSFile",
+  async function (
+    this: Context<CSSFile>,
+    id: string,
+    props: CSSFileProps,
+  ): Promise<CSSFile> {
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(props.path), { recursive: true });
+
+    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();
+    }
+
+    // Use provided system prompt or default
+    const system = props.system || DEFAULT_CSS_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 CSS code
+    let { code, error } = await extractCSSCode(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 CSS code block inside \`\`\`css 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 extractCSSCode(retryText);
+
+      if (retryResult.error) {
+        throw new Error(
+          `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);
+
+    // Return the resource
+    return this({
+      ...props,
+      content: code,
+      createdAt: stats.birthtimeMs,
+      updatedAt: stats.mtimeMs,
+    });
+  },
+);
+
+/**
+ * Extracts CSS code from between ```css fences
+ * Validates that exactly one CSS code block exists
+ *
+ * @param text The text to extract CSS code from
+ * @returns The extracted CSS code or error message
+ */
+async function extractCSSCode(
+  text: string,
+): Promise<{ code: string; error?: string }> {
+  const cssCodeRegex = /```css\s*([\s\S]*?)```/g;
+  const matches = Array.from(text.matchAll(cssCodeRegex));
+
+  if (matches.length === 0) {
+    return {
+      code: "",
+      error:
+        "No CSS code block found in the response. Please include your code within ```css fences.",
+    };
+  }
+
+  if (matches.length > 1) {
+    return {
+      code: "",
+      error:
+        "Multiple CSS code blocks found in the response. Please provide exactly one code block within ```css fences.",
+    };
+  }
+
+  return { code: matches[0][1].trim() };
+}

package/src/ai/data.ts

@@ -4,12 +4,7 @@ import type { Context } from "../context";
 import { Resource } from "../resource";
 import type { Secret } from "../secret";
 import { ark } from "./ark";
-import {
-  type ModelConfig,
-  createClient,
-  getModelId,
-  getModelOptions,
-} from "./client";
+import { type ModelConfig, createModel } from "./client";
 
 /**
  * Properties for creating or updating an AI Object
@@ -38,6 +33,14 @@ export interface DataProps<T extends Type<any, any>> {
    */
   system?: string;
 
+  /**
+   * 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;
+
   /**
    * Base URL for the OpenAI API
    * @default 'https://api.openai.com/v1'
@@ -86,13 +89,20 @@ export interface Data<T> extends Resource<"ai::Object"> {
  *   price: "number"
  * });
  *
- * const product = await Object("new-product", {
+ * const product = await Data("new-product", {
  *   schema: productSchema,
  *   prompt: "Generate a product description for a new smartphone",
- *   system: "You are a product copywriter specializing in tech products"
+ *   system: "You are a product copywriter specializing in tech products",
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai",
+ *     options: {
+ *       temperature: 0.7
+ *     }
+ *   }
  * });
  *
- * console.log(product.content); // Typed as per schema
+ * console.log(product.object); // Typed as per schema
  *
  * @example
  * // Generate code documentation with context
@@ -106,13 +116,39 @@ export interface Data<T> extends Resource<"ai::Object"> {
  *   returns: "string"
  * });
  *
- * const docs = await Object("function-docs", {
+ * const docs = await Data("function-docs", {
  *   schema: docSchema,
  *   prompt: await alchemy`
  *     Generate documentation for this function:
  *     ${alchemy.file("src/utils/format.ts")}
  *   `,
- *   system: "You are a technical documentation writer"
+ *   system: "You are a technical documentation writer",
+ *   temperature: 0.2
+ * });
+ *
+ * @example
+ * // Using specific model configuration with advanced options
+ * const analysisSchema = type({
+ *   insights: "string[]",
+ *   recommendations: "string[]",
+ *   risk: "'low'|'medium'|'high'"
+ * });
+ *
+ * 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
  * });
  */
 export const Data = Resource("ai::Object", async function <
@@ -124,20 +160,21 @@ export const Data = Resource("ai::Object", async function <
     return this.destroy();
   }
 
-  // Initialize OpenAI compatible provider using shared client
-  const provider = createClient(props);
-
   // Generate structured output using generateObject
   const { object } = await generateObject({
-    model: provider(getModelId(props)),
+    model: createModel(props),
     // Convert ArkType schema to Zod schema for generateObject
     // This is needed because generateObject expects a Zod schema
     schema: ark.schema<type.infer<T>>(props.schema),
+    providerOptions: props.model?.options,
     system:
       props.system ||
       "You are an AI assistant tasked with generating structured content.",
     prompt: props.prompt,
-    ...getModelOptions(props),
+    ...(props.temperature === undefined
+      ? {}
+      : // some models error if you provide it (rather than ignoring it)
+        { temperature: props.temperature }),
   });
 
   // Return the resource with typed content

package/src/ai/document.ts

@@ -4,12 +4,8 @@ import path from "node:path";
 import type { Context } from "../context";
 import { Resource } from "../resource";
 import type { Secret } from "../secret";
-import {
-  type ModelConfig,
-  createClient,
-  getModelId,
-  getModelOptions,
-} from "./client";
+import { ignore } from "../util/ignore";
+import { type ModelConfig, createModel } from "./client";
 
 /**
  * Properties for creating or updating a Document
@@ -42,6 +38,14 @@ export interface DocumentProps {
    */
   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 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
    * If not provided, will use OPENAI_API_KEY environment variable
@@ -52,6 +56,14 @@ 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;
 }
 
 /**
@@ -74,6 +86,12 @@ export interface Document extends DocumentProps, Resource<"docs::Document"> {
   updatedAt: number;
 }
 
+/**
+ * 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.
@@ -81,39 +99,49 @@ export interface Document extends DocumentProps, Resource<"docs::Document"> {
  * @example
  * // Create a document using alchemy template literals for context
  * 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 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(
@@ -138,18 +166,55 @@ export const Document = Resource(
       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
+    // Generate initial content
     const { text } = await generateText({
-      model: provider(getModelId(props)),
+      model: createModel(props),
       prompt: props.prompt,
-      ...getModelOptions(props),
+      system,
+      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);
+
+    // 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 retryResult = await extractMarkdownContent(retryText);
+
+      if (retryResult.error) {
+        throw new Error(
+          `Failed to generate valid markdown content: ${retryResult.error}`,
+        );
+      }
+
+      content = retryResult.content;
+    }
+
+    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, text);
+    await fs.writeFile(props.path, content);
 
     // Get file stats for timestamps
     const stats = await fs.stat(props.path);
@@ -157,9 +222,41 @@ export const Document = Resource(
     // Return the resource
     return this({
       ...props,
-      content: text,
+      content: content,
       createdAt: stats.birthtimeMs,
       updatedAt: stats.mtimeMs,
     });
   },
 );
+
+/**
+ * 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
+ */
+async function extractMarkdownContent(
+  text: string,
+): Promise<{ content: string; error?: string }> {
+  const mdCodeRegex = /```md\s*([\s\S]*?)```/g;
+  const matches = Array.from(text.matchAll(mdCodeRegex));
+
+  if (matches.length === 0) {
+    return {
+      content: "",
+      error:
+        "No markdown code block found in the response. Please include your markdown content within ```md fences.",
+    };
+  }
+
+  if (matches.length > 1) {
+    return {
+      content: "",
+      error:
+        "Multiple markdown code blocks found in the response. Please provide exactly one markdown block within ```md fences.",
+    };
+  }
+
+  return { content: matches[0][1].trim() };
+}