@justram/pie 0.1.0

package/dist/models.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Model utilities re-exported from pi-ai.
+ *
+ * Usage:
+ * ```typescript
+ * import { getModel, getModels, getProviders } from "pie";
+ *
+ * // Get specific model
+ * const model = getModel("anthropic", "claude-sonnet-4-5");
+ *
+ * // List all models for a provider
+ * const anthropicModels = getModels("anthropic");
+ *
+ * // List all providers
+ * const providers = getProviders();
+ * ```
+ *
+ * This approach avoids hardcoding model IDs which break when pi-ai updates.
+ * Users get full type safety from pi-ai's generated model types.
+ */
+export { getModel, getModels, getProviders } from "@mariozechner/pi-ai";

package/dist/models.js

@@ -0,0 +1,21 @@
+/**
+ * Model utilities re-exported from pi-ai.
+ *
+ * Usage:
+ * ```typescript
+ * import { getModel, getModels, getProviders } from "pie";
+ *
+ * // Get specific model
+ * const model = getModel("anthropic", "claude-sonnet-4-5");
+ *
+ * // List all models for a provider
+ * const anthropicModels = getModels("anthropic");
+ *
+ * // List all providers
+ * const providers = getProviders();
+ * ```
+ *
+ * This approach avoids hardcoding model IDs which break when pi-ai updates.
+ * Users get full type safety from pi-ai's generated model types.
+ */
+export { getModel, getModels, getProviders } from "@mariozechner/pi-ai";

package/dist/recipes/index.d.ts

