feat: public description-prompt API and explicit generate_description behavior (0.0.6)

[mingjerli]

Summary

Two behaviors in generate_description() made it impossible for a caller to know whether a column description actually came from the LLM:

1. It returned early, without calling the model, for any column whose description came from a SQL comment (description_source == SOURCE) — returning the authored text unchanged.
2. It caught LLM errors and substituted a rule-based description derived from the column name (order_id → "Order Id"), setting description_source = GENERATED either way.

A tool attributing the result to a model could therefore label a fallback string — or the user's own hand-written comment — as model-generated output. This was found in practice: clgraph Studio's describe endpoint was relabelling authored governance text as "AI-generated" for 57 of 94 columns in one demo pipeline.

What changed

Added

• build_description_prompt(column, pipeline) promoted to public API and exported from the package root, so callers who want to drive the model themselves can reuse clgraph's lineage-aware prompt. _build_description_prompt remains as an alias.
• generate_description(..., overwrite=False, on_error="fallback") — keyword-only.
  • overwrite=True describes a column even when a SQL comment already documented it.
  • on_error="raise" raises the new DescriptionGenerationError instead of silently writing a fallback.
• generate_description() now returns bool — True only when the LLM produced the stored description.
• Same overwrite / on_error pass-through on Pipeline.generate_all_descriptions() and MetadataManager.generate_all_descriptions().

Housekeeping

• The CHANGELOG's [Unreleased] section sat directly above [0.0.3] while pyproject.toml said 0.0.5. That content was written 2026-07-20 and shipped in the v0.0.5 tag (2026-07-31), so it is retitled [0.0.5] - 2026-07-31. New [0.0.6] section added.
• Version bumped to 0.0.6.

Compatibility

No breaking changes. All new parameters are keyword-only with defaults that preserve the previous behavior exactly, the new bool return replaces None (falsy either way), and the private prompt-builder name still resolves.

Test plan

• 14 new tests in tests/test_description_generation_api.py covering: public export and private alias, overwrite in both directions, on_error for both LLM failure and output-validation rejection, the bool return, keyword-only enforcement, and that an invalid on_error is rejected before the LLM is called.
• Defaults pinned by test — an authored description is still preserved and the LLM is not called; a failing LLM still produces the humanized fallback.
• Full suite: 1605 passed, 40 skipped, 2 xfailed.
• ruff check / ruff format --check clean.
• ty reports 52 errors; the released v0.0.5 tag reports the same 52, so this change adds none.
• Docs PR in clgraph-docs to be merged alongside.