index.md

Agent onboarding index

Purpose

pie is a structured extraction library and CLI built on @mariozechner/pi-ai.

Start here

• README.md: Overview, auth, CLI basics.
• docs/architecture.md: High-level layout.
• docs/agent/reports.md: Pre-indexed deep dive (generated by npx tsx scripts/preindex.ts).

When running examples or scripts

• Run from repo root: npm run build.
• List models: pie --list-models --models-provider <provider> (use --models-filter to narrow).
• Authenticate providers: pie --login <provider> (writes ~/.pi/agent/auth.json).
• Examples use the shared OAuth helper in examples/_shared/oauth.ts and will prompt if credentials are missing.
• Run scripts via npx tsx examples/<name>/run.ts (for example npx tsx examples/hn-insights/run.ts).

When implementing or reviewing changes

• docs/agent/guidelines.md: Conventions, workflows, error handling.
• examples/: Working usage patterns.

Examples for complex concepts

• Recipes and setup files: examples/recipe-system, examples/templated-support-triage
• Caching and cache warming: examples/caching, examples/warm-cache
• Validation layers: examples/validation-shell, examples/validation-http, examples/validation-retry
• Streaming events and retries: examples/retry-feedback
• Multimodal inputs: examples/vision-circle