@justram/pie 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## [Unreleased]
+
+### Breaking Changes
+
+- Published as `@justram/pie` because the unscoped name is already taken on npm.
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## 0.1.0
+
+- Initial release of the SDK and CLI.
+- Mini agent extraction loop with schema validation and retries.
+- Validator layers (sync/async, shell, HTTP).
+- Response caching with memory and file stores.
+- Recipe system for reusable extraction setups.
+- Added `src/main.ts` and moved CLI orchestration behind a thin `src/cli.ts` entry.
+- Moved internal CLI helpers from `src/core/helpers.ts` to `src/utils/helpers.ts`.
+- Routed cache/errors/setup exports through public wrapper modules and kept `bin/pie` as a thin entry.
+- Documented the CLI entry flow and added architecture notes.
+- Split TypeScript config into `tsconfig.base.json` and `tsconfig.build.json`.
+- Updated `.gitignore` for macOS and example artifacts.
+- Updated the thinking-comparison example default model to an available Gemini variant.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jheng Hong Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# pie
+
+Structured extraction library and CLI built on `@mariozechner/pi-ai`.
+
+- Mini agent loop: think → respond → validate → retry
+- Schema-first with TypeBox + AJV
+- Layered validation (schema, sync/async functions, shell, HTTP)
+- Streaming events for observability
+- Unix-friendly CLI
+- Optional response caching
+
+## Installation
+
+```bash
+npm install @justram/pie
+```
+
+## Getting Started
+
+### Pick a model
+
+`pie` uses the provider/model registry from `@mariozechner/pi-ai`. In the CLI, pass `--model provider/model`:
+
+```bash
+cat input.txt | pie \
+	-s schema.json \
+	-p "Extract fields" \
+	--model anthropic/claude-sonnet-4-5
+```
+
+### Authentication (API keys and OAuth)
+
+`pie` does not require Pi to be installed. It uses the OAuth helpers from `@mariozechner/pi-ai` and stores credentials in `~/.pi/agent/auth.json` (created automatically on first login).
+
+Credential resolution order:
+
+1. `~/.pi/agent/auth.json` (API keys or OAuth tokens)
+2. Environment variables (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`)
+3. OAuth login (only for supported providers)
+
+#### OAuth login
+
+Run `--login` to authenticate with an OAuth-capable provider. The CLI prints a URL and prompts you to complete login in your browser.
+
+```bash
+pie --login openai-codex
+```
+
+Supported OAuth providers:
+- `anthropic`
+- `github-copilot`
+- `google-gemini-cli`
+- `google-antigravity`
+- `openai-codex`
+
+If you skip this step, `pie` will still prompt for OAuth the first time you run a command that requires it.
+
+```bash
+cat input.txt | pie \
+	-s schema.json \
+	-p "Extract fields" \
+	--model github-copilot/gpt-4o
+```
+
+#### API keys (recommended for examples)
+
+Use environment variables:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Or add API keys to `~/.pi/agent/auth.json`:
+
+```json
+{
+  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
+  "openai": { "type": "api_key", "key": "sk-..." }
+}
+```
+
+Auth file entries take precedence over environment variables. To switch from OAuth to API keys, remove the OAuth entry for that provider and add an `api_key` entry.
+
+#### Already using Pi?
+
+`pie` shares the same auth store as Pi: `~/.pi/agent/auth.json`. If you have already run `/login` in Pi, `pie` will reuse those credentials automatically. You can also add API keys to the same file and both tools will pick them up.
+
+#### Resetting credentials
+
+Edit or delete `~/.pi/agent/auth.json` to remove a provider and force re-login.
+
+## SDK Usage
+
+```ts
+import { extractSync, getModel, Type } from "@justram/pie";
+
+const schema = Type.Object({
+	sentiment: Type.Union([
+		Type.Literal("positive"),
+		Type.Literal("negative"),
+		Type.Literal("neutral"),
+	]),
+	confidence: Type.Number({ minimum: 0, maximum: 1 }),
+});
+
+const model = getModel("anthropic", "claude-sonnet-4-5");
+
+const data = await extractSync("I love this product!", {
+	schema,
+	prompt: "Classify the sentiment.",
+	model,
+});
+
+console.log(data);
+```
+
+### Streaming events
+
+```ts
+import { extract } from "@justram/pie";
+
+const stream = extract("Example text", {
+	schema,
+	prompt: "Extract fields.",
+	model: getModel("openai", "gpt-4o"),
+});
+
+for await (const event of stream) {
+	if (event.type === "validation_error") {
+		console.error(event.layer, event.error);
+	}
+}
+
+const result = await stream.result();
+```
+
+### Caching
+
+```ts
+import { createFileCache, warmCache } from "@justram/pie/cache";
+import { getModel } from "@justram/pie";
+
+const model = getModel("anthropic", "claude-sonnet-4-5");
+const store = createFileCache({ directory: "./cache" });
+
+await warmCache(["doc1", "doc2"], {
+	schema,
+	prompt: "Extract fields.",
+	model,
+	cache: { store },
+});
+```
+
+### Validation examples
+
+#### Shell validator
+
+```ts
+const data = await extractSync(input, {
+	schema,
+	prompt: "Extract fields.",
+	model,
+	validateCommand: "jq -e '.score > 0.5'",
+});
+```
+
+```bash
+cat input.txt | pie -s schema.json -p "Extract" \
+	--validate "jq -e '.score > 0.5'"
+```
+
+#### HTTP validator
+
+```ts
+const data = await extractSync(input, {
+	schema,
+	prompt: "Extract fields.",
+	model,
+	validateUrl: "https://api.example.com/validate",
+});
+```
+
+```bash
+cat input.txt | pie -s schema.json -p "Extract" \
+	--validate-url "https://api.example.com/validate"
+```
+
+## CLI Usage
+
+```bash
+pie --help
+
+# Basic extraction
+cat input.txt | pie \
+	-s schema.json \
+	-p "Extract fields" \
+	--model anthropic/claude-sonnet-4-5
+
+# Stream partial JSON to stderr
+cat input.txt | pie -s schema.json -p "Extract" --stream 2>progress.jsonl
+```
+
+### CLI Requirements
+
+- A configured model credential (see [Authentication](#authentication-api-keys-and-oauth)).
+- A JSON Schema (`--schema`) and prompt (`--prompt`/`--prompt-file`) unless you use `--config` or `--recipe`.
+
+## Recipes
+
+Recipes live in `~/.pie/recipes` or `./.pie/recipes` and allow reusable setups.
+
+```bash
+pie --list-recipes
+pie --recipe support-triage --input ticket.txt
+```
+
+## Public API Surface
+
+- The package root (`@justram/pie`) exposes the SDK surface from `src/index.ts` (extract, models, recipes, cache, errors, types).
+- Cache helpers are also available via the `@justram/pie/cache` subpath.
+
+### CLI entry flow (contributors)
+
+- `src/cli.ts` is the executable entry (shebang) and delegates to `src/main.ts`.
+- `src/cli/index.ts` re-exports `runCli` for tests and internal callers.
+
+## Development
+
+```bash
+npm run build
+npm run test
+```
+
+## License
+
+MIT

package/bin/pie

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import { runCli } from "../dist/cli.js";
+
+async function main(): Promise<void> {
+	const exitCode = await runCli(process.argv.slice(2));
+	process.exitCode = exitCode;
+}
+
+void main().catch((error) => {
+	const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+	console.error(message);
+	process.exitCode = 1;
+});

package/dist/cache/index.d.ts

@@ -0,0 +1,4 @@
+export { createFileCache } from "../core/cache/file.js";
+export { createMemoryCache } from "../core/cache/memory.js";
+export type { CacheEntry, CacheOptions, CacheStore } from "../core/cache/types.js";
+export { warmCache } from "./warm.js";

package/dist/cache/index.js

@@ -0,0 +1,3 @@
+export { createFileCache } from "../core/cache/file.js";
+export { createMemoryCache } from "../core/cache/memory.js";
+export { warmCache } from "./warm.js";

package/dist/cache/warm.d.ts

@@ -0,0 +1,3 @@
+import type { Message } from "@mariozechner/pi-ai";
+import type { ExtractOptions } from "../types.js";
+export declare function warmCache<T>(inputs: Array<string | Message[]>, options: ExtractOptions<T>): Promise<void>;

package/dist/cache/warm.js

@@ -0,0 +1,23 @@
+import { extractSync } from "../extract.js";
+function normalizeCache(options) {
+    const raw = options.cache;
+    const hasFunctionValidators = Boolean(options.validate || options.validateAsync);
+    if (!raw) {
+        return hasFunctionValidators ? { revalidate: true } : true;
+    }
+    if (raw === true) {
+        return hasFunctionValidators ? { revalidate: true } : true;
+    }
+    const cache = { ...raw };
+    if (hasFunctionValidators && cache.revalidate === undefined) {
+        cache.revalidate = true;
+    }
+    return cache;
+}
+export async function warmCache(inputs, options) {
+    const cache = normalizeCache(options);
+    const warmedOptions = { ...options, cache };
+    for (const input of inputs) {
+        await extractSync(input, warmedOptions);
+    }
+}

package/dist/cli/args.d.ts

@@ -0,0 +1,30 @@
+export interface CliArgs {
+    schema?: string;
+    prompt?: string;
+    promptFile?: string;
+    input?: string;
+    attachments: string[];
+    output?: string;
+    model?: string;
+    maxTurns?: number;
+    validateCommand?: string;
+    validateUrl?: string;
+    stream?: boolean;
+    verbose?: boolean;
+    quiet?: boolean;
+    jsonSchema?: boolean;
+    config?: string;
+    recipe?: string;
+    recipeConfig?: string;
+    recipeVars?: string;
+    listRecipes?: boolean;
+    login?: string;
+    help?: boolean;
+    version?: boolean;
+}
+export interface ParsedArgs {
+    args: CliArgs;
+    errors: string[];
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function renderHelp(): string;

package/dist/cli/args.js

@@ -0,0 +1,185 @@
+export function parseArgs(argv) {
+    const args = {
+        attachments: [],
+    };
+    const errors = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const nextValue = (flag) => {
+            if (i + 1 >= argv.length) {
+                errors.push(`Missing value for ${flag}.`);
+                return undefined;
+            }
+            return argv[++i];
+        };
+        switch (arg) {
+            case "-s":
+            case "--schema": {
+                const value = nextValue(arg);
+                if (value)
+                    args.schema = value;
+                break;
+            }
+            case "-p":
+            case "--prompt": {
+                const value = nextValue(arg);
+                if (value)
+                    args.prompt = value;
+                break;
+            }
+            case "--prompt-file": {
+                const value = nextValue(arg);
+                if (value)
+                    args.promptFile = value;
+                break;
+            }
+            case "-i":
+            case "--input": {
+                const value = nextValue(arg);
+                if (value)
+                    args.input = value;
+                break;
+            }
+            case "-a":
+            case "--attach": {
+                const value = nextValue(arg);
+                if (value)
+                    args.attachments.push(value);
+                break;
+            }
+            case "-o":
+            case "--output": {
+                const value = nextValue(arg);
+                if (value)
+                    args.output = value;
+                break;
+            }
+            case "-m":
+            case "--model": {
+                const value = nextValue(arg);
+                if (value)
+                    args.model = value;
+                break;
+            }
+            case "-t":
+            case "--max-turns": {
+                const value = nextValue(arg);
+                if (!value)
+                    break;
+                const parsed = Number.parseInt(value, 10);
+                if (!Number.isFinite(parsed) || parsed <= 0) {
+                    errors.push(`Invalid value for ${arg}: ${value}`);
+                }
+                else {
+                    args.maxTurns = parsed;
+                }
+                break;
+            }
+            case "--validate": {
+                const value = nextValue(arg);
+                if (value)
+                    args.validateCommand = value;
+                break;
+            }
+            case "--validate-url": {
+                const value = nextValue(arg);
+                if (value)
+                    args.validateUrl = value;
+                break;
+            }
+            case "--stream":
+                args.stream = true;
+                break;
+            case "--verbose":
+                args.verbose = true;
+                break;
+            case "--quiet":
+                args.quiet = true;
+                break;
+            case "--json-schema":
+                args.jsonSchema = true;
+                break;
+            case "-c":
+            case "--config": {
+                const value = nextValue(arg);
+                if (value)
+                    args.config = value;
+                break;
+            }
+            case "--recipe": {
+                const value = nextValue(arg);
+                if (value)
+                    args.recipe = value;
+                break;
+            }
+            case "--recipe-config": {
+                const value = nextValue(arg);
+                if (value)
+                    args.recipeConfig = value;
+                break;
+            }
+            case "--recipe-vars": {
+                const value = nextValue(arg);
+                if (value)
+                    args.recipeVars = value;
+                break;
+            }
+            case "--list-recipes":
+                args.listRecipes = true;
+                break;
+            case "--login": {
+                const value = nextValue(arg);
+                if (value)
+                    args.login = value;
+                break;
+            }
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            case "-v":
+            case "--version":
+                args.version = true;
+                break;
+            default:
+                if (arg.startsWith("-")) {
+                    errors.push(`Unknown option: ${arg}`);
+                }
+                else {
+                    errors.push(`Unexpected argument: ${arg}`);
+                }
+        }
+    }
+    return { args, errors };
+}
+export function renderHelp() {
+    return `pie - Structured extraction CLI
+
+Usage:
+  pie [options]
+
+Options:
+  -s, --schema <file|json>   JSON Schema (required unless --config)
+  -p, --prompt <text>        System prompt (or setup frontmatter + Jinja template)
+  --prompt-file <file>       Load prompt or setup document from file
+  -i, --input <file>         Input file (default: stdin)
+  -a, --attach <file>        Attach file (repeatable) - text or image
+  -o, --output <file>        Output file (default: stdout)
+  -m, --model <name>         Model name (default: best available)
+  -t, --max-turns <n>        Max turns in extraction loop (default: 3)
+  --validate <cmd>           Shell validator command
+  --validate-url <url>       HTTP validator endpoint
+  --stream                   Stream partial JSON to stderr
+  --verbose                  Show detailed progress
+  --quiet                    Suppress non-essential output
+  --json-schema              Output the generated JSON Schema and exit
+  -c, --config <file>        Load JS config for advanced extraction
+  --recipe <name>            Use a named recipe from ~/.pie/recipes or ./.pie/recipes
+  --recipe-config <file>     Use a recipe config file (default: setup.md)
+  --recipe-vars <json>       JSON object for recipe template vars
+  --list-recipes             List available recipes and exit
+  --login <provider>         OAuth login for a provider (e.g. anthropic)
+  -h, --help                 Show help
+  -v, --version              Show version
+`;
+}

package/dist/cli/attachments.d.ts

@@ -0,0 +1,7 @@
+import type { ImageContent } from "@mariozechner/pi-ai";
+export interface AttachmentLoadResult {
+    textPrefix: string;
+    images: ImageContent[];
+}
+export declare function loadAttachments(paths: string[]): AttachmentLoadResult;
+export declare function renderFileBlock(path: string, content: string, mimeType?: string): string;

package/dist/cli/attachments.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isImagePath, mimeTypeForImage, resizeImage } from "./image.js";
+export function loadAttachments(paths) {
+    const images = [];
+    const blocks = [];
+    for (const inputPath of paths) {
+        const resolved = resolve(inputPath);
+        if (isImagePath(resolved)) {
+            const buffer = readFileSync(resolved);
+            const mimeType = mimeTypeForImage(resolved);
+            const base64 = buffer.toString("base64");
+            const resized = resizeImage({ type: "image", mimeType, data: base64 });
+            images.push(resized.image);
+            blocks.push(renderFileBlock(resolved, "[image attached]", resized.image.mimeType));
+            continue;
+        }
+        const content = readFileSync(resolved, "utf8");
+        blocks.push(renderFileBlock(resolved, content));
+    }
+    return {
+        textPrefix: blocks.join("\n\n"),
+        images,
+    };
+}
+export function renderFileBlock(path, content, mimeType) {
+    const typeAttr = mimeType ? ` type="${mimeType}"` : "";
+    return `<file name="${path}"${typeAttr}>\n${content}\n</file>`;
+}

package/dist/cli/config.d.ts

@@ -0,0 +1,22 @@
+import type { Message, Model } from "@mariozechner/pi-ai";
+import type { ExtractOptions } from "../core/types.js";
+import type { CliArgs } from "./args.js";
+import type { AttachmentLoadResult } from "./attachments.js";
+export interface CliConfigContext {
+    args: CliArgs;
+    input: string;
+    inputText: string;
+    attachments: AttachmentLoadResult;
+    resolveModel: (value: string) => Model<any>;
+    resolveApiKeyForProvider: (provider: string) => Promise<string | undefined>;
+}
+export interface CliConfigResult<T> {
+    options: ExtractOptions<T>;
+    input?: string | Message[];
+    output?: string;
+    stream?: boolean;
+    verbose?: boolean;
+    quiet?: boolean;
+}
+export type CliConfig<T> = (context: CliConfigContext) => CliConfigResult<T> | Promise<CliConfigResult<T>>;
+export declare function loadCliConfig(path: string): Promise<CliConfig<unknown>>;

package/dist/cli/config.js

@@ -0,0 +1,20 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+export async function loadCliConfig(path) {
+    const resolved = resolve(path);
+    const url = pathToFileURL(resolved).href;
+    let moduleExports;
+    try {
+        moduleExports = await import(url);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load config file ${resolved}: ${message}`);
+    }
+    const candidate = moduleExports.default ??
+        moduleExports.config;
+    if (typeof candidate !== "function") {
+        throw new Error(`Config file ${resolved} must export a default function or a named export "config".`);
+    }
+    return candidate;
+}

package/dist/cli/image.d.ts

@@ -0,0 +1,17 @@
+import type { ImageContent } from "@mariozechner/pi-ai";
+export interface ImageResizeOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+    jpegQuality?: number;
+}
+export interface ResizedImage {
+    image: ImageContent;
+    originalWidth: number;
+    originalHeight: number;
+    width: number;
+    height: number;
+    wasResized: boolean;
+}
+export declare function resizeImage(image: ImageContent, options?: ImageResizeOptions): ResizedImage;
+export declare function isImagePath(path: string): boolean;
+export declare function mimeTypeForImage(path: string): string;