alchemy 0.62.2 → 0.63.0

package/src/ai/document.ts

@@ -1,367 +0,0 @@
-import { generateText, type CoreMessage } from "ai";
-import type { Context } from "../context.ts";
-import { StaticTextFile } from "../fs/static-text-file.ts";
-import { Resource } from "../resource.ts";
-import type { Secret } from "../secret.ts";
-import { createModel, withRateLimitRetry, type ModelConfig } from "./client.ts";
-
-/**
- * Properties for creating or updating a Document
- */
-export interface DocumentProps {
-  /**
-   * Title of the document
-   *
-   * @default id
-   */
-  title?: string;
-
-  /**
-   * Optional path to the markdown document
-   * If provided, document will be written to this path
-   */
-  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 docs using:
-   *   ${alchemy.file("src/api.ts")}
-   * `
-   */
-  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
-   */
-  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;
-
-  /**
-   * 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
-   */
-  createdAt: number;
-
-  /**
-   * 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 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")}
- *   `,
- *   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 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")}
- *   `,
- *   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(
-  "docs::Document",
-  async function (
-    this: Context<Document>,
-    id: string,
-    props: DocumentProps,
-  ): Promise<Document> {
-    // 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") {
-      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 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 } = 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 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}\n${retryText}`,
-        );
-      }
-
-      content = retryResult.content;
-    }
-
-    // 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 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
- */
-export 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

@@ -1,244 +0,0 @@
-import { generateText } from "ai";
-import type { Context } from "../context.ts";
-import { StaticHTMLFile } from "../fs/static-html-file.ts";
-import { Resource } from "../resource.ts";
-import type { Secret } from "../secret.ts";
-import { type ModelConfig, createModel } from "./client.ts";
-
-/**
- * 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,10 +0,0 @@
-export * from "./ark.ts";
-export * from "./astro-file.ts";
-export * from "./css-file.ts";
-export * from "./data.ts";
-export * from "./document.ts";
-export * from "./html-file.ts";
-export * from "./json-file.ts";
-export * from "./typescript-file.ts";
-export * from "./vue-file.ts";
-export * from "./yaml-file.ts";