feat(pydantic_config): reusable pydantic-backed pipeline config loader

[brian-arnold]

Implements the orcapod-python (in-scope) portion of ENG-607. Design spec: superpowers/specs/2026-06-12-pydantic-config-loader-design.md; plan: superpowers/plans/2026-06-12-pydantic-config-loader.md.

Summary

Adds a reusable, pydantic-backed config facility so wrapped pipelines can define a config schema once, validate a YAML config into a typed model at build time, and pass that validated model into pods as a first-class, content-hashed input — pods receive it already deserialized and typed.

New module src/orcapod/pydantic_config.py:

• load_pydantic_config(path, model_cls) -> model — reads YAML, validates against a pydantic model; raises a clear, file-located ValueError on parse/validation/IO failure (before any pod runs).
• OrcapodBaseConfig — recommended strict base (extra="forbid", frozen=True) so typos error and instances are immutable.
• PydanticModelConverter — a semantic-type converter (modeled on the existing Path converter) mapping any pydantic.BaseModel ⇄ an Arrow struct <__pydantic_model__, __pydantic_json__> and back. Content hash is over the model's qualified name + canonical (sorted-key) JSON, so identity tracks config meaning, not YAML formatting or dict key order.

Registered in the production semantic registry (contexts/data/v0.1.json, shared by the type converter + arrow hasher) and the standalone fallback registry (hashing/versioned_hashers.py). Adds pydantic>=2 to dependencies.

Design decisions

• Validated typed config is what flows into pods (not the raw file); hashing the canonical config means formatting-only YAML edits no longer bust the cache (improves on the ENG-601 raw-file-hash behavior).
• Registering python_type=BaseModel globally is safe: conversion dispatch is keyed off the declared schema type, not runtime isinstance; no collision with existing converters (reviewed).

Out of scope (follow-up)

Spike-sorting adoption — config/ schema models, swapping the broadcast source, pod annotations, and enigma-ephys dict-key migration — per the spec.

Test plan

• tests/test_pydantic_config.py — loader (valid / wrong-type / unknown-key / missing-required / missing-file / empty-file), converter round-trip + struct signature + can_handle_*, bad-qualname ImportError, hash equality/inequality, hash stable across YAML formatting and dict key order, and end-to-end round-trip + stable hashing via get_default_context(). 17 tests.
• Full suite green: 3607 passed, 10 skipped (-m "not postgres").
• No regressions in tests/test_semantic_types / tests/test_hashing.

Built task-by-task with per-task spec + code-quality review and a final whole-implementation review.

Relates to ENG-607.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 39.77273% with 53 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/orcapod/pydantic_config.py	40.69%	51 Missing ⚠️
src/orcapod/hashing/versioned_hashers.py	0.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[brian-arnold]

it would be great to have UPath support in case config files are ever stored on object storage, please apply this change wherever appropriate throughout the changes made in this PR

[brian-arnold]

Done in c23fe26. load_pydantic_config now resolves the path through UPath and reads via UPath(path).read_text(...), so object-storage URIs (s3://, gs://, …) work alongside local paths. Signature broadened to str | Path | UPath; the OSError/YAMLError→ValueError wrapping still applies (fsspec raises FileNotFoundError/OSError for missing remote keys). Added test_loads_via_upath.

No change needed to PydanticModelConverter — it operates on the already-loaded model object and never reads the filesystem, so the loader is the only place a config file path is consumed.

[eywalker]

This PR has been superseded by #183