huggingface-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 実行可能ファイル

合成可能なユーティリティ（stdin → NDJSON）：

• references/hf_enrich_models.sh — stdin からモデル 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 は OpenAPI 標準に基づいて https://huggingface.co/.well-known/openapi.json でドキュメント化されています。

重要： 処理するには大きすぎるため、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.).
  buckets              Commands to interact with buckets.
  cache                Manage local cache directory.
  collections          Interact with collections on the Hub.
  datasets             Interact with datasets on the Hub.
  discussions          Manage discussions and pull requests on the Hub.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  env                  Print information about the environment.
  extensions           Manage hf CLI extensions.
  jobs                 Run and manage Jobs on the Hub.
  models               Interact with models on the Hub.
  papers               Interact with papers on the Hub.
  repos                Manage repos on the Hub.
  skills               Manage skills for AI assistants.
  spaces               Interact with spaces on the Hub.
  sync                 Sync files between local directory and a bucket.
  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.
  webhooks             Manage webhooks on the Hub.

hf CLI コマンドは、現在非推奨となっている huggingface-cli コマンドに置き換わりました。