feat: split Trouve into TrouveAbc + Trouve + PandasTrouve

[OmerBaddour]

What

Replaces the df_fn field with a PandasTrouve class, and splits Trouve into an abstract base plus one class per backend.

Before — the dependency rode on the parameter default, so the annotation was false and every parameter needed a # type: ignore:

def daily_event_counts(
    refined_events: pd.DataFrame = example_4_database_refined_events,  # type: ignore
) -> pd.DataFrame:
    ...

trouve = Trouve(df_fn=daily_event_counts)

After — the transform is an honest function; the dependencies live on the Trouve:

def daily_event_counts(refined_events: pd.DataFrame) -> pd.DataFrame:
    ...

trouve = PandasTrouve(
    transform=daily_event_counts,
    inputs=[example_4_database_refined_events],
)

Clair binds inputs to the transform parameters by position, so parameter names are free.

The class split

Class	Backend	Declares dependencies with
TrouveAbc	abstract base — columns, tests, docs, run_config, compiled	—
Trouve	Snowflake SQL	f-string references in sql
PandasTrouve	pandas	the inputs list

Backend-specific validation moved off the shared base: _validate_sql now lives on Trouve only. This is what makes room for a DatabricksTrouve later.

Why this shape

• The pd.DataFrame annotation is now true, so no # type: ignore — verified with ty.
• The transform takes plain DataFrames, so it is directly callable in a unit test or notebook.
• PandasTrouve validates transform arity at import time and rejects *args/**kwargs, with an error naming the parameters.
• Because dag.get_trouve() returns TrouveAbc, ty now forces explicit narrowing before any .sql / .transform / .build_sql access. Several call sites gained isinstance asserts as a result.

Breaking change

df_fn is removed rather than deprecated — pre-1.0, and keeping it would defeat the split. All in-repo callers migrated.

Notes

• The example's second # type: ignore came from pandas stubs (groupby().size() types as Series), not from clair. Rewritten as .agg(event_count=("event_type", "size")), which typechecks clean.
• CompiledAttributes.resolved_df_fn renamed to resolved_transform.
• build_dag / find_routing_collisions / recompile_for_selection take Sequence[TrouveAbc] — list is invariant, so a list[Trouve] would not have been accepted.

Verification

• uv run pytest tests/ — 529 passed
• uvx ruff check . — clean
• uvx ty check --exclude example_notebooks — clean
• mkdocs build --strict — clean
• clair dag and clair compile on example_projects/example_4 — DAG resolves with the [PANDAS] node in place, and the compiled artifact header maps refined_events -> example_4_database.refined.events

Docs updated: the pandas guide, the Trouve API reference, the Trouve concept page, the landing page, the reference index, and the README.

🤖 Generated with Claude Code