@@ -0,0 +1,34 @@
+import type { ExtractionSetup } from "../core/setup.js";
+import type { ExtractOptions } from "../core/types.js";
+export interface RecipeFrontmatter {
+    name?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+export interface Recipe {
+    name: string;
+    description: string;
+    filePath: string;
+    baseDir: string;
+    source: string;
+}
+export interface RecipeWarning {
+    recipePath: string;
+    message: string;
+}
+export interface LoadRecipesOptions {
+    cwd?: string;
+    customDirectories?: string[];
+}
+export interface LoadRecipesResult {
+    recipes: Recipe[];
+    warnings: RecipeWarning[];
+}
+export interface LoadRecipeSetupOptions<T> {
+    setupFile?: string;
+    vars?: Record<string, unknown>;
+    overrides?: Partial<Omit<ExtractOptions<T>, "prompt" | "schema">>;
+}
+export declare function loadRecipes(options?: LoadRecipesOptions): LoadRecipesResult;
+export declare function resolveRecipe(name: string, options?: LoadRecipesOptions): Recipe | undefined;
+export declare function loadRecipeSetup<T>(recipe: Recipe, options?: LoadRecipeSetupOptions<T>): ExtractionSetup<T>;

package/dist/recipes/index.js

@@ -0,0 +1,185 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { parseFrontmatter } from "../core/frontmatter.js";
+import { loadExtractionSetup } from "../core/setup.js";
+const RECIPE_FILE_NAME = "RECIPE.md";
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const ALLOWED_FRONTMATTER_FIELDS = new Set(["name", "description", "metadata"]);
+export function loadRecipes(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const customDirectories = options.customDirectories ?? [];
+    const sources = [
+        { dir: join(homedir(), ".pie", "recipes"), source: "pie-user" },
+        { dir: resolve(cwd, ".pie", "recipes"), source: "pie-project" },
+        ...customDirectories.map((dir) => ({ dir: expandHome(dir), source: "custom" })),
+    ];
+    const recipesByName = new Map();
+    const warnings = [];
+    for (const entry of sources) {
+        const result = loadRecipesFromDir(entry.dir, entry.source);
+        warnings.push(...result.warnings);
+        for (const recipe of result.recipes) {
+            const existing = recipesByName.get(recipe.name);
+            if (existing) {
+                warnings.push({
+                    recipePath: recipe.filePath,
+                    message: `Recipe "${recipe.name}" overrides ${existing.filePath}.`,
+                });
+            }
+            recipesByName.set(recipe.name, recipe);
+        }
+    }
+    return {
+        recipes: Array.from(recipesByName.values()),
+        warnings,
+    };
+}
+export function resolveRecipe(name, options = {}) {
+    const { recipes } = loadRecipes(options);
+    return recipes.find((recipe) => recipe.name === name);
+}
+export function loadRecipeSetup(recipe, options = {}) {
+    const setupFile = options.setupFile ?? "setup.md";
+    const setupPath = resolve(recipe.baseDir, setupFile);
+    const setupOptions = {
+        vars: options.vars,
+        overrides: options.overrides,
+    };
+    return loadExtractionSetup(setupPath, setupOptions);
+}
+function loadRecipesFromDir(dir, source) {
+    const recipes = [];
+    const warnings = [];
+    if (!existsSync(dir)) {
+        return { recipes, warnings };
+    }
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith(".")) {
+                continue;
+            }
+            if (entry.name === "node_modules") {
+                continue;
+            }
+            const fullPath = join(dir, entry.name);
+            let isDirectory = entry.isDirectory();
+            let isFile = entry.isFile();
+            if (entry.isSymbolicLink()) {
+                try {
+                    const stats = statSync(fullPath);
+                    isDirectory = stats.isDirectory();
+                    isFile = stats.isFile();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDirectory) {
+                const subResult = loadRecipesFromDir(fullPath, source);
+                recipes.push(...subResult.recipes);
+                warnings.push(...subResult.warnings);
+                continue;
+            }
+            if (isFile && entry.name === RECIPE_FILE_NAME) {
+                const result = loadRecipeFromFile(fullPath, source);
+                if (result.recipe) {
+                    recipes.push(result.recipe);
+                }
+                warnings.push(...result.warnings);
+            }
+        }
+    }
+    catch { }
+    return { recipes, warnings };
+}
+function loadRecipeFromFile(filePath, source) {
+    const warnings = [];
+    try {
+        const rawContent = readFileSync(filePath, "utf-8");
+        const { frontmatter } = parseFrontmatter(rawContent);
+        const allKeys = Object.keys(frontmatter);
+        const recipeDir = dirname(filePath);
+        const parentDirName = basename(recipeDir);
+        const fieldErrors = validateFrontmatterFields(allKeys);
+        for (const error of fieldErrors) {
+            warnings.push({ recipePath: filePath, message: error });
+        }
+        const descErrors = validateDescription(frontmatter.description);
+        for (const error of descErrors) {
+            warnings.push({ recipePath: filePath, message: error });
+        }
+        const name = frontmatter.name ?? parentDirName;
+        const nameErrors = validateName(name, parentDirName);
+        for (const error of nameErrors) {
+            warnings.push({ recipePath: filePath, message: error });
+        }
+        if (!frontmatter.description || frontmatter.description.trim() === "") {
+            return { recipe: null, warnings };
+        }
+        return {
+            recipe: {
+                name,
+                description: frontmatter.description,
+                filePath,
+                baseDir: recipeDir,
+                source,
+            },
+            warnings,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "failed to parse recipe file";
+        warnings.push({ recipePath: filePath, message });
+        return { recipe: null, warnings };
+    }
+}
+function validateFrontmatterFields(keys) {
+    const errors = [];
+    for (const key of keys) {
+        if (!ALLOWED_FRONTMATTER_FIELDS.has(key)) {
+            errors.push(`unknown frontmatter field "${key}"`);
+        }
+    }
+    return errors;
+}
+function validateDescription(description) {
+    const errors = [];
+    if (!description || description.trim() === "") {
+        errors.push("description is required");
+    }
+    else if (description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+    }
+    return errors;
+}
+function validateName(name, parentDirName) {
+    const errors = [];
+    if (name !== parentDirName) {
+        errors.push(`name "${name}" does not match parent directory "${parentDirName}"`);
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+    }
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        errors.push("name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)");
+    }
+    if (name.startsWith("-") || name.endsWith("-")) {
+        errors.push("name must not start or end with a hyphen");
+    }
+    if (name.includes("--")) {
+        errors.push("name must not contain consecutive hyphens");
+    }
+    return errors;
+}
+function expandHome(path) {
+    if (path === "~") {
+        return homedir();
+    }
+    if (path.startsWith("~/")) {
+        return join(homedir(), path.slice(2));
+    }
+    return path;
+}

