API Reference

@edv4h/alchemy-core

Core types, refiners, material utilities, and transform helpers. Zero runtime dependencies beyond Zod.

Types

MaterialPart

Discriminated union of all material types. Built-in types:

MaterialInput

Wire-format for API requests. Same structure as MaterialPart but used for client-to-server communication. Convert with toMaterialParts().

Transmuter

Interface for LLM provider adapters.

interface Transmuter {
  transmute(
    materials: MaterialPart[],
    options: TransmutationOptions,
  ): Promise<TransmutationResult>;

  stream(
    materials: MaterialPart[],
    options: TransmutationOptions,
  ): AsyncGenerator<string>;
}

TransmutationOptions

TransmutationResult

Refiner<TOutput>

Recipe<TInput, TOutput>

Validation

MaterialPartType

Union of all material part type strings: "text" | "image" | "audio" | "document" | "video" | "data"

MaterialRequirement

MaterialValidationResult

MaterialValidationIssue

MaterialEvaluation

Quality score returned by evaluate on a MaterialRequirement.

MaterialEvaluationEntry

Entry passed to judgeMaterials, grouping a requirement's type/label with its evaluation result.

MaterialJudgement

Result of judgeMaterials, deciding whether transmutation should proceed.

validateMaterialRequirements(requirements, parts)

Validate material parts against declarative requirements.

function validateMaterialRequirements(
  requirements: MaterialRequirement[],
  parts: MaterialPart[],
): MaterialValidationResult;

runMaterialValidation(recipe, parts)

Run the validation pipeline: declarative check → evaluate → judgeMaterials → custom validateMaterials. Each stage runs only when configured, and is skipped if a previous stage fails.

async function runMaterialValidation(
  recipe: {
    requiredMaterials?: MaterialRequirement[];
    validateMaterials?: (parts: MaterialPart[]) => MaterialValidationResult | Promise<MaterialValidationResult>;
    judgeMaterials?: (evaluations: MaterialEvaluationEntry[]) => MaterialJudgement;
  },
  parts: MaterialPart[],
): Promise<MaterialValidationResult>;

Validation stages (each runs only when configured, and is skipped if a previous stage fails):

1. Declarative check — validates requiredMaterials counts by type (if requiredMaterials is set)
2. Evaluate — runs each requirement's evaluate() in parallel, producing quality scores (only for requirements with evaluate)
3. Judge — passes evaluations to judgeMaterials() for transmute eligibility (only if evaluations exist and judgeMaterials is set)
4. Custom check — runs validateMaterials() as a final filter (if provided)

Refiners

TextRefiner

Trims whitespace from the raw output. Returns string.

JsonRefiner<T>

Validates output against a Zod schema.

new JsonRefiner(schema: ZodType<T>)

// Behavior:
// 1. Strips markdown code fences (```json ... ```)
// 2. Parses JSON
// 3. Validates against schema
// 4. Returns typed T
// 5. formatInstructions() returns JSON schema description

Material Utilities

Transforms

Errors

@edv4h/alchemy-node

Node.js-specific implementations. Depends on @edv4h/alchemy-core and openai.

Alchemist

Main orchestrator class.

Constructor

new Alchemist(config: AlchemistConfig)

interface AlchemistConfig {
  transmuter: Transmuter;
  transforms?: MaterialTransform[];
  validateMaterials?: boolean; // Auto-validate before transmute/stream (default: false)
}

Methods

transmute<TInput, TOutput>(recipe, material, options?)

Execute a recipe with materials and return the parsed output.

Returns: Promise<TOutput>

stream<TInput>(recipe, material, options?)

Stream the response progressively.

Returns: AsyncGenerator<string>

generate<TInput, TOutput>(recipe, material, count, options?)

Generate multiple variations of the same recipe in parallel.

Returns: Promise<Record<string, TOutput | { error: Error }>> — Keys are variation-1, variation-2, etc. Uses Promise.allSettled internally.

OpenAITransmuter

OpenAI Chat Completions API transmuter.

new OpenAITransmuter(config?: OpenAITransmuterConfig)

interface OpenAITransmuterConfig {
  apiKey?: string;       // Defaults to OPENAI_API_KEY env var
  defaultModel?: string; // Defaults to "gpt-4o-mini"
  baseURL?: string;      // Custom API endpoint
}

Material type mapping:

AnthropicTransmuter

Anthropic Messages API transmuter.

new AnthropicTransmuter(config?: AnthropicTransmuterConfig)

interface AnthropicTransmuterConfig {
  apiKey?: string;       // Defaults to ANTHROPIC_API_KEY env var
  defaultModel?: string; // Defaults to "claude-sonnet-4-20250514"
}

Material type mapping:

GoogleTransmuter

Google Generative AI (Gemini) transmuter.

new GoogleTransmuter(config?: GoogleTransmuterConfig)

interface GoogleTransmuterConfig {
  apiKey?: string;       // Defaults to GOOGLE_API_KEY env var
  defaultModel?: string; // Defaults to "gemini-2.0-flash"
}

Material type mapping:

Node Transforms

@edv4h/alchemy-react

React hooks for building LLM-powered UIs. Peer dependency: react@^18 || ^19.

useTransmute<TOutput>

Low-level hook for single recipe execution.

const {
  transmute,  // (recipeId, materials, options?) => Promise
  data,       // TOutput | null
  isLoading,  // boolean
  error,      // Error | null
  reset,      // () => void
} = useTransmute<TOutput>({
  baseUrl?: string;
  headers?: Record<string, string>;
});

Calls POST /api/transmute/{recipeId} with materials in the body. Supports request cancellation via AbortSignal.

useAlchemy<TOutput>

High-level orchestration hook combining useTransmute and useGenerate with full state management.

const {
  // Recipe selection
  selectedRecipeId,
  selectRecipe,

  // Material selection (ID-based)
  selectedIds,
  toggleMaterial,
  clearSelection,

  // Language
  selectedLanguage,
  setLanguage,

  // Actions
  transmute,       // (materials) => Promise

  // Results
  result,          // TOutput | null
  isLoading,
  error,
  resetResults,
} = useAlchemy<TOutput>({
  baseUrl?: string;
  headers?: Record<string, string>;
  initialRecipeId: string;
});