hugging-face-tool-builder

Hugging Face API ツールビルダー

目的は、Hugging Face API を利用する再利用可能なコマンドラインスクリプトとユーティリティを作成し、必要に応じてチェーン処理、パイプ処理、中間処理を行えるようにすることです。API に直接アクセスできるほか、hf コマンドラインツールも使用できます。モデルカードとデータセットカードは、リポジトリから直接アクセスできます。

スクリプトのルール

次のルールに従ってください。

• スクリプトには、入力と出力を説明する --help コマンドライン引数が必要です。
• 非破壊的なスクリプトは、ユーザーに渡す前にテストしてください。
• シェルスクリプトを優先しますが、複雑さやユーザーのニーズに応じて Python または TSX を使用してください。
• 重要：HF_TOKEN 環境変数を Authorization ヘッダーとして使用してください。例：curl -H "Authorization: Bearer ${HF_TOKEN}" https://huggingface.co/api/。これにより、より高いレート制限が適用され、データアクセスに適切な認証が行われます。
• 最終的な設計を決める前に API の結果の構造を調べてください。合成可能性が高まる場合はパイプ処理やチェーン処理を活用し、可能な限りシンプルな解決策を優先してください。
• 完成したら使用例を共有してください。

質問や確認が必要な点がある場合は、必ずユーザーの希望を確認してください。

スクリプトの例

以下のパスは、このスキルのディレクトリからの相対パスです。

参考例：

• references/hf_model_papers_auth.sh — HF_TOKEN を自動的に使用し、トレンド取得 → モデルメタデータ → モデルカードの解析をフォールバック付きでチェーン処理します。複数段階の API 利用と、ゲート付き／非公開コンテンツに対する認証の適切な取り扱いを示しています。
• references/find_models_by_paper.sh — --token による任意の HF_TOKEN 使用、一貫した認証付き検索、arXiv プレフィックス付き検索の範囲が狭すぎる場合の再試行経路を備えています。堅牢なクエリ戦略と、ユーザー向けの明確なヘルプを示しています。
• references/hf_model_card_frontmatter.sh — hf CLI を使用してモデルカードをダウンロードし、YAML フロントマターを抽出して、フィルタリングしやすい NDJSON の要約（ライセンス、パイプラインタグ、タグ、ゲート付き追加プロンプトフラグ）を出力します。

基本例（非常にシンプルで、ロジックは最小限、HF_TOKEN ヘッダーを使用して生の JSON を出力）：

• references/baseline_hf_api.sh — bash
• references/baseline_hf_api.py — python
• references/baseline_hf_api.tsx — typescript 実行可能ファイル

合成可能なユーティリティ（標準入力 → NDJSON）：

• references/hf_enrich_models.sh — 標準入力からモデル ID を読み取り、ID ごとにメタデータを取得し、ストリーミングパイプライン用に1行につき1つの JSON オブジェクトを出力します。

パイプ処理による合成可能性（シェルで扱いやすい JSON 出力）：

• references/baseline_hf_api.sh 25 | jq -r '.[].id' | references/hf_enrich_models.sh | jq -s 'sort_by(.downloads) | reverse | .[:10]'
• references/baseline_hf_api.sh 50 | jq '[.[] | {id, downloads}] | sort_by(.downloads) | reverse | .[:10]'
• printf '%s\n' openai/gpt-oss-120b meta-llama/Meta-Llama-3.1-8B | references/hf_model_card_frontmatter.sh | jq -s 'map({id, license, has_extra_gated_prompt})'

主なエンドポイント

https://huggingface.co で利用できる主な API エンドポイントは次のとおりです。

/api/datasets
/api/models
/api/spaces
/api/collections
/api/daily_papers
/api/notifications
/api/settings
/api/whoami-v2
/api/trending
/oauth/userinfo

API へのアクセス

API は https://huggingface.co/.well-known/openapi.json で OpenAPI 標準に基づいて文書化されています。

重要： https://huggingface.co/.well-known/openapi.json を直接読み込もうとしないでください。処理するには大きすぎます。

重要： jq を使用して、関連する部分を検索・抽出してください。例：

すべての160個のエンドポイントを取得するコマンド

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths | keys | sort'

モデル検索エンドポイントの詳細

curl -s "https://huggingface.co/.well-known/openapi.json" | jq '.paths["/api/models"]'

エンドポイントにクエリを送信して、データの構造を確認することもできます。その場合は、処理しやすく、かつ代表性のある結果になるよう、取得件数を少なく制限してください。

HF コマンドラインツールの使用

hf コマンドラインツールを使用すると、Hugging Face のリポジトリコンテンツやインフラストラクチャにさらにアクセスできます。

❯ hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:
  --help                Show this message and exit.

Commands:
  auth                 Manage authentication (login, logout, etc.).
  cache                Manage local cache directory.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  env                  Print information about the environment.
  jobs                 Run and manage Jobs on the Hub.
  repo                 Manage repos on the Hub.
  repo-files           Manage files in a repo on the Hub.
  upload               Upload a file or a folder to the Hub.
  upload-large-folder  Upload a large folder to the Hub.
  version              Print information about the hf version.

hf CLI コマンドは、非推奨となった huggingface_hub CLI コマンドに代わるものです。