alchemy 0.2.2 → 0.2.4

package/lib/ai/ark.d.ts

@@ -0,0 +1,11 @@
+import { type Tool as AITool, type Schema, type ToolExecutionOptions } from "ai";
+import { type JsonSchema, type type } from "arktype";
+export declare namespace ark {
+    function schema<T>(type: JsonSchema): Schema<T>;
+    interface Tool<Input extends type, Output> extends Omit<AITool<Schema<type.infer<Input>>>, "parameters" | "execute"> {
+        description?: string;
+        parameters: Input;
+        execute: (input: type.infer<Input>, options: ToolExecutionOptions) => Promise<Output>;
+    }
+    function tool<Input extends type, Output>(tool: Tool<Input, Output>): AITool<Schema<type.infer<Input>>, Output>;
+}

package/lib/ai/ark.js

@@ -0,0 +1,86 @@
+import { tool as aitool, jsonSchema, } from "ai";
+import { ArkErrors } from "arktype";
+export var ark;
+(function (ark) {
+    function schema(type) {
+        const jsonSchemaObj = type.toJsonSchema();
+        const processedSchema = processSchema(jsonSchemaObj);
+        return jsonSchema(processedSchema, {
+            validate: (value) => {
+                const out = type(value);
+                if (out instanceof ArkErrors) {
+                    return {
+                        success: false,
+                        error: new Error(out.summary),
+                    };
+                }
+                return {
+                    success: true,
+                    value: out,
+                };
+            },
+        });
+    }
+    ark.schema = schema;
+    /**
+     * Recursively processes a JSON schema and sets additionalProperties: false
+     * for any object types.
+     *
+     * Structured Outputs requires additionalProperties: false
+     */
+    function processSchema(schema) {
+        if (!schema || typeof schema !== "object")
+            return schema;
+        // Create a copy to avoid mutating the original
+        const result = { ...schema };
+        // Convert anyOf with all const values to enum
+        if (result.anyOf && Array.isArray(result.anyOf)) {
+            const allConst = result.anyOf.every((item) => item && typeof item === "object" && "const" in item);
+            if (allConst) {
+                // Extract all const values
+                const enumValues = result.anyOf.map((item) => item.const);
+                // Determine the type based on the first const value
+                // Assuming all const values are of the same type
+                const firstType = typeof enumValues[0];
+                // Replace anyOf with enum
+                delete result.anyOf;
+                result.type = firstType;
+                result.enum = enumValues;
+            }
+            else {
+                // Process each item in anyOf
+                result.anyOf = result.anyOf.map(processSchema);
+            }
+        }
+        // If this is an object type, set additionalProperties: false
+        if (result.type === "object") {
+            result.additionalProperties = false;
+            result.properties ??= {};
+        }
+        // Process properties of objects
+        if (result.properties && typeof result.properties === "object") {
+            result.properties = Object.fromEntries(Object.entries(result.properties).map(([key, value]) => [
+                key,
+                processSchema(value),
+            ]));
+        }
+        // Process items in arrays
+        if (result.items) {
+            result.items = processSchema(result.items);
+        }
+        // Process allOf, oneOf
+        for (const key of ["allOf", "oneOf"]) {
+            if (Array.isArray(result[key])) {
+                result[key] = result[key].map(processSchema);
+            }
+        }
+        return result;
+    }
+    function tool(tool) {
+        return aitool({
+            ...tool,
+            parameters: ark.schema(tool.parameters),
+        });
+    }
+    ark.tool = tool;
+})(ark || (ark = {}));

package/lib/ai/client.d.ts

@@ -0,0 +1,51 @@
+import type { Secret } from "../secret";
+/**
+ * Model configuration for AI operations
+ */
+export interface ModelConfig {
+    /**
+     * Model ID to use
+     * @default 'gpt-4o'
+     */
+    id?: string;
+    /**
+     * Model provider name
+     * @default 'openai'
+     */
+    provider?: string;
+    /**
+     * Model-specific options
+     */
+    options?: Record<string, unknown>;
+}
+/**
+ * Configuration for creating an OpenAI client
+ */
+export interface ClientConfig {
+    /**
+     * Base URL for the OpenAI API
+     * @default 'https://api.openai.com/v1'
+     */
+    baseURL?: 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;
+}
+/**
+ * Creates an OpenAI-compatible client with the given configuration
+ */
+export declare function createClient(config: ClientConfig): import("@ai-sdk/openai-compatible").OpenAICompatibleProvider<string, string, string, string>;
+/**
+ * Gets the model ID from the configuration or returns the default
+ */
+export declare function getModelId(config: ClientConfig): string;
+/**
+ * Gets the model options from the configuration
+ */
+export declare function getModelOptions(config: ClientConfig): Record<string, unknown>;

