hf-agentfinder 0.1.0

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. A search request returns matching Spaces as Agent Finder catalog entries. By default, results are presented as application/ai-skill artifacts: each entry points to a generated SKILL.md URL served by this project.

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.

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 local release 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 local release check with:

./scripts/release-local.sh

Optionally assert the expected project version:

./scripts/release-local.sh 0.1.0

Tagged pushes matching v* run the release workflow and attach the built artifacts to a GitHub Release. The workflow currently builds and publishes GitHub artifacts only; it does not publish to PyPI.

Usage

uv run agentfinder spaces search "generate image" --limit 5
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}