alchemy 0.2.5 → 0.3.1

package/src/ai/json-file.ts

@@ -0,0 +1,325 @@
+import { generateObject, generateText } from "ai";
+import type { JsonSchema, Type, type } from "arktype";
+import type { Context } from "../context";
+import { StaticJsonFile } from "../fs/static-json-file";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { ark } from "./ark";
+import { type ModelConfig, createModel } from "./client";
+
+/**
+ * Properties for creating or updating a JSONFile
+ */
+export interface JSONFileProps<
+  T extends Type<any, any> | undefined = undefined,
+> {
+  /**
+   * Path to the JSON file
+   */
+  path: string;
+
+  /**
+   * Optional ArkType schema to validate and structure the generated JSON
+   * When provided, the resource will use generateObject with schema validation
+   * When not provided, it will extract JSON from between ```json fences
+   */
+  schema?: T;
+
+  /**
+   * 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 a JSON configuration for:
+   *   ${alchemy.file("src/config.ts")}
+   * `
+   */
+  prompt: string;
+
+  /**
+   * System prompt for the model
+   * This is used to provide instructions to the model about how to format the response
+   * @default Depends on whether schema is provided
+   */
+  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;
+
+  /**
+   * Whether to pretty-print the JSON with indentation
+   * @default true
+   */
+  pretty?: boolean;
+
+  /**
+   * Number of spaces to use for indentation when pretty-printing
+   * @default 2
+   */
+  indent?: number;
+}
+
+/**
+ * A JSON file that can be created, updated, and deleted
+ */
+export interface JSONFile<T = any>
+  extends Omit<JSONFileProps, "schema">,
+    Resource<"ai::JSONFile"> {
+  /**
+   * Content of the JSON file as a string
+   */
+  content: string;
+
+  /**
+   * Parsed JSON object
+   */
+  json: T;
+
+  /**
+   * Schema used to validate the JSON (if provided)
+   */
+  schema?: JsonSchema;
+
+  /**
+   * Time at which the file was created
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the file was last updated
+   */
+  updatedAt: number;
+}
+
+/**
+ * Default system prompt for JSON file generation without schema
+ */
+const DEFAULT_JSON_SYSTEM_PROMPT =
+  "You are a JSON generator. Create valid JSON based on the user's requirements. Your response MUST include only JSON inside ```json fences. Do not include any other text, explanations, or multiple code blocks.";
+
+/**
+ * Resource for generating JSON files using AI models.
+ * Can operate in two modes:
+ * 1. With schema: Uses generateObject with type validation
+ * 2. Without schema: Extracts JSON from between ```json fences
+ *
+ * @example
+ * // Generate a configuration file with freeform JSON
+ * const config = await JSONFile("app-config", {
+ *   path: "./config/app.json",
+ *   prompt: await alchemy`
+ *     Generate a configuration for a web application with:
+ *     - Server settings (port, host, timeout)
+ *     - Database connection details (redact any passwords)
+ *     - Logging configuration
+ *     - Feature flags
+ *   `,
+ *   model: {
+ *     id: "gpt-4o",
+ *     provider: "openai"
+ *   }
+ * });
+ *
+ * @example
+ * // Generate JSON with schema validation
+ * import { type } from "arktype";
+ *
+ * const userSchema = type({
+ *   users: [{
+ *     id: "string",
+ *     name: "string",
+ *     email: "string",
+ *     role: "'admin' | 'user' | 'guest'",
+ *     permissions: "string[]",
+ *     active: "boolean"
+ *   }]
+ * });
+ *
+ * const userData = await JSONFile("user-data", {
+ *   path: "./data/users.json",
+ *   schema: userSchema,
+ *   prompt: "Generate sample user data for an application with various roles and permissions",
+ *   temperature: 0.2
+ * });
+ *
+ * // Type-safe access to the generated data
+ * console.log(userData.json.users[0].role); // Typed as 'admin' | 'user' | 'guest'
+ *
+ * @example
+ * // Generate API mock data with custom system prompt
+ * const apiMock = await JSONFile("api-mock", {
+ *   path: "./mocks/products-api.json",
+ *   prompt: await alchemy`
+ *     Create mock data for a product catalog API response with:
+ *     - 10 products with different categories
+ *     - Each product should have id, name, price, category, inventory, and image_url
+ *     - Include pagination metadata (total, page, limit)
+ *   `,
+ *   system: "You are an API design expert. Create realistic mock JSON data that follows REST API best practices. Your response must be valid JSON inside ```json fences.",
+ *   model: {
+ *     id: "claude-3-opus-20240229",
+ *     provider: "anthropic"
+ *   },
+ *   pretty: true,
+ *   indent: 4
+ * });
+ */
+export const JSONFile = Resource("ai::JSONFile", async function <
+  const T extends Type<any, any> | undefined = undefined,
+>(this: Context<JSONFile<T extends Type<any, any> ? type.infer<T> : any>>, id: string, props: JSONFileProps<T>): Promise<
+  JSONFile<T extends Type<any, any> ? type.infer<T> : any>
+> {
+  // Handle deletion phase
+  if (this.phase === "delete") {
+    return this.destroy();
+  }
+
+  let jsonContent: string;
+  let jsonObject: any;
+
+  // Check if schema is provided
+  if (props.schema) {
+    // Use schema-based generation
+    const { object } = await generateObject({
+      model: createModel(props),
+      schema: ark.schema<type.infer<typeof props.schema>>(props.schema),
+      providerOptions: props.model?.options,
+      system:
+        props.system ||
+        "Generate a valid JSON object based on the provided requirements.",
+      prompt: props.prompt,
+      ...(props.temperature === undefined
+        ? {}
+        : { temperature: props.temperature }),
+    });
+
+    jsonObject = object;
+
+    // Use StaticJsonFile to create the file
+    const file = await StaticJsonFile("file", props.path, jsonObject);
+    jsonContent = file.content;
+  } else {
+    // Use fence-based extraction
+    // Use provided system prompt or default
+    const system = props.system || DEFAULT_JSON_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 JSON content
+    let { content, error } = await extractJSONContent(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 valid JSON block inside \`\`\`json 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 extractJSONContent(retryText);
+
+      if (retryResult.error) {
+        throw new Error(`Failed to generate valid JSON: ${retryResult.error}`);
+      }
+
+      content = retryResult.content;
+    }
+
+    // Parse JSON to get the object representation
+    jsonObject = JSON.parse(content);
+
+    // Use StaticJsonFile to create the file
+    const file = await StaticJsonFile("file", props.path, jsonObject);
+    jsonContent = file.content;
+  }
+
+  // Return the resource
+  return this({
+    ...props,
+    schema: props.schema,
+    content: jsonContent,
+    json: jsonObject,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  });
+});
+
+/**
+ * Extracts JSON content from between ```json fences
+ * Validates that exactly one JSON code block exists
+ *
+ * @param text The text to extract JSON from
+ * @returns The extracted JSON or error message
+ */
+async function extractJSONContent(
+  text: string
+): Promise<{ content: string; error?: string }> {
+  const jsonCodeRegex = /```json\s*([\s\S]*?)```/g;
+  const matches = Array.from(text.matchAll(jsonCodeRegex));
+
+  if (matches.length === 0) {
+    return {
+      content: "",
+      error:
+        "No JSON code block found in the response. Please include your JSON within ```json fences.",
+    };
+  }
+
+  if (matches.length > 1) {
+    return {
+      content: "",
+      error:
+        "Multiple JSON code blocks found in the response. Please provide exactly one JSON block within ```json fences.",
+    };
+  }
+
+  const content = matches[0][1].trim();
+
+  // Validate JSON can be parsed
+  try {
+    JSON.parse(content);
+    return { content };
+  } catch (e) {
+    return {
+      content: "",
+      error: `Invalid JSON: ${(e as Error).message}. Please provide valid JSON syntax.`,
+    };
+  }
+}

package/src/ai/review.ts

@@ -0,0 +1,213 @@
+import { generateText, type CoreMessage } from "ai";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { createModel, withRateLimitRetry, type ModelConfig } from "./client";
+
+/**
+ * Properties for creating or updating a Review
+ */
+export interface ReviewProps {
+  /**
+   * Content to be reviewed
+   * Use alchemy template literals to include file context:
+   * @example
+   * content: await alchemy`
+   *   Review this code:
+   *   ${alchemy.file("src/api.ts")}
+   * `
+   *
+   * Required unless messages are provided
+   */
+  content?: string;
+
+  /**
+   * Prompt for the review
+   * This should include specific instructions for the review
+   * @example
+   * prompt: "Review this code for security vulnerabilities, performance issues, and best practices."
+   *
+   * Required unless messages are provided
+   */
+  prompt?: string;
+
+  /**
+   * Message history for the conversation
+   * If provided, this will be used instead of the prompt and content
+   */
+  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 act as a reviewer
+   */
+  system?: string;
+
+  /**
+   * AI 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;
+}
+
+/**
+ * Output returned after Review creation/update
+ */
+export interface Review extends ReviewProps, Resource<"ai::Review"> {
+  /**
+   * Content of the review
+   */
+  content: string;
+
+  /**
+   * Updated message history with the review response appended
+   */
+  messages: CoreMessage[];
+
+  /**
+   * Time at which the review was created
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the review was last updated
+   */
+  updatedAt: number;
+}
+
+/**
+ * Default system prompt for review generation
+ */
+const DEFAULT_REVIEW_SYSTEM_PROMPT = `You are an expert code reviewer and technical writer. Your task is to provide a thorough review of the provided content. Your review should include:
+
+1. A high-level summary of the content
+2. Detailed feedback on the content's quality, accuracy, and completeness
+3. Specific suggestions for improvement
+4. Alternative approaches or solutions where applicable
+5. Best practices that should be followed
+6. Potential issues or concerns that should be addressed
+
+Provide your review in a clear, well-structured format.`;
+
+/**
+ * Creates or updates a Review resource
+ *
+ * @example
+ * // Create a review of a code file
+ * const codeReview = await Review("api-review", {
+ *   content: await alchemy`
+ *     Review this API implementation:
+ *     ${alchemy.file("src/api.ts")}
+ *   `,
+ *   prompt: "Review this API implementation for security vulnerabilities, performance issues, and best practices. Suggest improvements and alternative approaches."
+ * });
+ *
+ * @example
+ * // Create a review of a document
+ * const docReview = await Review("tutorial-review", {
+ *   content: await alchemy`
+ *     Review this tutorial:
+ *     ${alchemy.file("docs/tutorials/getting-started.md")}
+ *   `,
+ *   prompt: "Review this tutorial for clarity, accuracy, and completeness. Suggest improvements to make it more user-friendly."
+ * });
+ *
+ * @example
+ * // Create a review with message history
+ * const reviewWithHistory = await Review("code-review-iteration-2", {
+ *   content: "Updated code implementation",
+ *   prompt: "Review this updated implementation",
+ *   messages: [
+ *     { role: "user", content: "Can you review my code?" },
+ *     { role: "assistant", content: "I'll review your code. Please share it." },
+ *     { role: "user", content: "Here's my implementation: [code]" },
+ *     { role: "assistant", content: "Here's my review of your code: [previous review]" }
+ *   ]
+ * });
+ */
+export const Review = Resource(
+  "ai::Review",
+  async function (
+    this: Context<Review>,
+    id: string,
+    props: ReviewProps
+  ): Promise<Review> {
+    if (this.phase === "delete") {
+      return this.destroy();
+    }
+
+    // Use provided system prompt or default
+    const system = props.system || DEFAULT_REVIEW_SYSTEM_PROMPT;
+
+    // Create messages array if not provided
+    const messages =
+      props.messages ||
+      (props.content && props.prompt
+        ? [
+            {
+              role: "user",
+              content: `${props.content}\n\n${props.prompt}`,
+            },
+          ]
+        : []);
+
+    if (messages.length === 0) {
+      throw new Error(
+        "Either messages or both content and prompt must be provided"
+      );
+    }
+
+    // Generate review content with rate limit retry
+    const { text } = await withRateLimitRetry(async () => {
+      return generateText({
+        model: createModel(props),
+        messages,
+        system,
+        maxTokens: props.maxTokens || 8192,
+        providerOptions: props.model?.options,
+        ...(props.temperature === undefined
+          ? {}
+          : { temperature: props.temperature }),
+      });
+    });
+
+    // Create updated message history with the AI's response
+    const updatedMessages = [
+      ...messages,
+      {
+        role: "assistant" as const,
+        content: text,
+      },
+    ];
+
+    // Return the review with the direct text from the LLM and updated messages
+    return this({
+      ...props,
+      content: text,
+      messages: updatedMessages,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+  }
+);