Upload 2 files

hf_api_tool.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+DEFAULT_MAX_RESULTS = 20
+DEFAULT_TIMEOUT_SEC = 30
+
+# ---------------------------------------------------------------------------
+# Endpoint allowlist (regex patterns)
+# Only endpoints matching these patterns are permitted.
+# ---------------------------------------------------------------------------
+ALLOWED_ENDPOINT_PATTERNS: list[str] = [
+    # User data
+    r"^/whoami-v2$",
+    r"^/users/[^/]+/overview$",
+    r"^/users/[^/]+/likes$",
+    r"^/users/[^/]+/followers$",
+    r"^/users/[^/]+/following$",
+    # Organizations
+    r"^/organizations/[^/]+/overview$",
+    r"^/organizations/[^/]+/members$",
+    r"^/organizations/[^/]+/followers$",
+    # Discussions & PRs (repo_type: models, datasets, spaces)
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/discussions$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+/comment$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+/comment/[^/]+/edit$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+/comment/[^/]+/hide$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+/status$",
+    # Access requests (gated repos)
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/user-access-request/pending$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/user-access-request/accepted$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/user-access-request/rejected$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/user-access-request/handle$",
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/user-access-request/grant$",
+    # Collections
+    r"^/collections$",
+    r"^/collections/[^/]+$",
+    r"^/collections/[^/]+/items$",
+    # Auth check
+    r"^/(models|datasets|spaces)/[^/]+/[^/]+/auth-check$",
+]
+
+_COMPILED_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(p) for p in ALLOWED_ENDPOINT_PATTERNS
+]
+
+
+def _is_endpoint_allowed(endpoint: str) -> bool:
+    """Return True if endpoint matches any allowed pattern."""
+    return any(pattern.match(endpoint) for pattern in _COMPILED_PATTERNS)
+
+
+def _load_token() -> str | None:
+    # Check for request-scoped token first (when running as MCP server)
+    # This allows clients to pass their own HF token via Authorization header
+    try:
+        from fast_agent.mcp.auth.context import request_bearer_token
+
+        ctx_token = request_bearer_token.get()
+        if ctx_token:
+            return ctx_token
+    except ImportError:
+        # fast_agent.mcp.auth.context not available
+        pass
+
+    # Fall back to HF_TOKEN environment variable
+    token = os.getenv("HF_TOKEN")
+    if token:
+        return token
+
+    # Fall back to cached huggingface token file
+    token_path = Path.home() / ".cache" / "huggingface" / "token"
+    if token_path.exists():
+        token_value = token_path.read_text(encoding="utf-8").strip()
+        return token_value or None
+
+    return None
+
+
+def _max_results_from_env() -> int:
+    raw = os.getenv("HF_MAX_RESULTS")
+    if not raw:
+        return DEFAULT_MAX_RESULTS
+    try:
+        value = int(raw)
+    except ValueError:
+        return DEFAULT_MAX_RESULTS
+    return value if value > 0 else DEFAULT_MAX_RESULTS
+
+
+def _normalize_endpoint(endpoint: str) -> str:
+    """Normalize and validate an endpoint path.
+
+    Checks:
+    - Must be a relative path (not a full URL)
+    - Must be non-empty
+    - No path traversal sequences (..)
+    - Must match the endpoint allowlist
+    """
+    if endpoint.startswith("http://") or endpoint.startswith("https://"):
+        raise ValueError("Endpoint must be a path relative to /api, not a full URL.")
+    endpoint = endpoint.strip()
+    if not endpoint:
+        raise ValueError("Endpoint must be a non-empty string.")
+
+    # Path traversal protection
+    if ".." in endpoint:
+        raise ValueError("Path traversal sequences (..) are not allowed in endpoints.")
+
+    if not endpoint.startswith("/"):
+        endpoint = f"/{endpoint}"
+
+    # Allowlist validation
+    if not _is_endpoint_allowed(endpoint):
+        raise ValueError(
+            f"Endpoint '{endpoint}' is not in the allowed list. "
+            "See ALLOWED_ENDPOINT_PATTERNS for permitted endpoints."
+        )
+
+    return endpoint
+
+
+def _normalize_params(params: dict[str, Any] | None) -> dict[str, Any]:
+    if not params:
+        return {}
+    normalized: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            normalized[key] = [str(item) for item in value]
+        else:
+            normalized[key] = str(value)
+    return normalized
+
+
+def _build_url(endpoint: str, params: dict[str, Any] | None) -> str:
+    base = os.getenv("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
+    url = f"{base}/api{_normalize_endpoint(endpoint)}"
+    normalized_params = _normalize_params(params)
+    if normalized_params:
+        url = f"{url}?{urlencode(normalized_params, doseq=True)}"
+    return url
+
+
+def hf_api_request(
+    endpoint: str,
+    method: str = "GET",
+    params: dict[str, Any] | None = None,
+    json_body: dict[str, Any] | None = None,
+    max_results: int | None = None,
+    offset: int | None = None,
+) -> dict[str, Any]:
+    """
+    Call the Hugging Face Hub API (GET/POST only).
+
+    Args:
+        endpoint: API endpoint relative to /api (e.g. "/whoami-v2").
+        method: HTTP method (GET or POST).
+        params: Optional query parameters.
+        json_body: Optional JSON payload for POST requests.
+        max_results: Max results when response is a list (defaults to HF_MAX_RESULTS).
+        offset: Client-side offset when response is a list (defaults to 0).
+
+    Returns:
+        A dict with the response data and request metadata.
+    """
+    method_upper = method.upper()
+    if method_upper not in {"GET", "POST"}:
+        raise ValueError("Only GET and POST are allowed for hf_api_request.")
+
+    if method_upper == "GET" and json_body is not None:
+        raise ValueError("GET requests do not accept json_body.")
+
+    url = _build_url(endpoint, params)
+
+    headers = {
+        "Accept": "application/json",
+    }
+    token = _load_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    data = None
+    if method_upper == "POST":
+        headers["Content-Type"] = "application/json"
+        data = json.dumps(json_body or {}).encode("utf-8")
+
+    request = Request(url, headers=headers, data=data, method=method_upper)
+
+    try:
+        with urlopen(request, timeout=DEFAULT_TIMEOUT_SEC) as response:
+            raw = response.read()
+            status_code = response.status
+    except HTTPError as exc:
+        error_body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"HF API error {exc.code} for {url}: {error_body}") from exc
+    except URLError as exc:
+        raise RuntimeError(f"HF API request failed for {url}: {exc}") from exc
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        payload = raw.decode("utf-8", errors="replace")
+
+    if isinstance(payload, list):
+        limit = max_results if max_results is not None else _max_results_from_env()
+        start = max(offset or 0, 0)
+        end = start + max(limit, 0)
+        payload = payload[start:end]
+
+    return {
+        "url": url,
+        "status": status_code,
+        "data": payload,
+    }

