alchemy 0.2.5 → 0.3.1

package/lib/ai/css-file.d.ts

@@ -0,0 +1,131 @@
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { type ModelConfig } 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;
+}
+/**
+ * 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 declare const CSSFile: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<CSSFile>, id: string, props: CSSFileProps) => Promise<CSSFile>);

package/lib/ai/css-file.js

@@ -0,0 +1,141 @@
+import { generateText } from "ai";
+import { StaticCSSFile } from "../fs/static-css-file";
+import { Resource } from "../resource";
+import { createModel } from "./client";
+/**
+ * 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 (id, props) {
+    // Handle deletion phase
+    if (this.phase === "delete") {
+        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;
+    }
+    // Use StaticCSSFile to create/update the file
+    const file = await StaticCSSFile("file", props.path, code);
+    // Return the resource
+    return this({
+        ...props,
+        content: file.content,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    });
+});
+/**
+ * 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) {
+    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/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,13 +21,25 @@ 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
      * system: "You are a technical writer tasked with describing code"
      */
     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'
@@ -51,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
      */
@@ -69,13 +86,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
@@ -89,13 +113,34 @@ 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 message history for iterative generation
+ * const feedbackSchema = type({
+ *   rating: "number",
+ *   positives: "string[]",
+ *   improvements: "string[]",
+ *   summary: "string"
+ * });
+ *
+ * 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

@@ -1,7 +1,7 @@
 import { generateObject } from "ai";
 import { Resource } from "../resource";
 import { ark } from "./ark";
-import { createClient, getModelId, getModelOptions, } from "./client";
+import { createModel } from "./client";
 /**
  * Resource for generating structured content using the Vercel AI SDK.
  * Supports powerful context handling through the alchemy template literal tag.
@@ -15,13 +15,20 @@ import { createClient, getModelId, getModelOptions, } from "./client";
  *   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
@@ -35,36 +42,75 @@ import { createClient, getModelId, getModelOptions, } from "./client";
  *   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 message history for iterative generation
+ * const feedbackSchema = type({
+ *   rating: "number",
+ *   positives: "string[]",
+ *   improvements: "string[]",
+ *   summary: "string"
+ * });
+ *
+ * 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();
     }
-    // Initialize OpenAI compatible provider using shared client
-    const provider = createClient(props);
+    // 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: 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(props.schema),
+        providerOptions: props.model?.options,
         system: props.system ||
             "You are an AI assistant tasked with generating structured content.",
-        prompt: props.prompt,
-        ...getModelOptions(props),
+        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,25 @@ 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
      * If not provided, will use OPENAI_API_KEY environment variable
@@ -38,6 +59,19 @@ 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;
 }
 /**
  * A markdown document that can be created, updated, and deleted
@@ -47,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
      */
@@ -55,47 +93,93 @@ 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",
  *   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 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",
  *   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 declare const Document: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Document>, id: string, props: DocumentProps) => Promise<Document>);