hf-agentfinder 0.1.4

Agent Finder registry adapter for Hugging Face Spaces

hf-agentfinder

A small Agent Finder registry adapter for Hugging Face Spaces.

It exposes Hugging Face Spaces semantic search as:

• a CLI: agentfinder spaces search "remove background from image"
• an Agent Finder-ish REST API: POST /search
• generated skill artifacts for Spaces via GET /skills/huggingface/{owner}/{space}/SKILL.md

Search results default to application/ai-skill entries. Each result points to a generated SKILL.md route that wraps the Space's agents.md instructions.

Features

Space Search and Skill Generation

agentfinder uses Hugging Face Spaces semantic search as a registry backend. Search requests use the Hub's agent-oriented semantic search (agents=true) and return matching Spaces as Agent Finder catalog entries. By default, results can include generated application/ai-skill artifacts, plus application/mcp-server+json entries for matching Spaces tagged mcp-server.

Search responses strictly include only Spaces whose runtime stage is RUNNING, so returned entries are limited to Spaces that are currently ready to serve traffic. The runtime stage is also surfaced in result metadata as runtimeStage.

The generated skill wraps the Space's agents.md instructions with the required skill frontmatter (name and description) plus source metadata such as the Space ID, Hub URL, app URL, and original agents.md URL. This lets clients discover a relevant Space, fetch the generated skill, and install or load it using their normal skill flow.

For clients that want raw Space descriptors instead of skills, the same search endpoint can return application/vnd.huggingface.space+json entries with inline JSON metadata.

Requests for application/mcp-server+json add filter=mcp-server to the downstream Hub search and return MCP server catalog entries that point at the Space's Gradio MCP endpoint using HTTP transport. When Hub runtime metadata includes a Space domain, that domain is used for app and MCP URLs; otherwise the adapter falls back to the standard .hf.space slug convention.

Release Automation

Releases are built through the same quality gates as CI: locked dependency sync, Ruff format/lint checks, ty type checking, and pytest. The release check script then builds both source and wheel distributions, inspects the artifacts, and smoke-installs the wheel in a clean Python 3.14 virtual environment.

Run the release check with:

./scripts/check-release.sh

Optionally assert the expected project version:

./scripts/check-release.sh 0.1.0

Use the Prepare Release GitHub Action to prepare a release branch. The workflow can bump patch, minor, or major from the current pyproject.toml version, regenerates uv.lock, updates CHANGELOG.md, runs the release check, pushes release-vX.Y.Z, and prints the PR URL in the workflow summary. After merging the PR, publish by running the Release workflow with the merged version, or by pushing the matching vX.Y.Z tag. The release workflow builds artifacts, publishes them to PyPI using trusted publishing, attaches the artifacts to the GitHub Release, and restarts the Hugging Face Space when the HF_TOKEN secret is configured.

Hugging Face Space Deployment

The project includes a reproducible Docker Space definition in deploy/huggingface-space/. It uses the official uv Python image and runs the latest published hf-agentfinder package with uvx --refresh, so restarting or rebuilding the Space resolves the newest PyPI release without committing generated application code to the Space repository. This keeps the hosted Space lightweight while letting PyPI releases drive runtime updates.

Usage

uv run agentfinder spaces search "generate image" --limit 5
uv run agentfinder spaces search "generate image" --kind skill --json
uv run agentfinder spaces search "generate image" --kind mcp --json
uv run agentfinder spaces search "generate image" --json
uv run agentfinder serve --port 8080

curl -X POST http://localhost:8080/search \
  -H 'content-type: application/json' \
  -d '{"query":{"text":"remove background from image","mediaType":"application/ai-skill"},"pageSize":5}'

Fetch a generated skill:

curl http://localhost:8080/skills/huggingface/mcp-tools/FLUX.1-Kontext-Dev/SKILL.md

To get generic Hugging Face Space descriptors instead of skill wrappers, request:

{"query":{"text":"remove background from image","mediaType":"application/vnd.huggingface.space+json"},"pageSize":5}

HF_TOKEN handling

HTTP search requests can forward a request-scoped Hugging Face token for the downstream Spaces search call. The server checks X-HF-Authorization: Bearer ..., then Authorization: Bearer ..., then HF_TOKEN: ...; a header token overrides any token configured when the server starts and is not stored beyond the request.