package/lib/ai/client.js

@@ -0,0 +1,29 @@
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+/**
+ * Creates an OpenAI-compatible client with the given configuration
+ */
+export function createClient(config) {
+    // Get API key from props or environment
+    const apiKey = config.apiKey?.unencrypted || process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        throw new Error("OpenAI API key is required");
+    }
+    // Initialize OpenAI compatible provider
+    return createOpenAICompatible({
+        name: config.model?.provider || "openai",
+        apiKey,
+        baseURL: config.baseURL || "https://api.openai.com/v1",
+    });
+}
+/**
+ * Gets the model ID from the configuration or returns the default
+ */
+export function getModelId(config) {
+    return config.model?.id || "gpt-4o";
+}
+/**
+ * Gets the model options from the configuration
+ */
+export function getModelOptions(config) {
+    return config.model?.options || {};
+}

package/lib/ai/document.d.ts

@@ -0,0 +1,97 @@
+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 Document
+ */
+export interface DocumentProps {
+    /**
+     * Path to the markdown document
+     */
+    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;
+    /**
+     * OpenAI API key to use for generating content
+     * If not provided, will use OPENAI_API_KEY environment variable
+     */
+    apiKey?: Secret;
+    /**
+     * Model configuration
+     */
+    model?: ModelConfig;
+}
+/**
+ * A markdown document that can be created, updated, and deleted
+ */
+export interface Document extends DocumentProps, Resource<"docs::Document"> {
+    /**
+     * Content of the document
+     */
+    content: string;
+    /**
+     * Time at which the document was created
+     */
+    createdAt: number;
+    /**
+     * Time at which the document was last updated
+     */
+    updatedAt: number;
+}
+/**
+ * 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
+ * const apiDocs = await Document("api-docs", {
+ *   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 ...
+ *   // ```
+ * });
+ *
+ * @example
+ * // Use alchemy template literals with file collections
+ * const modelDocs = await Document("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
+ * });
+ */
+export declare const Document: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | ((this: Context<Document>, id: string, props: DocumentProps) => Promise<Document>);

package/lib/ai/document.js

@@ -0,0 +1,82 @@
+import { generateText } from "ai";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Resource } from "../resource";
+import { createClient, getModelId, getModelOptions, } from "./client";
+/**
+ * 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
+ * const apiDocs = await Document("api-docs", {
+ *   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 ...
+ *   // ```
+ * });
+ *
+ * @example
+ * // Use alchemy template literals with file collections
+ * const modelDocs = await Document("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
+ * });
+ */
+export const Document = Resource("docs::Document", async function (id, props) {
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(props.path), { recursive: true });
+    if (this.phase === "delete") {
+        try {
+            await fs.unlink(props.path);
+        }
+        catch (error) {
+            // Ignore if file doesn't exist
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        return this.destroy();
+    }
+    // Initialize OpenAI compatible provider using shared client
+    const provider = createClient(props);
+    // Generate content
+    const { text } = await generateText({
+        model: provider(getModelId(props)),
+        prompt: props.prompt,
+        ...getModelOptions(props),
+    });
+    // Write content to file
+    await fs.writeFile(props.path, text);
+    // Get file stats for timestamps
+    const stats = await fs.stat(props.path);
+    // Return the resource
+    return this({
+        ...props,
+        content: text,
+        createdAt: stats.birthtimeMs,
+        updatedAt: stats.mtimeMs,
+    });
+});

package/lib/ai/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./document";
+export * from "./object";

package/lib/ai/index.js

@@ -0,0 +1,2 @@
+export * from "./document";
+export * from "./object";

