Evaluate griffe for SDK API tooling (breaking-change detection, docs, conformance)

[vdavez]

Summary

Evaluate adopting griffe in tango-python. Griffe loads a Python package into a structured API model (modules → classes → functions, with signatures, type annotations, defaults, and parsed docstrings) — statically, without importing. Three headline uses: griffe dump (API → JSON), griffe check old new (breaking-change detection between two git refs, exits non-zero in CI), and it's the engine behind mkdocstrings for doc generation.

Where it fits (ranked)

1. Breaking-change / semver gating on releases — strongest fit, lowest effort

This is a versioned PyPI package (currently 1.2.0) with a large CHANGELOG.md and semver expectations, but nothing checks the public surface across releases today. griffe check in CI would flag when a PR removes/renames a public method, drops or reorders a parameter, or changes an annotation — i.e. whether a release needs a major bump.

Proposed spike:

• Add griffe to dev deps.
• CI step: griffe check tango --against <latest-tag> (or compare two refs in the lint workflow).
• Surface the diff on PRs as a release/semver signal.

2. Generate docs/API_REFERENCE.md instead of hand-maintaining it

docs/API_REFERENCE.md is ~61KB of hand-written markdown with a manual TOC, and makegov/docs fetches it at build time (→ sdks/python/api-reference.md). The docs site already runs MkDocs but not mkdocstrings. griffe/mkdocstrings could render the reference from the actual client.py signatures + docstrings, removing the drift risk.

Caveat: the docs build currently pulls pre-rendered markdown and doesn't import the SDK, so wiring mkdocstrings means the docs build needs the package installed. Medium value, medium effort.

3. Back scripts/check_filter_shape_conformance.py with griffe instead of raw ast.parse

That script already hand-rolls ast.parse(client.py) to extract method params/annotations. griffe provides a cleaner resolved model (signatures, defaults, inherited members) for free. This is a refactor, not new capability — only worth it if the AST-walking becomes a maintenance burden.

Important caveat

griffe sees only Python. It cannot tell whether the SDK matches the server API — that's exactly what the OpenAPI-derived contracts/filter_shape_contract.json checker does. griffe complements that contract check (catches Python-side regressions); it never replaces it.

Scope: this is Python-only — does NOT cover tango-node

griffe parses Python source, so it does nothing for the TypeScript SDK. The equivalent tooling for tango-node would be a separate effort:

• API Extractor — closest analog: API report + breaking-change review + doc model
• TypeDoc — docs generation
• @arethetypeswrong/cli — published-types sanity

If we like the griffe outcome here, file a sibling issue on makegov/tango-node for the TS equivalent.

Proposed next step

Start with #1 (highest value-to-effort, doesn't touch the docs pipeline, directly supports CHANGELOG/semver discipline). Prototype the CI check and review the diff it reports against the current release before deciding on #2/#3.