CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A HuggingFace Space that exposes Moondream2's open-vocabulary detection (point and object_detection) via a Gradio interface. The entire app is app.py — a single detect() function wrapped by gr.Interface. README frontmatter (title, sdk, sdk_version, app_file) is the HF Space config and must stay valid YAML; the Space rebuilds from it.

Running

pip install -r requirements.txt
python app.py

Gradio launches with mcp_server=True (exposes an MCP endpoint) and app_kwargs={"docs_url": "/docs"} (attempt to expose FastAPI Swagger). Per the README, the /docs route is known not to work in practice — see https://github.com/gradio-app/gradio/issues/4054.

Runtime model

• Loads vikhyatk/moondream2 at revision 2025-04-14 with trust_remote_code=True. Pinning the revision is intentional — the model repo changes its API surface across revisions, so bumping it can break model.point(...) / model.detect(...) return shapes.
• @spaces.GPU(duration=30) decorators are HF Spaces ZeroGPU directives — they only activate on the Space; locally they are no-ops requiring a CUDA device (the device_map={"": "cuda"} hard-codes GPU). Local CPU runs need that removed.
• detect() returns the inner list (["points"] or ["objects"]) rather than the full dict — callers (including the MCP tool surface) depend on that shape.
• Concurrency (Gradio queue): detect runs at most 2 calls at once (concurrency_limit=2 on the Interface; ZeroGPU forks a worker per call), the pilbox annotate .change() event at most 4, and demo.queue(max_size=12) caps waiters (ZeroGPU otherwise forces max_size=1, so a second waiter gets a 503 "Queue is full"). Limits are per event; work inside a single request is still sequential.