--- name: space-doctor description: Diagnose broken Hugging Face Gradio Spaces from their actual logs and pinned source, then prepare a minimal verified source fix as candidate files. Use for scheduled Space monitoring, BUILD_ERROR or RUNTIME_ERROR triage, Gradio and ZeroGPU failures, source analysis, and patch preparation. Read-only against the Hub - it never uploads, publishes, or restarts anything. compatibility: "Requires Python 3.10+ and fast-agent shell access. Remote reads require either a connected Hugging Face MCP server or the hf CLI." metadata: author: space-doctor version: "2.0.0" --- # Space Doctor Diagnose a broken Hugging Face Space and, when a narrow reversible source fix is appropriate, write the complete fixed files into the candidate directory you were given. You have **no Hub write access**: never attempt an upload, PR, restart, or any other mutation. The parent process opens a PR from your candidate files and performs any restart itself. Use fast-agent for reasoning and Hub reads. Diagnose from the observed failure, actual Hub logs, and the pinned source; static patterns and generic automated rewrites are not a repair decision. ## Scheduled contract A scheduled request provides the Space ID, exact failing revision, run ID, observed status/stage/detail, previous restart outcome for that revision (when one exists), and a workspace containing a `candidate/` directory. Treat the restart outcome as evidence, not proof that the current failure has the same cause. Emit exactly one final structured result matching the configured JSON schema, only after all work is complete: - `status: "fix-proposed"` with `changed_files`, `fix_summary`, and `pr_title` when you have written complete fixed files (paths relative to the Space repository root) into `candidate/`. - `status: "needs-human"` with `needs_human_reason` otherwise. Diagnose exactly the requested revision. If the Space has moved to a different revision, report `needs-human` with reason `revision-changed`. Never place credentials, tokens, or local filesystem paths in any output field. ## Workflow ### 1. Inspect remote state Prefer connected Hugging Face MCP tools. With the `hf` CLI: ```bash hf spaces info --expand runtime --format json hf spaces logs --tail 300 hf spaces logs --build --tail 300 # for BUILD_ERROR ``` Record runtime stage, hardware, revision, `runtime.raw.errorMessage`, and the first actionable error. Read both build and runtime logs when relevant and compare them with the observed status/stage/detail supplied in the request. Always use the full 40-character repository SHA. Do not treat `RUNNING` alone as healthy. ### 2. Acquire source at the failing revision ```bash mkdir -p /source hf download --repo-type space \ --revision --local-dir /source \ --exclude '*.safetensors' --exclude '*.safetensors.index.json' \ --exclude '*.bin' --exclude '*.pt' --exclude '*.pth' --exclude '*.ckpt' \ --exclude '*.onnx' --exclude '*.gguf' --exclude '*.h5' --exclude '*.tflite' ``` Never download a moving default branch when diagnosing a specific failure. Acquire source, configuration, and dependency manifests needed to reproduce the failure, but do not download model weights or launch a large model locally. If a required source file is absent, fetch that named file at the same full SHA. ### 3. Run deterministic checks Read the source and log context yourself. Compile Python without writing `__pycache__` into the tree: ```bash python3 -I -c ' import pathlib, sys root = pathlib.Path(sys.argv[1]) for path in sorted(root.rglob("*.py")): compile(path.read_text(encoding="utf-8"), str(path), "exec") ' /source ``` Classify findings by full SHA, stage, and timestamp. If a new build stops earlier than a historical runtime failure, report the old failure as superseded rather than the active root cause. ### 4. Decide whether a fix is safe Report `needs-human` when: - actual Space runtime evidence establishes an authentication, permissions, secrets, or grants failure and no independent code fix is available; - billing, storage, or hardware must change; - the failure appears transient or platform-wide; - a fix would change product behavior or model choice; - dependency resolution needs a broad or major-version upgrade; - no clear root cause is supported by logs and source. Never repair access by adding or rotating a secret. Safe candidates are narrow, reversible fixes directly supported by a deterministic failure. ### 5. Prepare the candidate Make a source-aware edit only when the logs and source establish a narrow, reversible root cause. First copy the complete acquired source tree to `/verify/` and edit that complete tree. Do not edit a partial candidate directory. Once verified, create `/candidate/` containing only each changed file's complete contents at its repository-relative path; list exactly those paths in `changed_files`. ZeroGPU rules: - eager module-scope model loading and `.to("cuda")` placement are normally correct after `import spaces`; actual CUDA computation belongs inside `@spaces.GPU`; - do not move model construction into a request handler merely to make it lazy; - do not add platform-managed `gradio`, `spaces`, or `huggingface_hub` to `requirements.txt` solely because they are imported. ### 6. Verify before reporting Before reporting `fix-proposed`: - compile all modified Python and relevant entrypoint source in the complete `/verify/` tree with in-memory `compile(...)`, never `py_compile`; - inspect the complete verified tree, not the partial candidate, and confirm the root-cause failure is gone or directly mitigated without a new error; - compare `source/` and `verify/`, then ensure `candidate/` contains only the changed complete files, with no secret, cache, run artifact, or unrelated file. For dependency repairs, reconstruct the exact platform install inputs from the failing build (dependency file, injected Gradio/Spaces/torch requirements, Python version) and verify the resolution; a reduced synthetic resolver is exploratory evidence only. For gated models, verify authenticated read access without downloading weights when authorized credentials are available. An unauthenticated model probe returning 401/403 does not establish an access failure in the actual Space runtime: the Space may have its own authorized credentials. Do not infer a human hold from that probe alone (including Krea). A verified independent code repair may be `fix-proposed` for a PR even when model access remains unverified. Include a warning finding describing the probe context and verification limitation; do not claim full runtime success. For access issues, report `needs-human` only when actual Space runtime evidence establishes access failure and no independent fix is available. Never add, rotate, or expose secrets to repair access. Do not launch a large model locally. Finally, re-read the remote revision. If it no longer matches the requested revision, report `needs-human` with reason `revision-changed`.