Add customer enrichment Agent API tutorial

[andrewmadson-pplx]

Description

Adds a complete Python tutorial for enriching local ClickHouse customer records with the Perplexity Agent API, built-in people_search, and two narrowly scoped custom functions. The example teaches identity disambiguation and evidence-backed persistence without allowing model-authored SQL or URLs to cross the application boundary.

The tutorial includes a macOS-first walkthrough, exact dependency and ClickHouse image pins, deterministic offline fixtures, an explicitly gated live smoke test, and an automated README command runner.

Type of Contribution

• Example Tutorial
• Showcase Project
• Article/Integration Guide
• Documentation Update
• Bug Fix
• Other (please describe)

Project Details

What problem does this solve?

It demonstrates the full path from private source-row lookup through live professional research to append-only, source-validated enrichment records. The application checks every model-selected result ID against structured People Search output from the same customer run and resolves URLs itself.

What makes this contribution valuable to other developers?

The example combines Agent API continuation state, custom function execution, least-privilege ClickHouse access, provenance storage, retry-safe writes, deterministic troubleshooting, and explicit API-spend controls in one inspectable CLI project.

Behavior and safety

• Uses perplexity/glm-5.3 by default and allows MODEL or --model overrides.
• Seeds three distinguishable public identities, one ambiguous identity, and one fictitious not-found case.
• Keeps source rows immutable and appends every enrichment attempt with raw structured evidence and response metadata.
• Requires explicit acknowledgement before any billable command and never falls back to fixtures silently.

Testing

• The deterministic suite passes with 51 tests and one explicitly skipped live test.
• The pinned ClickHouse image completed idempotent setup, matched/ambiguous/not-found writes, skip and forced-append behavior, direct provenance queries, and reset.
• All 42 cookbook MDX files compile successfully, and all 26 tutorial shell blocks pass classification and syntax checks.
• The billable Agent API smoke test remains opt-in and was not rerun without an API key and spend acknowledgement.