inspect_api.py

"""
inspect_api.py — dump the API spec of the pipeline's Gradio Spaces.

`view_api()` reads the Space's config and prints every callable endpoint: its
api_name, each parameter (name, type, whether required, default) and the return
types. This is how you learn the EXACT signature to call — never guess it.

Reading the spec does NOT consume any GPU quota (it only fetches the config).

Usage:
    python inspect_api.py                       # all three pipeline Spaces
    python inspect_api.py owner/some-space      # one specific Space
    HF_TOKEN=hf_xxx python inspect_api.py        # token only needed for private Spaces

For each Space it prints the human-readable API and writes a machine-readable
`api_<owner>__<space>.json` you can diff later to catch signature drift.
"""

import os
import sys
import json

from gradio_client import Client

# Same defaults as app.py, so you inspect exactly what the server will call.
PIPELINE = [
    ("caption / identify (stage 1)", os.getenv("CAPTION_SPACE", "fancyfeast/joy-caption-beta-one")),
    ("concept / design  (stage 2)", os.getenv("CONCEPT_SPACE", "huggingface-projects/gemma-4-12b-it")),
    ("image             (stage 3)", os.getenv("IMAGE_SPACE",   "krea/Krea-2")),
]
TOKEN = os.getenv("HF_TOKEN")


def inspect(label: str, space_id: str) -> None:
    print("\n" + "=" * 78)
    print(f"{label}\nSPACE: {space_id}")
    print("=" * 78)
    client = Client(space_id, hf_token=TOKEN)

    # Human-readable — this is what you read to get the arg order.
    client.view_api()

    # Machine-readable snapshot -> file (default=str handles non-JSON types).
    try:
        spec = client.view_api(print_info=False, return_format="dict")
        fname = "api_" + space_id.replace("/", "__") + ".json"
        with open(fname, "w", encoding="utf-8") as f:
            json.dump(spec, f, indent=2, default=str)
        print(f"[saved] {fname}")
    except TypeError:
        # Older gradio_client without return_format — the printed output above is enough.
        print("[note] this gradio_client can't return a dict; use the printed spec above.")


def main() -> None:
    args = sys.argv[1:]
    targets = [("space", s) for s in args] if args else PIPELINE
    for label, space_id in targets:
        try:
            inspect(label, space_id)
        except Exception as exc:
            print(f"[error] {space_id}: {type(exc).__name__}: {exc}")
    print("\nDone. Match these signatures against app.py's caption_object / "
          "generate_concept / generate_image (see ARCHITECTURE.md \u00a75).")


if __name__ == "__main__":
    main()