alchemy 0.3.1 → 0.4.1

package/lib/internal/providers.js

@@ -1,172 +0,0 @@
-import { type } from "arktype";
-import fs from "fs/promises";
-import path from "path";
-import { Data, Document } from "../ai";
-import { alchemy } from "../alchemy";
-import { Folder } from "../fs";
-export async function AlchemyProviderDocs({ srcDir, outDir, filter, }) {
-    outDir = typeof outDir === "string" ? outDir : outDir.path;
-    const exclude = [
-        "util",
-        "test",
-        "vitepress",
-        "vite",
-        "shadcn",
-        "internal",
-        "web",
-    ];
-    // Get all folders in the alchemy/src directory
-    let providers = (await fs.readdir(srcDir, {
-        withFileTypes: true,
-    }))
-        .filter((dirent) => dirent.isDirectory() && !exclude.includes(dirent.name))
-        .map((dirent) => path.join(dirent.parentPath, dirent.name));
-    // For each provider, list all files
-    if (filter === false) {
-        return [];
-    }
-    else if (typeof filter === "number") {
-        providers = providers.slice(0, filter);
-    }
-    return await Promise.all(providers.map(async (provider) => {
-        const providerName = path.basename(provider);
-        const files = (await fs.readdir(path.resolve(provider), {
-            withFileTypes: true,
-        }))
-            .filter((dirent) => dirent.isFile())
-            .map((dirent) => path.relative(process.cwd(), path.resolve(provider, dirent.name)))
-            .filter((file) => file.endsWith(".ts") && !file.endsWith("index.ts"));
-        const { object: { groups }, } = await Data(`docs/${providerName}`, {
-            model: {
-                id: "o3-mini",
-                provider: "openai",
-                options: {
-                    reasoningEffort: "high",
-                },
-            },
-            temperature: 0.1,
-            schema: type({
-                groups: type({
-                    title: type("string").describe("The title of the group, should be the Resource Name exactly as it's defined in code (const ResourceName translates to 'Resource Name') without spaces, e.g. Bucket or Static Site."),
-                    filename: type("string").describe("The filename of the Resource's Document, e.g. bucket.md or static-site.md"),
-                    category: type("'Resource'|'Client'|'Utility'|'Types'").describe("The classification of the Resource's Document, one of: Resource, Client, Utility, or Types."),
-                }).array(),
-            }),
-            system: await alchemy `
-          You are a technical writer tasked with identifying the distinct documents that need to be written for a document group (folder) in a documentation site.
-          You will be provided with a list of documents and instructions on how to classify them.
-          Each document has a title, file name, and category.
-        `,
-            prompt: await alchemy `
-          Identify and classify the documents that need to be written for the '${provider}' Service's Alchemy Resources.
-          For background knowledge on Alchemy, see ${alchemy.file("./README.md")}.
-          For background knowledge on the structure of an Alchemy Resource, see ${alchemy.file("./.cursorrules")}.
-
-          The ${provider} Service has the following resources:
-          ${alchemy.files(files)}
-
-          A file is considered a "Resource" if it contains a const <ResourceName> = Resource(...) call or if it is a function that calls a Resource function, e.g. const TypeScriptFile = () => File(...).
-          A file is considered a "Client" if it exposes a wrapper around creating a SDK client or fetch.
-          A file is considered a "Utility" if it contains utility functions that are not resources or clients.
-          A file is considered a "Types" if it contains just type definitions and maybe helpers around working with those types.
-
-          The title should be simply the name of the resource's const in code (with spaces added in between each word), e.g. "Bucket" or "Function", except with spaces, e.g. "Static Site" for "const StaticSite". Maintain all other casing.
-
-          // "Resource Name"
-          const ResourceName = Resource(...)
-        `,
-        });
-        // console.log(groups);
-        const providerDocsDir = (await Folder(path.join(outDir, providerName)))
-            .path;
-        const documents = await Promise.allSettled(groups
-            .filter((g) => g.category === "Resource")
-            .map(async (g) => Document(`docs/${providerName}/${g.title}`, {
-            title: g.title,
-            path: path.join(providerDocsDir, `${g.filename.replace(".ts", "").replace(".md", "")}.md`),
-            model: {
-                id: "claude-3-5-sonnet-latest",
-                provider: "anthropic",
-                // options: {
-                //   reasoningEffort: "high",
-                // },
-            },
-            prompt: await alchemy `
-                You are a technical writer writing API documentation for an Alchemy IaC Resource.
-                See ${alchemy.file("./README.md")} to understand the overview of Alchemy.
-                See ${alchemy.file("./.cursorrules")} to better understand the structure and convention of an Alchemy Resource.
-
-                Relevant files for the ${providerName} Service:
-                ${alchemy.files(files)}
-                
-                Write concise documentation for the "${g.title}" Resource.
-
-                > [!CAUTION]
-                > Avoid the temptation to over explain or over describe. Focus on concise, simple, high value snippets. One heading and 0-1 descriptions per snippet.
-                
-                > [!TIP]
-                > Make sure the examples follow a natural progression from the minimal example to logical next steps of how the Resource might be used.
-
-                Each document must follow the following format:
-                
-                # ${g.title}
-
-                (simple description with an external link to the provider's website)
-                e.g.
-                The Efs component lets you add [Amazon Elastic File System (EFS)](https://docs.aws.amazon.com/efs/latest/ug/whatisefs.html) to your app.
-
-                # Minimal Example
-
-                (brief 1-2 sentences of what it does)
-
-                \`\`\`ts
-                import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
-
-                (example)
-                \`\`\`
-
-
-                # Create the ${g.title}
-
-                \`\`\`ts
-                import { ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
-
-                (example)
-                \`\`\`
-
-                ${providerName === "cloudflare"
-                ? await alchemy `# Bind to a Worker
-                (if it is a Cloudflare Resource)
-
-                \`\`\`ts
-                import { Worker, ${g.title.replaceAll(" ", "")} } from "alchemy/${providerName}";
-
-                const myResource = await ${g.title.replaceAll(" ", "")}("my-resource", {
-                  // ...
-                });
-
-                await Worker("my-worker", {
-                  name: "my-worker",
-                  script: "console.log('Hello, world!')",
-                  bindings: {
-                    myResource,
-                  },
-                });
-                \`\`\``
-                : ""}
-              `,
-        })));
-        // Unwrap all documents, fail if any rejected
-        const results = await Promise.all(documents.map((r) => {
-            if (r.status === "rejected") {
-                throw r.reason;
-            }
-            return r.value;
-        }));
-        return {
-            dir: providerDocsDir,
-            provider: providerName,
-            documents: results,
-        };
-    }));
-}

package/lib/internal/tutorial.d.ts

@@ -1,104 +0,0 @@
-import type { CoreMessage } from "ai";
-import { Document } from "../ai";
-import type { ModelConfig } from "../ai/client";
-import type { Context } from "../context";
-import type { Folder } from "../fs";
-import { Resource } from "../resource";
-/**
- * Properties for creating or updating a Tutorial
- */
-export interface TutorialProps {
-    /**
-     * The output directory for the tutorial document.
-     */
-    path: string | Folder;
-    /**
-     * The title of the tutorial.
-     */
-    title: string;
-    /**
-     * The prompt to use for generating the tutorial.
-     * This should include specific details about the tool or framework.
-     */
-    prompt: string;
-    /**
-     * Optional difficulty level for the tutorial.
-     * Defaults to "beginner".
-     */
-    difficulty?: "beginner" | "intermediate" | "advanced";
-    /**
-     * Optional estimated time to complete the tutorial in minutes.
-     * Defaults to 30.
-     */
-    estimatedTime?: number;
-    /**
-     * Optional model configuration for generating the tutorial.
-     * Defaults to Claude 3.5 Sonnet.
-     */
-    model?: ModelConfig;
-    /**
-     * Maximum number of review iterations.
-     * Defaults to 3.
-     */
-    maxIterations?: number;
-    /**
-     * Initial message history for the conversation.
-     * If not provided, a new conversation will be started.
-     */
-    messages?: CoreMessage[];
-}
-/**
- * Output returned after Tutorial creation/update
- */
-export interface Tutorial extends TutorialProps, Resource<"docs::Tutorial"> {
-    /**
-     * The Document resource
-     */
-    document: Document;
-    /**
-     * The content of the tutorial
-     */
-    content: string;
-    /**
-     * Message history from the conversation.
-     */
-    messages: CoreMessage[];
-    /**
-     * Time at which the tutorial was created
-     */
-    createdAt: number;
-    /**
-     * Time at which the tutorial was last updated
-     */
-    updatedAt: number;
-}
-/**
- * Creates a tutorial document with iterative review and improvement
- *
- * @example
- * // Create a basic tutorial
- * const tutorial = await Tutorial("getting-started", {
- *   path: "docs/tutorials/getting-started",
- *   title: "Getting Started with Alchemy",
- *   prompt: "Create a tutorial for getting started with the Alchemy framework",
- *   difficulty: "beginner",
- *   estimatedTime: 30
- * });
- *
- * @example
- * // Create an advanced tutorial with custom model and continue from existing messages
- * const advancedTutorial = await Tutorial("advanced-features", {
- *   path: "docs/tutorials/advanced-features",
- *   title: "Advanced Alchemy Features",
- *   prompt: "Create a tutorial covering advanced features of the Alchemy framework",
- *   difficulty: "advanced",
- *   estimatedTime: 60,
- *   model: {
- *     id: "claude-3-7-sonnet-latest",
- *     provider: "anthropic"
- *   },
- *   maxIterations: 5,
- *   messages: basicTutorial.messages
- * });
- */
-export declare const Tutorial: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Tutorial>, id: string, props: TutorialProps) => Promise<Tutorial>);

package/lib/internal/tutorial.js

@@ -1,251 +0,0 @@
-import { Approve, Document, Review } from "../ai";
-import { alchemy } from "../alchemy";
-import { Resource } from "../resource";
-/**
- * Creates a tutorial document with iterative review and improvement
- *
- * @example
- * // Create a basic tutorial
- * const tutorial = await Tutorial("getting-started", {
- *   path: "docs/tutorials/getting-started",
- *   title: "Getting Started with Alchemy",
- *   prompt: "Create a tutorial for getting started with the Alchemy framework",
- *   difficulty: "beginner",
- *   estimatedTime: 30
- * });
- *
- * @example
- * // Create an advanced tutorial with custom model and continue from existing messages
- * const advancedTutorial = await Tutorial("advanced-features", {
- *   path: "docs/tutorials/advanced-features",
- *   title: "Advanced Alchemy Features",
- *   prompt: "Create a tutorial covering advanced features of the Alchemy framework",
- *   difficulty: "advanced",
- *   estimatedTime: 60,
- *   model: {
- *     id: "claude-3-7-sonnet-latest",
- *     provider: "anthropic"
- *   },
- *   maxIterations: 5,
- *   messages: basicTutorial.messages
- * });
- */
-export const Tutorial = Resource("docs::Tutorial", async function (id, props) {
-    const { path: outFile, title, prompt, difficulty = "beginner", estimatedTime = 30, model = {
-        id: "claude-3-5-sonnet-latest",
-        provider: "anthropic",
-    }, maxIterations = 3, messages: initialMessages = [], } = props;
-    console.log(`Tutorial: Starting creation of "${title}" (ID: ${id})`);
-    // Handle deletion phase
-    if (this.phase === "delete") {
-        console.log(`Tutorial: Deleting tutorial "${title}" (ID: ${id})`);
-        return this.destroy();
-    }
-    // System prompts
-    const docSystemPrompt = `You are a technical writer creating a comprehensive tutorial.
-    
-    Your task is to create a detailed tutorial about ${title} with difficulty level: ${difficulty} and estimated time to complete: ${estimatedTime} minutes.
-    
-    The tutorial should take users from zero knowledge to a working understanding of the tool or framework.
-    
-    The tutorial should be structured as follows:
-    
-    # ${title}
-    
-    ## Overview
-    
-    (Provide a brief introduction to the tool/framework, its purpose, and what users will learn in this tutorial)
-    
-    ## Prerequisites
-    
-    (List any prerequisites, tools, or knowledge required before starting the tutorial)
-    
-    ## Setup
-    
-    ### Installation
-    
-    \`\`\`bash
-    # Installation commands
-    \`\`\`
-    
-    ### Configuration
-    
-    (Explain any necessary configuration steps)
-    
-    \`\`\`bash
-    # Configuration commands or code
-    \`\`\`
-    
-    ## Step 1: [First Step Title]
-    
-    (Explain the first step in detail)
-    
-    \`\`\`bash
-    # Commands or code for the first step
-    \`\`\`
-    
-    (Explain what the code does and why it's important)
-    
-    ## Step 2: [Second Step Title]
-    
-    (Explain the second step in detail)
-    
-    \`\`\`bash
-    # Commands or code for the second step
-    \`\`\`
-    
-    (Explain what the code does and why it's important)
-    
-    ## Step 3: [Third Step Title]
-    
-    (Explain the third step in detail)
-    
-    \`\`\`bash
-    # Commands or code for the third step
-    \`\`\`
-    
-    (Explain what the code does and why it's important)
-    
-    ## Step 4: [Fourth Step Title]
-    
-    (Explain the fourth step in detail)
-    
-    \`\`\`bash
-    # Commands or code for the fourth step
-    \`\`\`
-    
-    (Explain what the code does and why it's important)
-    
-    ## Step 5: [Fifth Step Title]
-    
-    (Explain the fifth step in detail)
-    
-    \`\`\`bash
-    # Commands or code for the fifth step
-    \`\`\`
-    
-    (Explain what the code does and why it's important)
-    
-    ## Testing Your Work
-    
-    (Explain how to verify that everything is working correctly)
-    
-    \`\`\`bash
-    # Testing commands or code
-    \`\`\`
-    
-    ## Troubleshooting
-    
-    (Common issues users might encounter and how to resolve them)
-    
-    ## Next Steps
-    
-    (Suggest additional resources, advanced topics, or projects to try next)
-    
-    ## Additional Resources
-    
-    (Links to documentation, community resources, or related tutorials)`;
-    // Initial message if none provided
-    const startingMessages = initialMessages.length > 0
-        ? initialMessages
-        : [
-            {
-                role: "user",
-                content: `Create a comprehensive tutorial about ${title}.\n\n${prompt}\n\nDifficulty level: ${difficulty}\nEstimated time to complete: ${estimatedTime} minutes`,
-            },
-        ];
-    // Generate the initial tutorial
-    console.log(`Tutorial: Generating initial tutorial for "${title}"`);
-    let tutorial = await Document(`document`, {
-        title: title,
-        path: typeof outFile === "string" ? outFile : outFile.path,
-        model,
-        messages: startingMessages,
-        system: docSystemPrompt,
-    });
-    console.log(`Tutorial: Initial tutorial generated for "${title}" (${tutorial.content.length} chars)`);
-    // Review and improve the tutorial in a loop
-    let iteration = 0;
-    let approved = false;
-    let finalMessages = tutorial.messages;
-    while (!approved && iteration < maxIterations) {
-        iteration++;
-        console.log(`Tutorial: Starting review iteration ${iteration}/${maxIterations} for "${title}"`);
-        // Review the tutorial using system prompt
-        console.log(`Tutorial: Requesting review for iteration ${iteration}`);
-        const review = await Review(`review-${iteration}`, {
-            messages: finalMessages,
-            system: await alchemy `Please review this tutorial for correctness, conciseness, logical flow, and accurateness. 
-        
-      The tutorial should:
-      1. Be technically accurate and free of errors
-      2. Be concise without over-explaining
-      3. Have a logical flow from basic to advanced concepts
-      4. Be accurate in its descriptions and instructions
-      5. Be appropriate for the ${difficulty} difficulty level
-      6. Be completable within approximately ${estimatedTime} minutes
-      
-      Provide specific feedback on areas that need improvement.`,
-            model,
-        });
-        // Extract the actual review content from the last assistant message
-        const reviewContent = review.messages[review.messages.length - 1]?.content || "";
-        console.log(`Tutorial: Review received for iteration ${iteration} (${reviewContent.length} chars)`);
-        // Check if the tutorial is approved using system prompt
-        console.log(`Tutorial: Evaluating approval for iteration ${iteration}`);
-        const approvalResult = await Approve(`approval-${iteration}`, {
-            messages: review.messages,
-            system: await alchemy `Based on the review above, determine if the tutorial meets the quality standards.
-      The tutorial should be approved if:
-      1. It is technically accurate and free of errors
-      2. It is concise without over-explaining
-      3. It has a logical flow from basic to advanced concepts
-      4. It is accurate in its descriptions and instructions
-      5. It is appropriate for the ${difficulty} difficulty level
-      6. It is completable within approximately ${estimatedTime} minutes
-      
-      Respond with APPROVED or DENIED, followed by your explanation.`,
-        });
-        console.log(`Tutorial: Approval result for iteration ${iteration}: ${approvalResult.approved ? "APPROVED" : "DENIED"}`);
-        // Log approval status
-        if (approvalResult.approved) {
-            console.log(`Tutorial: Final tutorial approved: ${approvalResult.explanation}`);
-            approved = true;
-            finalMessages = approvalResult.messages;
-        }
-        else {
-            console.log(`Tutorial: Tutorial needs improvement: ${approvalResult.explanation}`);
-            // Add improvement request and generate an improved tutorial
-            const improvementMessages = [
-                ...approvalResult.messages,
-                {
-                    role: "user",
-                    content: `Please create an improved version of the tutorial that addresses the issues identified in the review: ${approvalResult.explanation}`,
-                },
-            ];
-            console.log(`Tutorial: Regenerating tutorial based on feedback for iteration ${iteration}`);
-            tutorial = await Document(`tutorial-${iteration}`, {
-                title: title,
-                path: typeof outFile === "string" ? outFile : outFile.path,
-                model,
-                messages: improvementMessages,
-                system: docSystemPrompt,
-            });
-            console.log(`Tutorial: Improved tutorial generated for iteration ${iteration} (${tutorial.content.length} chars)`);
-            finalMessages = tutorial.messages;
-        }
-    }
-    if (!approved) {
-        console.log(`Tutorial: Tutorial not approved after ${maxIterations} iterations. Using the best version available.`);
-    }
-    console.log(`Tutorial: Completed creation of "${title}" (ID: ${id})`);
-    // Return the tutorial resource
-    return this({
-        ...props,
-        document: tutorial,
-        content: tutorial.content,
-        messages: finalMessages,
-        createdAt: Date.now(),
-        updatedAt: Date.now(),
-    });
-});

package/src/ai/approve.ts

@@ -1,163 +0,0 @@
-import type { CoreMessage } from "ai";
-import { type } from "arktype";
-import { Data } from "./data";
-
-/**
- * Properties for approving or denying content
- */
-export interface ApproveProps {
-  /**
-   * 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 approval decision
-   * This should include specific criteria for approval or denial
-   * @example
-   * prompt: "Approve this code if it follows security best practices and has proper error handling."
-   *
-   * Required unless messages are provided
-   */
-  prompt?: string;
-
-  /**
-   * System prompt for the model
-   * This is used to provide instructions to the model about how to make the decision
-   */
-  system?: string;
-
-  /**
-   * Message history for the conversation
-   * If provided, this will be used instead of the prompt and content
-   */
-  messages?: CoreMessage[];
-
-  /**
-   * 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.2 (lower for more consistent decisions)
-   */
-  temperature?: number;
-}
-
-/**
- * Result of the approval process
- */
-export interface ApprovalResult {
-  /**
-   * Whether the content was approved
-   */
-  approved: boolean;
-
-  /**
-   * Explanation for the decision
-   */
-  explanation: string;
-
-  /**
-   * Suggestions for improvement if denied
-   */
-  suggestions?: string[];
-
-  /**
-   * Updated message history with the approval response appended
-   */
-  messages: CoreMessage[];
-}
-
-export type Approve = ApprovalResult;
-
-/**
- * Default system prompt for approval decisions
- */
-const DEFAULT_APPROVE_SYSTEM_PROMPT = `You are an expert content reviewer tasked with approving or denying content based on specific criteria.
-
-Your role is to:
-1. Carefully evaluate the content against the provided criteria
-2. Make a clear decision to approve or deny the content
-3. Provide a detailed explanation for your decision
-4. If denying, offer specific suggestions for improvement
-
-Be objective, thorough, and fair in your assessment.`;
-
-/**
- * Approves or denies content based on a prompt or message history
- *
- * @example
- * // Approve or deny a code file
- * const result = await Approve("code-approval", {
- *   content: await alchemy`
- *     Review this API implementation:
- *     ${alchemy.file("src/api.ts")}
- *   `,
- *   prompt: "Approve this code if it follows security best practices and has proper error handling."
- * });
- *
- * if (result.approved) {
- *   console.log("Content approved:", result.explanation);
- * } else {
- *   console.log("Content denied:", result.explanation);
- *   console.log("Suggestions:", result.suggestions);
- * }
- *
- * @example
- * // Approve or deny using message history
- * const result = await Approve("doc-approval-with-history", {
- *   content: "This is the content to review",
- *   prompt: "Approve this documentation if it is clear and accurate",
- *   messages: [
- *     { role: "user", content: "Can you review this documentation?" },
- *     { role: "assistant", content: "Yes, I'd be happy to review it." },
- *     { role: "user", content: "Please check for clarity and accuracy." }
- *   ]
- * });
- */
-export async function Approve(
-  id: string,
-  props: ApproveProps
-): Promise<ApprovalResult> {
-  // Create messages array if not provided
-  const messages =
-    props.messages ||
-    (props.content && props.prompt
-      ? [
-          {
-            role: "user" as const,
-            content: `${props.content}\n\n${props.prompt}`,
-          },
-        ]
-      : []);
-
-  if (messages.length === 0) {
-    throw new Error(
-      "Either messages or both content and prompt must be provided"
-    );
-  }
-
-  const data = await Data(id, {
-    schema: type({
-      approved: "boolean",
-      explanation: "string",
-      suggestions: "string[]?",
-    }),
-    messages,
-    system: props.system || DEFAULT_APPROVE_SYSTEM_PROMPT,
-    temperature: props.temperature ?? 0.2,
-  });
-
-  // Return the result with updated messages from Data
-  return {
-    ...data.object,
-    messages: data.messages,
-  };
-}