Metadata-Version: 2.4
Name: hf-agentfinder
Version: 0.1.0
Summary: Agent Finder registry adapter for Hugging Face Spaces
Requires-Python: >=3.14
Requires-Dist: fastapi==0.136.1
Requires-Dist: huggingface-hub==1.14.0
Requires-Dist: pydantic==2.13.4
Requires-Dist: rich==15.0.0
Requires-Dist: typer==0.25.1
Requires-Dist: uvicorn==0.46.0
Description-Content-Type: text/markdown

# 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:

```bash
./scripts/release-local.sh
```

Optionally assert the expected project version:

```bash
./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

```bash
uv run agentfinder spaces search "generate image" --limit 5
uv run agentfinder spaces search "generate image" --json
uv run agentfinder serve --port 8080
```

```bash
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:

```bash
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:

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