Deploy structured tool description (community card)

hf_hub_community.md

@@ -2,11 +2,24 @@
 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."
+description: "Hub community API tool for user/org profiles, followers, discussions, PRs, collections, access requests, and recent activity feeds. Supports multi-step workflows with pagination and local filtering; not for model/dataset search."
 ---
 Hugging Face Hub Methods: How to Call (User/Org Focus)
 ======================================================
 
+What this tool does well
+------------------------
+- User/org intelligence: profiles, followers/following, likes, members.
+- Collaboration workflows: repo discussions, PRs, comments, status changes.
+- Gated repo operations: access request review and grants.
+- Collections: list/get/create and add items.
+- Activity intelligence: structured feed via `/api/recent-activity`.
+
+What this tool is not for
+-------------------------
+- Model/dataset semantic search or ranking.
+- PATCH/DELETE-only operations.
+
 Scope
 -----
 This card summarizes the curated user/organization-related methods and how to call
@@ -31,6 +44,22 @@ Tool call pattern:
 - 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={...})
 
+Enhanced refine/pagination pattern (for tool loops):
+- Cursor pagination + local filtering:
+  hf_api_request(
+    endpoint="/recent-activity",
+    params={"feedType": "user", "entity": "evalstate", "activityType": "all", "limit": 50},
+    auto_paginate=True,
+    max_pages=3,
+    data_path="recentActivity",
+    where={"repoType": "model"},
+    contains="diffusion",
+    sort_by="time",
+    sort_desc=True,
+    fields=["time", "user", "repoId", "repoType", "paper.id"],
+    max_items=20,
+  )
+
 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.
@@ -38,6 +67,22 @@ Notes:
 - 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).
+- The tool supports local refine on list payloads via:
+  - `data_path` (target list inside dict payload, e.g. `recentActivity`)
+  - `where` exact-match filters with dot keys
+  - `contains` case-insensitive text match on each item
+  - `fields` projection (return only selected keys)
+  - `sort_by` / `sort_desc`
+  - `max_items` and `offset` for post-filter windowing
+- Use `auto_paginate=True` with `max_pages` for cursor feeds to reduce model-side loops.
+
+Smart query loop guidance
+-------------------------
+When the user asks for complex outcomes, do this:
+1. Fetch broad results with API-native filters first (`params`).
+2. Use `auto_paginate` only when needed.
+3. Apply local refine (`where`/`contains`/`fields`) to shrink payload.
+4. If needed, follow up with targeted endpoint calls (discussion details, comments, etc.).
 
 USER DATA
 ---------
@@ -45,7 +90,7 @@ USER DATA
   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)
+  tool: use /api/recent-activity (see Recent Activity Feed section)
 
 - get_user_overview
   tool: hf_api_request(endpoint="/users/{username}/overview")
@@ -206,6 +251,71 @@ Direct REST usage example
 -------------------------
   hf_api_request(endpoint="/organizations/<org>/overview")
 
+Recent Activity Feed (Undocumented)
+===================================
+Use /api/recent-activity for structured activity data (same class of data used
+in Hub profile/activity UIs). Prefer this over HTML scraping.
+
+Tool call pattern:
+- hf_api_request(endpoint="/api/recent-activity", params={"feedType": "user", "entity": "evalstate", "activityType": "all", "limit": 20})
+
+Endpoint details
+----------------
+- Method: GET
+- URL: https://huggingface.co/api/recent-activity
+- OpenAPI: not listed in /.well-known/openapi.json
+- Auth: optional for public feeds; required for feedType=following
+
+Query parameters
+----------------
+- feedType: one of user | org | following (required in practice)
+- entity: required for user (username) and org (org slug/name)
+- activityType: optional; see list below (default effectively "all")
+- limit: 1..100 (default 20)
+- cursor: opaque pagination cursor
+- savePreferences: optional boolean (auth only)
+- user: internal/admin override (generally not needed)
+
+Allowed feedType values
+-----------------------
+- user: activity for one user
+- org: activity for one organization
+- following: feed from accounts the authenticated user follows
+
+Allowed activityType values
+---------------------------
+- all
+- all-without-repo-discussions
+- all-without-reactions
+- like
+- update-dataset
+- update-model
+- update-space
+- update-collection
+- update-paper
+- discussion
+- upvote
+- post
+- article
+
+Response shape
+--------------
+{
+  "recentActivity": [ /* heterogeneous activity objects */ ],
+  "cursor": "base64-opaque-cursor-or-null"
+}
+
+Each activity item includes base fields like time (ISO timestamp), user, and
+userAvatarUrl. Additional fields depend on activity type (repoId, repoType,
+blog, comment, paper, discussionData, etc.).
+
+Common error behavior
+---------------------
+- 400 invalid query (bad feedType/activityType/cursor)
+- 401 unauthenticated request to feedType=following
+- 403 blocked/system-account cases
+- 404 missing user/org entity
+
 See scripts/hf_api_endpoints.txt for full endpoint details and expected request bodies.
 
 Curated HfApi Methods: User & Organization Data, Discussions & Interactions