package/lib/ai/object.d.ts

@@ -0,0 +1,101 @@
+import type { JsonSchema, Type, type } from "arktype";
+import type { Context } from "../context";
+import { Resource } from "../resource";
+import type { Secret } from "../secret";
+import { type ModelConfig } from "./client";
+/**
+ * Properties for creating or updating an AI Object
+ */
+export interface ObjectProps<T extends Type<any, any>> {
+    /**
+     * The ArkType schema to validate and structure the generated content
+     */
+    schema: T | JsonSchema;
+    /**
+     * Prompt for generating the content
+     * Use alchemy template literals to include file context:
+     * @example
+     * prompt: await alchemy`
+     *   Generate a description for:
+     *   ${alchemy.file("src/data.ts")}
+     * `
+     */
+    prompt: string;
+    /**
+     * System prompt to guide the AI's behavior
+     * @example
+     * system: "You are a technical writer tasked with describing code"
+     */
+    system?: string;
+    /**
+     * Base URL for the OpenAI API
+     * @default 'https://api.openai.com/v1'
+     */
+    baseURL?: 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;
+}
+/**
+ * A resource that uses AI to generate structured content based on a schema
+ */
+export interface Object<T> extends Resource<"ai::Object"> {
+    type: JsonSchema;
+    /**
+     * The generated content, typed according to the provided schema
+     */
+    object: T;
+    /**
+     * Time at which the content was generated
+     */
+    createdAt: number;
+}
+/**
+ * Resource for generating structured content using the Vercel AI SDK.
+ * Supports powerful context handling through the alchemy template literal tag.
+ *
+ * @example
+ * // Generate a product description with specific fields
+ * const productSchema = type({
+ *   name: "string",
+ *   description: "string",
+ *   features: "string[]",
+ *   price: "number"
+ * });
+ *
+ * const product = await Object("new-product", {
+ *   schema: productSchema,
+ *   prompt: "Generate a product description for a new smartphone",
+ *   system: "You are a product copywriter specializing in tech products"
+ * });
+ *
+ * console.log(product.content); // Typed as per schema
+ *
+ * @example
+ * // Generate code documentation with context
+ * const docSchema = type({
+ *   summary: "string",
+ *   parameters: {
+ *     name: "string",
+ *     type: "string",
+ *     description: "string"
+ *   }[],
+ *   returns: "string"
+ * });
+ *
+ * const docs = await Object("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"
+ * });
+ */
+export declare const Object: (((this: any, id: string, props?: {}) => never) & (new (_: never) => never)) | (<const T extends Type<any, any>>(this: Context<Object<any>>, id: string, props: ObjectProps<T>) => Promise<Object<type.infer<T>>>);

package/lib/ai/object.js

@@ -0,0 +1,70 @@
+import { generateObject } from "ai";
+import { Resource } from "../resource";
+import { ark } from "./ark";
+import { createClient, getModelId, getModelOptions, } from "./client";
+/**
+ * Resource for generating structured content using the Vercel AI SDK.
+ * Supports powerful context handling through the alchemy template literal tag.
+ *
+ * @example
+ * // Generate a product description with specific fields
+ * const productSchema = type({
+ *   name: "string",
+ *   description: "string",
+ *   features: "string[]",
+ *   price: "number"
+ * });
+ *
+ * const product = await Object("new-product", {
+ *   schema: productSchema,
+ *   prompt: "Generate a product description for a new smartphone",
+ *   system: "You are a product copywriter specializing in tech products"
+ * });
+ *
+ * console.log(product.content); // Typed as per schema
+ *
+ * @example
+ * // Generate code documentation with context
+ * const docSchema = type({
+ *   summary: "string",
+ *   parameters: {
+ *     name: "string",
+ *     type: "string",
+ *     description: "string"
+ *   }[],
+ *   returns: "string"
+ * });
+ *
+ * const docs = await Object("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"
+ * });
+ */
+export const Object = 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);
+    // Generate structured output using generateObject
+    const { object } = await generateObject({
+        model: provider(getModelId(props)),
+        // Convert ArkType schema to Zod schema for generateObject
+        // This is needed because generateObject expects a Zod schema
+        schema: ark.schema(props.schema),
+        system: props.system ||
+            "You are an AI assistant tasked with generating structured content.",
+        prompt: props.prompt,
+        ...getModelOptions(props),
+    });
+    // Return the resource with typed content
+    return this({
+        type: props.schema,
+        object: object,
+        createdAt: Date.now(),
+    });
+});