hf_hub_community.md

@@ -0,0 +1,355 @@
+---
+function_tools:
+  - hf_api_tool.py:hf_api_request
+model: gpt-oss
+description: "Query Hugging Face community features: user/org profiles, followers, repo discussions, pull requests, comments, access requests, and collections. Use for people lookups and repo collaboration—not for model/dataset search."
+---
+Hugging Face Hub Methods: How to Call (User/Org Focus)
+======================================================
+
+Scope
+-----
+This card summarizes the curated user/organization-related methods and how to call
+them via the hf_api_request tool (no shell usage).
+
+References:
+- Curated method list (embedded below from scripts/hf_api_methods.txt)
+- REST endpoints: scripts/hf_api_endpoints.txt
+- Tool: hf_api_request (this card's function tool)
+
+Prereqs
+-------
+- HF_TOKEN env var (or ~/.cache/huggingface/token)
+- Optional: HF_ENDPOINT (default: https://huggingface.co)
+- Optional: HF_MAX_RESULTS (default: 20)
+
+Preferred: hf_api_request tool
+------------------------------
+Tool call pattern:
+- GET: hf_api_request(endpoint="/whoami-v2")
+- GET with params: hf_api_request(endpoint="/users/{username}/likes")
+- GET with local slicing: hf_api_request(endpoint="/users/{username}/likes", max_results=20, offset=20)
+- POST: hf_api_request(endpoint="/.../comment", method="POST", json_body={...})
+
+Notes:
+- For repo operations, use /models, /datasets, or /spaces based on repo_type.
+- Only GET/POST are supported by this tool. PATCH/DELETE are not supported.
+- Mutation/update endpoints that require PATCH/DELETE (collection updates/deletes, unlike, etc.) are not supported.
+- Avoid destructive operations unless the user explicitly confirms.
+- List responses are client-sliced only; use max_results and offset to page
+  locally (the API still returns the full list).
+
+USER DATA
+---------
+- whoami
+  tool: hf_api_request(endpoint="/whoami-v2")
+
+- activity (HTML scrape, not a public API endpoint)
+  tool: not available (HTML scrape is not supported by hf_api_request)
+
+- get_user_overview
+  tool: hf_api_request(endpoint="/users/{username}/overview")
+
+- list_liked_repos
+  tool: hf_api_request(endpoint="/users/{username}/likes")
+
+- get_token_permission
+  tool: not available (use /whoami-v2 and check auth.accessToken.role)
+
+USER NETWORK
+------------
+- list_user_followers
+  tool: hf_api_request(endpoint="/users/{username}/followers")
+
+- list_user_following
+  tool: hf_api_request(endpoint="/users/{username}/following")
+
+ORGANIZATIONS
+-------------
+- get_organization_overview
+  tool: hf_api_request(endpoint="/organizations/{organization}/overview")
+
+- list_organization_members
+  tool: hf_api_request(endpoint="/organizations/{organization}/members")
+
+- list_organization_followers
+  tool: hf_api_request(endpoint="/organizations/{organization}/followers")
+
+DISCUSSIONS & PULL REQUESTS
+---------------------------
+- get_repo_discussions
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/discussions",
+    params={"type": "pr|discussion", "author": "<user>", "status": "open|closed"}
+  )
+
+- get_discussion_details
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/discussions/{num}",
+    params={"diff": 1}
+  )
+
+- create_discussion
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/discussions",
+    method="POST",
+    json_body={"title": "...", "description": "...", "pullRequest": false}
+  )
+
+- create_pull_request
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/discussions",
+    method="POST",
+    json_body={"title": "...", "description": "...", "pullRequest": true}
+  )
+
+- comment_discussion
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/discussions/{num}/comment",
+    method="POST",
+    json_body={"comment": "..."}
+  )
+
+- edit_discussion_comment
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/discussions/{num}/comment/{comment_id}/edit",
+    method="POST",
+    json_body={"content": "..."}
+  )
+
+- hide_discussion_comment (destructive)
+  tool: only with explicit confirmation:
+    hf_api_request(
+      endpoint="/{repo_type}s/{repo_id}/discussions/{num}/comment/{comment_id}/hide",
+      method="POST"
+    )
+
+- change_discussion_status
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/discussions/{num}/status",
+    method="POST",
+    json_body={"status": "open|closed", "comment": "..."}
+  )
+
+ACCESS REQUESTS (GATED REPOS)
+-----------------------------
+- list_pending_access_requests
+  tool: hf_api_request(endpoint="/{repo_type}s/{repo_id}/user-access-request/pending")
+
+- list_accepted_access_requests
+  tool: hf_api_request(endpoint="/{repo_type}s/{repo_id}/user-access-request/accepted")
+
+- list_rejected_access_requests
+  tool: hf_api_request(endpoint="/{repo_type}s/{repo_id}/user-access-request/rejected")
+
+- accept_access_request
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/user-access-request/handle",
+    method="POST",
+    json_body={"user": "...", "status": "accepted"}
+  )
+
+- cancel_access_request
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/user-access-request/handle",
+    method="POST",
+    json_body={"user": "...", "status": "pending"}
+  )
+
+- reject_access_request (destructive)
+  tool: only with explicit confirmation:
+    hf_api_request(
+      endpoint="/{repo_type}s/{repo_id}/user-access-request/handle",
+      method="POST",
+      json_body={"user": "...", "status": "rejected", "rejectionReason": "..."}
+    )
+
+- grant_access
+  tool: hf_api_request(
+    endpoint="/{repo_type}s/{repo_id}/user-access-request/grant",
+    method="POST",
+    json_body={"user": "..."}
+  )
+
+USER COLLECTIONS
+----------------
+- list_collections
+  tool: hf_api_request(endpoint="/collections", params={"owner": "<user-or-org>"})
+
+- get_collection
+  tool: hf_api_request(endpoint="/collections/{slug}")
+
+- create_collection
+  tool: hf_api_request(
+    endpoint="/collections",
+    method="POST",
+    json_body={"title": "...", "namespace": "<user-or-org>", "description": "...", "private": false}
+  )
+
+- add_collection_item
+  tool: hf_api_request(
+    endpoint="/collections/{slug}/items",
+    method="POST",
+    json_body={"item": {"id": "...", "type": "model|dataset|space|paper"}, "note": "..."}
+  )
+
+Note: Collection update/delete endpoints use PATCH/DELETE and are not supported by hf_api_request.
+
+USER INTERACTIONS
+-----------------
+Note: Like/unlike endpoints are not available via hf_api_request.
+
+- auth_check
+  tool: hf_api_request(endpoint="/{repo_type}s/{repo_id}/auth-check")
+
+Direct REST usage example
+-------------------------
+  hf_api_request(endpoint="/organizations/<org>/overview")
+
+See scripts/hf_api_endpoints.txt for full endpoint details and expected request bodies.
+
+Curated HfApi Methods: User & Organization Data, Discussions & Interactions
+===========================================================================
+Note: PATCH/DELETE-only methods are excluded here; hf_api_request supports GET/POST only.
+
+28 methods selected from 126 total HfApi methods
+
+
+USER DATA (4 methods)
+================================================================================
+
+get_user_overview(username: str, token: ...) -> User
+--------------------------------------------------------------------------------
+Get an overview of a user on the Hub.
+
+list_liked_repos(user: Optional[str] = None, *, token: ...) -> UserLikes
+--------------------------------------------------------------------------------
+List all public repos liked by a user on huggingface.co.
+
+whoami(token: ...) -> Dict
+--------------------------------------------------------------------------------
+Call HF API to know "whoami".
+
+get_token_permission(token: ...) -> Literal['read', 'write', 'fineGrained', None]
+--------------------------------------------------------------------------------
+Check if a given token is valid and return its permissions.
+
+
+USER NETWORK (2 methods)
+================================================================================
+
+list_user_followers(username: str, token: ...) -> Iterable[User]
+--------------------------------------------------------------------------------
+Get the list of followers of a user on the Hub.
+
+list_user_following(username: str, token: ...) -> Iterable[User]
+--------------------------------------------------------------------------------
+Get the list of users followed by a user on the Hub.
+
+
+ORGANIZATIONS (3 methods)
+================================================================================
+
+get_organization_overview(organization: str, token: ...) -> Organization
+--------------------------------------------------------------------------------
+Get an overview of an organization on the Hub.
+
+list_organization_members(organization: str, token: ...) -> Iterable[User]
+--------------------------------------------------------------------------------
+List of members of an organization on the Hub.
+
+list_organization_followers(organization: str, token: ...) -> Iterable[User]
+--------------------------------------------------------------------------------
+List followers of an organization on the Hub.
+
+
+DISCUSSIONS & PULL REQUESTS (8 methods)
+================================================================================
+
+create_discussion(repo_id: str, title: str, *, token: ..., description: ..., repo_type: ..., pull_request: bool = False) -> DiscussionWithDetails
+--------------------------------------------------------------------------------
+Creates a Discussion or Pull Request.
+
+create_pull_request(repo_id: str, title: str, *, token: ..., description: ..., repo_type: ...) -> DiscussionWithDetails
+--------------------------------------------------------------------------------
+Creates a Pull Request. Pull Requests created programmatically will be in "draft" status.
+
+get_discussion_details(repo_id: str, discussion_num: int, *, repo_type: ..., token: ...) -> DiscussionWithDetails
+--------------------------------------------------------------------------------
+Fetches a Discussion's / Pull Request's details from the Hub.
+
+get_repo_discussions(repo_id: str, *, author: ..., discussion_type: ..., discussion_status: ..., repo_type: ..., token: ...) -> Iterator[Discussion]
+--------------------------------------------------------------------------------
+Fetches Discussions and Pull Requests for the given repo.
+
+comment_discussion(repo_id: str, discussion_num: int, comment: str, *, token: ..., repo_type: ...) -> DiscussionComment
+--------------------------------------------------------------------------------
+Creates a new comment on the given Discussion.
+
+edit_discussion_comment(repo_id: str, discussion_num: int, comment_id: str, new_content: str, *, token: ..., repo_type: ...) -> DiscussionComment
+--------------------------------------------------------------------------------
+Edits a comment on a Discussion / Pull Request.
+
+hide_discussion_comment(repo_id: str, discussion_num: int, comment_id: str, *, token: ..., repo_type: ...) -> DiscussionComment
+--------------------------------------------------------------------------------
+Hides a comment on a Discussion / Pull Request.
+
+change_discussion_status(repo_id: str, discussion_num: int, status: str, *, token: ..., repo_type: ..., comment: ...) -> Discussion
+--------------------------------------------------------------------------------
+Changes the status of a Discussion or Pull Request.
+
+
+ACCESS REQUESTS (GATED REPOS) (6 methods)
+================================================================================
+
+list_pending_access_requests(repo_id: str, *, token: ..., repo_type: ...) -> List[AccessRequest]
+--------------------------------------------------------------------------------
+List pending access requests for a gated repo.
+
+list_accepted_access_requests(repo_id: str, *, token: ..., repo_type: ...) -> List[AccessRequest]
+--------------------------------------------------------------------------------
+List accepted access requests for a gated repo.
+
+list_rejected_access_requests(repo_id: str, *, token: ..., repo_type: ...) -> List[AccessRequest]
+--------------------------------------------------------------------------------
+List rejected access requests for a gated repo.
+
+accept_access_request(repo_id: str, user: str, *, token: ..., repo_type: ...) -> None
+--------------------------------------------------------------------------------
+Accept access request to a gated repo.
+
+reject_access_request(repo_id: str, user: str, *, token: ..., repo_type: ..., rejection_reason: ...) -> None
+--------------------------------------------------------------------------------
+Reject access request to a gated repo.
+
+grant_access(repo_id: str, user: str, *, token: ..., repo_type: ...) -> None
+--------------------------------------------------------------------------------
+Grant access to a gated repo without an access request.
+
+
+USER COLLECTIONS (4 methods)
+================================================================================
+
+get_collection(collection_slug: str, *, token: ...) -> Collection
+--------------------------------------------------------------------------------
+Get a collection's details from the Hub.
+
+create_collection(title: str, *, namespace: ..., description: ..., private: ..., token: ...) -> Collection
+--------------------------------------------------------------------------------
+Create a new collection on the Hub.
+
+list_collections(*, owner: ..., item: ..., sort: ..., limit: ..., token: ...) -> Iterable[Collection]
+--------------------------------------------------------------------------------
+List collections on the Huggingface Hub, given some filters.
+
+add_collection_item(collection_slug: str, item_id: str, item_type: CollectionItemType_T, *, note: ..., exists_ok: bool = False, token: ...) -> Collection
+--------------------------------------------------------------------------------
+Add an item to a collection on the Hub.
+
+
+USER INTERACTIONS (1 method)
+================================================================================
+
+auth_check(repo_id: str, *, repo_type: ..., token: ...) -> None
+--------------------------------------------------------------------------------
+Check if the provided user token has access to a specific repository on the Hugging Face Hub.