package/dist/runtime/node.d.ts

@@ -0,0 +1,2 @@
+import type { Runtime } from "./types.js";
+export declare function createNodeRuntime(): Runtime;

package/dist/runtime/node.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { readFile, rm, stat, writeFile, mkdir } from "node:fs/promises";
+import { spawn } from "node:child_process";
+export function createNodeRuntime() {
+    return {
+        now: () => Date.now(),
+        env: {
+            get: (name) => process.env[name],
+        },
+        fs: {
+            exists: async (path) => {
+                try {
+                    await stat(path);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            readFile: async (path) => {
+                const buf = await readFile(path);
+                return new Uint8Array(buf);
+            },
+            readTextFile: async (path) => {
+                return await readFile(path, { encoding: "utf8" });
+            },
+            writeFile: async (path, data) => {
+                await writeFile(path, data);
+            },
+            writeTextFile: async (path, text) => {
+                await writeFile(path, text, { encoding: "utf8" });
+            },
+            mkdir: async (path, options) => {
+                await mkdir(path, { recursive: options?.recursive ?? false });
+            },
+            remove: async (path, options) => {
+                await rm(path, { recursive: options?.recursive ?? false, force: true });
+            },
+        },
+        crypto: {
+            sha256Hex: async (text) => {
+                return createHash("sha256").update(text).digest("hex");
+            },
+        },
+        process: {
+            runShell: async (command, options) => {
+                const child = spawn("sh", ["-c", command], {
+                    stdio: ["pipe", "pipe", "pipe"],
+                    signal: options?.signal,
+                });
+                const stdoutChunks = [];
+                const stderrChunks = [];
+                child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+                child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+                if (options?.stdin !== undefined) {
+                    child.stdin.write(options.stdin);
+                }
+                child.stdin.end();
+                const code = await new Promise((resolve, reject) => {
+                    child.on("error", reject);
+                    child.on("close", (c) => resolve(c ?? 0));
+                });
+                return {
+                    code,
+                    stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                    stderr: Buffer.concat(stderrChunks).toString("utf8"),
+                };
+            },
+        },
+    };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,32 @@
+export interface Runtime {
+    now(): number;
+    env: {
+        get(name: string): string | undefined;
+    };
+    fs: {
+        exists(path: string): Promise<boolean>;
+        readFile(path: string): Promise<Uint8Array>;
+        readTextFile(path: string): Promise<string>;
+        writeFile(path: string, data: Uint8Array): Promise<void>;
+        writeTextFile(path: string, text: string): Promise<void>;
+        mkdir(path: string, options?: {
+            recursive?: boolean;
+        }): Promise<void>;
+        remove(path: string, options?: {
+            recursive?: boolean;
+        }): Promise<void>;
+    };
+    crypto: {
+        sha256Hex(text: string): Promise<string>;
+    };
+    process: {
+        runShell(command: string, options?: {
+            stdin?: string;
+            signal?: AbortSignal;
+        }): Promise<{
+            code: number;
+            stdout: string;
+            stderr: string;
+        }>;
+    };
+}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/setup.d.ts

@@ -0,0 +1,2 @@
+export type { ExtractionSetup, LoadExtractionSetupOptions } from "./core/setup.js";
+export { loadExtractionSetup } from "./core/setup.js";

package/dist/setup.js

@@ -0,0 +1 @@
+export { loadExtractionSetup } from "./core/setup.js";

package/dist/types.d.ts

@@ -0,0 +1 @@
+export type * from "./core/types.js";

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/helpers.d.ts

@@ -0,0 +1,5 @@
+import type { AssistantMessage, ImageContent, Message, ToolCall } from "@mariozechner/pi-ai";
+export declare function buildMessages(input: string | Message[], attachments?: ImageContent[]): Message[];
+export declare function findToolCall(message: AssistantMessage, toolName: string): ToolCall | undefined;
+export declare function getTextContent(message: AssistantMessage): string;
+export declare function parseJsonFromText(message: AssistantMessage): unknown | null;

package/dist/utils/helpers.js

@@ -0,0 +1,80 @@
+export function buildMessages(input, attachments) {
+    if (typeof input !== "string") {
+        return input;
+    }
+    const content = attachments?.length
+        ? [{ type: "text", text: input }, ...attachments]
+        : input;
+    const message = {
+        role: "user",
+        content,
+        timestamp: Date.now(),
+    };
+    return [message];
+}
+export function findToolCall(message, toolName) {
+    for (const content of message.content) {
+        if (content.type === "toolCall" && content.name === toolName) {
+            return content;
+        }
+    }
+    return undefined;
+}
+export function getTextContent(message) {
+    return message.content
+        .filter((content) => content.type === "text")
+        .map((content) => content.text)
+        .join("\n")
+        .trim();
+}
+export function parseJsonFromText(message) {
+    const text = getTextContent(message);
+    if (!text) {
+        return null;
+    }
+    const candidates = collectJsonCandidates(text);
+    for (const candidate of candidates) {
+        const parsed = tryParseJson(candidate);
+        if (parsed !== null) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function collectJsonCandidates(text) {
+    const candidates = [];
+    const fenced = extractFencedJson(text);
+    if (fenced) {
+        candidates.push(fenced);
+    }
+    candidates.push(text);
+    const objectCandidate = sliceBetween(text, "{", "}");
+    if (objectCandidate) {
+        candidates.push(objectCandidate);
+    }
+    const arrayCandidate = sliceBetween(text, "[", "]");
+    if (arrayCandidate) {
+        candidates.push(arrayCandidate);
+    }
+    return candidates;
+}
+function extractFencedJson(text) {
+    const match = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+    return match ? match[1].trim() : null;
+}
+function sliceBetween(text, open, close) {
+    const start = text.indexOf(open);
+    const end = text.lastIndexOf(close);
+    if (start === -1 || end === -1 || end <= start) {
+        return null;
+    }
+    return text.slice(start, end + 1).trim();
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "@justram/pie",
+	"version": "0.1.0",
+	"description": "Structured extraction library and CLI built on @mariozechner/pi-ai.",
+	"license": "MIT",
+	"keywords": [
+		"llm",
+		"structured-data",
+		"extraction",
+		"cli",
+		"schema",
+		"pi-ai"
+	],
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./cache": {
+			"types": "./dist/cache/index.d.ts",
+			"default": "./dist/cache/index.js"
+		}
+	},
+	"bin": {
+		"pie": "./bin/pie"
+	},
+	"files": [
+		"bin",
+		"dist",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"typecheck": "tsc -p tsconfig.base.json --noEmit",
+		"lint": "biome check .",
+		"lint:imports": "eslint --fix \"{src,test,spec,examples}/**/*.ts\"",
+		"check": "biome check --write . && npm run typecheck",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:e2e": "vitest run --config vitest.config.e2e.ts",
+		"prepare": "husky"
+	},
+	"dependencies": {
+		"@mariozechner/pi-ai": "^0.49.2",
+		"@silvia-odwyer/photon-node": "^0.3.4",
+		"@sinclair/typebox": "^0.34.46",
+		"minijinja-js": "^2.14.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.11",
+		"@types/node": "^22.10.2",
+		"@typescript-eslint/parser": "^8.46.0",
+		"eslint": "^9.36.0",
+		"eslint-plugin-simple-import-sort": "^12.1.1",
+		"fast-check": "^4.5.3",
+		"husky": "^9.1.7",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.16"
+	}
+}