package/lib/alchemy.d.ts

@@ -2,14 +2,71 @@ import { destroy } from "./destroy";
 import { Scope } from "./scope";
 import { secret } from "./secret";
 import type { StateStoreType } from "./state";
+/**
+ * Type alias for semantic highlighting of `alchemy` as a type keyword
+ */
 export type alchemy = Alchemy;
 export declare const alchemy: Alchemy;
+/**
+ * The Alchemy interface provides core functionality and is augmented by providers.
+ * Supports both application scoping with secrets and template string interpolation.
+ *
+ * @example
+ * // Create an application scope with stage and secret handling
+ * const app = alchemy("github:alchemy", {
+ *   stage: "prod",
+ *   phase: "up",
+ *   // Required for encrypting/decrypting secrets
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ *
+ * // Create a resource with encrypted secrets
+ * const resource = await Resource("my-resource", {
+ *   apiKey: alchemy.secret(process.env.API_KEY)
+ * });
+ *
+ * await app.finalize();
+ */
 export interface Alchemy {
     scope: typeof scope;
     run: typeof run;
     destroy: typeof destroy;
+    /**
+     * Creates an encrypted secret that can be safely stored in state files.
+     * Requires a password to be set either globally in the application options
+     * or locally in the current scope.
+     */
     secret: typeof secret;
+    /**
+     * Creates a new application scope with the given name and options.
+     * Used to create and manage resources with proper secret handling.
+     *
+     * @example
+     * const app = alchemy("my-app", {
+     *   stage: "prod",
+     *   // Required for encrypting/decrypting secrets
+     *   password: process.env.SECRET_PASSPHRASE
+     * });
+     */
     (...parameters: Parameters<typeof scope>): ReturnType<typeof scope>;
+    /**
+     * Template literal tag that supports file interpolation for documentation.
+     * Automatically formats the content and appends file contents as code blocks.
+     *
+     * @example
+     * // Generate documentation using file contents
+     * await Document("api-docs", {
+     *   prompt: await alchemy`
+     *     Generate docs using the contents of:
+     *     ${alchemy.file("README.md")}
+     *     ${alchemy.file("./.cursorrules")}
+     *
+     *     And here are the source files:
+     *     ${alchemy.files(files)}
+     *   `
+     * });
+     */
+    (template: TemplateStringsArray, ...values: any[]): Promise<string>;
 }
 export interface AlchemyOptions {
     /**
@@ -50,15 +107,40 @@ export interface AlchemyOptions {
     quiet?: boolean;
     /**
      * A passphrase to use to encrypt/decrypt secrets.
+     * Required if using alchemy.secret() in this scope.
      */
     password?: string;
 }
 /**
  * Enter a new scope synchronously.
- * @param options
- * @returns
+ *
+ * @example
+ * // Create a scope with a password for secret handling
+ * await using scope = alchemy.scope("my-scope", {
+ *   password: process.env.SECRET_PASSPHRASE
+ * });
+ *
+ * // Use secrets within the scope
+ * const resource = await Resource("my-resource", {
+ *   apiKey: alchemy.secret(process.env.API_KEY)
+ * });
  */
 declare function scope(id: string | undefined, options?: AlchemyOptions): Scope;
+/**
+ * Run a function in a new scope asynchronously.
+ * Useful for isolating secret handling with a specific password.
+ *
+ * @example
+ * // Run operations in a scope with its own password
+ * await alchemy.run("secure-scope", {
+ *   password: process.env.SCOPE_PASSWORD
+ * }, async () => {
+ *   // Secrets in this scope will use this password
+ *   const resource = await Resource("my-resource", {
+ *     apiKey: alchemy.secret(process.env.API_KEY)
+ *   });
+ * });
+ */
 declare function run<T>(...args: [id: string, fn: (this: Scope, scope: Scope) => Promise<T>] | [
     id: string,
     options: AlchemyOptions,