Deploy hub-query staging with fast-agent OAuth

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+wheels/fast_agent_mcp-0.7.18-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,34 @@
+FROM python:3.13-slim
+
+RUN apt-get update && \
+    apt-get install -y \
+      bash \
+      git git-lfs \
+      wget curl procps \
+      && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+COPY wheels /tmp/wheels
+RUN uv pip install --system --no-cache \
+    /tmp/wheels/fast_agent_mcp-0.7.18-py3-none-any.whl \
+    huggingface_hub \
+    "pydantic-monty==0.0.17"
+
+COPY --link ./ /app
+RUN chown -R 1000:1000 /app
+USER 1000
+
+ENV FAST_AGENT_SERVE_OAUTH=huggingface
+ENV FAST_AGENT_OAUTH_SCOPES=inference-api
+
+EXPOSE 7860
+
+CMD ["fast-agent", "serve", \
+     "--card", "hf-hub-query.md", \
+     "--transport", "http", \
+     "--host", "0.0.0.0", \
+     "--port", "7860", \
+     "--instance-scope", "request"]

README.md

@@ -1,10 +1,50 @@
 ---
-title: Hub Query Staging
-emoji: 📉
-colorFrom: yellow
-colorTo: purple
+title: hub-query-staging
+emoji: 🔎
+colorFrom: blue
+colorTo: indigo
 sdk: docker
-pinned: false
+app_port: 7860
+short_description: Staging fast-agent MCP server for HF Hub queries.
+hf_oauth: true
+hf_oauth_expiration_minutes: 480
+hf_oauth_scopes:
+  - inference-api
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# hub-query-staging
+
+This staging Space runs a raw-passthrough fast-agent MCP server backed by the custom Monty build used for Hugging Face Hub querying.
+
+The deployed card uses `tool_result_mode: passthrough`, so tool results are returned directly rather than rewritten by a second LLM pass.
+
+## Auth
+
+This Space is configured for Hugging Face OAuth/token passthrough:
+
+- `FAST_AGENT_SERVE_OAUTH=huggingface`
+- `FAST_AGENT_OAUTH_SCOPES=inference-api`
+- `--instance-scope request`
+
+The README enables Space OAuth (`hf_oauth: true`) and the container sets the fast-agent OAuth environment. `SPACE_HOST` is used by fast-agent to derive the public OAuth resource URL. No shared `HF_TOKEN` is required for user-scoped OAuth/token pass-through.
+
+Clients can either:
+- send `Authorization: Bearer <HF_TOKEN>` directly, or
+- use MCP OAuth discovery/auth flow
+
+## Model
+
+The deployed card uses:
+
+- `hf.openai/gpt-oss-120b:sambanova`
+
+## Main files
+
+- `hf-hub-query.md` — raw MCP card
+- `tool_entrypoints.py` / `monty_api/` — Hub query tool implementation
+- `_monty_codegen_shared.md` — shared codegen instructions
+- `wheels/fast_agent_mcp-0.7.18-py3-none-any.whl` — staging fast-agent wheel from `../fast-agent-pr/`
+
+## Dependencies
+
+The Space installs the staged `fast-agent-mcp` wheel from this repo and `pydantic-monty==0.0.17` from PyPI.

_monty_codegen_shared.md

@@ -0,0 +1,784 @@
+## Code Generation Rules
+
+- You are writing Python to be executed in a secure runtime environment.
+- **NEVER** use `import` - it is NOT available in this environment.
+- All helper calls are async: always use `await`.
+- Write a top-level Monty Python script. Use a shape like:
+
+```py
+resp = await hf_models_search(limit=min(max_calls, 10))
+result = resp["items"]
+result
+```
+
+- `max_calls` is a runtime-provided top-level input.
+- `max_calls` is the total external-call budget for the whole program.
+- Always assign the final output to `result`.
+- End the script with a final line containing only `result`.
+- Never stop after `result = ...`; always add a final bare `result` line.
+- Do **not** define or call `solve(...)`.
+- Use only documented `hf_*` helpers.
+- `result` must be plain Python data only: `dict`, `list`, `str`, `int`, `float`, `bool`, or `None`.
+- Do **not** hand-build JSON strings, markdown strings, or your own transport wrapper like `{result: ..., meta: ...}` unless the user explicitly asked for prose.
+- If the user says "return only" some fields, make `result` exactly that shape.
+- If a helper already returns the requested row shape, use `resp["items"]` directly **only when helper coverage is clearly complete**. If helper `meta` suggests partial/unknown coverage, set `result = {"results": resp["items"], "coverage": resp["meta"]}` instead of bare items.
+- For current-user prompts (`my`, `me`), try helpers with `username=None` / `handle=None` first.
+- For current-user follower/following aggregation prompts, prefer `hf_user_graph(relation=..., ...)` directly instead of `hf_whoami()` plus a second graph call. This saves a call and avoids unnecessary branching.
+- If a current-user helper returns `ok=false`, assign that helper response to `result`.
+- For relationship / aggregation questions (followers, members, likes, likers, intersections), preserve attribution in `result` unless the user explicitly asked for a collapsed deduped list.
+- Do **not** choose tiny hard-coded limits like `5` for follower/member/likes aggregation unless the user explicitly asked for a tiny sample. Prefer larger limits and preserve coverage when partial.
+- If you branch on an error path, you must still end the module with a final top-level bare `result` line outside every `if` / loop.
+
+## Search rules
+
+- If the user is asking about models, use `hf_models_search(...)`.
+- If the user is asking about datasets, use `hf_datasets_search(...)`.
+- If the user is asking about spaces, use `hf_spaces_search(...)`.
+- Use `hf_repo_search(...)` only for intentionally cross-type search.
+- Use `hf_trending(...)` only for the small "what is trending right now" feed.
+- If the user says "trending" but also adds searchable constraints like `pipeline_tag`, `author`, search text, or `num_params` bounds, prefer the repo search helper sorted by `trending_score`.
+- Think of search helpers as filter-first discovery and `hf_trending(...)` as rank-first current-feed inspection.
+
+## Parameter notes
+
+- Trust the generated helper contracts below for per-helper params, fields, sort keys, expand values, and defaults.
+- When the user asks for helper-owned coverage metadata, use `helper_resp["meta"]`.
+- Treat any of the following helper-meta signals as coverage-sensitive: `limit_boundary_hit`, `truncated`, `more_available` not equal to `False`, `sample_complete=false`, `exact_count=false`, `ranking_complete=false`, `ranking_window_hit=true`, or `hard_cap_applied=true`. In those cases, do **not** return bare items; return `{"results": ..., "coverage": ...}`.
+- For pro-only follower/member/liker queries, prefer `pro_only=True` instead of filtering on a projected field.
+- `hf_user_likes(...)` already returns full normalized like rows by default; omit `fields` unless the user asked for a subset.
+- When sorting `hf_user_likes(...)` by `repo_likes` or `repo_downloads`, set `ranking_window=50` unless the user explicitly asked for a narrower recent window.
+- For human-facing follower/member/liker lists without an explicit requested count, prefer `limit=100` and return coverage when more may exist.
+- For follower/following/member/liker queries that require local filtering on actor fields such as `username` or `fullname`, prefer a bounded scan like `limit=100` / `scan_limit=100` by default, or at most about `200` when a slightly broader sample is justified. Do **not** jump to `1000` unless the user explicitly asked for exhaustive coverage or a very large sample.
+- Unknown `fields` / `where` keys now fail fast. Use only canonical field names.
+- Ownership phrasing like "what collections does Qwen have", "collections by Qwen", or "collections owned by Qwen" means an owner lookup, so use `hf_collections_search(owner="Qwen")`, not a keyword-only `query="Qwen"` search; it filters owners case-insensitively.
+- Ownership phrasing like "what spaces does X have", "what models does X have", or "what datasets does X have" means an author/owner inventory lookup, so use `hf_spaces_search(author="X")`, `hf_models_search(author="X")`, or `hf_datasets_search(author="X")` rather than a global keyword-only search.
+- For profile/detail/social questions about a user or org — bio, description, display name, website, GitHub, Twitter/X, LinkedIn, Bluesky, organizations, or pro status — use `hf_profile_summary(...)` first.
+- For join-style questions that need profile details for followers, following, members, likers, or other actor lists, first fetch a **bounded** actor list, filter locally on actor fields like `username` / `fullname`, then hydrate only the bounded matches with `hf_profile_summary(...)`.
+- Do **not** set the initial actor-list limit equal to the whole remaining call budget when each match needs a follow-up profile lookup; reserve budget for the profile-detail calls and return coverage if the hydration step is partial.
+- For exact aggregate counts like "how many models/datasets/spaces does X have", prefer `hf_profile_summary(...)['item']` counts. Those overview-owned counts may differ slightly from visible public search/list results, so if the user also asked for the list, preserve that distinction.
+- For owner inventory queries without an explicit requested count, use `hf_profile_summary(...)` first when a specific owner is known. If the count is modest, use it to size the follow-up list call; otherwise return a bounded list plus coverage instead of pretending completeness.
+- Think like `huggingface_hub`: `search`, `filter`, `author`, repo-type-specific upstream params, then `fields`.
+- Push constraints upstream whenever a first-class helper argument exists.
+- `post_filter` is only for normalized row filters that cannot be pushed upstream.
+- `num_params` is a first-class upstream model-search arg; use `num_params="min:6B,max:128B"` instead of `post_filter` when possible.
+- For created/updated date constraints, pair local `post_filter` with the matching sort (`created_at` or `last_modified`). Do **not** rely on date-only `post_filter` over an unsorted repo search window.
+- Keep `post_filter` simple:
+  - exact match or `in` for returned fields like `runtime_stage`
+  - `gte` / `lte` for normalized numeric fields like `downloads` and `likes`
+  - `gte` / `lte` also work for normalized ISO timestamp fields like `created_at` and `last_modified`
+- Do **not** use `post_filter` for things that already have first-class upstream params like `author`, `pipeline_tag`, `num_params` on model search, `dataset_name`, `language`, `models`, or `datasets`.
+
+Examples:
+
+```py
+result = await hf_models_search(pipeline_tag="text-to-image", limit=10)
+result
+```
+
+```py
+result = await hf_models_search(
+    pipeline_tag="text-generation",
+    num_params="min:20B,max:80B",
+    sort="trending_score",
+    limit=50,
+)
+result
+```
+
+```py
+result = await hf_collections_search(owner="Qwen", limit=10)
+result
+```
+
+Field-only pattern:
+
+```py
+resp = await hf_models_search(
+    pipeline_tag="text-to-image",
+    fields=["repo_id", "author", "likes", "downloads", "repo_url"],
+    limit=3,
+)
+result = resp["items"]
+result
+```
+
+Coverage pattern:
+
+```py
+resp = await hf_user_likes(
+    username="julien-c",
+    sort="repo_likes",
+    ranking_window=50,
+    limit=20,
+    fields=["repo_id", "repo_likes", "repo_url"],
+)
+result = {"results": resp["items"], "coverage": resp["meta"]}
+result
+```
+
+Owner-inventory pattern:
+
+```py
+profile = await hf_profile_summary(handle="huggingface")
+count = (profile.get("item") or {}).get("spaces_count")
+limit = 200 if not isinstance(count, int) else min(max(count, 1), 200)
+resp = await hf_spaces_search(
+    author="huggingface",
+    limit=limit,
+    fields=["repo_id", "repo_url"],
+)
+meta = resp.get("meta") or {}
+if meta.get("limit_boundary_hit") or meta.get("more_available") not in {False, None}:
+    result = {"results": resp["items"], "coverage": {**meta, "profile_spaces_count": count}}
+else:
+    result = resp["items"]
+result
+```
+
+Follower-profile join pattern:
+
+```py
+followers_resp = await hf_user_graph(
+    relation="followers",
+    limit=100,
+    scan_limit=100,
+    fields=["username", "fullname"],
+)
+followers = followers_resp.get("items") or []
+matches = []
+for follower in followers:
+    username = follower.get("username")
+    fullname = follower.get("fullname")
+    starts_with_b = (
+        (isinstance(username, str) and username.lower().startswith("b"))
+        or (isinstance(fullname, str) and fullname.lower().startswith("b"))
+    )
+    if starts_with_b:
+        matches.append(follower)
+remaining_profile_calls = max(0, max_calls - 1)
+results = []
+for follower in matches[:remaining_profile_calls]:
+    username = follower.get("username")
+    if not username:
+        continue
+    profile = await hf_profile_summary(handle=username)
+    item = profile.get("item") or {}
+    results.append(
+        {
+            "username": username,
+            "fullname": follower.get("fullname"),
+            "github_url": item.get("github_url"),
+        }
+    )
+result = {
+    "results": results,
+    "coverage": {
+        "followers": followers_resp.get("meta") or {},
+        "matching_followers_seen": len(matches),
+        "profile_calls_used": len(results),
+        "profile_hydration_partial": len(matches) > len(results),
+    },
+}
+result
+```
+
+Follower-likes aggregation pattern:
+
+```py
+followers_resp = await hf_user_graph(relation="followers", limit=100, fields=["username"])
+followers = followers_resp.get("items") or []
+results = []
+for follower in followers:
+    username = follower.get("username")
+    if not username:
+        continue
+    likes_resp = await hf_user_likes(
+        username=username,
+        repo_types=["model"],
+        limit=20,
+        fields=["repo_id", "liked_at"],
+    )
+    results.append(
+        {
+            "follower": username,
+            "liked_models": likes_resp.get("items") or [],
+        }
+    )
+coverage = {
+    "followers": followers_resp.get("meta") or {},
+}
+result = {"results": results, "coverage": coverage}
+result
+```
+
+Current-user pro-follower model-likes pattern:
+
+```py
+followers_resp = await hf_user_graph(
+    relation="followers",
+    pro_only=True,
+    limit=100,
+    fields=["username"],
+)
+followers = followers_resp.get("items") or []
+remaining_calls = max(0, max_calls - 1)
+results = {}
+partial = (
+    (followers_resp.get("meta") or {}).get("limit_boundary_hit")
+    or (followers_resp.get("meta") or {}).get("more_available") not in {False, None}
+)
+processed_followers = 0
+for follower in followers:
+    if remaining_calls <= 0:
+        partial = True
+        break
+    username = follower.get("username")
+    if not username:
+        continue
+    likes_resp = await hf_user_likes(
+        username=username,
+        repo_types=["model"],
+        limit=2,
+        fields=["repo_id", "repo_author", "liked_at"],
+    )
+    remaining_calls -= 1
+    likes_meta = likes_resp.get("meta") or {}
+    if likes_meta.get("limit_boundary_hit") or likes_meta.get("more_available") not in {False, None}:
+        partial = True
+    items = likes_resp.get("items") or []
+    if items:
+        results[username] = items
+    processed_followers += 1
+coverage = {
+    "followers": followers_resp.get("meta") or {},
+    "processed_followers": processed_followers,
+    "partial": partial,
+}
+result = {"results": results, "coverage": coverage}
+result
+```
+
+## Navigation graph
+
+Use the helper that matches the question type.
+
+- exact repo details → `hf_repo_details(...)`
+- model search/list/discovery → `hf_models_search(...)`
+- dataset search/list/discovery → `hf_datasets_search(...)`
+- space search/list/discovery → `hf_spaces_search(...)`
+- cross-type repo search → `hf_repo_search(...)`
+- trending repos → `hf_trending(...)`
+- daily papers → `hf_daily_papers(...)`
+- repo discussions → `hf_repo_discussions(...)`
+- specific discussion details → `hf_repo_discussion_details(...)`
+- users who liked one repo → `hf_repo_likers(...)`
+- profile / overview / social/detail / aggregate counts → `hf_profile_summary(...)`
+- followers / following lists → `hf_user_graph(...)`
+- repos a user liked → `hf_user_likes(...)`
+- recent activity feed → `hf_recent_activity(...)`
+- organization members → `hf_org_members(...)`
+- collections search → `hf_collections_search(...)`
+- items inside a known collection → `hf_collection_items(...)`
+- explicit current username → `hf_whoami()`
+
+Direction reminders:
+- `hf_user_likes(...)` = user → repos
+- `hf_repo_likers(...)` = repo → users
+- `hf_user_graph(...)` = user/org → followers/following
+
+## Helper result shape
+
+All helpers return:
+
+```py
+{
+  "ok": bool,
+  "item": dict | None,
+  "items": list[dict],
+  "meta": dict,
+  "error": str | None,
+}
+```
+
+Rules:
+- `items` is the canonical list field.
+- `item` is just a singleton convenience.
+- `meta` contains helper-owned execution, limit, and coverage info.
+
+## High-signal output rules
+
+- Prefer compact dict/list outputs over prose when the user asked for fields.
+- Use canonical snake_case keys in generated code and structured output.
+- Use `repo_id` as the display label for repos.
+- For joins/intersections/rankings, fetch the needed working set first and compute locally.
+- If the result is partial, use top-level keys `results` and `coverage`.
+
+## Helper signatures (generated from Python)
+
+These signatures are exported from the live runtime with `inspect.signature(...)`.
+If prompt prose and signatures disagree, trust these signatures.
+
+```py
+await hf_collection_items(collection_id: 'str', repo_types: 'list[str] | None' = None, limit: 'int' = 100, count_only: 'bool' = False, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_collections_search(query: 'str | None' = None, owner: 'str | None' = None, limit: 'int' = 20, count_only: 'bool' = False, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_daily_papers(limit: 'int' = 20, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_datasets_search(search: 'str | None' = None, filter: 'str | list[str] | None' = None, author: 'str | None' = None, benchmark: 'str | bool | None' = None, dataset_name: 'str | None' = None, gated: 'bool | None' = None, language_creators: 'str | list[str] | None' = None, language: 'str | list[str] | None' = None, multilinguality: 'str | list[str] | None' = None, size_categories: 'str | list[str] | None' = None, task_categories: 'str | list[str] | None' = None, task_ids: 'str | list[str] | None' = None, sort: 'str | None' = None, limit: 'int' = 100, expand: 'list[str] | None' = None, full: 'bool | None' = None, fields: 'list[str] | None' = None, post_filter: 'dict[str, Any] | None' = None) -> 'dict[str, Any]'
+
+await hf_models_search(search: 'str | None' = None, filter: 'str | list[str] | None' = None, author: 'str | None' = None, apps: 'str | list[str] | None' = None, gated: 'bool | None' = None, inference: 'str | None' = None, inference_provider: 'str | list[str] | None' = None, model_name: 'str | None' = None, trained_dataset: 'str | list[str] | None' = None, pipeline_tag: 'str | None' = None, num_params: 'str | None' = None, emissions_thresholds: 'tuple[float, float] | None' = None, sort: 'str | None' = None, limit: 'int' = 100, expand: 'list[str] | None' = None, full: 'bool | None' = None, card_data: 'bool' = False, fetch_config: 'bool' = False, fields: 'list[str] | None' = None, post_filter: 'dict[str, Any] | None' = None) -> 'dict[str, Any]'
+
+await hf_org_members(organization: 'str', limit: 'int | None' = None, scan_limit: 'int | None' = None, count_only: 'bool' = False, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_profile_summary(handle: 'str | None' = None, include: 'list[str] | None' = None, likes_limit: 'int' = 10, activity_limit: 'int' = 10) -> 'dict[str, Any]'
+
+await hf_recent_activity(feed_type: 'str | None' = None, entity: 'str | None' = None, activity_types: 'list[str] | None' = None, repo_types: 'list[str] | None' = None, limit: 'int | None' = None, max_pages: 'int | None' = None, start_cursor: 'str | None' = None, count_only: 'bool' = False, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_repo_details(repo_id: 'str | None' = None, repo_ids: 'list[str] | None' = None, repo_type: 'str' = 'auto', fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_repo_discussion_details(repo_type: 'str', repo_id: 'str', discussion_num: 'int', fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_repo_discussions(repo_type: 'str', repo_id: 'str', limit: 'int' = 20, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_repo_likers(repo_id: 'str', repo_type: 'str', limit: 'int | None' = None, count_only: 'bool' = False, pro_only: 'bool | None' = None, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_repo_search(search: 'str | None' = None, repo_type: 'str | None' = None, repo_types: 'list[str] | None' = None, filter: 'str | list[str] | None' = None, author: 'str | None' = None, sort: 'str | None' = None, limit: 'int' = 100, fields: 'list[str] | None' = None, post_filter: 'dict[str, Any] | None' = None) -> 'dict[str, Any]'
+
+await hf_runtime_capabilities(section: 'str | None' = None) -> 'dict[str, Any]'
+
+await hf_spaces_search(search: 'str | None' = None, filter: 'str | list[str] | None' = None, author: 'str | None' = None, datasets: 'str | list[str] | None' = None, models: 'str | list[str] | None' = None, linked: 'bool' = False, sort: 'str | None' = None, limit: 'int' = 100, expand: 'list[str] | None' = None, full: 'bool | None' = None, fields: 'list[str] | None' = None, post_filter: 'dict[str, Any] | None' = None) -> 'dict[str, Any]'
+
+await hf_trending(repo_type: 'str' = 'model', limit: 'int' = 20, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_user_graph(username: 'str | None' = None, relation: 'str' = 'followers', limit: 'int | None' = None, scan_limit: 'int | None' = None, count_only: 'bool' = False, pro_only: 'bool | None' = None, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None) -> 'dict[str, Any]'
+
+await hf_user_likes(username: 'str | None' = None, repo_types: 'list[str] | None' = None, limit: 'int | None' = None, scan_limit: 'int | None' = None, count_only: 'bool' = False, where: 'dict[str, Any] | None' = None, fields: 'list[str] | None' = None, sort: 'str | None' = None, ranking_window: 'int | None' = None) -> 'dict[str, Any]'
+
+await hf_whoami() -> 'dict[str, Any]'
+```
+
+## Helper contracts (generated from runtime + wrapper metadata)
+
+These contracts describe the normalized wrapper surface exposed to generated code.
+Field names and helper-visible enum values are canonical snake_case wrapper names.
+
+All helpers return the same envelope: `{ok, item, items, meta, error}`.
+
+### hf_collection_items
+
+- category: `collection_navigation`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `repo`
+  - default_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - guaranteed_fields: `repo_id`, `repo_type`, `repo_url`
+  - optional_fields: `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+- supported_params: `collection_id`, `repo_types`, `limit`, `count_only`, `where`, `fields`
+- param_values:
+  - repo_types: `model`, `dataset`, `space`
+- fields_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `100`
+  - max_limit: `500`
+- notes: Returns repos inside one collection as summary rows.
+
+### hf_collections_search
+
+- category: `collection_search`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `collection`
+  - default_fields: `collection_id`, `slug`, `title`, `owner`, `owner_type`, `description`, `gating`, `last_updated`, `item_count`
+  - guaranteed_fields: `collection_id`, `title`, `owner`
+  - optional_fields: `slug`, `owner_type`, `description`, `gating`, `last_updated`, `item_count`
+- supported_params: `query`, `owner`, `limit`, `count_only`, `where`, `fields`
+- fields_contract:
+  - allowed_fields: `collection_id`, `slug`, `title`, `owner`, `owner_type`, `description`, `gating`, `last_updated`, `item_count`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `collection_id`, `slug`, `title`, `owner`, `owner_type`, `description`, `gating`, `last_updated`, `item_count`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `20`
+  - max_limit: `500`
+- notes: Collection summary helper.
+
+### hf_daily_papers
+
+- category: `curated_feed`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `daily_paper`
+  - default_fields: `paper_id`, `title`, `summary`, `published_at`, `submitted_on_daily_at`, `authors`, `organization`, `submitted_by`, `discussion_id`, `upvotes`, `github_repo_url`, `github_stars`, `project_page_url`, `num_comments`, `is_author_participating`, `repo_id`, `rank`
+  - guaranteed_fields: `paper_id`, `title`, `published_at`, `rank`
+  - optional_fields: `summary`, `submitted_on_daily_at`, `authors`, `organization`, `submitted_by`, `discussion_id`, `upvotes`, `github_repo_url`, `github_stars`, `project_page_url`, `num_comments`, `is_author_participating`, `repo_id`
+- supported_params: `limit`, `where`, `fields`
+- fields_contract:
+  - allowed_fields: `paper_id`, `title`, `summary`, `published_at`, `submitted_on_daily_at`, `authors`, `organization`, `submitted_by`, `discussion_id`, `upvotes`, `github_repo_url`, `github_stars`, `project_page_url`, `num_comments`, `is_author_participating`, `repo_id`, `rank`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `paper_id`, `title`, `summary`, `published_at`, `submitted_on_daily_at`, `authors`, `organization`, `submitted_by`, `discussion_id`, `upvotes`, `github_repo_url`, `github_stars`, `project_page_url`, `num_comments`, `is_author_participating`, `repo_id`, `rank`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `20`
+  - max_limit: `500`
+- notes: Returns daily paper summary rows. repo_id is omitted unless the upstream payload provides it.
+
+### hf_datasets_search
+
+- category: `wrapped_hf_repo_search`
+- backed_by: `HfApi.list_datasets`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `repo`
+  - default_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - guaranteed_fields: `repo_id`, `repo_type`, `author`, `repo_url`
+  - optional_fields: `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+- supported_params: `search`, `filter`, `author`, `benchmark`, `dataset_name`, `gated`, `language_creators`, `language`, `multilinguality`, `size_categories`, `task_categories`, `task_ids`, `sort`, `limit`, `expand`, `full`, `fields`, `post_filter`
+- sort_values: `created_at`, `downloads`, `last_modified`, `likes`, `trending_score`
+- expand_values: `author`, `card_data`, `citation`, `created_at`, `description`, `disabled`, `downloads`, `downloads_all_time`, `gated`, `last_modified`, `likes`, `paperswithcode_id`, `private`, `resource_group`, `sha`, `siblings`, `tags`, `trending_score`, `xet_enabled`, `gitaly_uid`
+- fields_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - canonical_only: `true`
+- post_filter_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `100`
+  - max_limit: `5000`
+- notes: Thin dataset-search wrapper around the Hub list_datasets path. Prefer this over hf_repo_search for dataset-only queries. This is a one-shot selective search; if meta.limit_boundary_hit is true, more rows may exist and counts are not exact.
+
+### hf_models_search
+
+- category: `wrapped_hf_repo_search`
+- backed_by: `HfApi.list_models`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `repo`
+  - default_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - guaranteed_fields: `repo_id`, `repo_type`, `author`, `repo_url`
+  - optional_fields: `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+- supported_params: `search`, `filter`, `author`, `apps`, `gated`, `inference`, `inference_provider`, `model_name`, `trained_dataset`, `pipeline_tag`, `num_params`, `emissions_thresholds`, `sort`, `limit`, `expand`, `full`, `card_data`, `fetch_config`, `fields`, `post_filter`
+- sort_values: `created_at`, `downloads`, `last_modified`, `likes`, `trending_score`
+- expand_values: `author`, `base_models`, `card_data`, `config`, `created_at`, `disabled`, `downloads`, `downloads_all_time`, `eval_results`, `gated`, `gguf`, `inference`, `inference_provider_mapping`, `last_modified`, `library_name`, `likes`, `mask_token`, `model_index`, `pipeline_tag`, `private`, `resource_group`, `safetensors`, `sha`, `siblings`, `spaces`, `tags`, `transformers_info`, `trending_score`, `widget_data`, `xet_enabled`, `gitaly_uid`
+- fields_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - canonical_only: `true`
+- post_filter_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `100`
+  - max_limit: `5000`
+- notes: Thin model-search wrapper around the Hub list_models path. Prefer this over hf_repo_search for model-only queries. This is a one-shot selective search; if meta.limit_boundary_hit is true, more rows may exist and counts are not exact.
+
+### hf_org_members
+
+- category: `graph_scan`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `actor`
+  - default_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - guaranteed_fields: `username`
+  - optional_fields: `fullname`, `is_pro`, `role`, `type`
+- supported_params: `organization`, `limit`, `scan_limit`, `count_only`, `where`, `fields`
+- fields_contract:
+  - allowed_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `1000`
+  - max_limit: `10000`
+  - scan_max: `10000`
+- notes: Returns organization member summary rows.
+
+### hf_profile_summary
+
+- category: `profile_summary`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `profile`
+  - default_fields: `handle`, `entity_type`, `display_name`, `bio`, `description`, `avatar_url`, `website_url`, `twitter_url`, `github_url`, `linkedin_url`, `bluesky_url`, `followers_count`, `following_count`, `likes_count`, `members_count`, `models_count`, `datasets_count`, `spaces_count`, `discussions_count`, `papers_count`, `upvotes_count`, `organizations`, `is_pro`, `likes_sample`, `activity_sample`
+  - guaranteed_fields: `handle`, `entity_type`
+  - optional_fields: `display_name`, `bio`, `description`, `avatar_url`, `website_url`, `twitter_url`, `github_url`, `linkedin_url`, `bluesky_url`, `followers_count`, `following_count`, `likes_count`, `members_count`, `models_count`, `datasets_count`, `spaces_count`, `discussions_count`, `papers_count`, `upvotes_count`, `organizations`, `is_pro`, `likes_sample`, `activity_sample`
+- supported_params: `handle`, `include`, `likes_limit`, `activity_limit`
+- param_values:
+  - include: `likes`, `activity`
+- notes: Profile summary helper. Aggregate counts like followers_count/following_count are in the base item. include=['likes', 'activity'] adds composed samples and extra upstream work; no other include values are supported. Overview-owned repo counts may differ slightly from visible public search/list results.
+
+### hf_recent_activity
+
+- category: `activity_feed`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `activity`
+  - default_fields: `event_type`, `repo_id`, `repo_type`, `timestamp`
+  - guaranteed_fields: `event_type`, `timestamp`
+  - optional_fields: `repo_id`, `repo_type`
+- supported_params: `feed_type`, `entity`, `activity_types`, `repo_types`, `limit`, `max_pages`, `start_cursor`, `count_only`, `where`, `fields`
+- param_values:
+  - feed_type: `user`, `org`
+  - repo_types: `model`, `dataset`, `space`
+- fields_contract:
+  - allowed_fields: `event_type`, `repo_id`, `repo_type`, `timestamp`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `event_type`, `repo_id`, `repo_type`, `timestamp`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `100`
+  - max_limit: `2000`
+  - max_pages: `10`
+  - page_limit: `100`
+- notes: Activity helper may fetch multiple pages when requested coverage exceeds one page. count_only may still be a lower bound unless the feed exhausts before max_pages.
+
+### hf_repo_details
+
+- category: `repo_detail`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `repo`
+  - default_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - guaranteed_fields: `repo_id`, `repo_type`, `author`, `repo_url`
+  - optional_fields: `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+- supported_params: `repo_id`, `repo_ids`, `repo_type`, `fields`
+- param_values:
+  - repo_type: `model`, `dataset`, `space`, `auto`
+- fields_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - canonical_only: `true`
+- notes: Exact repo metadata path. Multiple repo_ids may trigger one detail call per requested repo.
+
+### hf_repo_discussion_details
+
+- category: `discussion_detail`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `discussion_detail`
+  - default_fields: `num`, `repo_id`, `repo_type`, `title`, `author`, `created_at`, `status`, `url`, `comment_count`, `latest_comment_author`, `latest_comment_created_at`, `latest_comment_text`, `latest_comment_html`
+  - guaranteed_fields: `repo_id`, `repo_type`, `title`, `author`, `status`
+  - optional_fields: `num`, `created_at`, `url`, `comment_count`, `latest_comment_author`, `latest_comment_created_at`, `latest_comment_text`, `latest_comment_html`
+- supported_params: `repo_type`, `repo_id`, `discussion_num`, `fields`
+- param_values:
+  - repo_type: `model`, `dataset`, `space`
+- fields_contract:
+  - allowed_fields: `num`, `repo_id`, `repo_type`, `title`, `author`, `created_at`, `status`, `url`, `comment_count`, `latest_comment_author`, `latest_comment_created_at`, `latest_comment_text`, `latest_comment_html`
+  - canonical_only: `true`
+- notes: Exact discussion detail helper.
+
+### hf_repo_discussions
+
+- category: `discussion_summary`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `discussion`
+  - default_fields: `num`, `repo_id`, `repo_type`, `title`, `author`, `created_at`, `status`, `url`
+  - guaranteed_fields: `num`, `title`, `author`, `status`
+  - optional_fields: `repo_id`, `repo_type`, `created_at`, `url`
+- supported_params: `repo_type`, `repo_id`, `limit`, `fields`
+- param_values:
+  - repo_type: `model`, `dataset`, `space`
+- fields_contract:
+  - allowed_fields: `num`, `repo_id`, `repo_type`, `title`, `author`, `created_at`, `status`, `url`
+  - canonical_only: `true`
+- limit_contract:
+  - default_limit: `20`
+  - max_limit: `200`
+- notes: Discussion summary helper.
+
+### hf_repo_likers
+
+- category: `repo_to_users`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `actor`
+  - default_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - guaranteed_fields: `username`
+  - optional_fields: `fullname`, `is_pro`, `role`, `type`
+- supported_params: `repo_id`, `repo_type`, `limit`, `count_only`, `pro_only`, `where`, `fields`
+- param_values:
+  - repo_type: `model`, `dataset`, `space`
+- fields_contract:
+  - allowed_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `1000`
+- notes: Returns users who liked a repo.
+
+### hf_repo_search
+
+- category: `cross_type_repo_search`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `repo`
+  - default_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - guaranteed_fields: `repo_id`, `repo_type`, `author`, `repo_url`
+  - optional_fields: `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+- supported_params: `search`, `repo_type`, `repo_types`, `filter`, `author`, `sort`, `limit`, `fields`, `post_filter`
+- sort_values_by_repo_type:
+  - dataset: `created_at`, `downloads`, `last_modified`, `likes`, `trending_score`
+  - model: `created_at`, `downloads`, `last_modified`, `likes`, `trending_score`
+  - space: `created_at`, `last_modified`, `likes`, `trending_score`
+- param_values:
+  - repo_type: `model`, `dataset`, `space`
+  - repo_types: `model`, `dataset`, `space`
+  - sort: `created_at`, `downloads`, `last_modified`, `likes`, `trending_score`
+- fields_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - canonical_only: `true`
+- post_filter_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `100`
+  - max_limit: `5000`
+- notes: Small generic repo-search helper. Prefer hf_models_search, hf_datasets_search, or hf_spaces_search for single-type queries; use hf_repo_search for intentionally cross-type search. This is a one-shot selective search; if meta.limit_boundary_hit is true, more rows may exist and counts are not exact.
+
+### hf_runtime_capabilities
+
+- category: `introspection`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `runtime_capability`
+  - default_fields: `allowed_sections`, `overview`, `helpers`, `helper_contracts`, `helper_defaults`, `fields`, `limits`, `repo_search`
+  - guaranteed_fields: `allowed_sections`, `overview`, `helpers`, `helper_contracts`, `helper_defaults`, `fields`, `limits`, `repo_search`
+  - optional_fields: []
+- supported_params: `section`
+- param_values:
+  - section: `overview`, `helpers`, `helper_contracts`, `helper_defaults`, `fields`, `limits`, `repo_search`
+- notes: Introspection helper. Use section=... to narrow the response.
+
+### hf_spaces_search
+
+- category: `wrapped_hf_repo_search`
+- backed_by: `HfApi.list_spaces`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `repo`
+  - default_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - guaranteed_fields: `repo_id`, `repo_type`, `author`, `repo_url`
+  - optional_fields: `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+- supported_params: `search`, `filter`, `author`, `datasets`, `models`, `linked`, `sort`, `limit`, `expand`, `full`, `fields`, `post_filter`
+- sort_values: `created_at`, `last_modified`, `likes`, `trending_score`
+- expand_values: `author`, `card_data`, `created_at`, `datasets`, `disabled`, `last_modified`, `likes`, `models`, `private`, `resource_group`, `runtime`, `sdk`, `sha`, `siblings`, `subdomain`, `tags`, `trending_score`, `xet_enabled`, `gitaly_uid`
+- fields_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - canonical_only: `true`
+- post_filter_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `100`
+  - max_limit: `5000`
+- notes: Thin space-search wrapper around the Hub list_spaces path. Prefer this over hf_repo_search for space-only queries. This is a one-shot selective search; if meta.limit_boundary_hit is true, more rows may exist and counts are not exact.
+
+### hf_trending
+
+- category: `curated_repo_feed`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `repo`
+  - default_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`, `trending_rank`
+  - guaranteed_fields: `repo_id`, `repo_type`, `author`, `repo_url`, `trending_rank`
+  - optional_fields: `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`
+- supported_params: `repo_type`, `limit`, `where`, `fields`
+- param_values:
+  - repo_type: `model`, `dataset`, `space`, `all`
+- fields_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`, `trending_rank`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `trending_score`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `repo_url`, `tags`, `library_name`, `description`, `paperswithcode_id`, `sdk`, `models`, `datasets`, `subdomain`, `runtime_stage`, `runtime`, `trending_rank`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `20`
+  - max_limit: `20`
+- notes: Returns ordered trending summary rows only. Use hf_repo_details for exact repo metadata.
+
+### hf_user_graph
+
+- category: `graph_scan`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `actor`
+  - default_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - guaranteed_fields: `username`
+  - optional_fields: `fullname`, `is_pro`, `role`, `type`
+- supported_params: `username`, `relation`, `limit`, `scan_limit`, `count_only`, `pro_only`, `where`, `fields`
+- param_values:
+  - relation: `followers`, `following`
+- fields_contract:
+  - allowed_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `username`, `fullname`, `is_pro`, `role`, `type`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `1000`
+  - max_limit: `10000`
+  - scan_max: `10000`
+- notes: Returns followers/following summary rows.
+
+### hf_user_likes
+
+- category: `user_to_repos`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `user_like`
+  - default_fields: `liked_at`, `repo_id`, `repo_type`, `repo_author`, `repo_likes`, `repo_downloads`, `repo_url`
+  - guaranteed_fields: `liked_at`, `repo_id`, `repo_type`
+  - optional_fields: `repo_author`, `repo_likes`, `repo_downloads`, `repo_url`
+- supported_params: `username`, `repo_types`, `limit`, `scan_limit`, `count_only`, `where`, `fields`, `sort`, `ranking_window`
+- sort_values: `liked_at`, `repo_likes`, `repo_downloads`
+- param_values:
+  - repo_types: `model`, `dataset`, `space`
+  - sort: `liked_at`, `repo_likes`, `repo_downloads`
+- fields_contract:
+  - allowed_fields: `liked_at`, `repo_id`, `repo_type`, `repo_author`, `repo_likes`, `repo_downloads`, `repo_url`
+  - canonical_only: `true`
+- where_contract:
+  - allowed_fields: `liked_at`, `repo_id`, `repo_type`, `repo_author`, `repo_likes`, `repo_downloads`, `repo_url`
+  - supported_ops: `eq`, `in`, `contains`, `icontains`, `gte`, `lte`
+  - normalized_only: `true`
+- limit_contract:
+  - default_limit: `100`
+  - max_limit: `2000`
+  - enrich_max: `50`
+  - ranking_default: `50`
+  - scan_max: `10000`
+- notes: Default recency mode is cheap. Popularity-ranked sorts use canonical keys liked_at/repo_likes/repo_downloads and rerank only a bounded recent shortlist. Check meta.ranking_complete / meta.ranking_window when ranking by popularity; helper-owned coverage matters here.
+
+### hf_whoami
+
+- category: `identity`
+- returns:
+  - envelope: `{ok, item, items, meta, error}`
+  - row_type: `user`
+  - default_fields: `username`, `fullname`, `is_pro`
+  - guaranteed_fields: `username`
+  - optional_fields: `fullname`, `is_pro`
+- supported_params: []
+- notes: Returns the current authenticated user when a request token is available.

hf-hub-query.md

@@ -0,0 +1,50 @@
+---
+type: agent
+name: hf_hub_query
+model: hf.openai/gpt-oss-120b:sambanova
+use_history: false
+default: true
+description: "Read-only Hugging Face Hub navigator for discovery, lookup, filtering, ranking, counts, field-constrained extraction, and relationship questions across users, orgs, models, datasets, spaces, collections, discussions, daily papers, recent activity, followers/following, likes, and likers. Good for structured raw outputs and compact results. Generated helper calls can explicitly bound limit, scan_limit, max_pages, and ranking_window for brevity or broader coverage, and the tool can also be asked about its supported helpers, canonical fields, defaults, and coverage behavior."
+shell: false
+skills: []
+#tool_hooks:
+#  after_llm_call: monty_api/llm_time_hook.py:display_llm_time
+function_tools:
+  - entrypoint: tool_entrypoints.py:hf_hub_query_raw
+    variant: code
+    code_arg: code
+    language: python
+request_params:
+  tool_result_mode: passthrough
+---
+
+reasoning: medium
+
+You are a **tool-using, read-only** Hugging Face Hub search/navigation agent.
+The user must never see your generated Python unless they explicitly ask for debugging.
+
+## Turn protocol
+- For normal requests, your **first assistant action must be exactly one tool call** to `hf_hub_query_raw`.
+- Put the generated Python only in the tool's `code` argument.
+- Do **not** output planning text, pseudocode, code fences, or contract explanations before the tool call.
+- Only ask a brief clarification question if the request is genuinely ambiguous or missing required identity.
+- The generated program is a top-level Monty Python script.
+- `max_calls` is provided by the runtime as a top-level input.
+- Always assign the final output to `result`.
+- The final line must be exactly `result`.
+- Never stop after `result = ...`; always add a final bare `result` line.
+- Do **not** define or call `solve(...)`.
+- The tool call only needs `code` unless you truly need optional raw-query metadata.
+- Do **not** pass explicit `max_calls` or `timeout_sec` tool arguments unless the user explicitly asked for a non-default budget/timeout. Let the runtime defaults apply for ordinary requests.
+- One user request = one `hf_hub_query_raw` call. Do **not** retry in the same turn.
+
+## Raw return rules
+- The value of `result` is the user-facing payload.
+- Make `result` a dict/list when JSON is appropriate; use a string/number/bool only when that scalar is the intended payload.
+- For composed structured outputs that include your own coverage metadata, always use the exact top-level keys `results` and `coverage` unless the user explicitly asked for different key names.
+- Prefer emitting outputs directly unless post-processing is required. Do **NOT** rename fields unless asked specifically.
+- Runtime will wrap the value of `result` under `result` and attach runtime information under `meta`.
+- When helper-owned coverage metadata matters, prefer returning the helper envelope directly.
+- Do **not** create your own transport wrapper such as `{result: ..., meta: ...}` in generated code.
+
+{{file:_monty_codegen_shared.md}}

monty_api/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from .registry import HELPER_EXTERNALS
+
+
+def __getattr__(name: str):  # pragma: no cover - tiny import shim
+    if name in {"hf_hub_query", "hf_hub_query_raw", "main"}:
+        from .query_entrypoints import hf_hub_query, hf_hub_query_raw, main
+
+        exports = {
+            "hf_hub_query": hf_hub_query,
+            "hf_hub_query_raw": hf_hub_query_raw,
+            "main": main,
+        }
+        return exports[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__all__ = [
+    "HELPER_EXTERNALS",
+    "hf_hub_query",
+    "hf_hub_query_raw",
+    "main",
+]

monty_api/aliases.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import get_args
+
+try:
+    from huggingface_hub.hf_api import DatasetSort_T, ModelSort_T, SpaceSort_T
+except ModuleNotFoundError:  # pragma: no cover - dependency-light test/import path
+    DatasetSort_T = ()
+    ModelSort_T = ()
+    SpaceSort_T = ()
+
+REPO_SORT_KEYS: dict[str, set[str]] = {
+    "model": set(get_args(ModelSort_T))
+    or {
+        "created_at",
+        "downloads",
+        "last_modified",
+        "likes",
+        "trending_score",
+    },
+    "dataset": set(get_args(DatasetSort_T))
+    or {
+        "created_at",
+        "downloads",
+        "last_modified",
+        "likes",
+        "trending_score",
+    },
+    "space": set(get_args(SpaceSort_T))
+    or {
+        "created_at",
+        "last_modified",
+        "likes",
+        "trending_score",
+    },
+}

monty_api/constants.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+DEFAULT_TIMEOUT_SEC = 90  # Default end-to-end timeout for one Monty run.
+
+DEFAULT_MAX_CALLS = 400  # Default external-call budget exposed to callers.
+
+MAX_CALLS_LIMIT = 400  # Absolute max external-call budget accepted by the runtime.
+
+INTERNAL_STRICT_MODE = False
+
+OUTPUT_ITEMS_TRUNCATION_LIMIT = (
+    500  # Final output truncation for oversized `items` payloads.
+)
+
+EXHAUSTIVE_HELPER_RETURN_HARD_CAP = (
+    2_000  # Runtime hard cap for exhaustive-helper output rows.
+)
+
+SELECTIVE_ENDPOINT_RETURN_HARD_CAP = (
+    200  # Default cap for one-shot selective endpoint helpers.
+)
+
+TRENDING_ENDPOINT_MAX_LIMIT = 20  # Upstream `/api/trending` endpoint maximum.
+
+GRAPH_SCAN_LIMIT_CAP = 10_000  # Max follower/member rows scanned in one helper call.
+
+LIKES_SCAN_LIMIT_CAP = 10_000  # Max like-event rows scanned in one helper call.
+
+LIKES_RANKING_WINDOW_DEFAULT = (
+    50  # Default shortlist size when ranking likes by repo popularity.
+)
+
+LIKES_ENRICHMENT_MAX_REPOS = (
+    50  # Max liked repos enriched with extra repo-detail calls.
+)
+
+RECENT_ACTIVITY_PAGE_SIZE = 100  # Rows requested per `/api/recent-activity` page.
+
+RECENT_ACTIVITY_SCAN_MAX_PAGES = (
+    10  # Max recent-activity pages fetched in one helper call.
+)
+
+USER_SUMMARY_LIKES_SCAN_LIMIT = 1_000  # Like rows sampled for user summary.
+
+USER_SUMMARY_ACTIVITY_MAX_PAGES = 3  # Activity pages sampled for user summary.
+
+DEFAULT_MONTY_MAX_MEMORY = 64 * 1024 * 1024  # 64 MiB
+
+DEFAULT_MONTY_MAX_ALLOCATIONS = (
+    250_000  # Approximate object-allocation ceiling in the sandbox.
+)
+
+DEFAULT_MONTY_MAX_RECURSION_DEPTH = 100  # Python recursion limit inside the sandbox.
+
+REPO_CANONICAL_FIELDS: tuple[str, ...] = (
+    "repo_id",
+    "repo_type",
+    "author",
+    "likes",
+    "downloads",
+    "trending_score",
+    "created_at",
+    "last_modified",
+    "pipeline_tag",
+    "num_params",
+    "repo_url",
+    "tags",
+    "library_name",
+    "description",
+    "paperswithcode_id",
+    "sdk",
+    "models",
+    "datasets",
+    "subdomain",
+    "runtime_stage",
+    "runtime",
+)
+
+USER_CANONICAL_FIELDS: tuple[str, ...] = (
+    "username",
+    "fullname",
+    "bio",
+    "website_url",
+    "twitter",
+    "github",
+    "linkedin",
+    "bluesky",
+    "followers",
+    "following",
+    "likes",
+    "is_pro",
+)
+
+PROFILE_CANONICAL_FIELDS: tuple[str, ...] = (
+    "handle",
+    "entity_type",
+    "display_name",
+    "bio",
+    "description",
+    "avatar_url",
+    "website_url",
+    "twitter_url",
+    "github_url",
+    "linkedin_url",
+    "bluesky_url",
+    "followers_count",
+    "following_count",
+    "likes_count",
+    "members_count",
+    "models_count",
+    "datasets_count",
+    "spaces_count",
+    "discussions_count",
+    "papers_count",
+    "upvotes_count",
+    "organizations",
+    "is_pro",
+    "likes_sample",
+    "activity_sample",
+)
+
+ACTOR_CANONICAL_FIELDS: tuple[str, ...] = (
+    "username",
+    "fullname",
+    "is_pro",
+    "role",
+    "type",
+)
+
+USER_LIKES_CANONICAL_FIELDS: tuple[str, ...] = (
+    "liked_at",
+    "repo_id",
+    "repo_type",
+    "repo_author",
+    "repo_likes",
+    "repo_downloads",
+    "repo_url",
+)
+
+DISCUSSION_CANONICAL_FIELDS: tuple[str, ...] = (
+    "num",
+    "repo_id",
+    "repo_type",
+    "title",
+    "author",
+    "created_at",
+    "status",
+    "url",
+)
+
+DISCUSSION_DETAIL_CANONICAL_FIELDS: tuple[str, ...] = (
+    "num",
+    "repo_id",
+    "repo_type",
+    "title",
+    "author",
+    "created_at",
+    "status",
+    "url",
+    "comment_count",
+    "latest_comment_author",
+    "latest_comment_created_at",
+    "latest_comment_text",
+    "latest_comment_html",
+)
+
+ACTIVITY_CANONICAL_FIELDS: tuple[str, ...] = (
+    "event_type",
+    "repo_id",
+    "repo_type",
+    "timestamp",
+)
+
+COLLECTION_CANONICAL_FIELDS: tuple[str, ...] = (
+    "collection_id",
+    "slug",
+    "title",
+    "owner",
+    "owner_type",
+    "description",
+    "gating",
+    "last_updated",
+    "item_count",
+)
+
+DAILY_PAPER_CANONICAL_FIELDS: tuple[str, ...] = (
+    "paper_id",
+    "title",
+    "summary",
+    "published_at",
+    "submitted_on_daily_at",
+    "authors",
+    "organization",
+    "submitted_by",
+    "discussion_id",
+    "upvotes",
+    "github_repo_url",
+    "github_stars",
+    "project_page_url",
+    "num_comments",
+    "is_author_participating",
+    "repo_id",
+    "rank",
+)

monty_api/context_types.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class HelperRuntimeContext(Protocol):
+    """Typed helper-facing runtime context interface."""
+
+    helper_registry: dict[str, Any]
+    call_count: dict[str, int]
+    trace: list[dict[str, Any]]
+    limit_summaries: list[dict[str, Any]]
+    latest_helper_error_box: dict[str, dict[str, Any] | None]
+    internal_helper_used: dict[str, bool]
+
+    async def call_helper(
+        self, helper_name: str, /, *args: Any, **kwargs: Any
+    ) -> Any: ...
+
+    def __getattr__(self, name: str) -> Any: ...

monty_api/helper_contracts.py

@@ -0,0 +1,531 @@
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Callable, Mapping
+from functools import lru_cache
+from typing import Any, TypedDict, get_args
+
+try:
+    import huggingface_hub.hf_api as hf_api
+except ModuleNotFoundError:  # pragma: no cover - dependency-light test/import path
+    hf_api = None
+
+from .aliases import REPO_SORT_KEYS
+from .constants import (
+    ACTIVITY_CANONICAL_FIELDS,
+    ACTOR_CANONICAL_FIELDS,
+    COLLECTION_CANONICAL_FIELDS,
+    DAILY_PAPER_CANONICAL_FIELDS,
+    DISCUSSION_CANONICAL_FIELDS,
+    DISCUSSION_DETAIL_CANONICAL_FIELDS,
+    PROFILE_CANONICAL_FIELDS,
+    REPO_CANONICAL_FIELDS,
+    USER_CANONICAL_FIELDS,
+    USER_LIKES_CANONICAL_FIELDS,
+)
+from .registry import (
+    HELPER_DEFAULT_METADATA,
+    PAGINATION_POLICY,
+    REPO_SEARCH_ALLOWED_EXPAND,
+    RUNTIME_CAPABILITY_FIELDS,
+)
+
+
+HELPER_RESULT_ENVELOPE = {
+    "ok": "bool",
+    "item": "dict | None",
+    "items": "list[dict]",
+    "meta": "dict",
+    "error": "str | None",
+}
+
+FILTER_OPERATORS = ["eq", "in", "contains", "icontains", "gte", "lte"]
+REPO_TYPE_VALUES = ["model", "dataset", "space"]
+TRENDING_CANONICAL_FIELDS = [*REPO_CANONICAL_FIELDS, "trending_rank"]
+COMMON_REPO_SEARCH_PARAMS = {
+    "search",
+    "filter",
+    "author",
+    "sort",
+    "limit",
+    "fields",
+    "post_filter",
+}
+
+
+class HelperContract(TypedDict, total=False):
+    name: str
+    signature: str
+    category: str
+    backed_by: str
+    supported_params: list[str]
+    sort_values: list[str]
+    sort_values_by_repo_type: dict[str, list[str]]
+    expand_values: list[str]
+    param_values: dict[str, list[str]]
+    fields_contract: dict[str, Any]
+    where_contract: dict[str, Any]
+    post_filter_contract: dict[str, Any]
+    limit_contract: dict[str, Any]
+    returns: dict[str, Any]
+    notes: str
+
+
+FIELD_GROUPS: dict[str, list[str]] = {
+    "activity": list(ACTIVITY_CANONICAL_FIELDS),
+    "actor": list(ACTOR_CANONICAL_FIELDS),
+    "collection": list(COLLECTION_CANONICAL_FIELDS),
+    "daily_paper": list(DAILY_PAPER_CANONICAL_FIELDS),
+    "discussion": list(DISCUSSION_CANONICAL_FIELDS),
+    "discussion_detail": list(DISCUSSION_DETAIL_CANONICAL_FIELDS),
+    "profile": list(PROFILE_CANONICAL_FIELDS),
+    "repo": list(REPO_CANONICAL_FIELDS),
+    "trending_repo": list(TRENDING_CANONICAL_FIELDS),
+    "runtime_capability": list(RUNTIME_CAPABILITY_FIELDS),
+    "user": list(USER_CANONICAL_FIELDS),
+    "user_like": list(USER_LIKES_CANONICAL_FIELDS),
+}
+RUNTIME_CAPABILITY_SECTION_VALUES = [
+    field for field in RUNTIME_CAPABILITY_FIELDS if field != "allowed_sections"
+]
+
+
+HELPER_CONTRACT_SPECS: dict[str, dict[str, Any]] = {
+    "hf_collection_items": {
+        "category": "collection_navigation",
+        "row_type": "repo",
+        "fields_group": "repo",
+        "filter_param": "where",
+        "filter_group": "repo",
+        "param_values": {"repo_types": REPO_TYPE_VALUES},
+    },
+    "hf_collections_search": {
+        "category": "collection_search",
+        "row_type": "collection",
+        "fields_group": "collection",
+        "filter_param": "where",
+        "filter_group": "collection",
+    },
+    "hf_daily_papers": {
+        "category": "curated_feed",
+        "row_type": "daily_paper",
+        "fields_group": "daily_paper",
+        "filter_param": "where",
+        "filter_group": "daily_paper",
+    },
+    "hf_datasets_search": {
+        "category": "wrapped_hf_repo_search",
+        "row_type": "repo",
+        "fields_group": "repo",
+        "filter_param": "post_filter",
+        "filter_group": "repo",
+        "upstream_repo_type": "dataset",
+    },
+    "hf_models_search": {
+        "category": "wrapped_hf_repo_search",
+        "row_type": "repo",
+        "fields_group": "repo",
+        "filter_param": "post_filter",
+        "filter_group": "repo",
+        "upstream_repo_type": "model",
+    },
+    "hf_org_members": {
+        "category": "graph_scan",
+        "row_type": "actor",
+        "fields_group": "actor",
+        "filter_param": "where",
+        "filter_group": "actor",
+    },
+    "hf_profile_summary": {
+        "category": "profile_summary",
+        "row_type": "profile",
+        "param_values": {"include": ["likes", "activity"]},
+    },
+    "hf_recent_activity": {
+        "category": "activity_feed",
+        "row_type": "activity",
+        "fields_group": "activity",
+        "filter_param": "where",
+        "filter_group": "activity",
+        "param_values": {"feed_type": ["user", "org"], "repo_types": REPO_TYPE_VALUES},
+    },
+    "hf_repo_details": {
+        "category": "repo_detail",
+        "row_type": "repo",
+        "fields_group": "repo",
+        "param_values": {"repo_type": [*REPO_TYPE_VALUES, "auto"]},
+    },
+    "hf_repo_discussion_details": {
+        "category": "discussion_detail",
+        "row_type": "discussion_detail",
+        "fields_group": "discussion_detail",
+        "param_values": {"repo_type": REPO_TYPE_VALUES},
+    },
+    "hf_repo_discussions": {
+        "category": "discussion_summary",
+        "row_type": "discussion",
+        "fields_group": "discussion",
+        "param_values": {"repo_type": REPO_TYPE_VALUES},
+    },
+    "hf_repo_likers": {
+        "category": "repo_to_users",
+        "row_type": "actor",
+        "fields_group": "actor",
+        "filter_param": "where",
+        "filter_group": "actor",
+        "param_values": {"repo_type": REPO_TYPE_VALUES},
+    },
+    "hf_repo_search": {
+        "category": "cross_type_repo_search",
+        "row_type": "repo",
+        "fields_group": "repo",
+        "filter_param": "post_filter",
+        "filter_group": "repo",
+        "param_values": {"repo_type": REPO_TYPE_VALUES, "repo_types": REPO_TYPE_VALUES},
+    },
+    "hf_runtime_capabilities": {
+        "category": "introspection",
+        "row_type": "runtime_capability",
+        "param_values": {"section": list(RUNTIME_CAPABILITY_SECTION_VALUES)},
+    },
+    "hf_spaces_search": {
+        "category": "wrapped_hf_repo_search",
+        "row_type": "repo",
+        "fields_group": "repo",
+        "filter_param": "post_filter",
+        "filter_group": "repo",
+        "upstream_repo_type": "space",
+    },
+    "hf_trending": {
+        "category": "curated_repo_feed",
+        "row_type": "repo",
+        "fields_group": "trending_repo",
+        "filter_param": "where",
+        "filter_group": "trending_repo",
+        "param_values": {"repo_type": [*REPO_TYPE_VALUES, "all"]},
+    },
+    "hf_user_graph": {
+        "category": "graph_scan",
+        "row_type": "actor",
+        "fields_group": "actor",
+        "filter_param": "where",
+        "filter_group": "actor",
+        "param_values": {
+            "relation": ["followers", "following"],
+        },
+    },
+    "hf_user_likes": {
+        "category": "user_to_repos",
+        "row_type": "user_like",
+        "fields_group": "user_like",
+        "filter_param": "where",
+        "filter_group": "user_like",
+        "param_values": {
+            "repo_types": REPO_TYPE_VALUES,
+            "sort": ["liked_at", "repo_likes", "repo_downloads"],
+        },
+    },
+    "hf_whoami": {
+        "category": "identity",
+        "row_type": "user",
+    },
+}
+
+
+def _dedupe(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for value in values:
+        item = str(value).strip()
+        if not item or item in seen:
+            continue
+        seen.add(item)
+        out.append(item)
+    return out
+
+
+def _snake_case_token(value: str) -> str:
+    cleaned = str(value).strip().replace("-", "_")
+    cleaned = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", cleaned)
+    cleaned = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", cleaned)
+    cleaned = re.sub(r"__+", "_", cleaned)
+    return cleaned.lower()
+
+
+def repo_expand_alias_map(repo_type: str) -> dict[str, str]:
+    aliases: dict[str, str] = {}
+    for raw_value in REPO_SEARCH_ALLOWED_EXPAND.get(repo_type, []):
+        aliases[str(raw_value)] = str(raw_value)
+        aliases[_snake_case_token(str(raw_value))] = str(raw_value)
+    return aliases
+
+
+def normalized_repo_expand_values(repo_type: str) -> list[str]:
+    return _dedupe(
+        [
+            _snake_case_token(value)
+            for value in REPO_SEARCH_ALLOWED_EXPAND.get(repo_type, [])
+        ]
+    )
+
+
+@lru_cache(maxsize=1)
+def _upstream_repo_search_facts() -> dict[str, dict[str, Any]]:
+    alias_names = {
+        "dataset": ("list_datasets", "DatasetSort_T"),
+        "model": ("list_models", "ModelSort_T"),
+        "space": ("list_spaces", "SpaceSort_T"),
+    }
+    facts: dict[str, dict[str, Any]] = {}
+    for repo_type, (method_name, sort_alias_name) in alias_names.items():
+        if hf_api is None:
+            supported_params = sorted(COMMON_REPO_SEARCH_PARAMS)
+            sort_values = sorted(REPO_SORT_KEYS.get(repo_type, set()))
+        else:
+            method = getattr(hf_api.HfApi, method_name)
+            signature = inspect.signature(method)
+            supported_params = [
+                name for name in signature.parameters if name not in {"self", "token"}
+            ]
+            sort_alias = getattr(hf_api, sort_alias_name, None)
+            sort_values = _dedupe([str(value) for value in get_args(sort_alias)])
+        facts[repo_type] = {
+            "method_name": f"HfApi.{method_name}",
+            "supported_params": supported_params,
+            "sort_values": sort_values,
+            "expand_values": normalized_repo_expand_values(repo_type),
+        }
+    return facts
+
+
+def _returns_contract(helper_name: str, row_type: str | None) -> dict[str, Any]:
+    metadata = HELPER_DEFAULT_METADATA.get(helper_name, {})
+    returns: dict[str, Any] = {"envelope": dict(HELPER_RESULT_ENVELOPE)}
+    if row_type is not None:
+        returns["row_type"] = row_type
+    for key in ("default_fields", "guaranteed_fields", "optional_fields"):
+        value = metadata.get(key)
+        if isinstance(value, list):
+            returns[key] = list(value)
+    return returns
+
+
+def _limit_contract(helper_name: str) -> dict[str, Any] | None:
+    metadata = HELPER_DEFAULT_METADATA.get(helper_name, {})
+    limits: dict[str, Any] = {}
+    for key in ("default_limit", "max_limit"):
+        value = metadata.get(key)
+        if value is not None:
+            limits[key] = value
+    for key, value in PAGINATION_POLICY.get(helper_name, {}).items():
+        if value is not None and key not in limits:
+            limits[key] = value
+    return limits or None
+
+
+def _fields_contract(field_group: str | None) -> dict[str, Any] | None:
+    if field_group is None:
+        return None
+    return {
+        "canonical_only": True,
+        "allowed_fields": list(FIELD_GROUPS[field_group]),
+    }
+
+
+def _filter_contract(filter_param: str | None, field_group: str | None) -> tuple[str, dict[str, Any]] | None:
+    if filter_param is None or field_group is None:
+        return None
+    return (
+        f"{filter_param}_contract",
+        {
+            "allowed_fields": list(FIELD_GROUPS[field_group]),
+            "supported_ops": list(FILTER_OPERATORS),
+            "normalized_only": True,
+        },
+    )
+
+
+def _notes_for_helper(helper_name: str) -> str | None:
+    note = HELPER_DEFAULT_METADATA.get(helper_name, {}).get("notes")
+    if not isinstance(note, str):
+        return None
+    cleaned = note.strip()
+    return cleaned or None
+
+
+def _param_values_for_helper(helper_name: str) -> dict[str, list[str]] | None:
+    values = {
+        key: list(raw_values)
+        for key, raw_values in HELPER_CONTRACT_SPECS.get(helper_name, {})
+        .get("param_values", {})
+        .items()
+    }
+    if helper_name == "hf_repo_search":
+        values["sort"] = sorted(_dedupe([key for keys in REPO_SORT_KEYS.values() for key in keys]))
+    return values or None
+
+
+def build_helper_contracts(
+    helper_functions: Mapping[str, Callable[..., Any]],
+) -> dict[str, HelperContract]:
+    upstream_facts = _upstream_repo_search_facts()
+    contracts: dict[str, HelperContract] = {}
+    for helper_name, fn in sorted(helper_functions.items()):
+        spec = HELPER_CONTRACT_SPECS.get(helper_name, {})
+        row_type = spec.get("row_type")
+        fields_group = spec.get("fields_group")
+        filter_param = spec.get("filter_param")
+        filter_group = spec.get("filter_group")
+        contract: HelperContract = {
+            "name": helper_name,
+            "signature": f"await {helper_name}{inspect.signature(fn)}",
+            "category": str(spec.get("category") or "helper"),
+            "supported_params": list(inspect.signature(fn).parameters),
+            "returns": _returns_contract(helper_name, row_type),
+        }
+        fields_contract = _fields_contract(fields_group)
+        if fields_contract is not None:
+            contract["fields_contract"] = fields_contract
+        filter_contract = _filter_contract(filter_param, filter_group)
+        if filter_contract is not None:
+            contract[filter_contract[0]] = filter_contract[1]
+        limit_contract = _limit_contract(helper_name)
+        if limit_contract is not None:
+            contract["limit_contract"] = limit_contract
+        param_values = _param_values_for_helper(helper_name)
+        if param_values is not None:
+            contract["param_values"] = param_values
+
+        upstream_repo_type = spec.get("upstream_repo_type")
+        if isinstance(upstream_repo_type, str):
+            upstream = upstream_facts[upstream_repo_type]
+            contract["backed_by"] = str(upstream["method_name"])
+            contract["sort_values"] = list(upstream["sort_values"])
+            contract["expand_values"] = list(upstream["expand_values"])
+        elif helper_name == "hf_repo_search":
+            contract["sort_values_by_repo_type"] = {
+                repo_type: sorted(values)
+                for repo_type, values in sorted(REPO_SORT_KEYS.items())
+            }
+
+        if helper_name == "hf_user_likes":
+            contract["sort_values"] = ["liked_at", "repo_likes", "repo_downloads"]
+
+        note = _notes_for_helper(helper_name)
+        if note is not None:
+            contract["notes"] = note
+        contracts[helper_name] = contract
+    return contracts
+
+
+def _format_list(values: list[str] | None) -> str:
+    if not values:
+        return "[]"
+    return ", ".join(f"`{value}`" for value in values)
+
+
+def _append_returns(lines: list[str], returns: Mapping[str, Any]) -> None:
+    lines.append("- returns:")
+    envelope = returns.get("envelope")
+    if isinstance(envelope, Mapping):
+        lines.append("  - envelope: `{ok, item, items, meta, error}`")
+    row_type = returns.get("row_type")
+    if isinstance(row_type, str):
+        lines.append(f"  - row_type: `{row_type}`")
+    for key in ("default_fields", "guaranteed_fields", "optional_fields"):
+        value = returns.get(key)
+        if isinstance(value, list):
+            lines.append(f"  - {key}: {_format_list(value)}")
+
+
+def _append_named_contract(
+    lines: list[str],
+    label: str,
+    contract: Mapping[str, Any] | None,
+) -> None:
+    if not isinstance(contract, Mapping):
+        return
+    lines.append(f"- {label}:")
+    allowed_fields = contract.get("allowed_fields")
+    if isinstance(allowed_fields, list):
+        lines.append(f"  - allowed_fields: {_format_list(allowed_fields)}")
+    supported_ops = contract.get("supported_ops")
+    if isinstance(supported_ops, list):
+        lines.append(f"  - supported_ops: {_format_list(supported_ops)}")
+    canonical_only = contract.get("canonical_only")
+    if canonical_only is True:
+        lines.append("  - canonical_only: `true`")
+    normalized_only = contract.get("normalized_only")
+    if normalized_only is True:
+        lines.append("  - normalized_only: `true`")
+
+
+def _append_limit_contract(lines: list[str], contract: Mapping[str, Any] | None) -> None:
+    if not isinstance(contract, Mapping) or not contract:
+        return
+    lines.append("- limit_contract:")
+    for key, value in contract.items():
+        lines.append(f"  - {key}: `{value}`")
+
+
+def _append_param_values(lines: list[str], param_values: Mapping[str, Any] | None) -> None:
+    if not isinstance(param_values, Mapping) or not param_values:
+        return
+    lines.append("- param_values:")
+    for key, value in param_values.items():
+        if isinstance(value, list):
+            lines.append(f"  - {key}: {_format_list(value)}")
+
+
+def build_helper_contracts_markdown(
+    helper_contracts: Mapping[str, Mapping[str, Any]],
+) -> str:
+    lines = [
+        "## Helper contracts (generated from runtime + wrapper metadata)",
+        "",
+        "These contracts describe the normalized wrapper surface exposed to generated code.",
+        "Field names and helper-visible enum values are canonical snake_case wrapper names.",
+        "",
+        "All helpers return the same envelope: `{ok, item, items, meta, error}`.",
+        "",
+    ]
+    for helper_name, contract in sorted(helper_contracts.items()):
+        lines.append(f"### {helper_name}")
+        lines.append("")
+        category = contract.get("category")
+        if isinstance(category, str):
+            lines.append(f"- category: `{category}`")
+        backed_by = contract.get("backed_by")
+        if isinstance(backed_by, str):
+            lines.append(f"- backed_by: `{backed_by}`")
+        returns = contract.get("returns")
+        if isinstance(returns, Mapping):
+            _append_returns(lines, returns)
+        supported_params = contract.get("supported_params")
+        if isinstance(supported_params, list):
+            lines.append(f"- supported_params: {_format_list(supported_params)}")
+        sort_values = contract.get("sort_values")
+        if isinstance(sort_values, list):
+            lines.append(f"- sort_values: {_format_list(sort_values)}")
+        sort_values_by_repo_type = contract.get("sort_values_by_repo_type")
+        if isinstance(sort_values_by_repo_type, Mapping):
+            lines.append("- sort_values_by_repo_type:")
+            for repo_type, values in sort_values_by_repo_type.items():
+                if isinstance(values, list):
+                    lines.append(f"  - {repo_type}: {_format_list(values)}")
+        expand_values = contract.get("expand_values")
+        if isinstance(expand_values, list):
+            lines.append(f"- expand_values: {_format_list(expand_values)}")
+        _append_param_values(lines, contract.get("param_values"))
+        _append_named_contract(lines, "fields_contract", contract.get("fields_contract"))
+        _append_named_contract(lines, "where_contract", contract.get("where_contract"))
+        _append_named_contract(
+            lines, "post_filter_contract", contract.get("post_filter_contract")
+        )
+        _append_limit_contract(lines, contract.get("limit_contract"))
+        notes = contract.get("notes")
+        if isinstance(notes, str):
+            lines.append(f"- notes: {notes}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"

monty_api/helpers/__init__.py

@@ -0,0 +1,13 @@
+from .activity import register_activity_helpers
+from .collections import register_collection_helpers
+from .introspection import register_introspection_helpers
+from .profiles import register_profile_helpers
+from .repos import register_repo_helpers
+
+__all__ = [
+    "register_activity_helpers",
+    "register_collection_helpers",
+    "register_introspection_helpers",
+    "register_profile_helpers",
+    "register_repo_helpers",
+]

monty_api/helpers/activity.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+# ruff: noqa: C901, PLR0912, PLR0913, PLR0915, PLR0917
+from functools import partial
+from typing import Any, Callable
+
+from ..constants import (
+    ACTIVITY_CANONICAL_FIELDS,
+    EXHAUSTIVE_HELPER_RETURN_HARD_CAP,
+    RECENT_ACTIVITY_PAGE_SIZE,
+    RECENT_ACTIVITY_SCAN_MAX_PAGES,
+)
+from ..context_types import HelperRuntimeContext
+
+
+async def hf_recent_activity(
+    ctx: HelperRuntimeContext,
+    feed_type: str | None = None,
+    entity: str | None = None,
+    activity_types: list[str] | None = None,
+    repo_types: list[str] | None = None,
+    limit: int | None = None,
+    max_pages: int | None = None,
+    start_cursor: str | None = None,
+    count_only: bool = False,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    default_limit = ctx._policy_int("hf_recent_activity", "default_limit", 100)
+    page_cap = ctx._policy_int(
+        "hf_recent_activity", "page_limit", RECENT_ACTIVITY_PAGE_SIZE
+    )
+    pages_cap = ctx._policy_int(
+        "hf_recent_activity", "max_pages", RECENT_ACTIVITY_SCAN_MAX_PAGES
+    )
+    requested_max_pages = max_pages
+    ft = str(feed_type or "").strip().lower()
+    ent = str(entity or "").strip()
+    if ft not in {"user", "org"}:
+        if ft and (not ent):
+            ent = ft
+            ft = "user"
+        elif not ft and ent:
+            ft = "user"
+    if ft not in {"user", "org"}:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/recent-activity",
+            error="feed_type must be 'user' or 'org'",
+        )
+    if not ent:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/recent-activity",
+            error="entity is required",
+        )
+    limit_plan = ctx._resolve_exhaustive_limits(
+        limit=limit,
+        count_only=count_only,
+        default_limit=default_limit,
+        max_limit=EXHAUSTIVE_HELPER_RETURN_HARD_CAP,
+    )
+    applied_limit = int(limit_plan["applied_limit"])
+    page_lim = page_cap
+    pages_lim = ctx._clamp_int(
+        requested_max_pages, default=pages_cap, minimum=1, maximum=pages_cap
+    )
+    type_filter = {
+        str(t).strip().lower() for t in activity_types or [] if str(t).strip()
+    }
+    repo_filter = {
+        ctx._canonical_repo_type(t, default="")
+        for t in repo_types or []
+        if str(t).strip()
+    }
+    next_cursor = (
+        str(start_cursor).strip()
+        if isinstance(start_cursor, str) and start_cursor.strip()
+        else None
+    )
+    items: list[dict[str, Any]] = []
+    scanned = 0
+    matched = 0
+    pages = 0
+    exhausted_feed = False
+    stopped_for_budget = False
+    try:
+        normalized_where = ctx._normalize_where(
+            where, allowed_fields=ACTIVITY_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/recent-activity",
+            error=exc,
+        )
+    while pages < pages_lim and (applied_limit == 0 or len(items) < applied_limit):
+        if ctx._budget_remaining() <= 0:
+            stopped_for_budget = True
+            break
+        params: dict[str, Any] = {"feedType": ft, "entity": ent, "limit": page_lim}
+        if next_cursor:
+            params["cursor"] = next_cursor
+        resp = ctx._host_raw_call("/api/recent-activity", params=params)
+        if not resp.get("ok"):
+            if pages == 0:
+                return ctx._helper_error(
+                    start_calls=start_calls,
+                    source="/api/recent-activity",
+                    error=resp.get("error") or "recent-activity fetch failed",
+                )
+            break
+        payload = resp.get("data") if isinstance(resp.get("data"), dict) else {}
+        rows = (
+            payload.get("recentActivity")
+            if isinstance(payload.get("recentActivity"), list)
+            else []
+        )
+        cursor_raw = payload.get("cursor")
+        next_cursor = cursor_raw if isinstance(cursor_raw, str) and cursor_raw else None
+        pages += 1
+        if not rows:
+            exhausted_feed = True
+            break
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            scanned += 1
+            typ = str(row.get("type") or "").strip().lower()
+            repo_id = row.get("repoId")
+            repo_type = row.get("repoType")
+            repo_data = (
+                row.get("repoData") if isinstance(row.get("repoData"), dict) else None
+            )
+            repo_obj = row.get("repo") if isinstance(row.get("repo"), dict) else None
+            if repo_id is None and repo_data is not None:
+                repo_id = repo_data.get("id") or repo_data.get("name")
+            if repo_id is None and repo_obj is not None:
+                repo_id = repo_obj.get("id") or repo_obj.get("name")
+            if repo_type is None and repo_data is not None:
+                repo_type = repo_data.get("type")
+            if repo_type is None and repo_obj is not None:
+                repo_type = repo_obj.get("type")
+            rt = ctx._canonical_repo_type(repo_type, default="") if repo_type else ""
+            if type_filter and typ not in type_filter:
+                continue
+            if repo_filter and rt not in repo_filter:
+                continue
+            item = {
+                "timestamp": row.get("time"),
+                "event_type": row.get("type"),
+                "repo_type": rt or repo_type,
+                "repo_id": repo_id,
+            }
+            if not ctx._item_matches_where(item, normalized_where):
+                continue
+            matched += 1
+            if len(items) < applied_limit:
+                items.append(item)
+        if not next_cursor:
+            exhausted_feed = True
+            break
+    try:
+        items = ctx._project_activity_items(items, fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/recent-activity",
+            error=exc,
+        )
+    exact_count = exhausted_feed and (not stopped_for_budget)
+    sample_complete = (
+        exact_count and applied_limit >= matched and (not count_only or matched == 0)
+    )
+    page_limit_hit = (
+        next_cursor is not None and pages >= pages_lim and (not exhausted_feed)
+    )
+    more_available: bool | str = ctx._derive_more_available(
+        sample_complete=sample_complete,
+        exact_count=exact_count,
+        returned=len(items),
+        total=matched if exact_count else None,
+    )
+    if next_cursor is not None:
+        more_available = True
+    elif stopped_for_budget and (not exact_count):
+        more_available = "unknown"
+    meta = ctx._build_exhaustive_result_meta(
+        base_meta={
+            "scanned": scanned,
+            "total": matched,
+            "total_matched": matched,
+            "pages": pages,
+            "count_source": "scan" if exact_count else "none",
+            "lower_bound": not exact_count,
+            "page_limit": page_lim,
+            "stopped_for_budget": stopped_for_budget,
+            "feed_type": ft,
+            "entity": ent,
+        },
+        limit_plan=limit_plan,
+        matched_count=matched,
+        returned_count=len(items),
+        exact_count=exact_count,
+        count_only=count_only,
+        sample_complete=sample_complete,
+        more_available=more_available,
+        page_limit_hit=page_limit_hit,
+        truncated_extra=stopped_for_budget,
+        requested_max_pages=requested_max_pages,
+        applied_max_pages=pages_lim,
+    )
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source="/api/recent-activity",
+        items=items,
+        meta=meta,
+        cursor=next_cursor,
+    )
+
+
+def register_activity_helpers(
+    ctx: HelperRuntimeContext,
+) -> dict[str, Callable[..., Any]]:
+    return {"hf_recent_activity": partial(hf_recent_activity, ctx)}

monty_api/helpers/collections.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+# ruff: noqa: C901, PLR0912, PLR0913, PLR0915, PLR0917
+from functools import partial
+from typing import Any, Callable
+
+from ..constants import (
+    COLLECTION_CANONICAL_FIELDS,
+    OUTPUT_ITEMS_TRUNCATION_LIMIT,
+    REPO_CANONICAL_FIELDS,
+)
+from ..context_types import HelperRuntimeContext
+
+
+async def hf_collections_search(
+    ctx: HelperRuntimeContext,
+    query: str | None = None,
+    owner: str | None = None,
+    limit: int = 20,
+    count_only: bool = False,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    default_limit = ctx._policy_int("hf_collections_search", "default_limit", 20)
+    max_limit = ctx._policy_int(
+        "hf_collections_search", "max_limit", OUTPUT_ITEMS_TRUNCATION_LIMIT
+    )
+    if count_only:
+        limit = 0
+    applied_limit = ctx._clamp_int(
+        limit,
+        default=default_limit,
+        minimum=0,
+        maximum=max_limit,
+    )
+    owner_clean = str(owner or "").strip() or None
+    owner_casefold = owner_clean.casefold() if owner_clean is not None else None
+    fetch_limit = max_limit if applied_limit == 0 or owner_clean else applied_limit
+    if owner_clean:
+        fetch_limit = min(fetch_limit, 100)
+    term = str(query or "").strip()
+    if not term and owner_clean:
+        term = owner_clean
+    if not term:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/collections",
+            error="query or owner is required",
+        )
+    params: dict[str, Any] = {"limit": fetch_limit}
+    if term:
+        params["q"] = term
+    if owner_clean:
+        params["owner"] = owner_clean
+    resp = ctx._host_raw_call("/api/collections", params=params)
+    if not resp.get("ok"):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/collections",
+            error=resp.get("error") or "collections fetch failed",
+        )
+    payload = resp.get("data") if isinstance(resp.get("data"), list) else []
+
+    def _row_owner_matches_owner(row: Any) -> bool:
+        if owner_casefold is None or not isinstance(row, dict):
+            return owner_casefold is None
+        row_owner = ctx._author_from_any(row.get("owner")) or ctx._author_from_any(
+            row.get("ownerData")
+        )
+        if (
+            not row_owner
+            and isinstance(row.get("slug"), str)
+            and "/" in str(row.get("slug"))
+        ):
+            row_owner = str(row.get("slug")).split("/", 1)[0]
+        if not isinstance(row_owner, str) or not row_owner:
+            return False
+        return row_owner.casefold() == owner_casefold
+
+    owner_fallback_used = False
+    if owner_casefold is not None and not any(
+        _row_owner_matches_owner(row) for row in payload
+    ):
+        fallback_params: dict[str, Any] = {"limit": fetch_limit}
+        if term:
+            fallback_params["q"] = term
+        fallback_resp = ctx._host_raw_call("/api/collections", params=fallback_params)
+        if fallback_resp.get("ok"):
+            fallback_payload = (
+                fallback_resp.get("data")
+                if isinstance(fallback_resp.get("data"), list)
+                else []
+            )
+            if any(_row_owner_matches_owner(row) for row in fallback_payload):
+                payload = fallback_payload
+                owner_fallback_used = True
+
+    items: list[dict[str, Any]] = []
+    for row in payload[:fetch_limit]:
+        if not isinstance(row, dict):
+            continue
+        row_owner = ctx._author_from_any(row.get("owner")) or ctx._author_from_any(
+            row.get("ownerData")
+        )
+        if (
+            not row_owner
+            and isinstance(row.get("slug"), str)
+            and "/" in str(row.get("slug"))
+        ):
+            row_owner = str(row.get("slug")).split("/", 1)[0]
+        if owner_casefold is not None and (
+            not isinstance(row_owner, str) or row_owner.casefold() != owner_casefold
+        ):
+            continue
+        owner_payload = row.get("owner") if isinstance(row.get("owner"), dict) else {}
+        collection_items = (
+            row.get("items") if isinstance(row.get("items"), list) else []
+        )
+        slug = row.get("slug")
+        items.append(
+            {
+                "collection_id": slug,
+                "slug": slug,
+                "title": row.get("title"),
+                "owner": row_owner,
+                "owner_type": owner_payload.get("type")
+                if isinstance(owner_payload.get("type"), str)
+                else None,
+                "description": row.get("description"),
+                "gating": row.get("gating"),
+                "last_updated": row.get("lastUpdated"),
+                "item_count": len(collection_items),
+            }
+        )
+    try:
+        items = ctx._apply_where(
+            items, where, allowed_fields=COLLECTION_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/collections",
+            error=exc,
+        )
+    total_matched = len(items)
+    items = items[:applied_limit]
+    try:
+        items = ctx._project_collection_items(items, fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/collections",
+            error=exc,
+        )
+    truncated = (
+        applied_limit > 0 and total_matched > applied_limit
+        or (applied_limit == 0 and len(payload) >= fetch_limit)
+    )
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source="/api/collections",
+        items=items,
+        scanned=len(payload),
+        matched=total_matched,
+        returned=len(items),
+        total=len(payload),
+        total_matched=total_matched,
+        total_population=len(payload),
+        truncated=truncated,
+        complete=not truncated,
+        query=term,
+        owner=owner_clean,
+        owner_case_insensitive_fallback=owner_fallback_used,
+    )
+
+
+async def hf_collection_items(
+    ctx: HelperRuntimeContext,
+    collection_id: str,
+    repo_types: list[str] | None = None,
+    limit: int = 100,
+    count_only: bool = False,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    default_limit = ctx._policy_int("hf_collection_items", "default_limit", 100)
+    max_limit = ctx._policy_int(
+        "hf_collection_items", "max_limit", OUTPUT_ITEMS_TRUNCATION_LIMIT
+    )
+    cid = str(collection_id or "").strip()
+    if not cid:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/collections/<collection_id>",
+            error="collection_id is required",
+        )
+    if count_only:
+        limit = 0
+    applied_limit = ctx._clamp_int(
+        limit,
+        default=default_limit,
+        minimum=0,
+        maximum=max_limit,
+    )
+    allowed_repo_types: set[str] | None = None
+    try:
+        raw_repo_types = (
+            ctx._coerce_str_list(repo_types) if repo_types is not None else []
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/collections/{cid}",
+            error=exc,
+            collection_id=cid,
+        )
+    if raw_repo_types:
+        allowed_repo_types = set()
+        for raw in raw_repo_types:
+            canonical = ctx._canonical_repo_type(raw, default="")
+            if canonical not in {"model", "dataset", "space"}:
+                return ctx._helper_error(
+                    start_calls=start_calls,
+                    source=f"/api/collections/{cid}",
+                    error=f"Unsupported repo_type '{raw}'",
+                    collection_id=cid,
+                )
+            allowed_repo_types.add(canonical)
+    endpoint = f"/api/collections/{cid}"
+    resp = ctx._host_raw_call(endpoint)
+    if not resp.get("ok"):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=resp.get("error") or "collection fetch failed",
+            collection_id=cid,
+        )
+    payload = resp.get("data") if isinstance(resp.get("data"), dict) else {}
+    raw_items = payload.get("items") if isinstance(payload.get("items"), list) else []
+    owner = ctx._author_from_any(payload.get("owner"))
+    owner_payload = (
+        payload.get("owner") if isinstance(payload.get("owner"), dict) else {}
+    )
+    if owner is None and "/" in cid:
+        owner = cid.split("/", 1)[0]
+    try:
+        normalized_where = ctx._normalize_where(
+            where, allowed_fields=REPO_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+            collection_id=cid,
+        )
+    normalized: list[dict[str, Any]] = []
+    for row in raw_items:
+        if not isinstance(row, dict):
+            continue
+        item = ctx._normalize_collection_repo_item(row)
+        if item is None:
+            continue
+        repo_type = item.get("repo_type")
+        if allowed_repo_types is not None and repo_type not in allowed_repo_types:
+            continue
+        if not ctx._item_matches_where(item, normalized_where):
+            continue
+        normalized.append(item)
+    total_matched = len(normalized)
+    items = [] if count_only else normalized[:applied_limit]
+    try:
+        items = ctx._project_repo_items(items, fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+            collection_id=cid,
+        )
+    truncated = applied_limit > 0 and total_matched > applied_limit
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source=endpoint,
+        items=items,
+        scanned=len(raw_items),
+        matched=total_matched,
+        returned=len(items),
+        total=len(raw_items),
+        total_matched=total_matched,
+        total_population=len(raw_items),
+        truncated=truncated,
+        complete=not truncated,
+        collection_id=cid,
+        title=payload.get("title"),
+        owner=owner,
+        owner_type=owner_payload.get("type")
+        if isinstance(owner_payload.get("type"), str)
+        else None,
+        repo_types=sorted(allowed_repo_types)
+        if allowed_repo_types is not None
+        else None,
+    )
+
+
+def register_collection_helpers(
+    ctx: HelperRuntimeContext,
+) -> dict[str, Callable[..., Any]]:
+    return {
+        "hf_collections_search": partial(hf_collections_search, ctx),
+        "hf_collection_items": partial(hf_collection_items, ctx),
+    }

monty_api/helpers/common.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+
+from ..context_types import HelperRuntimeContext
+
+
+async def resolve_username_or_current(
+    ctx: HelperRuntimeContext,
+    username: str | None,
+) -> tuple[str | None, str | None]:
+    resolved = str(username or "").strip()
+    if resolved:
+        return resolved, None
+
+    whoami = await ctx.call_helper("hf_whoami")
+    if whoami.get("ok") is not True:
+        return (
+            None,
+            str(whoami.get("error") or "Could not resolve current authenticated user"),
+        )
+    item = ctx._helper_item(whoami)
+    current = item.get("username") if isinstance(item, dict) else None
+    if not isinstance(current, str) or not current.strip():
+        return (
+            None,
+            "username was not provided and current authenticated user could not be resolved",
+        )
+    return current.strip(), None

monty_api/helpers/introspection.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+# ruff: noqa: C901, PLR0912, PLR0913, PLR0915, PLR0917
+import inspect
+from functools import partial
+from typing import Any, Callable
+
+from ..helper_contracts import build_helper_contracts
+from ..constants import (
+    ACTIVITY_CANONICAL_FIELDS,
+    ACTOR_CANONICAL_FIELDS,
+    COLLECTION_CANONICAL_FIELDS,
+    DAILY_PAPER_CANONICAL_FIELDS,
+    DISCUSSION_CANONICAL_FIELDS,
+    DISCUSSION_DETAIL_CANONICAL_FIELDS,
+    DEFAULT_MAX_CALLS,
+    DEFAULT_TIMEOUT_SEC,
+    GRAPH_SCAN_LIMIT_CAP,
+    LIKES_SCAN_LIMIT_CAP,
+    MAX_CALLS_LIMIT,
+    OUTPUT_ITEMS_TRUNCATION_LIMIT,
+    PROFILE_CANONICAL_FIELDS,
+    RECENT_ACTIVITY_SCAN_MAX_PAGES,
+    REPO_CANONICAL_FIELDS,
+    TRENDING_ENDPOINT_MAX_LIMIT,
+    USER_CANONICAL_FIELDS,
+    USER_LIKES_CANONICAL_FIELDS,
+)
+from ..context_types import HelperRuntimeContext
+from ..registry import (
+    HELPER_COVERED_ENDPOINT_PATTERNS,
+    HELPER_DEFAULT_METADATA,
+    PAGINATION_POLICY,
+)
+
+
+def _render_annotation(annotation: Any) -> str:
+    if annotation is inspect.Signature.empty:
+        return "Any"
+    return str(annotation)
+
+
+def _render_default(default: Any) -> str | None:
+    if default is inspect.Signature.empty:
+        return None
+    return repr(default)
+
+
+def _signature_payload(fn: Callable[..., Any]) -> dict[str, Any]:
+    signature = inspect.signature(fn)
+    parameters: list[dict[str, Any]] = []
+    for parameter in signature.parameters.values():
+        item: dict[str, Any] = {
+            "name": parameter.name,
+            "kind": str(parameter.kind).replace("Parameter.", "").lower(),
+            "annotation": _render_annotation(parameter.annotation),
+            "required": parameter.default is inspect.Signature.empty,
+        }
+        default = _render_default(parameter.default)
+        if default is not None:
+            item["default"] = default
+        parameters.append(item)
+    return {
+        "parameters": parameters,
+        "returns": _render_annotation(signature.return_annotation),
+    }
+
+
+async def hf_runtime_capabilities(
+    ctx: HelperRuntimeContext,
+    section: str | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    ctx.internal_helper_used["used"] = True
+
+    helper_functions = {
+        **ctx.helper_registry,
+        "hf_runtime_capabilities": partial(hf_runtime_capabilities, ctx),
+    }
+    helper_payload = {
+        name: _signature_payload(fn) for name, fn in sorted(helper_functions.items())
+    }
+    helper_contracts = build_helper_contracts(helper_functions)
+    repo_type_helper_names = {
+        "dataset": "hf_datasets_search",
+        "model": "hf_models_search",
+        "space": "hf_spaces_search",
+    }
+
+    def _helper_contract(name: str) -> dict[str, Any]:
+        contract = helper_contracts.get(name)
+        return dict(contract) if isinstance(contract, dict) else {}
+
+    def _type_specific_params(name: str) -> list[str]:
+        params = _helper_contract(name).get("supported_params")
+        if not isinstance(params, list):
+            return []
+        common = {
+            "search",
+            "filter",
+            "author",
+            "sort",
+            "limit",
+            "expand",
+            "full",
+            "fields",
+            "post_filter",
+        }
+        return [param for param in params if param not in common]
+
+    manifest: dict[str, Any] = {
+        "overview": {
+            "helper_count": len(helper_functions),
+            "supports_current_user": True,
+            "helper_result_envelope": {
+                "ok": "bool",
+                "item": "dict | None",
+                "items": "list[dict]",
+                "meta": "dict",
+                "error": "str | None",
+            },
+            "raw_result_envelope": {
+                "result": "Any",
+                "meta": {
+                    "ok": "bool",
+                    "api_calls": "int",
+                    "elapsed_ms": "int",
+                    "limits_reached": "bool",
+                    "limit_summary": "list[dict]",
+                },
+            },
+        },
+        "helpers": helper_payload,
+        "helper_contracts": helper_contracts,
+        "fields": {
+            "profile": list(PROFILE_CANONICAL_FIELDS),
+            "repo": list(REPO_CANONICAL_FIELDS),
+            "user": list(USER_CANONICAL_FIELDS),
+            "actor": list(ACTOR_CANONICAL_FIELDS),
+            "user_likes": list(USER_LIKES_CANONICAL_FIELDS),
+            "activity": list(ACTIVITY_CANONICAL_FIELDS),
+            "collection": list(COLLECTION_CANONICAL_FIELDS),
+            "daily_paper": list(DAILY_PAPER_CANONICAL_FIELDS),
+            "discussion": list(DISCUSSION_CANONICAL_FIELDS),
+            "discussion_detail": list(DISCUSSION_DETAIL_CANONICAL_FIELDS),
+        },
+        "helper_defaults": {
+            helper_name: dict(sorted(metadata.items()))
+            for helper_name, metadata in sorted(HELPER_DEFAULT_METADATA.items())
+        },
+        "limits": {
+            "default_timeout_sec": DEFAULT_TIMEOUT_SEC,
+            "default_max_calls": DEFAULT_MAX_CALLS,
+            "max_calls_limit": MAX_CALLS_LIMIT,
+            "output_items_truncation_limit": OUTPUT_ITEMS_TRUNCATION_LIMIT,
+            "graph_scan_limit_cap": GRAPH_SCAN_LIMIT_CAP,
+            "likes_scan_limit_cap": LIKES_SCAN_LIMIT_CAP,
+            "recent_activity_scan_max_pages": RECENT_ACTIVITY_SCAN_MAX_PAGES,
+            "trending_endpoint_max_limit": TRENDING_ENDPOINT_MAX_LIMIT,
+            "pagination_policy": {
+                helper_name: dict(sorted(policy.items()))
+                for helper_name, policy in sorted(PAGINATION_POLICY.items())
+            },
+            "helper_covered_endpoint_patterns": [
+                {"pattern": pattern, "helper": helper_name}
+                for pattern, helper_name in HELPER_COVERED_ENDPOINT_PATTERNS
+            ],
+        },
+        "repo_search": {
+            "helper_selection": {
+                "preferred_rule": (
+                    "Prefer hf_models_search for model queries, hf_datasets_search for "
+                    "dataset queries, and hf_spaces_search for space queries. Use "
+                    "hf_repo_search only for intentionally cross-type search."
+                ),
+                "model": "hf_models_search",
+                "dataset": "hf_datasets_search",
+                "space": "hf_spaces_search",
+                "cross_type": "hf_repo_search",
+            },
+            "can_do": [
+                "search models",
+                "search datasets",
+                "search spaces",
+                "search across multiple repo types",
+                "project selected fields",
+                "apply local post-fetch row filtering",
+            ],
+            "parameter_contract": {
+                "search": {
+                    "meaning": "Upstream Hugging Face search text.",
+                },
+                "filter": {
+                    "meaning": (
+                        "Upstream Hugging Face filter/tag argument passed directly into "
+                        "the Hub client."
+                    ),
+                },
+                "post_filter": {
+                    "meaning": (
+                        "Local predicate applied after the rows are fetched and normalized."
+                    ),
+                    "recommended_shapes": [
+                        {"runtime_stage": "RUNNING"},
+                        {"runtime_stage": {"in": ["BUILD_ERROR", "RUNTIME_ERROR"]}},
+                        {"downloads": {"gte": 1000}},
+                        {"likes": {"lte": 5000}},
+                    ],
+                    "prefer_for": [
+                        "normalized returned fields such as runtime_stage",
+                        "downloads / likes thresholds after a broad search",
+                    ],
+                    "avoid_when": [
+                        "author is already a first-class helper argument",
+                        "pipeline_tag is already a first-class model-search argument",
+                        "dataset_name, language, task_ids, apps, models, or datasets already have first-class helper args",
+                    ],
+                },
+                "fields": {
+                    "meaning": "Select which normalized row fields are returned to the caller.",
+                    "canonical_only": True,
+                },
+            },
+            "repo_type_specific_helpers": {
+                repo_type: {
+                    "helper": helper_name,
+                    "supported_params": _helper_contract(helper_name).get(
+                        "supported_params"
+                    ),
+                    "type_specific_params": _type_specific_params(helper_name),
+                    "sort_values": _helper_contract(helper_name).get("sort_values"),
+                    "expand_values": _helper_contract(helper_name).get("expand_values"),
+                    "fields_contract": _helper_contract(helper_name).get(
+                        "fields_contract"
+                    ),
+                    "post_filter_contract": _helper_contract(helper_name).get(
+                        "post_filter_contract"
+                    ),
+                }
+                for repo_type, helper_name in sorted(repo_type_helper_names.items())
+            },
+            "generic_helper": {
+                "helper": "hf_repo_search",
+                "use_for": "Intentionally cross-type search only.",
+                "supports": _helper_contract("hf_repo_search").get("supported_params"),
+                "sort_values_by_repo_type": _helper_contract("hf_repo_search").get(
+                    "sort_values_by_repo_type"
+                ),
+                "fields_contract": _helper_contract("hf_repo_search").get(
+                    "fields_contract"
+                ),
+                "post_filter_contract": _helper_contract("hf_repo_search").get(
+                    "post_filter_contract"
+                ),
+                "does_not_support": [
+                    "repo-type-specific knobs such as pipeline_tag or dataset_name",
+                    "nested advanced routing",
+                ],
+            },
+            "space_runtime_contract": {
+                "returned_field": "runtime_stage",
+                "full_runtime_field": "runtime",
+                "preferred_filter_channel": "post_filter",
+                "note": (
+                    "Treat runtime_stage like any other returned field: use exact values "
+                    "or an 'in' list in post_filter."
+                ),
+                "common_values": ["BUILD_ERROR", "RUNTIME_ERROR", "RUNNING", "SLEEPING"],
+            },
+        },
+    }
+    allowed_sections = sorted(manifest)
+    requested = str(section or "").strip().lower()
+    if requested:
+        if requested not in manifest:
+            return ctx._helper_error(
+                start_calls=start_calls,
+                source="internal://runtime-capabilities",
+                error=f"Unsupported section {section!r}. Allowed sections: {allowed_sections}",
+                section=section,
+                allowed_sections=allowed_sections,
+            )
+        payload = {
+            "section": requested,
+            "content": manifest[requested],
+            "allowed_sections": allowed_sections,
+        }
+    else:
+        payload = {"allowed_sections": allowed_sections, **manifest}
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source="internal://runtime-capabilities",
+        items=[payload],
+        section=requested or None,
+    )
+
+
+def register_introspection_helpers(
+    ctx: HelperRuntimeContext,
+) -> dict[str, Callable[..., Any]]:
+    return {"hf_runtime_capabilities": partial(hf_runtime_capabilities, ctx)}

monty_api/helpers/profiles.py

@@ -0,0 +1,861 @@
+from __future__ import annotations
+
+# ruff: noqa: C901, PLR0912, PLR0913, PLR0915, PLR0917
+from itertools import islice
+import re
+from typing import Any, Callable
+from ..context_types import HelperRuntimeContext
+from ..constants import (
+    ACTOR_CANONICAL_FIELDS,
+    EXHAUSTIVE_HELPER_RETURN_HARD_CAP,
+    GRAPH_SCAN_LIMIT_CAP,
+    OUTPUT_ITEMS_TRUNCATION_LIMIT,
+    USER_SUMMARY_ACTIVITY_MAX_PAGES,
+    USER_SUMMARY_LIKES_SCAN_LIMIT,
+)
+
+
+from .common import resolve_username_or_current
+
+from functools import partial
+
+
+def _clean_social_handle(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    cleaned = value.strip()
+    if not cleaned:
+        return None
+    if re.match("^https?://", cleaned, flags=re.IGNORECASE):
+        return cleaned
+    return cleaned.lstrip("@")
+
+
+def _social_url(kind: str, value: Any) -> str | None:
+    cleaned = _clean_social_handle(value)
+    if cleaned is None:
+        return None
+    if re.match("^https?://", cleaned, flags=re.IGNORECASE):
+        return cleaned
+    if kind == "twitter":
+        return f"https://twitter.com/{cleaned}"
+    if kind == "github":
+        return f"https://github.com/{cleaned}"
+    if kind == "linkedin":
+        if cleaned.startswith(("in/", "company/")):
+            return f"https://www.linkedin.com/{cleaned}"
+        return f"https://www.linkedin.com/in/{cleaned}"
+    if kind == "bluesky":
+        return f"https://bsky.app/profile/{cleaned}"
+    return cleaned
+
+
+async def hf_whoami(ctx: HelperRuntimeContext) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    endpoint = "/api/whoami-v2"
+    token = ctx._load_token()
+    if token is None:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error="Current authenticated user is unavailable for this request. No request-scoped or fallback HF token was found.",
+        )
+    try:
+        payload = ctx._host_hf_call(
+            endpoint,
+            lambda: ctx._get_hf_api_client().whoami(token=token, cache=True),
+        )
+    except Exception as e:
+        return ctx._helper_error(start_calls=start_calls, source=endpoint, error=e)
+    username = payload.get("name") or payload.get("user") or payload.get("username")
+    item = {
+        "username": username,
+        "fullname": payload.get("fullname"),
+        "is_pro": payload.get("isPro"),
+    }
+    items = [item] if isinstance(username, str) and username else []
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source=endpoint,
+        items=items,
+        scanned=1,
+        matched=len(items),
+        returned=len(items),
+        truncated=False,
+    )
+
+
+async def _hf_user_overview(ctx: HelperRuntimeContext, username: str) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    u = str(username or "").strip()
+    if not u:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/users/<u>/overview",
+            error="username is required",
+        )
+    endpoint = f"/api/users/{u}/overview"
+    try:
+        obj = ctx._host_hf_call(
+            endpoint, lambda: ctx._get_hf_api_client().get_user_overview(u)
+        )
+    except Exception as e:
+        return ctx._helper_error(start_calls=start_calls, source=endpoint, error=e)
+    twitter = getattr(obj, "twitter", None) or getattr(obj, "twitterUsername", None)
+    github = getattr(obj, "github", None) or getattr(obj, "githubUsername", None)
+    linkedin = getattr(obj, "linkedin", None) or getattr(obj, "linkedinUsername", None)
+    bluesky = getattr(obj, "bluesky", None) or getattr(obj, "blueskyUsername", None)
+    if ctx._budget_remaining() > 0 and any(
+        (v in {None, ""} for v in [twitter, github, linkedin, bluesky])
+    ):
+        socials_ep = f"/api/users/{u}/socials"
+        socials_resp = ctx._host_raw_call(socials_ep)
+        if socials_resp.get("ok"):
+            socials_payload = (
+                socials_resp.get("data")
+                if isinstance(socials_resp.get("data"), dict)
+                else {}
+            )
+            handles = (
+                socials_payload.get("socialHandles")
+                if isinstance(socials_payload.get("socialHandles"), dict)
+                else {}
+            )
+            twitter = twitter or handles.get("twitter")
+            github = github or handles.get("github")
+            linkedin = linkedin or handles.get("linkedin")
+            bluesky = bluesky or handles.get("bluesky")
+    orgs_raw = getattr(obj, "orgs", None)
+    org_names: list[str] | None = None
+    if isinstance(orgs_raw, (list, tuple, set)):
+        names = []
+        for org in orgs_raw:
+            if isinstance(org, str) and org.strip():
+                names.append(org.strip())
+                continue
+            name = getattr(org, "name", None)
+            if isinstance(name, str) and name.strip():
+                names.append(name.strip())
+        org_names = names or None
+    twitter_handle = _clean_social_handle(twitter)
+    github_handle = _clean_social_handle(github)
+    linkedin_handle = _clean_social_handle(linkedin)
+    bluesky_handle = _clean_social_handle(bluesky)
+    item = {
+        "username": obj.username or u,
+        "fullname": obj.fullname,
+        "bio": getattr(obj, "details", None),
+        "avatar_url": obj.avatar_url,
+        "website_url": getattr(obj, "websiteUrl", None),
+        "twitter": _social_url("twitter", twitter_handle),
+        "github": _social_url("github", github_handle),
+        "linkedin": _social_url("linkedin", linkedin_handle),
+        "bluesky": _social_url("bluesky", bluesky_handle),
+        "twitter_handle": twitter_handle,
+        "github_handle": github_handle,
+        "linkedin_handle": linkedin_handle,
+        "bluesky_handle": bluesky_handle,
+        "followers": ctx._as_int(obj.num_followers),
+        "following": ctx._as_int(obj.num_following),
+        "likes": ctx._as_int(obj.num_likes),
+        "models": ctx._as_int(getattr(obj, "num_models", None)),
+        "datasets": ctx._as_int(getattr(obj, "num_datasets", None)),
+        "spaces": ctx._as_int(getattr(obj, "num_spaces", None)),
+        "discussions": ctx._as_int(getattr(obj, "num_discussions", None)),
+        "papers": ctx._as_int(getattr(obj, "num_papers", None)),
+        "upvotes": ctx._as_int(getattr(obj, "num_upvotes", None)),
+        "orgs": org_names,
+        "is_pro": obj.is_pro,
+    }
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source=endpoint,
+        items=[item],
+        scanned=1,
+        matched=1,
+        returned=1,
+        truncated=False,
+    )
+
+
+async def _hf_org_overview(
+    ctx: HelperRuntimeContext, organization: str
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    org = str(organization or "").strip()
+    if not org:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/organizations/<o>/overview",
+            error="organization is required",
+        )
+    endpoint = f"/api/organizations/{org}/overview"
+    try:
+        obj = ctx._host_hf_call(
+            endpoint,
+            lambda: ctx._get_hf_api_client().get_organization_overview(org),
+        )
+    except Exception as e:
+        return ctx._helper_error(start_calls=start_calls, source=endpoint, error=e)
+    item = {
+        "organization": obj.name or org,
+        "display_name": obj.fullname,
+        "avatar_url": obj.avatar_url,
+        "description": obj.details,
+        "website_url": getattr(obj, "websiteUrl", None),
+        "followers": ctx._as_int(obj.num_followers),
+        "members": ctx._as_int(obj.num_users),
+        "models": ctx._as_int(getattr(obj, "num_models", None)),
+        "datasets": ctx._as_int(getattr(obj, "num_datasets", None)),
+        "spaces": ctx._as_int(getattr(obj, "num_spaces", None)),
+    }
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source=endpoint,
+        items=[item],
+        scanned=1,
+        matched=1,
+        returned=1,
+        truncated=False,
+    )
+
+
+async def hf_org_members(
+    ctx: HelperRuntimeContext,
+    organization: str,
+    limit: int | None = None,
+    scan_limit: int | None = None,
+    count_only: bool = False,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    org = str(organization or "").strip()
+    if not org:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/organizations/<o>/members",
+            error="organization is required",
+        )
+    default_limit = ctx._policy_int("hf_org_members", "default_limit", 100)
+    scan_cap = ctx._policy_int("hf_org_members", "scan_max", GRAPH_SCAN_LIMIT_CAP)
+    limit_plan = ctx._resolve_exhaustive_limits(
+        limit=limit,
+        count_only=count_only,
+        default_limit=default_limit,
+        max_limit=EXHAUSTIVE_HELPER_RETURN_HARD_CAP,
+        scan_limit=scan_limit,
+        scan_cap=scan_cap,
+    )
+    applied_limit = int(limit_plan["applied_limit"])
+    scan_lim = int(limit_plan["applied_scan_limit"])
+    has_where = isinstance(where, dict) and bool(where)
+    overview_total: int | None = None
+    overview_source = f"/api/organizations/{org}/overview"
+    if ctx._budget_remaining() > 0:
+        try:
+            org_obj = ctx._host_hf_call(
+                overview_source,
+                lambda: ctx._get_hf_api_client().get_organization_overview(org),
+            )
+            overview_total = ctx._as_int(getattr(org_obj, "num_users", None))
+        except Exception:
+            overview_total = None
+    if count_only and (not has_where) and (overview_total is not None):
+        return ctx._overview_count_only_success(
+            start_calls=start_calls,
+            source=overview_source,
+            total=overview_total,
+            limit_plan=limit_plan,
+            base_meta={
+                "scanned": 1,
+                "count_source": "overview",
+                "organization": org,
+            },
+        )
+    endpoint = f"/api/organizations/{org}/members"
+    try:
+        rows = ctx._host_hf_call(
+            endpoint,
+            lambda: list(
+                islice(
+                    ctx._get_hf_api_client().list_organization_members(org),
+                    scan_lim,
+                )
+            ),
+        )
+    except Exception as e:
+        return ctx._helper_error(
+            start_calls=start_calls, source=endpoint, error=e, organization=org
+        )
+    normalized: list[dict[str, Any]] = []
+    for row in rows:
+        handle = getattr(row, "username", None)
+        if not isinstance(handle, str) or not handle:
+            continue
+        item = {
+            "username": handle,
+            "fullname": getattr(row, "fullname", None),
+            "is_pro": getattr(row, "is_pro", None),
+            "role": getattr(row, "role", None),
+        }
+        normalized.append(item)
+    try:
+        normalized = ctx._apply_where(
+            normalized, where, allowed_fields=ACTOR_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+            organization=org,
+        )
+    observed_total = len(rows)
+    scan_exhaustive = observed_total < scan_lim
+    overview_list_mismatch = (
+        overview_total is not None
+        and scan_exhaustive
+        and (observed_total != overview_total)
+    )
+    if has_where:
+        exact_count = scan_exhaustive
+        total = len(normalized)
+        total_matched = len(normalized)
+    elif overview_total is not None:
+        exact_count = True
+        total = overview_total
+        total_matched = overview_total
+    else:
+        exact_count = scan_exhaustive
+        total = observed_total
+        total_matched = observed_total
+    total_available = overview_total if overview_total is not None else observed_total
+    items = normalized[:applied_limit]
+    scan_limit_hit = not exact_count and observed_total >= scan_lim
+    count_source = (
+        "overview" if overview_total is not None and (not has_where) else "scan"
+    )
+    sample_complete = (
+        exact_count
+        and len(normalized) <= applied_limit
+        and (not count_only or len(normalized) == 0)
+    )
+    more_available = ctx._derive_more_available(
+        sample_complete=sample_complete,
+        exact_count=exact_count,
+        returned=len(items),
+        total=total,
+    )
+    if not exact_count and scan_limit_hit:
+        more_available = "unknown" if has_where else True
+    try:
+        items = ctx._project_actor_items(items, fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+            organization=org,
+        )
+    meta = ctx._build_exhaustive_result_meta(
+        base_meta={
+            "scanned": observed_total,
+            "total": total,
+            "total_available": total_available,
+            "total_matched": total_matched,
+            "count_source": count_source,
+            "lower_bound": bool(has_where and (not exact_count)),
+            "overview_total": overview_total,
+            "listed_total": observed_total,
+            "overview_list_mismatch": overview_list_mismatch,
+            "organization": org,
+        },
+        limit_plan=limit_plan,
+        matched_count=len(normalized),
+        returned_count=len(items),
+        exact_count=exact_count,
+        count_only=count_only,
+        sample_complete=sample_complete,
+        more_available=more_available,
+        scan_limit_hit=scan_limit_hit,
+    )
+    return ctx._helper_success(
+        start_calls=start_calls, source=endpoint, items=items, meta=meta
+    )
+
+
+async def _user_graph_helper(
+    ctx: HelperRuntimeContext,
+    kind: str,
+    username: str,
+    pro_only: bool | None,
+    limit: int | None,
+    scan_limit: int | None,
+    count_only: bool,
+    where: dict[str, Any] | None,
+    fields: list[str] | None,
+    *,
+    helper_name: str,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    default_limit = ctx._policy_int(helper_name, "default_limit", 100)
+    scan_cap = ctx._policy_int(helper_name, "scan_max", GRAPH_SCAN_LIMIT_CAP)
+    max_limit = ctx._policy_int(
+        helper_name, "max_limit", EXHAUSTIVE_HELPER_RETURN_HARD_CAP
+    )
+    u = str(username or "").strip()
+    if not u:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/<u>/{kind}",
+            error="username is required",
+        )
+    limit_plan = ctx._resolve_exhaustive_limits(
+        limit=limit,
+        count_only=count_only,
+        default_limit=default_limit,
+        max_limit=max_limit,
+        scan_limit=scan_limit,
+        scan_cap=scan_cap,
+    )
+    applied_limit = int(limit_plan["applied_limit"])
+    scan_lim = int(limit_plan["applied_scan_limit"])
+    has_where = isinstance(where, dict) and bool(where)
+    filtered = pro_only is not None or has_where
+    entity_type = "user"
+    overview_total: int | None = None
+    overview_source = f"/api/users/{u}/overview"
+    if ctx._budget_remaining() > 0:
+        try:
+            user_obj = ctx._host_hf_call(
+                overview_source,
+                lambda: ctx._get_hf_api_client().get_user_overview(u),
+            )
+            overview_total = ctx._as_int(
+                user_obj.num_followers
+                if kind == "followers"
+                else user_obj.num_following
+            )
+        except Exception:
+            org_overview_source = f"/api/organizations/{u}/overview"
+            try:
+                org_obj = ctx._host_hf_call(
+                    org_overview_source,
+                    lambda: ctx._get_hf_api_client().get_organization_overview(u),
+                )
+            except Exception:
+                overview_total = None
+            else:
+                entity_type = "organization"
+                overview_source = org_overview_source
+                if kind != "followers":
+                    return ctx._helper_error(
+                        start_calls=start_calls,
+                        source=f"/api/organizations/{u}/{kind}",
+                        error="organization graph only supports relation='followers'; organizations do not expose a following list",
+                        relation=kind,
+                        organization=u,
+                        entity=u,
+                        entity_type=entity_type,
+                    )
+                overview_total = ctx._as_int(getattr(org_obj, "num_followers", None))
+    if count_only and (not filtered) and (overview_total is not None):
+        return ctx._overview_count_only_success(
+            start_calls=start_calls,
+            source=overview_source,
+            total=overview_total,
+            limit_plan=limit_plan,
+            base_meta={
+                "scanned": 1,
+                "count_source": "overview",
+                "relation": kind,
+                "pro_only": pro_only,
+                "where_applied": has_where,
+                "entity": u,
+                "entity_type": entity_type,
+                "username": u,
+                "organization": u if entity_type == "organization" else None,
+            },
+        )
+    endpoint = f"/api/users/{u}/{kind}"
+    try:
+        if entity_type == "organization":
+            endpoint = f"/api/organizations/{u}/followers"
+            rows = ctx._host_hf_call(
+                endpoint,
+                lambda: list(
+                    islice(
+                        ctx._get_hf_api_client().list_organization_followers(u),
+                        scan_lim,
+                    )
+                ),
+            )
+        elif kind == "followers":
+            rows = ctx._host_hf_call(
+                endpoint,
+                lambda: list(
+                    islice(ctx._get_hf_api_client().list_user_followers(u), scan_lim)
+                ),
+            )
+        else:
+            rows = ctx._host_hf_call(
+                endpoint,
+                lambda: list(
+                    islice(ctx._get_hf_api_client().list_user_following(u), scan_lim)
+                ),
+            )
+    except Exception as e:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=e,
+            relation=kind,
+            username=u,
+            entity=u,
+            entity_type=entity_type,
+            organization=u if entity_type == "organization" else None,
+        )
+    normalized: list[dict[str, Any]] = []
+    for row in rows:
+        handle = getattr(row, "username", None)
+        if not isinstance(handle, str) or not handle:
+            continue
+        item = {
+            "username": handle,
+            "fullname": getattr(row, "fullname", None),
+            "is_pro": getattr(row, "is_pro", None),
+        }
+        if pro_only is True and item.get("is_pro") is not True:
+            continue
+        if pro_only is False and item.get("is_pro") is True:
+            continue
+        normalized.append(item)
+    try:
+        normalized = ctx._apply_where(
+            normalized, where, allowed_fields=ACTOR_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+            relation=kind,
+            username=u,
+            entity=u,
+            entity_type=entity_type,
+            organization=u if entity_type == "organization" else None,
+        )
+    observed_total = len(rows)
+    scan_exhaustive = observed_total < scan_lim
+    overview_list_mismatch = (
+        overview_total is not None
+        and scan_exhaustive
+        and (observed_total != overview_total)
+    )
+    if filtered:
+        exact_count = scan_exhaustive
+        total = len(normalized)
+        total_matched = len(normalized)
+    elif overview_total is not None:
+        exact_count = True
+        total = overview_total
+        total_matched = overview_total
+    else:
+        exact_count = scan_exhaustive
+        total = observed_total
+        total_matched = observed_total
+    total_available = overview_total if overview_total is not None else observed_total
+    items = normalized[:applied_limit]
+    scan_limit_hit = not exact_count and observed_total >= scan_lim
+    count_source = (
+        "overview" if overview_total is not None and (not filtered) else "scan"
+    )
+    sample_complete = (
+        exact_count
+        and len(normalized) <= applied_limit
+        and (not count_only or len(normalized) == 0)
+    )
+    more_available = ctx._derive_more_available(
+        sample_complete=sample_complete,
+        exact_count=exact_count,
+        returned=len(items),
+        total=total,
+    )
+    if not exact_count and scan_limit_hit:
+        more_available = "unknown" if filtered else True
+    try:
+        items = ctx._project_actor_items(items, fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+            relation=kind,
+            username=u,
+            entity=u,
+            entity_type=entity_type,
+            organization=u if entity_type == "organization" else None,
+        )
+    meta = ctx._build_exhaustive_result_meta(
+        base_meta={
+            "scanned": observed_total,
+            "total": total,
+            "total_available": total_available,
+            "total_matched": total_matched,
+            "count_source": count_source,
+            "lower_bound": bool(filtered and (not exact_count)),
+            "overview_total": overview_total,
+            "listed_total": observed_total,
+            "overview_list_mismatch": overview_list_mismatch,
+            "relation": kind,
+            "pro_only": pro_only,
+            "where_applied": has_where,
+            "entity": u,
+            "entity_type": entity_type,
+            "username": u,
+            "organization": u if entity_type == "organization" else None,
+        },
+        limit_plan=limit_plan,
+        matched_count=len(normalized),
+        returned_count=len(items),
+        exact_count=exact_count,
+        count_only=count_only,
+        sample_complete=sample_complete,
+        more_available=more_available,
+        scan_limit_hit=scan_limit_hit,
+    )
+    return ctx._helper_success(
+        start_calls=start_calls, source=endpoint, items=items, meta=meta
+    )
+
+
+async def hf_profile_summary(
+    ctx: HelperRuntimeContext,
+    handle: str | None = None,
+    include: list[str] | None = None,
+    likes_limit: int = 10,
+    activity_limit: int = 10,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    resolved_handle, resolve_error = await resolve_username_or_current(ctx, handle)
+    if resolve_error:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/users/<u>/overview",
+            error=resolve_error,
+        )
+    if not isinstance(resolved_handle, str):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/users/<u>/overview",
+            error="handle was not provided and current authenticated user could not be resolved",
+        )
+    try:
+        requested_sections = (
+            {part.lower() for part in ctx._coerce_str_list(include) if part.strip()}
+            if include is not None
+            else set()
+        )
+    except ValueError as e:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/{resolved_handle}/overview",
+            error=e,
+        )
+    invalid_sections = sorted(requested_sections - {"likes", "activity"})
+    if invalid_sections:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/{resolved_handle}/overview",
+            error=f"Unsupported include values: {invalid_sections}",
+        )
+    likes_lim = ctx._clamp_int(
+        likes_limit, default=10, minimum=0, maximum=OUTPUT_ITEMS_TRUNCATION_LIMIT
+    )
+    activity_lim = ctx._clamp_int(
+        activity_limit, default=10, minimum=0, maximum=OUTPUT_ITEMS_TRUNCATION_LIMIT
+    )
+    section_errors: dict[str, str] = {}
+    user_overview = await _hf_user_overview(ctx, resolved_handle)
+    if user_overview.get("ok") is True:
+        overview_item = ctx._helper_item(user_overview) or {"username": resolved_handle}
+        item: dict[str, Any] = {
+            "handle": str(overview_item.get("username") or resolved_handle),
+            "entity_type": "user",
+            "display_name": overview_item.get("fullname")
+            or str(overview_item.get("username") or resolved_handle),
+            "bio": overview_item.get("bio"),
+            "avatar_url": overview_item.get("avatar_url"),
+            "website_url": overview_item.get("website_url"),
+            "twitter_url": overview_item.get("twitter"),
+            "github_url": overview_item.get("github"),
+            "linkedin_url": overview_item.get("linkedin"),
+            "bluesky_url": overview_item.get("bluesky"),
+            "followers_count": ctx._overview_count(overview_item, "followers"),
+            "following_count": ctx._overview_count(overview_item, "following"),
+            "likes_count": ctx._overview_count(overview_item, "likes"),
+            "models_count": ctx._overview_count(overview_item, "models"),
+            "datasets_count": ctx._overview_count(overview_item, "datasets"),
+            "spaces_count": ctx._overview_count(overview_item, "spaces"),
+            "discussions_count": ctx._overview_count(overview_item, "discussions"),
+            "papers_count": ctx._overview_count(overview_item, "papers"),
+            "upvotes_count": ctx._overview_count(overview_item, "upvotes"),
+            "organizations": overview_item.get("orgs"),
+            "is_pro": overview_item.get("is_pro"),
+        }
+        if "likes" in requested_sections:
+            likes = await ctx.call_helper(
+                "hf_user_likes",
+                username=resolved_handle,
+                limit=likes_lim,
+                scan_limit=USER_SUMMARY_LIKES_SCAN_LIMIT,
+                count_only=likes_lim == 0,
+                sort="liked_at",
+                fields=[
+                    "liked_at",
+                    "repo_id",
+                    "repo_type",
+                    "repo_author",
+                    "repo_url",
+                ],
+            )
+            item["likes_sample"] = likes.get("items") if likes.get("ok") is True else []
+            if likes.get("ok") is not True:
+                section_errors["likes"] = str(
+                    likes.get("error") or "likes fetch failed"
+                )
+        if "activity" in requested_sections:
+            activity = await ctx.call_helper(
+                "hf_recent_activity",
+                feed_type="user",
+                entity=resolved_handle,
+                limit=activity_lim,
+                max_pages=USER_SUMMARY_ACTIVITY_MAX_PAGES,
+                count_only=activity_lim == 0,
+                fields=["timestamp", "event_type", "repo_type", "repo_id"],
+            )
+            item["activity_sample"] = (
+                activity.get("items") if activity.get("ok") is True else []
+            )
+            if activity.get("ok") is not True:
+                section_errors["activity"] = str(
+                    activity.get("error") or "activity fetch failed"
+                )
+        return ctx._helper_success(
+            start_calls=start_calls,
+            source=f"/api/users/{resolved_handle}/overview",
+            items=[item],
+            scanned=1,
+            matched=1,
+            returned=1,
+            truncated=False,
+            handle=resolved_handle,
+            entity_type="user",
+            include=sorted(requested_sections),
+            likes_limit=likes_lim,
+            activity_limit=activity_lim,
+            section_errors=section_errors or None,
+        )
+    org_overview = await _hf_org_overview(ctx, resolved_handle)
+    if org_overview.get("ok") is True:
+        overview_item = ctx._helper_item(org_overview) or {
+            "organization": resolved_handle
+        }
+        item = {
+            "handle": str(overview_item.get("organization") or resolved_handle),
+            "entity_type": "organization",
+            "display_name": overview_item.get("display_name")
+            or str(overview_item.get("organization") or resolved_handle),
+            "description": overview_item.get("description"),
+            "avatar_url": overview_item.get("avatar_url"),
+            "website_url": overview_item.get("website_url"),
+            "followers_count": ctx._overview_count(overview_item, "followers"),
+            "members_count": ctx._overview_count(overview_item, "members"),
+            "models_count": ctx._overview_count(overview_item, "models"),
+            "datasets_count": ctx._overview_count(overview_item, "datasets"),
+            "spaces_count": ctx._overview_count(overview_item, "spaces"),
+        }
+        return ctx._helper_success(
+            start_calls=start_calls,
+            source=f"/api/organizations/{resolved_handle}/overview",
+            items=[item],
+            scanned=1,
+            matched=1,
+            returned=1,
+            truncated=False,
+            handle=resolved_handle,
+            entity_type="organization",
+            include=[],
+            ignored_includes=sorted(requested_sections) or None,
+        )
+    error = (
+        user_overview.get("error")
+        or org_overview.get("error")
+        or "profile fetch failed"
+    )
+    return ctx._helper_error(
+        start_calls=start_calls,
+        source=f"/api/profiles/{resolved_handle}",
+        error=error,
+        handle=resolved_handle,
+    )
+
+
+async def hf_user_graph(
+    ctx: HelperRuntimeContext,
+    username: str | None = None,
+    relation: str = "followers",
+    limit: int | None = None,
+    scan_limit: int | None = None,
+    count_only: bool = False,
+    pro_only: bool | None = None,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    rel = str(relation or "").strip().lower() or "followers"
+    if rel not in {"followers", "following"}:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/users/<u>/followers",
+            error="relation must be 'followers' or 'following'",
+        )
+    resolved_username, resolve_error = await resolve_username_or_current(ctx, username)
+    if resolve_error:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/<u>/{rel}",
+            error=resolve_error,
+            relation=rel,
+        )
+    if not isinstance(resolved_username, str):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/<u>/{rel}",
+            error="username is required",
+            relation=rel,
+        )
+    return await _user_graph_helper(
+        ctx,
+        rel,
+        resolved_username,
+        pro_only,
+        limit,
+        scan_limit,
+        count_only,
+        where,
+        fields,
+        helper_name="hf_user_graph",
+    )
+
+
+def register_profile_helpers(
+    ctx: HelperRuntimeContext,
+) -> dict[str, Callable[..., Any]]:
+    return {
+        "hf_whoami": partial(hf_whoami, ctx),
+        "hf_org_members": partial(hf_org_members, ctx),
+        "hf_profile_summary": partial(hf_profile_summary, ctx),
+        "hf_user_graph": partial(hf_user_graph, ctx),
+    }

monty_api/helpers/repos.py

@@ -0,0 +1,1364 @@
+from __future__ import annotations
+
+# ruff: noqa: C901, PLR0912, PLR0913, PLR0915, PLR0917
+from itertools import islice
+from typing import TYPE_CHECKING, Any, Callable
+from ..context_types import HelperRuntimeContext
+from ..helper_contracts import repo_expand_alias_map
+from ..constants import (
+    ACTOR_CANONICAL_FIELDS,
+    DAILY_PAPER_CANONICAL_FIELDS,
+    EXHAUSTIVE_HELPER_RETURN_HARD_CAP,
+    LIKES_ENRICHMENT_MAX_REPOS,
+    LIKES_RANKING_WINDOW_DEFAULT,
+    LIKES_SCAN_LIMIT_CAP,
+    OUTPUT_ITEMS_TRUNCATION_LIMIT,
+    REPO_CANONICAL_FIELDS,
+    SELECTIVE_ENDPOINT_RETURN_HARD_CAP,
+    TRENDING_ENDPOINT_MAX_LIMIT,
+    USER_LIKES_CANONICAL_FIELDS,
+)
+from ..registry import (
+    REPO_SEARCH_DEFAULT_EXPAND,
+    REPO_SEARCH_EXTRA_ARGS,
+    TRENDING_DEFAULT_FIELDS,
+)
+
+
+from .common import resolve_username_or_current
+
+from functools import partial
+
+if TYPE_CHECKING:
+    from huggingface_hub import HfApi
+
+
+def _sanitize_repo_expand_values(
+    repo_type: str, raw_expand: Any
+) -> tuple[list[str] | None, list[str], str | None]:
+    if raw_expand is None:
+        return (None, [], None)
+    if isinstance(raw_expand, str):
+        requested_values = [raw_expand]
+    elif isinstance(raw_expand, (list, tuple, set)):
+        requested_values = list(raw_expand)
+    else:
+        return (None, [], "expand must be a string or a list of strings")
+
+    cleaned: list[str] = []
+    for value in requested_values:
+        value_str = str(value).strip()
+        if value_str and value_str not in cleaned:
+            cleaned.append(value_str)
+
+    alias_map = repo_expand_alias_map(repo_type)
+    dropped = [value for value in cleaned if value not in alias_map]
+    deduped_kept: list[str] = []
+    for value in cleaned:
+        resolved = alias_map.get(value)
+        if resolved is None or resolved in deduped_kept:
+            continue
+        deduped_kept.append(resolved)
+    return (deduped_kept or None, dropped, None)
+
+
+def _resolve_repo_search_types(
+    ctx: HelperRuntimeContext,
+    *,
+    repo_type: str | None,
+    repo_types: list[str] | None,
+    default_repo_type: str = "model",
+) -> tuple[list[str] | None, str | None]:
+    if repo_type is not None and repo_types is not None:
+        return (None, "Pass either repo_type or repo_types, not both")
+
+    if repo_types is None:
+        raw_type = str(repo_type or "").strip()
+        if not raw_type:
+            return ([default_repo_type], None)
+        canonical = ctx._canonical_repo_type(raw_type, default="")
+        if canonical not in {"model", "dataset", "space"}:
+            return (None, f"Unsupported repo_type '{repo_type}'")
+        return ([canonical], None)
+
+    raw_types = ctx._coerce_str_list(repo_types)
+    if not raw_types:
+        return (None, "repo_types must not be empty")
+
+    requested_repo_types: list[str] = []
+    for raw in raw_types:
+        canonical = ctx._canonical_repo_type(raw, default="")
+        if canonical not in {"model", "dataset", "space"}:
+            return (None, f"Unsupported repo_type '{raw}'")
+        if canonical not in requested_repo_types:
+            requested_repo_types.append(canonical)
+    return (requested_repo_types, None)
+
+
+def _clean_repo_search_text(value: str | None) -> str | None:
+    cleaned = str(value or "").strip()
+    return cleaned or None
+
+
+def _normalize_repo_search_filter(
+    ctx: HelperRuntimeContext, value: str | list[str] | None
+) -> tuple[list[str] | None, str | None]:
+    if value is None:
+        return (None, None)
+    try:
+        normalized = ctx._coerce_str_list(value)
+    except ValueError:
+        return (None, "filter must be a string or a list of strings")
+    return (normalized or None, None)
+
+
+def _build_repo_search_extra_args(
+    repo_type: str, **candidate_args: Any
+) -> tuple[dict[str, Any], list[str], str | None]:
+    normalized: dict[str, Any] = {}
+    for key, value in candidate_args.items():
+        if value is None:
+            continue
+        if key in {"card_data", "cardData"}:
+            if value:
+                normalized["cardData"] = True
+            continue
+        if key in {"num_params", "num_parameters"}:
+            normalized["num_parameters"] = value
+            continue
+        if key in {"fetch_config", "linked"}:
+            if value:
+                normalized[key] = True
+            continue
+        normalized[key] = value
+
+    allowed_extra = REPO_SEARCH_EXTRA_ARGS.get(repo_type, set())
+    unsupported = sorted(str(key) for key in normalized if str(key) not in allowed_extra)
+    if unsupported:
+        return (
+            {},
+            [],
+            f"Unsupported search args for repo_type='{repo_type}': {unsupported}. Allowed args: {sorted(allowed_extra)}",
+        )
+
+    dropped_expand: list[str] = []
+    if "expand" in normalized:
+        kept_expand, dropped_expand, expand_error = _sanitize_repo_expand_values(
+            repo_type, normalized.get("expand")
+        )
+        if expand_error:
+            return ({}, [], expand_error)
+        if kept_expand is None:
+            normalized.pop("expand", None)
+        else:
+            normalized["expand"] = kept_expand
+
+    if not any(
+        key in normalized for key in ("expand", "full", "cardData", "fetch_config")
+    ):
+        normalized["expand"] = list(REPO_SEARCH_DEFAULT_EXPAND[repo_type])
+
+    return (normalized, dropped_expand, None)
+
+
+def _normalize_user_likes_sort(sort: str | None) -> tuple[str | None, str | None]:
+    normalized = str(sort or "liked_at").strip() or "liked_at"
+    if normalized not in {"liked_at", "repo_likes", "repo_downloads"}:
+        return (None, "sort must be one of liked_at, repo_likes, repo_downloads")
+    return (normalized, None)
+
+
+async def _run_repo_search(
+    ctx: HelperRuntimeContext,
+    *,
+    helper_name: str,
+    requested_repo_types: list[str],
+    search: str | None,
+    filter: str | list[str] | None,
+    author: str | None,
+    sort: str | None,
+    limit: int,
+    fields: list[str] | None,
+    post_filter: dict[str, Any] | None,
+    extra_args_by_type: dict[str, dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    default_limit = ctx._policy_int(helper_name, "default_limit", 100)
+    max_limit = ctx._policy_int(
+        helper_name, "max_limit", SELECTIVE_ENDPOINT_RETURN_HARD_CAP
+    )
+    filter_list, filter_error = _normalize_repo_search_filter(ctx, filter)
+    if filter_error:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos",
+            error=filter_error,
+        )
+
+    term = _clean_repo_search_text(search)
+    author_clean = _clean_repo_search_text(author)
+    requested_limit = limit
+    applied_limit = ctx._clamp_int(
+        limit,
+        default=default_limit,
+        minimum=1,
+        maximum=max_limit,
+    )
+    limit_meta = ctx._derive_limit_metadata(
+        requested_limit=requested_limit,
+        applied_limit=applied_limit,
+        default_limit_used=limit == default_limit,
+    )
+    hard_cap_applied = bool(limit_meta.get("hard_cap_applied"))
+
+    sort_keys: dict[str, str | None] = {}
+    for repo_type in requested_repo_types:
+        sort_key, sort_error = ctx._normalize_repo_sort_key(repo_type, sort)
+        if sort_error:
+            return ctx._helper_error(
+                start_calls=start_calls,
+                source=f"/api/{repo_type}s",
+                error=sort_error,
+            )
+        sort_keys[repo_type] = sort_key
+
+    all_items: list[dict[str, Any]] = []
+    scanned = 0
+    source_endpoints: list[str] = []
+    limit_boundary_hit = False
+    ignored_expand: dict[str, list[str]] = {}
+    api = ctx._get_hf_api_client()
+
+    for repo_type in requested_repo_types:
+        endpoint = f"/api/{repo_type}s"
+        source_endpoints.append(endpoint)
+        raw_extra_args = dict((extra_args_by_type or {}).get(repo_type, {}))
+        extra_args, dropped_expand, extra_error = _build_repo_search_extra_args(
+            repo_type,
+            **raw_extra_args,
+        )
+        if extra_error:
+            return ctx._helper_error(
+                start_calls=start_calls,
+                source=endpoint,
+                error=extra_error,
+            )
+        if dropped_expand:
+            ignored_expand[repo_type] = dropped_expand
+        try:
+            payload = ctx._host_hf_call(
+                endpoint,
+                lambda repo_type=repo_type, extra_args=extra_args: ctx._repo_list_call(
+                    api,
+                    repo_type,
+                    search=term,
+                    author=author_clean,
+                    filter=filter_list,
+                    sort=sort_keys[repo_type],
+                    limit=applied_limit,
+                    **extra_args,
+                ),
+            )
+        except Exception as e:
+            return ctx._helper_error(start_calls=start_calls, source=endpoint, error=e)
+        scanned += len(payload)
+        if len(payload) >= applied_limit:
+            limit_boundary_hit = True
+        all_items.extend(
+            ctx._normalize_repo_search_row(row, repo_type)
+            for row in payload[:applied_limit]
+        )
+
+    try:
+        all_items = ctx._apply_where(
+            all_items, post_filter, allowed_fields=REPO_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos",
+            error=exc,
+        )
+    combined_sort_key = next(iter(sort_keys.values()), None)
+    all_items = ctx._sort_repo_rows(all_items, combined_sort_key)
+    matched = len(all_items)
+    try:
+        all_items = ctx._project_repo_items(all_items[:applied_limit], fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos",
+            error=exc,
+        )
+
+    more_available: bool | str = False
+    truncated = False
+    truncated_by = "none"
+    next_request_hint: str | None = None
+    if hard_cap_applied and scanned >= applied_limit:
+        truncated = True
+        truncated_by = "hard_cap"
+        more_available = "unknown"
+        next_request_hint = f"Increase limit above {applied_limit} to improve coverage"
+    elif limit_boundary_hit:
+        more_available = "unknown"
+        next_request_hint = (
+            f"Increase limit above {applied_limit} to check whether more rows exist"
+        )
+
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source=",".join(source_endpoints),
+        items=all_items,
+        helper=helper_name,
+        search=term,
+        repo_types=requested_repo_types,
+        filter=filter_list,
+        sort=combined_sort_key,
+        author=author_clean,
+        limit=applied_limit,
+        post_filter=post_filter if isinstance(post_filter, dict) and post_filter else None,
+        scanned=scanned,
+        matched=matched,
+        returned=len(all_items),
+        truncated=truncated,
+        truncated_by=truncated_by,
+        more_available=more_available,
+        limit_boundary_hit=limit_boundary_hit,
+        next_request_hint=next_request_hint,
+        ignored_expand=ignored_expand or None,
+        **limit_meta,
+    )
+
+
+async def hf_models_search(
+    ctx: HelperRuntimeContext,
+    search: str | None = None,
+    filter: str | list[str] | None = None,
+    author: str | None = None,
+    apps: str | list[str] | None = None,
+    gated: bool | None = None,
+    inference: str | None = None,
+    inference_provider: str | list[str] | None = None,
+    model_name: str | None = None,
+    trained_dataset: str | list[str] | None = None,
+    pipeline_tag: str | None = None,
+    num_params: str | None = None,
+    emissions_thresholds: tuple[float, float] | None = None,
+    sort: str | None = None,
+    limit: int = 100,
+    expand: list[str] | None = None,
+    full: bool | None = None,
+    card_data: bool = False,
+    fetch_config: bool = False,
+    fields: list[str] | None = None,
+    post_filter: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return await _run_repo_search(
+        ctx,
+        helper_name="hf_models_search",
+        requested_repo_types=["model"],
+        search=search,
+        filter=filter,
+        author=author,
+        sort=sort,
+        limit=limit,
+        fields=fields,
+        post_filter=post_filter,
+        extra_args_by_type={
+            "model": {
+                "apps": apps,
+                "gated": gated,
+                "inference": inference,
+                "inference_provider": inference_provider,
+                "model_name": model_name,
+                "trained_dataset": trained_dataset,
+                "pipeline_tag": pipeline_tag,
+                "num_params": num_params,
+                "emissions_thresholds": emissions_thresholds,
+                "expand": expand,
+                "full": full,
+                "card_data": card_data,
+                "fetch_config": fetch_config,
+            }
+        },
+    )
+
+
+async def hf_datasets_search(
+    ctx: HelperRuntimeContext,
+    search: str | None = None,
+    filter: str | list[str] | None = None,
+    author: str | None = None,
+    benchmark: str | bool | None = None,
+    dataset_name: str | None = None,
+    gated: bool | None = None,
+    language_creators: str | list[str] | None = None,
+    language: str | list[str] | None = None,
+    multilinguality: str | list[str] | None = None,
+    size_categories: str | list[str] | None = None,
+    task_categories: str | list[str] | None = None,
+    task_ids: str | list[str] | None = None,
+    sort: str | None = None,
+    limit: int = 100,
+    expand: list[str] | None = None,
+    full: bool | None = None,
+    fields: list[str] | None = None,
+    post_filter: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return await _run_repo_search(
+        ctx,
+        helper_name="hf_datasets_search",
+        requested_repo_types=["dataset"],
+        search=search,
+        filter=filter,
+        author=author,
+        sort=sort,
+        limit=limit,
+        fields=fields,
+        post_filter=post_filter,
+        extra_args_by_type={
+            "dataset": {
+                "benchmark": benchmark,
+                "dataset_name": dataset_name,
+                "gated": gated,
+                "language_creators": language_creators,
+                "language": language,
+                "multilinguality": multilinguality,
+                "size_categories": size_categories,
+                "task_categories": task_categories,
+                "task_ids": task_ids,
+                "expand": expand,
+                "full": full,
+            }
+        },
+    )
+
+
+async def hf_spaces_search(
+    ctx: HelperRuntimeContext,
+    search: str | None = None,
+    filter: str | list[str] | None = None,
+    author: str | None = None,
+    datasets: str | list[str] | None = None,
+    models: str | list[str] | None = None,
+    linked: bool = False,
+    sort: str | None = None,
+    limit: int = 100,
+    expand: list[str] | None = None,
+    full: bool | None = None,
+    fields: list[str] | None = None,
+    post_filter: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return await _run_repo_search(
+        ctx,
+        helper_name="hf_spaces_search",
+        requested_repo_types=["space"],
+        search=search,
+        filter=filter,
+        author=author,
+        sort=sort,
+        limit=limit,
+        fields=fields,
+        post_filter=post_filter,
+        extra_args_by_type={
+            "space": {
+                "datasets": datasets,
+                "models": models,
+                "linked": linked,
+                "expand": expand,
+                "full": full,
+            }
+        },
+    )
+
+
+async def hf_repo_search(
+    ctx: HelperRuntimeContext,
+    search: str | None = None,
+    repo_type: str | None = None,
+    repo_types: list[str] | None = None,
+    filter: str | list[str] | None = None,
+    author: str | None = None,
+    sort: str | None = None,
+    limit: int = 100,
+    fields: list[str] | None = None,
+    post_filter: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    requested_repo_types, type_error = _resolve_repo_search_types(
+        ctx,
+        repo_type=repo_type,
+        repo_types=repo_types,
+    )
+    if type_error:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos",
+            error=type_error,
+        )
+    if not requested_repo_types:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos",
+            error="repo_type or repo_types is required",
+        )
+    return await _run_repo_search(
+        ctx,
+        helper_name="hf_repo_search",
+        requested_repo_types=requested_repo_types,
+        search=search,
+        filter=filter,
+        author=author,
+        sort=sort,
+        limit=limit,
+        fields=fields,
+        post_filter=post_filter,
+    )
+
+
+async def hf_user_likes(
+    ctx: HelperRuntimeContext,
+    username: str | None = None,
+    repo_types: list[str] | None = None,
+    limit: int | None = None,
+    scan_limit: int | None = None,
+    count_only: bool = False,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+    sort: str | None = None,
+    ranking_window: int | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    default_limit = ctx._policy_int("hf_user_likes", "default_limit", 100)
+    scan_cap = ctx._policy_int("hf_user_likes", "scan_max", LIKES_SCAN_LIMIT_CAP)
+    ranking_default = ctx._policy_int(
+        "hf_user_likes", "ranking_default", LIKES_RANKING_WINDOW_DEFAULT
+    )
+    enrich_cap = ctx._policy_int(
+        "hf_user_likes", "enrich_max", LIKES_ENRICHMENT_MAX_REPOS
+    )
+    resolved_username, resolve_error = await resolve_username_or_current(ctx, username)
+    if resolve_error:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/users/<u>/likes",
+            error=resolve_error,
+        )
+    if not isinstance(resolved_username, str):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/users/<u>/likes",
+            error="username is required",
+        )
+    sort_key, sort_error = _normalize_user_likes_sort(sort)
+    if sort_error:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/{resolved_username}/likes",
+            error=sort_error,
+        )
+    if sort_key is None:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/{resolved_username}/likes",
+            error="sort must be one of liked_at, repo_likes, repo_downloads",
+        )
+    limit_plan = ctx._resolve_exhaustive_limits(
+        limit=limit,
+        count_only=count_only,
+        default_limit=default_limit,
+        max_limit=EXHAUSTIVE_HELPER_RETURN_HARD_CAP,
+        scan_limit=scan_limit,
+        scan_cap=scan_cap,
+    )
+    applied_limit = int(limit_plan["applied_limit"])
+    scan_lim = int(limit_plan["applied_scan_limit"])
+    try:
+        normalized_where = ctx._normalize_where(
+            where, allowed_fields=USER_LIKES_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/{resolved_username}/likes",
+            error=exc,
+        )
+    allowed_repo_types: set[str] | None = None
+    try:
+        raw_repo_types: list[str] = (
+            ctx._coerce_str_list(repo_types) if repo_types is not None else []
+        )
+    except ValueError as e:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/users/{resolved_username}/likes",
+            error=e,
+        )
+    if raw_repo_types:
+        allowed_repo_types = set()
+        for raw in raw_repo_types:
+            canonical = ctx._canonical_repo_type(raw, default="")
+            if canonical not in {"model", "dataset", "space"}:
+                return ctx._helper_error(
+                    start_calls=start_calls,
+                    source=f"/api/users/{resolved_username}/likes",
+                    error=f"Unsupported repo_type '{raw}'",
+                )
+            allowed_repo_types.add(canonical)
+    endpoint = f"/api/users/{resolved_username}/likes"
+    resp = ctx._host_raw_call(endpoint, params={"limit": scan_lim})
+    if not resp.get("ok"):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=resp.get("error") or "likes fetch failed",
+        )
+    payload = resp.get("data") if isinstance(resp.get("data"), list) else []
+    scanned_rows = payload[:scan_lim]
+    matched_rows: list[tuple[int, dict[str, Any]]] = []
+    for row in scanned_rows:
+        if not isinstance(row, dict):
+            continue
+        repo = row.get("repo") if isinstance(row.get("repo"), dict) else {}
+        repo_data = row.get("repoData") if isinstance(row.get("repoData"), dict) else {}
+        repo_id = repo_data.get("id") or repo_data.get("name") or repo.get("name")
+        if not isinstance(repo_id, str) or not repo_id:
+            continue
+        repo_type = ctx._canonical_repo_type(
+            repo_data.get("type") or repo.get("type"), default=""
+        )
+        if not repo_type:
+            repo_type = ctx._canonical_repo_type(repo.get("type"), default="model")
+        if allowed_repo_types is not None and repo_type not in allowed_repo_types:
+            continue
+        repo_author = repo_data.get("author")
+        if not isinstance(repo_author, str) and "/" in repo_id:
+            repo_author = repo_id.split("/", 1)[0]
+        item = {
+            "liked_at": row.get("likedAt") or row.get("createdAt"),
+            "repo_id": repo_id,
+            "repo_type": repo_type,
+            "repo_author": repo_author,
+            "repo_likes": ctx._as_int(repo_data.get("likes")),
+            "repo_downloads": ctx._as_int(repo_data.get("downloads")),
+            "repo_url": ctx._repo_web_url(repo_type, repo_id),
+        }
+        if not ctx._item_matches_where(item, normalized_where):
+            continue
+        matched_rows.append((len(matched_rows), item))
+    matched = len(matched_rows)
+    scan_exhaustive = len(payload) < scan_lim
+    exact_count = scan_exhaustive
+    total_matched = matched
+    total = total_matched
+    effective_ranking_window: int | None = None
+    ranking_window_hit = False
+    ranking_window_applied = False
+    ranking_next_request_hint: str | None = None
+    ranking_complete = sort_key == "liked_at" and exact_count
+    enriched = 0
+    selected_pairs: list[tuple[int, dict[str, Any]]]
+    if count_only:
+        selected_pairs = []
+        ranking_complete = False if matched > 0 else exact_count
+    elif sort_key == "liked_at":
+        selected_pairs = matched_rows[:applied_limit]
+    else:
+        metric = str(sort_key)
+        requested_window = (
+            ranking_window if ranking_window is not None else ranking_default
+        )
+        effective_ranking_window = ctx._clamp_int(
+            requested_window, default=ranking_default, minimum=1, maximum=enrich_cap
+        )
+        ranking_window_applied = (
+            ranking_window is not None
+            and effective_ranking_window != int(ranking_window)
+        )
+        shortlist_size = min(effective_ranking_window, matched, scan_lim)
+        ranking_window_hit = matched > shortlist_size
+        shortlist = matched_rows[:shortlist_size]
+        candidates = [
+            pair
+            for pair in shortlist
+            if pair[1].get(metric) is None
+            and isinstance(pair[1].get("repo_id"), str)
+            and (pair[1].get("repo_type") in {"model", "dataset", "space"})
+        ]
+        enrich_budget = min(len(candidates), ctx._budget_remaining(), shortlist_size)
+        for _, item in candidates[:enrich_budget]:
+            repo_type = str(item.get("repo_type"))
+            repo_id = str(item.get("repo_id"))
+            detail_endpoint = f"/api/{ctx._canonical_repo_type(repo_type)}s/{repo_id}"
+            try:
+                detail = ctx._host_hf_call(
+                    detail_endpoint,
+                    lambda rt=repo_type, rid=repo_id: ctx._repo_detail_call(
+                        ctx._get_hf_api_client(), rt, rid
+                    ),
+                )
+            except Exception:
+                continue
+            likes = ctx._as_int(getattr(detail, "likes", None))
+            downloads = ctx._as_int(getattr(detail, "downloads", None))
+            if likes is not None:
+                item["repo_likes"] = likes
+            if downloads is not None:
+                item["repo_downloads"] = downloads
+            enriched += 1
+
+        def _ranking_key(pair: tuple[int, dict[str, Any]]) -> tuple[int, int, int]:
+            idx, row = pair
+            metric_value = ctx._as_int(row.get(metric))
+            if metric_value is None:
+                return (1, 0, idx)
+            return (0, -metric_value, idx)
+
+        ranked_shortlist = sorted(shortlist, key=_ranking_key)
+        selected_pairs = ranked_shortlist[:applied_limit]
+        ranking_complete = (
+            exact_count
+            and shortlist_size >= matched
+            and (len(candidates) <= enrich_budget)
+        )
+        if not ranking_complete:
+            if ranking_window_hit:
+                if effective_ranking_window < enrich_cap:
+                    ranking_next_request_hint = (
+                        f"Increase ranking_window above {effective_ranking_window} "
+                        "for broader popularity reranking"
+                    )
+                else:
+                    ranking_next_request_hint = (
+                        f"Popularity reranking is capped at {effective_ranking_window} "
+                        "candidate repos per call"
+                    )
+            elif len(candidates) > enrich_budget:
+                ranking_next_request_hint = (
+                    f"Popularity reranking exhausted detail budget after {enrich_budget} "
+                    "repo enrichments"
+                )
+    try:
+        items = ctx._project_user_like_items([row for _, row in selected_pairs], fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+        )
+    popularity_present = sum(
+        (1 for _, row in selected_pairs if row.get("repo_likes") is not None)
+    )
+    sample_complete = (
+        exact_count
+        and applied_limit >= matched
+        and (sort_key == "liked_at" or ranking_complete)
+        and (not count_only or matched == 0)
+    )
+    scan_limit_hit = not scan_exhaustive and len(payload) >= scan_lim
+    more_available = ctx._derive_more_available(
+        sample_complete=sample_complete,
+        exact_count=exact_count,
+        returned=len(items),
+        total=total,
+    )
+    if scan_limit_hit:
+        more_available = "unknown" if allowed_repo_types is not None or where else True
+    meta = ctx._build_exhaustive_result_meta(
+        base_meta={
+            "scanned": len(scanned_rows),
+            "total": total,
+            "total_available": len(payload),
+            "total_matched": total_matched,
+            "count_source": "scan",
+            "lower_bound": not exact_count,
+            "enriched": enriched,
+            "popularity_present": popularity_present,
+            "sort_applied": sort_key,
+            "ranking_window": effective_ranking_window,
+            "requested_ranking_window": ranking_window,
+            "ranking_window_applied": ranking_window_applied,
+            "ranking_window_hit": ranking_window_hit,
+            "ranking_next_request_hint": ranking_next_request_hint,
+            "ranking_complete": ranking_complete,
+            "username": resolved_username,
+        },
+        limit_plan=limit_plan,
+        matched_count=matched,
+        returned_count=len(items),
+        exact_count=exact_count,
+        count_only=count_only,
+        sample_complete=sample_complete,
+        more_available=more_available,
+        scan_limit_hit=scan_limit_hit,
+        truncated_extra=sort_key != "liked_at" and (not ranking_complete),
+    )
+    return ctx._helper_success(
+        start_calls=start_calls, source=endpoint, items=items, meta=meta
+    )
+
+
+async def hf_repo_likers(
+    ctx: HelperRuntimeContext,
+    repo_id: str,
+    repo_type: str,
+    limit: int | None = None,
+    count_only: bool = False,
+    pro_only: bool | None = None,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    rid = str(repo_id or "").strip()
+    if not rid:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos/<repo>/likers",
+            error="repo_id is required",
+        )
+    rt = ctx._canonical_repo_type(repo_type, default="")
+    if rt not in {"model", "dataset", "space"}:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/repos/{rid}/likers",
+            error=f"Unsupported repo_type '{repo_type}'",
+            repo_id=rid,
+        )
+    default_limit = ctx._policy_int("hf_repo_likers", "default_limit", 1000)
+    requested_limit = limit
+    default_limit_used = requested_limit is None and (not count_only)
+    has_where = isinstance(where, dict) and bool(where)
+    endpoint = f"/api/{rt}s/{rid}/likers"
+    resp = ctx._host_raw_call(endpoint)
+    if not resp.get("ok"):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=resp.get("error") or "repo likers fetch failed",
+            repo_id=rid,
+            repo_type=rt,
+        )
+    payload = resp.get("data") if isinstance(resp.get("data"), list) else []
+    try:
+        normalized_where = ctx._normalize_where(
+            where, allowed_fields=ACTOR_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+            repo_id=rid,
+            repo_type=rt,
+        )
+    normalized: list[dict[str, Any]] = []
+    for row in payload:
+        if not isinstance(row, dict):
+            continue
+        username = row.get("user") or row.get("username")
+        if not isinstance(username, str) or not username:
+            continue
+        item = {
+            "username": username,
+            "fullname": row.get("fullname"),
+            "type": row.get("type")
+            if isinstance(row.get("type"), str) and row.get("type")
+            else "user",
+            "is_pro": row.get("isPro"),
+        }
+        if pro_only is True and item.get("is_pro") is not True:
+            continue
+        if pro_only is False and item.get("is_pro") is True:
+            continue
+        if not ctx._item_matches_where(item, normalized_where):
+            continue
+        normalized.append(item)
+    if count_only:
+        applied_limit = 0
+    elif requested_limit is None:
+        applied_limit = default_limit
+    else:
+        try:
+            applied_limit = max(0, int(requested_limit))
+        except Exception:
+            applied_limit = default_limit
+    limit_plan = {
+        "requested_limit": requested_limit,
+        "applied_limit": applied_limit,
+        "default_limit_used": default_limit_used,
+        "hard_cap_applied": False,
+    }
+    matched = len(normalized)
+    items = [] if count_only else normalized[:applied_limit]
+    limit_hit = applied_limit > 0 and matched > applied_limit
+    truncated_by = ctx._derive_truncated_by(
+        hard_cap=False, limit_hit=limit_hit
+    )
+    sample_complete = matched <= applied_limit and (not count_only or matched == 0)
+    truncated = truncated_by != "none"
+    more_available = ctx._derive_more_available(
+        sample_complete=sample_complete,
+        exact_count=True,
+        returned=len(items),
+        total=matched,
+    )
+    try:
+        items = ctx._project_actor_items(items, fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=endpoint,
+            error=exc,
+            repo_id=rid,
+            repo_type=rt,
+        )
+    meta = ctx._build_exhaustive_meta(
+        base_meta={
+            "scanned": len(payload),
+            "matched": matched,
+            "returned": len(items),
+            "total": matched,
+            "total_available": len(payload),
+            "total_matched": matched,
+            "truncated": truncated,
+            "count_source": "likers_list",
+            "lower_bound": False,
+            "repo_id": rid,
+            "repo_type": rt,
+            "pro_only": pro_only,
+            "where_applied": has_where,
+            "upstream_pagination": "none",
+        },
+        limit_plan=limit_plan,
+        sample_complete=sample_complete,
+        exact_count=True,
+        truncated_by=truncated_by,
+        more_available=more_available,
+    )
+    meta["hard_cap_applied"] = False
+    return ctx._helper_success(
+        start_calls=start_calls, source=endpoint, items=items, meta=meta
+    )
+
+
+async def hf_repo_discussions(
+    ctx: HelperRuntimeContext,
+    repo_type: str,
+    repo_id: str,
+    limit: int = 20,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    rt = ctx._canonical_repo_type(repo_type)
+    rid = str(repo_id or "").strip()
+    if "/" not in rid:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/.../discussions",
+            error="repo_id must be owner/name",
+        )
+    lim = ctx._clamp_int(
+        limit, default=20, minimum=1, maximum=SELECTIVE_ENDPOINT_RETURN_HARD_CAP
+    )
+    endpoint = f"/api/{rt}s/{rid}/discussions"
+    try:
+        discussions = ctx._host_hf_call(
+            endpoint,
+            lambda: list(
+                islice(
+                    ctx._get_hf_api_client().get_repo_discussions(
+                        repo_id=rid, repo_type=rt
+                    ),
+                    lim,
+                )
+            ),
+        )
+    except Exception as e:
+        return ctx._helper_error(start_calls=start_calls, source=endpoint, error=e)
+    items: list[dict[str, Any]] = []
+    for d in discussions:
+        num = ctx._as_int(getattr(d, "num", None))
+        items.append(
+            {
+                "num": num,
+                "repo_id": rid,
+                "repo_type": rt,
+                "title": getattr(d, "title", None),
+                "author": getattr(d, "author", None),
+                "created_at": str(getattr(d, "created_at", None))
+                if getattr(d, "created_at", None) is not None
+                else None,
+                "status": getattr(d, "status", None),
+                "url": getattr(d, "url", None),
+            }
+        )
+    try:
+        items = ctx._project_discussion_items(items, fields)
+    except ValueError as exc:
+        return ctx._helper_error(start_calls=start_calls, source=endpoint, error=exc)
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source=endpoint,
+        items=items,
+        scanned=len(items),
+        matched=len(items),
+        returned=len(items),
+        truncated=False,
+        total_count=None,
+    )
+
+
+async def hf_repo_discussion_details(
+    ctx: HelperRuntimeContext,
+    repo_type: str,
+    repo_id: str,
+    discussion_num: int,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    rt = ctx._canonical_repo_type(repo_type)
+    rid = str(repo_id or "").strip()
+    if "/" not in rid:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/.../discussions/<num>",
+            error="repo_id must be owner/name",
+        )
+    num = ctx._as_int(discussion_num)
+    if num is None:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source=f"/api/{rt}s/{rid}/discussions/<num>",
+            error="discussion_num must be an integer",
+        )
+    endpoint = f"/api/{rt}s/{rid}/discussions/{num}"
+    try:
+        detail = ctx._host_hf_call(
+            endpoint,
+            lambda: ctx._get_hf_api_client().get_discussion_details(
+                repo_id=rid, discussion_num=int(num), repo_type=rt
+            ),
+        )
+    except Exception as e:
+        return ctx._helper_error(start_calls=start_calls, source=endpoint, error=e)
+    comment_events: list[dict[str, Any]] = []
+    raw_events = getattr(detail, "events", None)
+    if isinstance(raw_events, list):
+        for event in raw_events:
+            if str(getattr(event, "type", "")).strip().lower() != "comment":
+                continue
+            comment_events.append(
+                {
+                    "author": getattr(event, "author", None),
+                    "created_at": ctx._dt_to_str(getattr(event, "created_at", None)),
+                    "text": getattr(event, "content", None),
+                    "rendered": getattr(event, "rendered", None),
+                }
+            )
+    latest_comment: dict[str, Any] | None = None
+    if comment_events:
+        latest_comment = max(
+            comment_events, key=lambda row: str(row.get("created_at") or "")
+        )
+    item: dict[str, Any] = {
+        "num": num,
+        "repo_id": rid,
+        "repo_type": rt,
+        "title": getattr(detail, "title", None),
+        "author": getattr(detail, "author", None),
+        "created_at": ctx._dt_to_str(getattr(detail, "created_at", None)),
+        "status": getattr(detail, "status", None),
+        "url": getattr(detail, "url", None),
+        "comment_count": len(comment_events),
+        "latest_comment_author": latest_comment.get("author")
+        if latest_comment
+        else None,
+        "latest_comment_created_at": latest_comment.get("created_at")
+        if latest_comment
+        else None,
+        "latest_comment_text": latest_comment.get("text") if latest_comment else None,
+        "latest_comment_html": latest_comment.get("rendered")
+        if latest_comment
+        else None,
+    }
+    try:
+        items = ctx._project_discussion_detail_items([item], fields)
+    except ValueError as exc:
+        return ctx._helper_error(start_calls=start_calls, source=endpoint, error=exc)
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source=endpoint,
+        items=items,
+        scanned=len(comment_events),
+        matched=1,
+        returned=len(items),
+        truncated=False,
+        total_comments=len(comment_events),
+    )
+
+
+def _resolve_repo_detail_row(
+    ctx: HelperRuntimeContext,
+    api: "HfApi",
+    repo_id: str,
+    attempt_types: list[str],
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    rid = str(repo_id or "").strip()
+    if "/" not in rid:
+        return (None, {"repo_id": rid, "error": "repo_id must be owner/name"})
+    resolved_type: str | None = None
+    detail: Any = None
+    last_endpoint = "/api/repos"
+    errors: list[str] = []
+    for rt in attempt_types:
+        endpoint = f"/api/{rt}s/{rid}"
+        last_endpoint = endpoint
+        try:
+            detail = ctx._host_hf_call(
+                endpoint, lambda rt=rt, rid=rid: ctx._repo_detail_call(api, rt, rid)
+            )
+            resolved_type = rt
+            break
+        except Exception as e:
+            errors.append(f"{rt}: {str(e)}")
+    if resolved_type is None or detail is None:
+        return (
+            None,
+            {
+                "repo_id": rid,
+                "error": "; ".join(errors[:3]) if errors else "repo lookup failed",
+                "attempted_repo_types": list(attempt_types),
+                "source": last_endpoint,
+            },
+        )
+    return (ctx._normalize_repo_detail_row(detail, resolved_type, rid), None)
+
+
+async def hf_repo_details(
+    ctx: HelperRuntimeContext,
+    repo_id: str | None = None,
+    repo_ids: list[str] | None = None,
+    repo_type: str = "auto",
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    if repo_id is not None and repo_ids is not None:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos",
+            error="Pass either repo_id or repo_ids, not both",
+        )
+    requested_ids = (
+        [str(repo_id).strip()]
+        if isinstance(repo_id, str) and str(repo_id).strip()
+        else []
+    )
+    if repo_ids is not None:
+        requested_ids = ctx._coerce_str_list(repo_ids)
+    if not requested_ids:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos",
+            error="repo_id or repo_ids is required",
+        )
+    raw_type = str(repo_type or "auto").strip().lower()
+    if raw_type in {"", "auto"}:
+        base_attempt_types = ["model", "dataset", "space"]
+    else:
+        canonical_type = ctx._canonical_repo_type(raw_type, default="")
+        if canonical_type not in {"model", "dataset", "space"}:
+            return ctx._helper_error(
+                start_calls=start_calls,
+                source="/api/repos",
+                error=f"Unsupported repo_type '{repo_type}'",
+            )
+        base_attempt_types = [canonical_type]
+    api = ctx._get_hf_api_client()
+    items: list[dict[str, Any]] = []
+    failures: list[dict[str, Any]] = []
+    for rid in requested_ids:
+        row, failure = _resolve_repo_detail_row(ctx, api, rid, base_attempt_types)
+        if row is None:
+            if failure is not None:
+                failures.append(failure)
+            continue
+        items.append(row)
+    if not items:
+        summary = failures[0]["error"] if failures else "repo lookup failed"
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/repos",
+            error=summary,
+            failures=failures,
+            repo_type=repo_type,
+        )
+    try:
+        items = ctx._project_repo_items(items, fields)
+    except ValueError as exc:
+        return ctx._helper_error(start_calls=start_calls, source="/api/repos", error=exc)
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source="/api/repos",
+        items=items,
+        repo_type=repo_type,
+        requested_repo_ids=requested_ids,
+        failures=failures or None,
+        matched=len(items),
+        returned=len(items),
+    )
+
+
+async def hf_trending(
+    ctx: HelperRuntimeContext,
+    repo_type: str = "model",
+    limit: int = 20,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    default_limit = ctx._policy_int("hf_trending", "default_limit", 20)
+    max_limit = ctx._policy_int(
+        "hf_trending", "max_limit", TRENDING_ENDPOINT_MAX_LIMIT
+    )
+    raw_type = str(repo_type or "model").strip().lower()
+    if raw_type == "all":
+        requested_type = "all"
+    else:
+        requested_type = ctx._canonical_repo_type(raw_type, default="")
+        if requested_type not in {"model", "dataset", "space"}:
+            return ctx._helper_error(
+                start_calls=start_calls,
+                source="/api/trending",
+                error=f"Unsupported repo_type '{repo_type}'",
+            )
+    lim = ctx._clamp_int(limit, default=default_limit, minimum=1, maximum=max_limit)
+    resp = ctx._host_raw_call(
+        "/api/trending", params={"type": requested_type, "limit": lim}
+    )
+    if not resp.get("ok"):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/trending",
+            error=resp.get("error") or "trending fetch failed",
+        )
+    payload = resp.get("data") if isinstance(resp.get("data"), dict) else {}
+    rows = (
+        payload.get("recentlyTrending")
+        if isinstance(payload.get("recentlyTrending"), list)
+        else []
+    )
+    items: list[dict[str, Any]] = []
+    default_row_type = requested_type if requested_type != "all" else "model"
+    for idx, row in enumerate(rows[:lim], start=1):
+        if not isinstance(row, dict):
+            continue
+        repo = row.get("repoData") if isinstance(row.get("repoData"), dict) else {}
+        items.append(ctx._normalize_trending_row(repo, default_row_type, rank=idx))
+    try:
+        items = ctx._apply_where(items, where, allowed_fields=TRENDING_DEFAULT_FIELDS)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/trending",
+            error=exc,
+        )
+    matched = len(items)
+    try:
+        items = ctx._project_items(
+            items[:lim],
+            fields,
+            allowed_fields=TRENDING_DEFAULT_FIELDS,
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/trending",
+            error=exc,
+        )
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source="/api/trending",
+        items=items,
+        repo_type=requested_type,
+        limit=lim,
+        scanned=len(rows),
+        matched=matched,
+        returned=len(items),
+        trending_score_available=any(
+            (item.get("trending_score") is not None for item in items)
+        ),
+        ordered_ranking=True,
+    )
+
+
+async def hf_daily_papers(
+    ctx: HelperRuntimeContext,
+    limit: int = 20,
+    where: dict[str, Any] | None = None,
+    fields: list[str] | None = None,
+) -> dict[str, Any]:
+    start_calls = ctx.call_count["n"]
+    default_limit = ctx._policy_int("hf_daily_papers", "default_limit", 20)
+    max_limit = ctx._policy_int(
+        "hf_daily_papers", "max_limit", OUTPUT_ITEMS_TRUNCATION_LIMIT
+    )
+    lim = ctx._clamp_int(limit, default=default_limit, minimum=1, maximum=max_limit)
+    resp = ctx._host_raw_call("/api/daily_papers", params={"limit": lim})
+    if not resp.get("ok"):
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/daily_papers",
+            error=resp.get("error") or "daily papers fetch failed",
+        )
+    payload = resp.get("data") if isinstance(resp.get("data"), list) else []
+    items: list[dict[str, Any]] = []
+    for idx, row in enumerate(payload[:lim], start=1):
+        if not isinstance(row, dict):
+            continue
+        items.append(ctx._normalize_daily_paper_row(row, rank=idx))
+    try:
+        items = ctx._apply_where(
+            items, where, allowed_fields=DAILY_PAPER_CANONICAL_FIELDS
+        )
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/daily_papers",
+            error=exc,
+        )
+    matched = len(items)
+    try:
+        items = ctx._project_daily_paper_items(items[:lim], fields)
+    except ValueError as exc:
+        return ctx._helper_error(
+            start_calls=start_calls,
+            source="/api/daily_papers",
+            error=exc,
+        )
+    return ctx._helper_success(
+        start_calls=start_calls,
+        source="/api/daily_papers",
+        items=items,
+        limit=lim,
+        scanned=len(payload),
+        matched=matched,
+        returned=len(items),
+        ordered_ranking=True,
+    )
+
+
+def register_repo_helpers(ctx: HelperRuntimeContext) -> dict[str, Callable[..., Any]]:
+    return {
+        "hf_models_search": partial(hf_models_search, ctx),
+        "hf_datasets_search": partial(hf_datasets_search, ctx),
+        "hf_spaces_search": partial(hf_spaces_search, ctx),
+        "hf_repo_search": partial(hf_repo_search, ctx),
+        "hf_user_likes": partial(hf_user_likes, ctx),
+        "hf_repo_likers": partial(hf_repo_likers, ctx),
+        "hf_repo_discussions": partial(hf_repo_discussions, ctx),
+        "hf_repo_discussion_details": partial(hf_repo_discussion_details, ctx),
+        "hf_repo_details": partial(hf_repo_details, ctx),
+        "hf_trending": partial(hf_trending, ctx),
+        "hf_daily_papers": partial(hf_daily_papers, ctx),
+    }

monty_api/http_runtime.py

@@ -0,0 +1,597 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import TYPE_CHECKING, Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .aliases import REPO_SORT_KEYS
+from .constants import (
+    DEFAULT_TIMEOUT_SEC,
+)
+from .registry import REPO_API_ADAPTERS, REPO_SEARCH_DEFAULT_EXPAND
+from .validation import _endpoint_allowed, _normalize_endpoint, _sanitize_params
+
+if TYPE_CHECKING:
+    from huggingface_hub import HfApi
+
+
+def _load_request_token() -> str | None:
+    try:
+        from fast_agent.mcp.auth.context import request_bearer_token  # type: ignore
+
+        token = request_bearer_token.get()
+        if token:
+            return token
+    except Exception:
+        pass
+    return None
+
+
+def _load_token() -> str | None:
+    token = _load_request_token()
+    if token:
+        return token
+    return os.getenv("HF_TOKEN") or None
+
+
+def _json_best_effort(raw: bytes) -> Any:
+    try:
+        return json.loads(raw)
+    except Exception:
+        return raw.decode("utf-8", errors="replace")
+
+
+def _clamp_int(value: Any, *, default: int, minimum: int, maximum: int) -> int:
+    try:
+        out = int(value)
+    except Exception:
+        out = default
+    return max(minimum, min(out, maximum))
+
+
+def _as_int(value: Any) -> int | None:
+    try:
+        return int(value)
+    except Exception:
+        return None
+
+
+def _canonical_repo_type(value: Any, *, default: str = "model") -> str:
+    raw = str(value or "").strip().lower()
+    aliases = {
+        "model": "model",
+        "models": "model",
+        "dataset": "dataset",
+        "datasets": "dataset",
+        "space": "space",
+        "spaces": "space",
+    }
+    return aliases.get(raw, default)
+
+
+def _normalize_repo_sort_key(
+    repo_type: str, sort_value: Any
+) -> tuple[str | None, str | None]:
+    raw = str(sort_value or "").strip()
+    if not raw:
+        return None, None
+
+    key = raw
+    if key not in {
+        "created_at",
+        "downloads",
+        "last_modified",
+        "likes",
+        "trending_score",
+    }:
+        return None, f"Invalid sort key '{raw}'"
+
+    rt = _canonical_repo_type(repo_type)
+    allowed = REPO_SORT_KEYS.get(rt, set())
+    if key not in allowed:
+        return (
+            None,
+            f"Invalid sort key '{raw}' for repo_type='{rt}'. Allowed: {', '.join(sorted(allowed))}",
+        )
+    return key, None
+
+
+def _repo_api_adapter(repo_type: str) -> Any:
+    rt = _canonical_repo_type(repo_type, default="")
+    adapter = REPO_API_ADAPTERS.get(rt)
+    if adapter is None:
+        raise ValueError(f"Unsupported repo_type '{repo_type}'")
+    return adapter
+
+
+def _repo_list_call(api: HfApi, repo_type: str, **kwargs: Any) -> list[Any]:
+    adapter = _repo_api_adapter(repo_type)
+    method = getattr(api, adapter.list_method_name)
+    return list(method(**kwargs))
+
+
+def _repo_detail_call(api: HfApi, repo_type: str, repo_id: str) -> Any:
+    adapter = _repo_api_adapter(repo_type)
+    method = getattr(api, adapter.detail_method_name)
+    if _canonical_repo_type(repo_type) == "space":
+        return method(repo_id, expand=list(REPO_SEARCH_DEFAULT_EXPAND["space"]))
+    return method(repo_id)
+
+
+def _coerce_str_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        raw = [value]
+    elif isinstance(value, (list, tuple, set)):
+        raw = list(value)
+    else:
+        raise ValueError("Expected a string or list of strings")
+    return [str(v).strip() for v in raw if str(v).strip()]
+
+
+def _optional_str_list(value: Any) -> list[str] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        out = [value.strip()] if value.strip() else []
+        return out or None
+    if isinstance(value, (list, tuple, set)):
+        out = [str(v).strip() for v in value if str(v).strip()]
+        return out or None
+    return None
+
+
+def _space_runtime_to_dict(value: Any) -> dict[str, Any] | None:
+    if value is None:
+        return None
+
+    if isinstance(value, dict):
+        raw = value
+        hardware = raw.get("hardware")
+        current_hardware = (
+            hardware.get("current") if isinstance(hardware, dict) else hardware
+        )
+        requested_hardware = (
+            hardware.get("requested")
+            if isinstance(hardware, dict)
+            else raw.get("requested_hardware") or raw.get("requestedHardware")
+        )
+        sleep_time = _as_int(
+            raw.get("gcTimeout")
+            if raw.get("gcTimeout") is not None
+            else raw.get("sleep_time") or raw.get("sleepTime")
+        )
+        out = {
+            "stage": raw.get("stage"),
+            "hardware": current_hardware,
+            "requested_hardware": requested_hardware,
+            "sleep_time": sleep_time,
+        }
+        return {key: val for key, val in out.items() if val is not None} or None
+
+    out = {
+        "stage": getattr(value, "stage", None),
+        "hardware": getattr(value, "hardware", None),
+        "requested_hardware": getattr(value, "requested_hardware", None),
+        "sleep_time": _as_int(getattr(value, "sleep_time", None)),
+    }
+    return {key: val for key, val in out.items() if val is not None} or None
+
+
+def _extract_num_params(num_params: Any = None, safetensors: Any = None) -> int | None:
+    direct = _as_int(num_params)
+    if direct is not None:
+        return direct
+
+    total = getattr(safetensors, "total", None)
+    if total is None and isinstance(safetensors, dict):
+        total = safetensors.get("total")
+    return _as_int(total)
+
+
+def _extract_num_params_from_object(row: Any) -> int | None:
+    raw_num_params = getattr(row, "num_params", None)
+    if raw_num_params is None:
+        raw_num_params = getattr(row, "numParameters", None)
+    if raw_num_params is None:
+        raw_num_params = getattr(row, "num_parameters", None)
+    return _extract_num_params(raw_num_params, getattr(row, "safetensors", None))
+
+
+def _extract_num_params_from_dict(row: dict[str, Any]) -> int | None:
+    raw_num_params = row.get("num_params")
+    if raw_num_params is None:
+        raw_num_params = row.get("numParameters")
+    if raw_num_params is None:
+        raw_num_params = row.get("num_parameters")
+    return _extract_num_params(raw_num_params, row.get("safetensors"))
+
+
+def _extract_author_names(value: Any) -> list[str] | None:
+    if not isinstance(value, (list, tuple)):
+        return None
+    names: list[str] = []
+    for item in value:
+        if isinstance(item, str) and item.strip():
+            names.append(item.strip())
+            continue
+        if isinstance(item, dict):
+            name = item.get("name")
+            if isinstance(name, str) and name.strip():
+                names.append(name.strip())
+            continue
+        name = getattr(item, "name", None)
+        if isinstance(name, str) and name.strip():
+            names.append(name.strip())
+    return names or None
+
+
+def _extract_profile_name(value: Any) -> str | None:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    if isinstance(value, dict):
+        for key in ("user", "name", "fullname", "handle"):
+            candidate = value.get(key)
+            if isinstance(candidate, str) and candidate.strip():
+                return candidate.strip()
+        return None
+    for attr in ("user", "name", "fullname", "handle"):
+        candidate = getattr(value, attr, None)
+        if isinstance(candidate, str) and candidate.strip():
+            return candidate.strip()
+    return None
+
+
+def _author_from_any(value: Any) -> str | None:
+    if isinstance(value, str) and value:
+        return value
+    if isinstance(value, dict):
+        for key in ("name", "username", "user", "login"):
+            candidate = value.get(key)
+            if isinstance(candidate, str) and candidate:
+                return candidate
+    return None
+
+
+def _dt_to_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    iso = getattr(value, "isoformat", None)
+    if callable(iso):
+        try:
+            return str(iso())
+        except Exception:
+            pass
+    return str(value)
+
+
+def _repo_web_url(repo_type: str, repo_id: str | None) -> str | None:
+    if not isinstance(repo_id, str) or not repo_id:
+        return None
+    base = os.getenv("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
+    rt = _canonical_repo_type(repo_type, default="")
+    if rt == "dataset":
+        return f"{base}/datasets/{repo_id}"
+    if rt == "space":
+        return f"{base}/spaces/{repo_id}"
+    return f"{base}/{repo_id}"
+
+
+def _build_repo_row(
+    *,
+    repo_id: Any,
+    repo_type: str,
+    author: Any = None,
+    likes: Any = None,
+    downloads: Any = None,
+    created_at: Any = None,
+    last_modified: Any = None,
+    pipeline_tag: Any = None,
+    num_params: Any = None,
+    private: Any = None,
+    trending_score: Any = None,
+    tags: Any = None,
+    sha: Any = None,
+    gated: Any = None,
+    library_name: Any = None,
+    description: Any = None,
+    paperswithcode_id: Any = None,
+    sdk: Any = None,
+    models: Any = None,
+    datasets: Any = None,
+    subdomain: Any = None,
+    runtime: Any = None,
+    runtime_stage: Any = None,
+) -> dict[str, Any]:
+    rt = _canonical_repo_type(repo_type)
+    author_value = author
+    if (
+        not isinstance(author_value, str)
+        and isinstance(repo_id, str)
+        and "/" in repo_id
+    ):
+        author_value = repo_id.split("/", 1)[0]
+
+    runtime_payload = _space_runtime_to_dict(runtime)
+    resolved_runtime_stage = (
+        runtime_stage
+        if runtime_stage is not None
+        else runtime_payload.get("stage")
+        if isinstance(runtime_payload, dict)
+        else None
+    )
+
+    return {
+        "id": repo_id,
+        "slug": repo_id,
+        "repo_id": repo_id,
+        "repo_type": rt,
+        "author": author_value,
+        "likes": _as_int(likes),
+        "downloads": _as_int(downloads),
+        "created_at": _dt_to_str(created_at),
+        "last_modified": _dt_to_str(last_modified),
+        "pipeline_tag": pipeline_tag,
+        "num_params": _as_int(num_params),
+        "private": private,
+        "trending_score": _as_int(trending_score)
+        if trending_score is not None
+        else None,
+        "repo_url": _repo_web_url(rt, repo_id if isinstance(repo_id, str) else None),
+        "tags": _optional_str_list(tags),
+        "sha": sha,
+        "gated": gated,
+        "library_name": library_name,
+        "description": description,
+        "paperswithcode_id": paperswithcode_id,
+        "sdk": sdk,
+        "models": _optional_str_list(models),
+        "datasets": _optional_str_list(datasets),
+        "subdomain": subdomain,
+        "runtime_stage": resolved_runtime_stage,
+        "runtime": runtime_payload,
+    }
+
+
+def _normalize_repo_search_row(row: Any, repo_type: str) -> dict[str, Any]:
+    return _build_repo_row(
+        repo_id=getattr(row, "id", None),
+        repo_type=repo_type,
+        author=getattr(row, "author", None),
+        likes=getattr(row, "likes", None),
+        downloads=getattr(row, "downloads", None),
+        created_at=getattr(row, "created_at", None),
+        last_modified=getattr(row, "last_modified", None),
+        pipeline_tag=getattr(row, "pipeline_tag", None),
+        num_params=_extract_num_params_from_object(row),
+        private=getattr(row, "private", None),
+        trending_score=getattr(row, "trending_score", None),
+        tags=getattr(row, "tags", None),
+        sha=getattr(row, "sha", None),
+        gated=getattr(row, "gated", None),
+        library_name=getattr(row, "library_name", None),
+        description=getattr(row, "description", None),
+        paperswithcode_id=getattr(row, "paperswithcode_id", None),
+        sdk=getattr(row, "sdk", None),
+        models=getattr(row, "models", None),
+        datasets=getattr(row, "datasets", None),
+        subdomain=getattr(row, "subdomain", None),
+        runtime=getattr(row, "runtime", None),
+    )
+
+
+def _normalize_repo_detail_row(
+    detail: Any, repo_type: str, repo_id: str
+) -> dict[str, Any]:
+    row = _normalize_repo_search_row(detail, repo_type)
+    resolved_repo_id = row.get("repo_id") or repo_id
+    row["id"] = row.get("id") or resolved_repo_id
+    row["slug"] = row.get("slug") or resolved_repo_id
+    row["repo_id"] = resolved_repo_id
+    row["repo_url"] = _repo_web_url(repo_type, resolved_repo_id)
+    return row
+
+
+def _normalize_trending_row(
+    repo: dict[str, Any], default_repo_type: str, rank: int | None = None
+) -> dict[str, Any]:
+    row = _build_repo_row(
+        repo_id=repo.get("id"),
+        repo_type=repo.get("type") or repo.get("repoType") or default_repo_type,
+        author=repo.get("author"),
+        likes=repo.get("likes"),
+        downloads=repo.get("downloads"),
+        created_at=repo.get("createdAt"),
+        last_modified=repo.get("lastModified"),
+        pipeline_tag=repo.get("pipeline_tag"),
+        num_params=_extract_num_params_from_dict(repo),
+        private=repo.get("private"),
+        trending_score=repo.get("trendingScore"),
+        tags=repo.get("tags"),
+        sha=repo.get("sha"),
+        gated=repo.get("gated"),
+        library_name=repo.get("library_name"),
+        description=repo.get("description"),
+        paperswithcode_id=repo.get("paperswithcode_id"),
+        sdk=repo.get("sdk"),
+        models=repo.get("models"),
+        datasets=repo.get("datasets"),
+        subdomain=repo.get("subdomain"),
+        runtime=repo.get("runtime"),
+        runtime_stage=repo.get("runtime_stage") or repo.get("runtimeStage"),
+    )
+    if rank is not None:
+        row["trending_rank"] = rank
+    return row
+
+
+def _normalize_daily_paper_row(
+    row: dict[str, Any], rank: int | None = None
+) -> dict[str, Any]:
+    paper = row.get("paper") if isinstance(row.get("paper"), dict) else {}
+    org = (
+        row.get("organization")
+        if isinstance(row.get("organization"), dict)
+        else paper.get("organization")
+    )
+    organization = None
+    if isinstance(org, dict):
+        organization = org.get("name") or org.get("fullname")
+
+    item = {
+        "paper_id": paper.get("id"),
+        "title": row.get("title") or paper.get("title"),
+        "summary": row.get("summary")
+        or paper.get("summary")
+        or paper.get("ai_summary"),
+        "published_at": row.get("publishedAt") or paper.get("publishedAt"),
+        "submitted_on_daily_at": paper.get("submittedOnDailyAt"),
+        "authors": _extract_author_names(paper.get("authors")),
+        "organization": organization,
+        "submitted_by": _extract_profile_name(
+            row.get("submittedBy") or paper.get("submittedOnDailyBy")
+        ),
+        "discussion_id": paper.get("discussionId"),
+        "upvotes": _as_int(paper.get("upvotes")),
+        "github_repo_url": paper.get("githubRepo"),
+        "github_stars": _as_int(paper.get("githubStars")),
+        "project_page_url": paper.get("projectPage"),
+        "num_comments": _as_int(row.get("numComments")),
+        "is_author_participating": row.get("isAuthorParticipating")
+        if isinstance(row.get("isAuthorParticipating"), bool)
+        else None,
+        "repo_id": row.get("repo_id") or paper.get("repo_id"),
+        "rank": rank,
+    }
+    return item
+
+
+def _normalize_collection_repo_item(row: dict[str, Any]) -> dict[str, Any] | None:
+    repo_id = row.get("id") or row.get("repoId") or row.get("repo_id")
+    if not isinstance(repo_id, str) or not repo_id:
+        return None
+
+    repo_type = _canonical_repo_type(
+        row.get("repoType") or row.get("repo_type") or row.get("type"), default=""
+    )
+    if repo_type not in {"model", "dataset", "space"}:
+        return None
+
+    return _build_repo_row(
+        repo_id=repo_id,
+        repo_type=repo_type,
+        author=row.get("author") or _author_from_any(row.get("authorData")),
+        likes=row.get("likes"),
+        downloads=row.get("downloads"),
+        created_at=row.get("createdAt") or row.get("created_at"),
+        last_modified=row.get("lastModified") or row.get("last_modified"),
+        pipeline_tag=row.get("pipeline_tag") or row.get("pipelineTag"),
+        num_params=_extract_num_params_from_dict(row),
+        private=row.get("private"),
+        tags=row.get("tags"),
+        gated=row.get("gated"),
+        library_name=row.get("library_name") or row.get("libraryName"),
+        description=row.get("description"),
+        paperswithcode_id=row.get("paperswithcode_id") or row.get("paperswithcodeId"),
+        sdk=row.get("sdk"),
+        models=row.get("models"),
+        datasets=row.get("datasets"),
+        subdomain=row.get("subdomain"),
+        runtime=row.get("runtime"),
+        runtime_stage=row.get("runtime_stage") or row.get("runtimeStage"),
+    )
+
+
+def _sort_repo_rows(
+    rows: list[dict[str, Any]], sort_key: str | None
+) -> list[dict[str, Any]]:
+    if not sort_key:
+        return rows
+
+    if sort_key in {"likes", "downloads", "trending_score"}:
+        return sorted(
+            rows, key=lambda row: _as_int(row.get(sort_key)) or -1, reverse=True
+        )
+
+    if sort_key in {"created_at", "last_modified"}:
+        return sorted(rows, key=lambda row: str(row.get(sort_key) or ""), reverse=True)
+
+    return rows
+
+
+def call_api_host(
+    endpoint: str,
+    *,
+    method: str = "GET",
+    params: dict[str, Any] | None = None,
+    json_body: dict[str, Any] | None = None,
+    timeout_sec: int = DEFAULT_TIMEOUT_SEC,
+    strict_mode: bool = False,
+) -> dict[str, Any]:
+    method_u = method.upper().strip()
+    if method_u not in {"GET", "POST"}:
+        raise ValueError("Only GET and POST are supported")
+
+    ep = _normalize_endpoint(endpoint)
+    if not _endpoint_allowed(ep, strict_mode):
+        raise ValueError(f"Endpoint not allowed: {ep}")
+
+    params = _sanitize_params(ep, params)
+    if ep == "/api/recent-activity":
+        feed_type = str((params or {}).get("feedType", "")).strip().lower()
+        if feed_type not in {"user", "org"}:
+            raise ValueError("/api/recent-activity requires feedType=user|org")
+        if not str((params or {}).get("entity", "")).strip():
+            raise ValueError("/api/recent-activity requires entity")
+
+    base = os.getenv("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
+    q = urlencode(params or {}, doseq=True)
+    url = f"{base}{ep}" + (f"?{q}" if q else "")
+
+    headers = {"Accept": "application/json"}
+    token = _load_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    data = None
+    if method_u == "POST":
+        headers["Content-Type"] = "application/json"
+        data = json.dumps(json_body or {}).encode("utf-8")
+
+    req = Request(url, method=method_u, headers=headers, data=data)
+    try:
+        with urlopen(req, timeout=timeout_sec) as res:
+            payload = _json_best_effort(res.read())
+            return {
+                "ok": True,
+                "status": int(res.status),
+                "url": url,
+                "data": payload,
+                "error": None,
+            }
+    except HTTPError as e:
+        payload = _json_best_effort(e.read())
+        err = (
+            payload
+            if isinstance(payload, str)
+            else json.dumps(payload, ensure_ascii=False)[:1000]
+        )
+        return {
+            "ok": False,
+            "status": int(e.code),
+            "url": url,
+            "data": payload,
+            "error": err,
+        }
+    except URLError as e:
+        return {
+            "ok": False,
+            "status": 0,
+            "url": url,
+            "data": None,
+            "error": f"Network error: {e}",
+        }

monty_api/llm_time_hook.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from fast_agent.constants import FAST_AGENT_TIMING
+from fast_agent.hooks import show_hook_message
+from fast_agent.mcp.helpers.content_helpers import get_text
+
+if TYPE_CHECKING:
+    from fast_agent.hooks import HookContext
+
+
+def _timing_payload(ctx: "HookContext") -> dict[str, object] | None:
+    channels = ctx.message.channels or {}
+    timing_blocks = channels.get(FAST_AGENT_TIMING, [])
+    if not timing_blocks:
+        return None
+
+    payload_text = get_text(timing_blocks[0])
+    if not payload_text:
+        return None
+
+    try:
+        payload = json.loads(payload_text)
+    except json.JSONDecodeError:
+        return None
+
+    return payload if isinstance(payload, dict) else None
+
+
+def _coerce_float(value: object) -> float | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int | float):
+        return float(value)
+    return None
+
+
+def _format_duration_ms(duration_ms: float) -> str:
+    if duration_ms >= 1000:
+        return f"{duration_ms / 1000:.2f}s"
+    return f"{duration_ms:.0f}ms"
+
+
+async def display_llm_time(ctx: "HookContext") -> None:
+    payload = _timing_payload(ctx)
+    if payload is None:
+        return
+
+    duration_ms = _coerce_float(payload.get("duration_ms"))
+    if duration_ms is None:
+        return
+
+    show_hook_message(
+        ctx,
+        _format_duration_ms(duration_ms),
+        hook_name="llm_time",
+        hook_kind="tool",
+    )

monty_api/query_entrypoints.py

@@ -0,0 +1,434 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import inspect
+import json
+import os
+import sys
+import time
+from typing import Any, Callable
+
+from .constants import (
+    DEFAULT_MAX_CALLS,
+    DEFAULT_MONTY_MAX_ALLOCATIONS,
+    DEFAULT_MONTY_MAX_MEMORY,
+    DEFAULT_MONTY_MAX_RECURSION_DEPTH,
+    DEFAULT_TIMEOUT_SEC,
+    INTERNAL_STRICT_MODE,
+    MAX_CALLS_LIMIT,
+)
+from .runtime_context import build_runtime_helper_environment
+from .validation import (
+    _coerce_jsonish_python_literals,
+    _compact_result_metadata,
+    _summarize_limit_hit,
+    _truncate_result_payload,
+    _validate_generated_code,
+    _wrap_raw_result,
+)
+
+
+class MontyExecutionError(RuntimeError):
+    def __init__(self, message: str, api_calls: int, trace: list[dict[str, Any]]):
+        super().__init__(message)
+        self.api_calls = api_calls
+        self.trace = trace
+
+
+def _query_debug_enabled() -> bool:
+    value = os.environ.get("MONTY_DEBUG_QUERY", "")
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _execution_debug_enabled() -> bool:
+    value = os.environ.get("MONTY_DEBUG_EXECUTION", "")
+    if value.strip().lower() in {"1", "true", "yes", "on"}:
+        return True
+    return _query_debug_enabled()
+
+
+def _debug_log(*parts: Any) -> None:
+    if not _execution_debug_enabled():
+        return
+    print("[monty-debug]", *parts, file=sys.stderr)
+    sys.stderr.flush()
+
+
+def _log_generated_query(
+    *, query: str | None, code: str, max_calls: int | None, timeout_sec: int | None
+) -> None:
+    if not _query_debug_enabled():
+        return
+    if query:
+        print("[monty-debug] query:", file=sys.stderr)
+        print(query, file=sys.stderr)
+    print("[monty-debug] max_calls:", max_calls, file=sys.stderr)
+    print("[monty-debug] timeout_sec:", timeout_sec, file=sys.stderr)
+    print("[monty-debug] code:", file=sys.stderr)
+    print(code, file=sys.stderr)
+    sys.stderr.flush()
+
+
+def _introspect_helper_signatures() -> dict[str, set[str]]:
+    env = build_runtime_helper_environment(
+        max_calls=DEFAULT_MAX_CALLS,
+        strict_mode=INTERNAL_STRICT_MODE,
+        timeout_sec=DEFAULT_TIMEOUT_SEC,
+    )
+    signatures = {
+        name: {
+            parameter.name for parameter in inspect.signature(fn).parameters.values()
+        }
+        for name, fn in env.helper_functions.items()
+    }
+    return signatures
+
+
+async def _run_with_monty(
+    *,
+    code: str,
+    query: str | None,
+    max_calls: int,
+    strict_mode: bool,
+    timeout_sec: int,
+) -> dict[str, Any]:
+    _debug_log(
+        "run_monty:start",
+        f"max_calls={max_calls}",
+        f"timeout_sec={timeout_sec}",
+        f"strict_mode={strict_mode}",
+    )
+    try:
+        import pydantic_monty
+    except Exception as e:
+        raise RuntimeError(
+            "pydantic_monty is not installed. Install with `uv pip install pydantic-monty`."
+        ) from e
+
+    env = build_runtime_helper_environment(
+        max_calls=max_calls,
+        strict_mode=strict_mode,
+        timeout_sec=timeout_sec,
+    )
+
+    m = pydantic_monty.Monty(
+        code,
+        inputs=["query", "max_calls"],
+        script_name="monty_agent.py",
+        type_check=False,
+    )
+
+    def _collecting_wrapper(
+        helper_name: str, fn: Callable[..., Any]
+    ) -> Callable[..., Any]:
+        async def wrapped(*args: Any, **kwargs: Any) -> Any:
+            started = time.perf_counter()
+            _debug_log(
+                "helper:start",
+                helper_name,
+                f"args={len(args)}",
+                f"kwargs={sorted(kwargs)}",
+            )
+            result = await fn(*args, **kwargs)
+            summary = _summarize_limit_hit(helper_name, result)
+            if summary is not None and len(env.limit_summaries) < 20:
+                env.limit_summaries.append(summary)
+            elapsed_ms = round((time.perf_counter() - started) * 1000, 2)
+            _debug_log(
+                "helper:end",
+                helper_name,
+                f"elapsed_ms={elapsed_ms}",
+                f"api_calls={env.call_count['n']}",
+            )
+            return result
+
+        return wrapped
+
+    limits: pydantic_monty.ResourceLimits = {
+        "max_duration_secs": float(timeout_sec),
+        "max_memory": DEFAULT_MONTY_MAX_MEMORY,
+        "max_allocations": DEFAULT_MONTY_MAX_ALLOCATIONS,
+        "max_recursion_depth": DEFAULT_MONTY_MAX_RECURSION_DEPTH,
+    }
+
+    try:
+        _debug_log("run_monty:invoke")
+        result = await pydantic_monty.run_monty_async(
+            m,
+            inputs={"query": query or "", "max_calls": max_calls},
+            external_functions={
+                name: _collecting_wrapper(name, fn)
+                for name, fn in env.helper_functions.items()
+            },
+            limits=limits,
+        )
+        _debug_log("run_monty:return", f"api_calls={env.call_count['n']}")
+    except Exception as e:
+        _debug_log("run_monty:error", type(e).__name__, str(e))
+        raise MontyExecutionError(str(e), env.call_count["n"], env.trace) from e
+
+    if env.call_count["n"] == 0:
+        if env.internal_helper_used["used"]:
+            return {
+                "output": _truncate_result_payload(result),
+                "api_calls": env.call_count["n"],
+                "trace": env.trace,
+                "limit_summaries": env.limit_summaries,
+            }
+        if isinstance(result, dict) and result.get("ok") is True:
+            meta = result.get("meta") if isinstance(result.get("meta"), dict) else {}
+            source = meta.get("source")
+            if isinstance(source, str) and source.startswith("internal://"):
+                return {
+                    "output": _truncate_result_payload(result),
+                    "api_calls": env.call_count["n"],
+                    "trace": env.trace,
+                    "limit_summaries": env.limit_summaries,
+                }
+        latest_helper_error = env.latest_helper_error_box.get("value")
+        if latest_helper_error is not None:
+            return {
+                "output": _truncate_result_payload(latest_helper_error),
+                "api_calls": env.call_count["n"],
+                "trace": env.trace,
+                "limit_summaries": env.limit_summaries,
+            }
+        if (
+            isinstance(result, dict)
+            and result.get("ok") is False
+            and isinstance(result.get("error"), str)
+        ):
+            return {
+                "output": _truncate_result_payload(result),
+                "api_calls": env.call_count["n"],
+                "trace": env.trace,
+                "limit_summaries": env.limit_summaries,
+            }
+        raise MontyExecutionError(
+            "Code completed without calling any external API function",
+            env.call_count["n"],
+            env.trace,
+        )
+
+    if not any(step.get("ok") is True for step in env.trace):
+        if (
+            isinstance(result, dict)
+            and result.get("ok") is False
+            and isinstance(result.get("error"), str)
+        ):
+            return {
+                "output": _truncate_result_payload(result),
+                "api_calls": env.call_count["n"],
+                "trace": env.trace,
+                "limit_summaries": env.limit_summaries,
+            }
+        raise MontyExecutionError(
+            "Code completed without a successful API call; refusing non-live fallback result",
+            env.call_count["n"],
+            env.trace,
+        )
+
+    return {
+        "output": _truncate_result_payload(result),
+        "api_calls": env.call_count["n"],
+        "trace": env.trace,
+        "limit_summaries": env.limit_summaries,
+    }
+
+
+def _prepare_query_inputs(
+    *,
+    query: str | None,
+    code: str,
+    max_calls: int | None,
+    timeout_sec: int | None,
+) -> tuple[str, str, int, int]:
+    if not code or not code.strip():
+        raise ValueError("code is required")
+
+    normalized_query = str(query or "").strip()
+    resolved_max_calls = DEFAULT_MAX_CALLS if max_calls is None else max_calls
+    resolved_timeout_sec = DEFAULT_TIMEOUT_SEC if timeout_sec is None else timeout_sec
+    normalized_max_calls = max(1, min(int(resolved_max_calls), MAX_CALLS_LIMIT))
+    normalized_timeout_sec = int(resolved_timeout_sec)
+    normalized_code = _coerce_jsonish_python_literals(code.strip())
+    _validate_generated_code(normalized_code)
+    return normalized_query, normalized_code, normalized_max_calls, normalized_timeout_sec
+
+
+async def _execute_query(
+    *,
+    query: str | None,
+    code: str,
+    max_calls: int | None,
+    timeout_sec: int | None,
+) -> dict[str, Any]:
+    _debug_log("execute_query:start")
+    prepared_query, prepared_code, prepared_max_calls, prepared_timeout = (
+        _prepare_query_inputs(
+            query=query,
+            code=code,
+            max_calls=max_calls,
+            timeout_sec=timeout_sec,
+        )
+    )
+    _debug_log(
+        "execute_query:prepared",
+        f"query_len={len(prepared_query)}",
+        f"code_len={len(prepared_code)}",
+        f"max_calls={prepared_max_calls}",
+        f"timeout_sec={prepared_timeout}",
+    )
+    _log_generated_query(
+        query=prepared_query,
+        code=prepared_code,
+        max_calls=prepared_max_calls,
+        timeout_sec=prepared_timeout,
+    )
+    return await _run_with_monty(
+        code=prepared_code,
+        query=prepared_query,
+        max_calls=prepared_max_calls,
+        strict_mode=INTERNAL_STRICT_MODE,
+        timeout_sec=prepared_timeout,
+    )
+
+
+async def hf_hub_query(
+    code: str,
+    query: str | None = None,
+    max_calls: int | None = DEFAULT_MAX_CALLS,
+    timeout_sec: int | None = DEFAULT_TIMEOUT_SEC,
+) -> dict[str, Any]:
+    """Use natural-language queries to explore the Hugging Face Hub.
+
+    Best for read-only Hub discovery, lookup, ranking, and relationship questions
+    across users, organizations, repositories, activity, followers, likes,
+    discussions, and collections.
+    """
+    try:
+        run = await _execute_query(
+            query=query,
+            code=code,
+            max_calls=max_calls,
+            timeout_sec=timeout_sec,
+        )
+        return {
+            "ok": True,
+            "data": _compact_result_metadata(run["output"]),
+            "error": None,
+            "api_calls": run["api_calls"],
+        }
+    except MontyExecutionError as e:
+        return {
+            "ok": False,
+            "data": None,
+            "error": str(e),
+            "api_calls": e.api_calls,
+        }
+    except Exception as e:
+        return {
+            "ok": False,
+            "data": None,
+            "error": str(e),
+            "api_calls": 0,
+        }
+
+
+async def hf_hub_query_raw(
+    code: str,
+    query: str | None = None,
+    max_calls: int | None = DEFAULT_MAX_CALLS,
+    timeout_sec: int | None = DEFAULT_TIMEOUT_SEC,
+) -> Any:
+    """Use natural-language queries to explore the Hugging Face Hub in raw mode.
+
+    Best for read-only Hub discovery, lookup, ranking, and relationship
+    questions when the caller wants a runtime-owned raw envelope:
+    ``result`` contains the generated script's final `result` value and ``meta`` contains
+    execution details such as timing, call counts, and limit summaries.
+    """
+    started = time.perf_counter()
+    try:
+        run = await _execute_query(
+            query=query,
+            code=code,
+            max_calls=max_calls,
+            timeout_sec=timeout_sec,
+        )
+        elapsed_ms = int((time.perf_counter() - started) * 1000)
+        return _wrap_raw_result(
+            _compact_result_metadata(run["output"]),
+            ok=True,
+            api_calls=run["api_calls"],
+            elapsed_ms=elapsed_ms,
+            limit_summaries=run.get("limit_summaries"),
+        )
+    except MontyExecutionError as e:
+        elapsed_ms = int((time.perf_counter() - started) * 1000)
+        return _wrap_raw_result(
+            None,
+            ok=False,
+            api_calls=e.api_calls,
+            elapsed_ms=elapsed_ms,
+            error=str(e),
+        )
+    except Exception as e:
+        elapsed_ms = int((time.perf_counter() - started) * 1000)
+        return _wrap_raw_result(
+            None,
+            ok=False,
+            api_calls=0,
+            elapsed_ms=elapsed_ms,
+            error=str(e),
+        )
+
+
+def _arg_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description="Monty-backed API chaining tool (v3)")
+    p.add_argument("--query", default=None, help="Optional natural language query/context")
+    p.add_argument("--code", default=None, help="Inline Monty code to execute")
+    p.add_argument(
+        "--code-file", default=None, help="Path to .py file with Monty code to execute"
+    )
+    p.add_argument(
+        "--max-calls",
+        type=int,
+        default=DEFAULT_MAX_CALLS,
+        help="Max external API/helper calls",
+    )
+    p.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT_SEC)
+    return p
+
+
+def main() -> int:
+    args = _arg_parser().parse_args()
+    code = args.code
+    if args.code_file:
+        with open(args.code_file, "r", encoding="utf-8") as f:
+            code = f.read()
+
+    if not code:
+        print(
+            json.dumps(
+                {"ok": False, "error": "Either --code or --code-file is required"},
+                ensure_ascii=False,
+            )
+        )
+        return 1
+
+    try:
+        out = asyncio.run(
+            hf_hub_query(
+                code=code,
+                query=args.query,
+                max_calls=args.max_calls,
+                timeout_sec=args.timeout,
+            )
+        )
+        print(json.dumps(out, ensure_ascii=False))
+        return 0 if out.get("ok") else 1
+    except Exception as e:
+        print(json.dumps({"ok": False, "error": str(e)}, ensure_ascii=False))
+        return 1

monty_api/registry.py

@@ -0,0 +1,682 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, NamedTuple
+
+from .constants import (
+    ACTIVITY_CANONICAL_FIELDS,
+    ACTOR_CANONICAL_FIELDS,
+    COLLECTION_CANONICAL_FIELDS,
+    DAILY_PAPER_CANONICAL_FIELDS,
+    DISCUSSION_CANONICAL_FIELDS,
+    DISCUSSION_DETAIL_CANONICAL_FIELDS,
+    GRAPH_SCAN_LIMIT_CAP,
+    LIKES_ENRICHMENT_MAX_REPOS,
+    LIKES_RANKING_WINDOW_DEFAULT,
+    LIKES_SCAN_LIMIT_CAP,
+    OUTPUT_ITEMS_TRUNCATION_LIMIT,
+    PROFILE_CANONICAL_FIELDS,
+    RECENT_ACTIVITY_PAGE_SIZE,
+    RECENT_ACTIVITY_SCAN_MAX_PAGES,
+    REPO_CANONICAL_FIELDS,
+    TRENDING_ENDPOINT_MAX_LIMIT,
+    USER_LIKES_CANONICAL_FIELDS,
+)
+
+
+class RepoApiAdapter(NamedTuple):
+    list_method_name: str
+    detail_method_name: str
+
+
+@dataclass(frozen=True)
+class HelperConfig:
+    name: str
+    endpoint_patterns: tuple[str, ...] = ()
+    default_metadata: Mapping[str, Any] = field(default_factory=dict)
+    pagination: Mapping[str, Any] = field(default_factory=dict)
+
+
+REPO_SEARCH_EXTRA_ARGS: dict[str, set[str]] = {
+    "dataset": {
+        "benchmark",
+        "dataset_name",
+        "expand",
+        "full",
+        "gated",
+        "language",
+        "language_creators",
+        "multilinguality",
+        "size_categories",
+        "task_categories",
+        "task_ids",
+    },
+    "model": {
+        "apps",
+        "cardData",
+        "emissions_thresholds",
+        "expand",
+        "fetch_config",
+        "full",
+        "gated",
+        "inference",
+        "inference_provider",
+        "model_name",
+        "num_parameters",
+        "pipeline_tag",
+        "trained_dataset",
+    },
+    "space": {"datasets", "expand", "full", "linked", "models"},
+}
+
+REPO_SEARCH_DEFAULT_EXPAND: dict[str, list[str]] = {
+    "dataset": [
+        "author",
+        "createdAt",
+        "description",
+        "downloads",
+        "gated",
+        "lastModified",
+        "likes",
+        "paperswithcode_id",
+        "private",
+        "sha",
+        "tags",
+        "trendingScore",
+    ],
+    "model": [
+        "author",
+        "createdAt",
+        "downloads",
+        "gated",
+        "lastModified",
+        "library_name",
+        "likes",
+        "pipeline_tag",
+        "private",
+        "safetensors",
+        "sha",
+        "tags",
+        "trendingScore",
+    ],
+    "space": [
+        "author",
+        "createdAt",
+        "datasets",
+        "lastModified",
+        "likes",
+        "models",
+        "private",
+        "runtime",
+        "sdk",
+        "sha",
+        "subdomain",
+        "tags",
+        "trendingScore",
+    ],
+}
+
+# NOTE:
+# The huggingface_hub client type literals currently advertise a few expand values
+# that the live Hub API rejects (`childrenModelCount`, `usedStorage`) and omits a
+# few that the API now accepts (`xetEnabled`, `gitalyUid`). Keep this allowlist in
+# sync with the live API error contract rather than the client typing surface so we
+# can sanitize generated requests before they hit the network.
+REPO_SEARCH_ALLOWED_EXPAND: dict[str, list[str]] = {
+    "dataset": [
+        "author",
+        "cardData",
+        "citation",
+        "createdAt",
+        "description",
+        "disabled",
+        "downloads",
+        "downloadsAllTime",
+        "gated",
+        "lastModified",
+        "likes",
+        "paperswithcode_id",
+        "private",
+        "resourceGroup",
+        "sha",
+        "siblings",
+        "tags",
+        "trendingScore",
+        "xetEnabled",
+        "gitalyUid",
+    ],
+    "model": [
+        "author",
+        "baseModels",
+        "cardData",
+        "config",
+        "createdAt",
+        "disabled",
+        "downloads",
+        "downloadsAllTime",
+        "evalResults",
+        "gated",
+        "gguf",
+        "inference",
+        "inferenceProviderMapping",
+        "lastModified",
+        "library_name",
+        "likes",
+        "mask_token",
+        "model-index",
+        "pipeline_tag",
+        "private",
+        "resourceGroup",
+        "safetensors",
+        "sha",
+        "siblings",
+        "spaces",
+        "tags",
+        "transformersInfo",
+        "trendingScore",
+        "widgetData",
+        "xetEnabled",
+        "gitalyUid",
+    ],
+    "space": [
+        "author",
+        "cardData",
+        "createdAt",
+        "datasets",
+        "disabled",
+        "lastModified",
+        "likes",
+        "models",
+        "private",
+        "resourceGroup",
+        "runtime",
+        "sdk",
+        "sha",
+        "siblings",
+        "subdomain",
+        "tags",
+        "trendingScore",
+        "xetEnabled",
+        "gitalyUid",
+    ],
+}
+
+RUNTIME_CAPABILITY_FIELDS = [
+    "allowed_sections",
+    "overview",
+    "helpers",
+    "helper_contracts",
+    "helper_defaults",
+    "fields",
+    "limits",
+    "repo_search",
+]
+REPO_SUMMARY_FIELDS = list(REPO_CANONICAL_FIELDS)
+REPO_SUMMARY_OPTIONAL_FIELDS = [
+    field
+    for field in REPO_CANONICAL_FIELDS
+    if field not in {"repo_id", "repo_type", "author", "repo_url"}
+]
+ACTOR_OPTIONAL_FIELDS = [
+    field for field in ACTOR_CANONICAL_FIELDS if field != "username"
+]
+PROFILE_OPTIONAL_FIELDS = [
+    field
+    for field in PROFILE_CANONICAL_FIELDS
+    if field not in {"handle", "entity_type"}
+]
+TRENDING_DEFAULT_FIELDS = [*REPO_SUMMARY_FIELDS, "trending_rank"]
+TRENDING_OPTIONAL_FIELDS = [
+    field
+    for field in TRENDING_DEFAULT_FIELDS
+    if field not in {"repo_id", "repo_type", "author", "repo_url", "trending_rank"}
+]
+DAILY_PAPER_DEFAULT_FIELDS = list(DAILY_PAPER_CANONICAL_FIELDS)
+DAILY_PAPER_OPTIONAL_FIELDS = [
+    field
+    for field in DAILY_PAPER_CANONICAL_FIELDS
+    if field not in {"paper_id", "title", "published_at", "rank"}
+]
+COLLECTION_DEFAULT_FIELDS = list(COLLECTION_CANONICAL_FIELDS)
+COLLECTION_OPTIONAL_FIELDS = [
+    field
+    for field in COLLECTION_CANONICAL_FIELDS
+    if field not in {"collection_id", "title", "owner"}
+]
+
+
+def _metadata(
+    *,
+    default_fields: list[str],
+    guaranteed_fields: list[str],
+    notes: str,
+    optional_fields: list[str] | None = None,
+    default_upstream_calls: int = 1,
+    may_fan_out: bool = False,
+    default_limit: int | None = None,
+    max_limit: int | None = None,
+) -> dict[str, Any]:
+    metadata: dict[str, Any] = {
+        "default_fields": list(default_fields),
+        "guaranteed_fields": list(guaranteed_fields),
+        "optional_fields": list(
+            optional_fields
+            if optional_fields is not None
+            else [
+                field for field in default_fields if field not in set(guaranteed_fields)
+            ]
+        ),
+        "default_upstream_calls": default_upstream_calls,
+        "may_fan_out": may_fan_out,
+        "notes": notes,
+    }
+    if default_limit is not None:
+        metadata["default_limit"] = default_limit
+    if max_limit is not None:
+        metadata["max_limit"] = max_limit
+    return metadata
+
+
+def _config(
+    name: str,
+    *,
+    endpoint_patterns: tuple[str, ...] = (),
+    default_metadata: Mapping[str, Any],
+    pagination: Mapping[str, Any] | None = None,
+) -> HelperConfig:
+    return HelperConfig(
+        name=name,
+        endpoint_patterns=endpoint_patterns,
+        default_metadata=dict(default_metadata),
+        pagination=dict(pagination or {}),
+    )
+
+
+HELPER_CONFIGS: dict[str, HelperConfig] = {
+    "hf_runtime_capabilities": _config(
+        "hf_runtime_capabilities",
+        default_metadata=_metadata(
+            default_fields=RUNTIME_CAPABILITY_FIELDS,
+            guaranteed_fields=RUNTIME_CAPABILITY_FIELDS,
+            optional_fields=[],
+            default_upstream_calls=0,
+            notes="Introspection helper. Use section=... to narrow the response.",
+        ),
+    ),
+    "hf_whoami": _config(
+        "hf_whoami",
+        endpoint_patterns=(r"^/api/whoami-v2$",),
+        default_metadata=_metadata(
+            default_fields=["username", "fullname", "is_pro"],
+            guaranteed_fields=["username"],
+            notes="Returns the current authenticated user when a request token is available.",
+        ),
+    ),
+    "hf_profile_summary": _config(
+        "hf_profile_summary",
+        endpoint_patterns=(
+            r"^/api/users/[^/]+/overview$",
+            r"^/api/organizations/[^/]+/overview$",
+        ),
+        default_metadata=_metadata(
+            default_fields=list(PROFILE_CANONICAL_FIELDS),
+            guaranteed_fields=["handle", "entity_type"],
+            optional_fields=PROFILE_OPTIONAL_FIELDS,
+            may_fan_out=True,
+            notes=(
+                "Profile summary helper. Aggregate counts like followers_count/following_count "
+                "are in the base item. include=['likes', 'activity'] adds composed samples and "
+                "extra upstream work; no other include values are supported. Overview-owned "
+                "repo counts may differ slightly from visible public search/list results."
+            ),
+        ),
+    ),
+    "hf_org_members": _config(
+        "hf_org_members",
+        endpoint_patterns=(r"^/api/organizations/[^/]+/members$",),
+        default_metadata=_metadata(
+            default_fields=list(ACTOR_CANONICAL_FIELDS),
+            guaranteed_fields=["username"],
+            optional_fields=ACTOR_OPTIONAL_FIELDS,
+            default_limit=1_000,
+            max_limit=GRAPH_SCAN_LIMIT_CAP,
+            notes="Returns organization member summary rows.",
+        ),
+        pagination={"default_limit": 1_000, "scan_max": GRAPH_SCAN_LIMIT_CAP},
+    ),
+    "hf_models_search": _config(
+        "hf_models_search",
+        endpoint_patterns=(r"^/api/models$",),
+        default_metadata=_metadata(
+            default_fields=REPO_SUMMARY_FIELDS,
+            guaranteed_fields=["repo_id", "repo_type", "author", "repo_url"],
+            optional_fields=REPO_SUMMARY_OPTIONAL_FIELDS,
+            default_limit=100,
+            max_limit=5_000,
+            notes=(
+                "Thin model-search wrapper around the Hub list_models path. Prefer this "
+                "over hf_repo_search for model-only queries. This is a one-shot selective "
+                "search; if meta.limit_boundary_hit is true, more rows may exist and counts "
+                "are not exact."
+            ),
+        ),
+        pagination={"default_limit": 100, "max_limit": 5_000},
+    ),
+    "hf_datasets_search": _config(
+        "hf_datasets_search",
+        endpoint_patterns=(r"^/api/datasets$",),
+        default_metadata=_metadata(
+            default_fields=REPO_SUMMARY_FIELDS,
+            guaranteed_fields=["repo_id", "repo_type", "author", "repo_url"],
+            optional_fields=REPO_SUMMARY_OPTIONAL_FIELDS,
+            default_limit=100,
+            max_limit=5_000,
+            notes=(
+                "Thin dataset-search wrapper around the Hub list_datasets path. Prefer "
+                "this over hf_repo_search for dataset-only queries. This is a one-shot "
+                "selective search; if meta.limit_boundary_hit is true, more rows may exist "
+                "and counts are not exact."
+            ),
+        ),
+        pagination={"default_limit": 100, "max_limit": 5_000},
+    ),
+    "hf_spaces_search": _config(
+        "hf_spaces_search",
+        endpoint_patterns=(r"^/api/spaces$",),
+        default_metadata=_metadata(
+            default_fields=REPO_SUMMARY_FIELDS,
+            guaranteed_fields=["repo_id", "repo_type", "author", "repo_url"],
+            optional_fields=REPO_SUMMARY_OPTIONAL_FIELDS,
+            default_limit=100,
+            max_limit=5_000,
+            notes=(
+                "Thin space-search wrapper around the Hub list_spaces path. Prefer this "
+                "over hf_repo_search for space-only queries. This is a one-shot selective "
+                "search; if meta.limit_boundary_hit is true, more rows may exist and counts "
+                "are not exact."
+            ),
+        ),
+        pagination={"default_limit": 100, "max_limit": 5_000},
+    ),
+    "hf_repo_search": _config(
+        "hf_repo_search",
+        endpoint_patterns=(r"^/api/models$", r"^/api/datasets$", r"^/api/spaces$"),
+        default_metadata=_metadata(
+            default_fields=REPO_SUMMARY_FIELDS,
+            guaranteed_fields=["repo_id", "repo_type", "author", "repo_url"],
+            optional_fields=REPO_SUMMARY_OPTIONAL_FIELDS,
+            default_limit=100,
+            max_limit=5_000,
+            notes=(
+                "Small generic repo-search helper. Prefer hf_models_search, "
+                "hf_datasets_search, or hf_spaces_search for single-type queries; use "
+                "hf_repo_search for intentionally cross-type search. This is a one-shot "
+                "selective search; if meta.limit_boundary_hit is true, more rows may exist "
+                "and counts are not exact."
+            ),
+        ),
+        pagination={"default_limit": 100, "max_limit": 5_000},
+    ),
+    "hf_user_graph": _config(
+        "hf_user_graph",
+        endpoint_patterns=(
+            r"^/api/users/[^/]+/(followers|following)$",
+            r"^/api/organizations/[^/]+/followers$",
+        ),
+        default_metadata=_metadata(
+            default_fields=list(ACTOR_CANONICAL_FIELDS),
+            guaranteed_fields=["username"],
+            optional_fields=ACTOR_OPTIONAL_FIELDS,
+            default_limit=1_000,
+            max_limit=GRAPH_SCAN_LIMIT_CAP,
+            notes="Returns followers/following summary rows.",
+        ),
+        pagination={
+            "default_limit": 1_000,
+            "max_limit": GRAPH_SCAN_LIMIT_CAP,
+            "scan_max": GRAPH_SCAN_LIMIT_CAP,
+        },
+    ),
+    "hf_repo_likers": _config(
+        "hf_repo_likers",
+        endpoint_patterns=(
+            r"^/api/(models|datasets|spaces)/(?:[^/]+|[^/]+/[^/]+)/likers$",
+        ),
+        default_metadata=_metadata(
+            default_fields=list(ACTOR_CANONICAL_FIELDS),
+            guaranteed_fields=["username"],
+            optional_fields=ACTOR_OPTIONAL_FIELDS,
+            default_limit=1_000,
+            notes="Returns users who liked a repo.",
+        ),
+        pagination={"default_limit": 1_000},
+    ),
+    "hf_user_likes": _config(
+        "hf_user_likes",
+        endpoint_patterns=(r"^/api/users/[^/]+/likes$",),
+        default_metadata=_metadata(
+            default_fields=list(USER_LIKES_CANONICAL_FIELDS),
+            guaranteed_fields=["liked_at", "repo_id", "repo_type"],
+            optional_fields=["repo_author", "repo_likes", "repo_downloads", "repo_url"],
+            default_limit=100,
+            max_limit=2_000,
+            may_fan_out=True,
+            notes=(
+                "Default recency mode is cheap. Popularity-ranked sorts use canonical keys "
+                "liked_at/repo_likes/repo_downloads and rerank only a bounded recent "
+                "shortlist. Check meta.ranking_complete / meta.ranking_window when ranking "
+                "by popularity; helper-owned coverage matters here."
+            ),
+        ),
+        pagination={
+            "default_limit": 100,
+            "enrich_max": LIKES_ENRICHMENT_MAX_REPOS,
+            "ranking_default": LIKES_RANKING_WINDOW_DEFAULT,
+            "scan_max": LIKES_SCAN_LIMIT_CAP,
+        },
+    ),
+    "hf_recent_activity": _config(
+        "hf_recent_activity",
+        endpoint_patterns=(r"^/api/recent-activity$",),
+        default_metadata=_metadata(
+            default_fields=list(ACTIVITY_CANONICAL_FIELDS),
+            guaranteed_fields=["event_type", "timestamp"],
+            optional_fields=["repo_id", "repo_type"],
+            default_limit=100,
+            max_limit=2_000,
+            may_fan_out=True,
+            notes=(
+                "Activity helper may fetch multiple pages when requested coverage exceeds "
+                "one page. count_only may still be a lower bound unless the feed exhausts "
+                "before max_pages."
+            ),
+        ),
+        pagination={
+            "default_limit": 100,
+            "max_pages": RECENT_ACTIVITY_SCAN_MAX_PAGES,
+            "page_limit": RECENT_ACTIVITY_PAGE_SIZE,
+        },
+    ),
+    "hf_repo_discussions": _config(
+        "hf_repo_discussions",
+        endpoint_patterns=(r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions$",),
+        default_metadata=_metadata(
+            default_fields=list(DISCUSSION_CANONICAL_FIELDS),
+            guaranteed_fields=["num", "title", "author", "status"],
+            optional_fields=["repo_id", "repo_type", "created_at", "url"],
+            default_limit=20,
+            max_limit=200,
+            notes="Discussion summary helper.",
+        ),
+    ),
+    "hf_repo_discussion_details": _config(
+        "hf_repo_discussion_details",
+        endpoint_patterns=(
+            r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+$",
+        ),
+        default_metadata=_metadata(
+            default_fields=list(DISCUSSION_DETAIL_CANONICAL_FIELDS),
+            guaranteed_fields=["repo_id", "repo_type", "title", "author", "status"],
+            optional_fields=[
+                "num",
+                "created_at",
+                "url",
+                "comment_count",
+                "latest_comment_author",
+                "latest_comment_created_at",
+                "latest_comment_text",
+                "latest_comment_html",
+            ],
+            notes="Exact discussion detail helper.",
+        ),
+    ),
+    "hf_repo_details": _config(
+        "hf_repo_details",
+        endpoint_patterns=(r"^/api/(models|datasets|spaces)/[^/]+/[^/]+$",),
+        default_metadata=_metadata(
+            default_fields=REPO_SUMMARY_FIELDS,
+            guaranteed_fields=["repo_id", "repo_type", "author", "repo_url"],
+            optional_fields=REPO_SUMMARY_OPTIONAL_FIELDS,
+            may_fan_out=True,
+            notes="Exact repo metadata path. Multiple repo_ids may trigger one detail call per requested repo.",
+        ),
+    ),
+    "hf_trending": _config(
+        "hf_trending",
+        endpoint_patterns=(r"^/api/trending$",),
+        default_metadata=_metadata(
+            default_fields=TRENDING_DEFAULT_FIELDS,
+            guaranteed_fields=[
+                "repo_id",
+                "repo_type",
+                "author",
+                "repo_url",
+                "trending_rank",
+            ],
+            optional_fields=TRENDING_OPTIONAL_FIELDS,
+            default_limit=20,
+            max_limit=TRENDING_ENDPOINT_MAX_LIMIT,
+            notes="Returns ordered trending summary rows only. Use hf_repo_details for exact repo metadata.",
+        ),
+        pagination={"default_limit": 20, "max_limit": TRENDING_ENDPOINT_MAX_LIMIT},
+    ),
+    "hf_daily_papers": _config(
+        "hf_daily_papers",
+        endpoint_patterns=(r"^/api/daily_papers$",),
+        default_metadata=_metadata(
+            default_fields=DAILY_PAPER_DEFAULT_FIELDS,
+            guaranteed_fields=["paper_id", "title", "published_at", "rank"],
+            optional_fields=DAILY_PAPER_OPTIONAL_FIELDS,
+            default_limit=20,
+            max_limit=OUTPUT_ITEMS_TRUNCATION_LIMIT,
+            notes="Returns daily paper summary rows. repo_id is omitted unless the upstream payload provides it.",
+        ),
+        pagination={"default_limit": 20, "max_limit": OUTPUT_ITEMS_TRUNCATION_LIMIT},
+    ),
+    "hf_collections_search": _config(
+        "hf_collections_search",
+        endpoint_patterns=(r"^/api/collections$",),
+        default_metadata=_metadata(
+            default_fields=COLLECTION_DEFAULT_FIELDS,
+            guaranteed_fields=["collection_id", "title", "owner"],
+            optional_fields=COLLECTION_OPTIONAL_FIELDS,
+            default_limit=20,
+            max_limit=OUTPUT_ITEMS_TRUNCATION_LIMIT,
+            notes="Collection summary helper.",
+        ),
+        pagination={"default_limit": 20, "max_limit": OUTPUT_ITEMS_TRUNCATION_LIMIT},
+    ),
+    "hf_collection_items": _config(
+        "hf_collection_items",
+        endpoint_patterns=(
+            r"^/api/collections/[^/]+$",
+            r"^/api/collections/[^/]+/[^/]+$",
+        ),
+        default_metadata=_metadata(
+            default_fields=REPO_SUMMARY_FIELDS,
+            guaranteed_fields=["repo_id", "repo_type", "repo_url"],
+            optional_fields=[
+                field
+                for field in REPO_CANONICAL_FIELDS
+                if field not in {"repo_id", "repo_type", "repo_url"}
+            ],
+            default_limit=100,
+            max_limit=OUTPUT_ITEMS_TRUNCATION_LIMIT,
+            notes="Returns repos inside one collection as summary rows.",
+        ),
+        pagination={"default_limit": 100, "max_limit": OUTPUT_ITEMS_TRUNCATION_LIMIT},
+    ),
+}
+
+HELPER_EXTERNALS = tuple(HELPER_CONFIGS)
+
+HELPER_DEFAULT_METADATA: dict[str, dict[str, Any]] = {
+    name: dict(config.default_metadata) for name, config in HELPER_CONFIGS.items()
+}
+
+PAGINATION_POLICY: dict[str, dict[str, Any]] = {
+    name: dict(config.pagination)
+    for name, config in HELPER_CONFIGS.items()
+    if config.pagination
+}
+
+HELPER_COVERED_ENDPOINT_PATTERNS: list[tuple[str, str]] = [
+    (pattern, config.name)
+    for config in HELPER_CONFIGS.values()
+    for pattern in config.endpoint_patterns
+]
+
+ALLOWLIST_PATTERNS = [
+    r"^/api/whoami-v2$",
+    r"^/api/trending$",
+    r"^/api/daily_papers$",
+    r"^/api/models$",
+    r"^/api/datasets$",
+    r"^/api/spaces$",
+    r"^/api/models-tags-by-type$",
+    r"^/api/datasets-tags-by-type$",
+    r"^/api/(models|datasets|spaces)/[^/]+/[^/]+$",
+    r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions$",
+    r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+$",
+    r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+/status$",
+    r"^/api/users/[^/]+/overview$",
+    r"^/api/users/[^/]+/socials$",
+    r"^/api/users/[^/]+/followers$",
+    r"^/api/users/[^/]+/following$",
+    r"^/api/users/[^/]+/likes$",
+    r"^/api/(models|datasets|spaces)/(?:[^/]+|[^/]+/[^/]+)/likers$",
+    r"^/api/organizations/[^/]+/overview$",
+    r"^/api/organizations/[^/]+/members$",
+    r"^/api/organizations/[^/]+/followers$",
+    r"^/api/collections$",
+    r"^/api/collections/[^/]+$",
+    r"^/api/collections/[^/]+/[^/]+$",
+    r"^/api/recent-activity$",
+]
+
+STRICT_ALLOWLIST_PATTERNS = [
+    r"^/api/users/[^/]+/overview$",
+    r"^/api/users/[^/]+/socials$",
+    r"^/api/whoami-v2$",
+    r"^/api/trending$",
+    r"^/api/daily_papers$",
+    r"^/api/(models|datasets|spaces)/(?:[^/]+|[^/]+/[^/]+)/likers$",
+    r"^/api/collections$",
+    r"^/api/collections/[^/]+$",
+    r"^/api/collections/[^/]+/[^/]+$",
+    r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions$",
+    r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+$",
+    r"^/api/(models|datasets|spaces)/[^/]+/[^/]+/discussions/\d+/status$",
+]
+
+REPO_API_ADAPTERS: dict[str, RepoApiAdapter] = {
+    "model": RepoApiAdapter(
+        list_method_name="list_models", detail_method_name="model_info"
+    ),
+    "dataset": RepoApiAdapter(
+        list_method_name="list_datasets", detail_method_name="dataset_info"
+    ),
+    "space": RepoApiAdapter(
+        list_method_name="list_spaces", detail_method_name="space_info"
+    ),
+}

monty_api/runtime_context.py

@@ -0,0 +1,409 @@
+from __future__ import annotations
+
+import os
+import sys
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, NamedTuple, cast
+
+import httpx
+
+from .constants import MAX_CALLS_LIMIT
+from .helpers.activity import register_activity_helpers
+from .helpers.collections import register_collection_helpers
+from .helpers.introspection import register_introspection_helpers
+from .helpers.profiles import register_profile_helpers
+from .helpers.repos import register_repo_helpers
+from .http_runtime import (
+    _as_int,
+    _author_from_any,
+    _canonical_repo_type,
+    _clamp_int,
+    _coerce_str_list,
+    _dt_to_str,
+    _extract_author_names,
+    _extract_num_params,
+    _extract_profile_name,
+    _load_token,
+    _normalize_collection_repo_item,
+    _normalize_daily_paper_row,
+    _normalize_repo_detail_row,
+    _normalize_repo_search_row,
+    _normalize_repo_sort_key,
+    _normalize_trending_row,
+    _optional_str_list,
+    _repo_detail_call,
+    _repo_list_call,
+    _repo_web_url,
+    _sort_repo_rows,
+    call_api_host,
+)
+from .registry import PAGINATION_POLICY
+from .runtime_envelopes import (
+    _build_exhaustive_meta,
+    _build_exhaustive_result_meta,
+    _derive_can_request_more,
+    _derive_limit_metadata,
+    _derive_more_available,
+    _derive_next_request_hint,
+    _derive_truncated_by,
+    _helper_error,
+    _helper_meta,
+    _helper_success,
+    _overview_count_only_success,
+    _resolve_exhaustive_limits,
+)
+from .runtime_filtering import (
+    _apply_where,
+    _helper_item,
+    _item_matches_where,
+    _normalize_where,
+    _overview_count,
+    _project_activity_items,
+    _project_actor_items,
+    _project_collection_items,
+    _project_discussion_detail_items,
+    _project_discussion_items,
+    _project_daily_paper_items,
+    _project_items,
+    _project_repo_items,
+    _project_user_items,
+    _project_user_like_items,
+)
+from .validation import _resolve_helper_functions
+
+if TYPE_CHECKING:
+    from huggingface_hub import HfApi
+
+
+class RuntimeHelperEnvironment(NamedTuple):
+    context: "RuntimeContext"
+    call_count: dict[str, int]
+    trace: list[dict[str, Any]]
+    limit_summaries: list[dict[str, Any]]
+    latest_helper_error_box: dict[str, dict[str, Any] | None]
+    internal_helper_used: dict[str, bool]
+    helper_functions: dict[str, Callable[..., Any]]
+
+
+def _execution_debug_enabled() -> bool:
+    for key in ("MONTY_DEBUG_EXECUTION", "MONTY_DEBUG_QUERY"):
+        value = os.environ.get(key, "")
+        if value.strip().lower() in {"1", "true", "yes", "on"}:
+            return True
+    return False
+
+
+def _debug_log(*parts: Any) -> None:
+    if not _execution_debug_enabled():
+        return
+    print("[monty-debug]", *parts, file=sys.stderr)
+    sys.stderr.flush()
+
+
+def _hf_call_timeout_default() -> int:
+    raw = os.environ.get("MONTY_HF_CALL_TIMEOUT_SEC", "20").strip()
+    try:
+        return max(1, int(raw))
+    except Exception:
+        return 20
+
+
+_HF_CLIENT_TIMEOUT_SEC: int | None = None
+
+
+def _configure_hf_client_factory(timeout_sec: int) -> None:
+    global _HF_CLIENT_TIMEOUT_SEC
+    if _HF_CLIENT_TIMEOUT_SEC == timeout_sec:
+        return
+    from huggingface_hub.utils._http import hf_request_event_hook, set_client_factory
+
+    set_client_factory(
+        lambda: httpx.Client(
+            event_hooks={"request": [hf_request_event_hook]},
+            follow_redirects=True,
+            timeout=float(timeout_sec),
+        )
+    )
+    _HF_CLIENT_TIMEOUT_SEC = timeout_sec
+
+
+@dataclass(slots=True)
+class RuntimeContext:
+    max_calls: int
+    strict_mode: bool
+    timeout_sec: int
+    call_count: dict[str, int] = field(default_factory=lambda: {"n": 0})
+    trace: list[dict[str, Any]] = field(default_factory=list)
+    limit_summaries: list[dict[str, Any]] = field(default_factory=list)
+    latest_helper_error_box: dict[str, dict[str, Any] | None] = field(
+        default_factory=lambda: {"value": None}
+    )
+    internal_helper_used: dict[str, bool] = field(
+        default_factory=lambda: {"used": False}
+    )
+    helper_registry: dict[str, Callable[..., Any]] = field(default_factory=dict)
+    _hf_api_client: "HfApi | None" = field(default=None, init=False, repr=False)
+
+    def _budget_remaining(self) -> int:
+        return max(0, self.max_calls - self.call_count["n"])
+
+    def _policy_int(self, helper_name: str, key: str, default: int) -> int:
+        cfg = PAGINATION_POLICY.get(helper_name) or {}
+        try:
+            return int(cfg.get(key, default))
+        except Exception:
+            return int(default)
+
+    def _consume_call(self, endpoint: str, method: str = "GET") -> int:
+        if self.call_count["n"] >= self.max_calls:
+            raise RuntimeError(f"Max API calls exceeded ({self.max_calls})")
+        self.call_count["n"] += 1
+        return self.call_count["n"]
+
+    def _trace_ok(
+        self, idx: int, endpoint: str, method: str = "GET", status: int = 200
+    ) -> None:
+        self.trace.append(
+            {
+                "call_index": idx,
+                "depth": idx,
+                "method": method,
+                "endpoint": endpoint,
+                "ok": True,
+                "status": status,
+            }
+        )
+
+    def _trace_err(
+        self, idx: int, endpoint: str, err: Any, method: str = "GET", status: int = 0
+    ) -> None:
+        self.trace.append(
+            {
+                "call_index": idx,
+                "depth": idx,
+                "method": method,
+                "endpoint": endpoint,
+                "ok": False,
+                "status": status,
+                "error": str(err),
+            }
+        )
+
+    def _host_raw_call(
+        self,
+        endpoint: str,
+        *,
+        params: dict[str, Any] | None = None,
+        method: str = "GET",
+        json_body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        idx = self._consume_call(endpoint, method)
+        started = time.perf_counter()
+        _debug_log("host_raw:start", f"call={idx}", method, endpoint)
+        try:
+            resp = call_api_host(
+                endpoint,
+                method=method,
+                params=params,
+                json_body=json_body,
+                timeout_sec=self.timeout_sec,
+                strict_mode=self.strict_mode,
+            )
+            if resp.get("ok"):
+                self._trace_ok(
+                    idx, endpoint, method=method, status=int(resp.get("status") or 200)
+                )
+            else:
+                self._trace_err(
+                    idx,
+                    endpoint,
+                    resp.get("error"),
+                    method=method,
+                    status=int(resp.get("status") or 0),
+                )
+            elapsed_ms = round((time.perf_counter() - started) * 1000, 2)
+            _debug_log(
+                "host_raw:end",
+                f"call={idx}",
+                method,
+                endpoint,
+                f"ok={bool(resp.get('ok'))}",
+                f"status={resp.get('status')}",
+                f"elapsed_ms={elapsed_ms}",
+            )
+            return resp
+        except Exception as exc:
+            self._trace_err(idx, endpoint, exc, method=method, status=0)
+            elapsed_ms = round((time.perf_counter() - started) * 1000, 2)
+            _debug_log(
+                "host_raw:error",
+                f"call={idx}",
+                method,
+                endpoint,
+                type(exc).__name__,
+                str(exc),
+                f"elapsed_ms={elapsed_ms}",
+            )
+            raise
+
+    def _get_hf_api_client(self) -> "HfApi":
+        if self._hf_api_client is None:
+            from huggingface_hub import HfApi
+
+            endpoint = os.getenv("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
+            _configure_hf_client_factory(
+                max(1, min(self.timeout_sec, _hf_call_timeout_default()))
+            )
+            self._hf_api_client = HfApi(endpoint=endpoint, token=_load_token())
+        return self._hf_api_client
+
+    def _host_hf_call(self, endpoint: str, fn: Callable[[], Any]) -> Any:
+        idx = self._consume_call(endpoint, "GET")
+        started = time.perf_counter()
+        timeout_sec = max(1, min(self.timeout_sec, _hf_call_timeout_default()))
+        _debug_log(
+            "host_hf:start",
+            f"call={idx}",
+            endpoint,
+            f"timeout_sec={timeout_sec}",
+        )
+        try:
+            out = fn()
+            self._trace_ok(idx, endpoint, method="GET", status=200)
+            elapsed_ms = round((time.perf_counter() - started) * 1000, 2)
+            _debug_log("host_hf:end", f"call={idx}", endpoint, f"elapsed_ms={elapsed_ms}")
+            return out
+        except Exception as exc:
+            self._trace_err(idx, endpoint, exc, method="GET", status=0)
+            elapsed_ms = round((time.perf_counter() - started) * 1000, 2)
+            _debug_log(
+                "host_hf:error",
+                f"call={idx}",
+                endpoint,
+                type(exc).__name__,
+                str(exc),
+                f"elapsed_ms={elapsed_ms}",
+            )
+            raise
+
+    async def call_helper(self, helper_name: str, /, *args: Any, **kwargs: Any) -> Any:
+        fn = self.helper_registry.get(helper_name)
+        if not callable(fn):
+            raise RuntimeError(f"Helper '{helper_name}' is not registered")
+        started = time.perf_counter()
+        _debug_log(
+            "runtime_helper:start",
+            helper_name,
+            f"args={len(args)}",
+            f"kwargs={sorted(kwargs)}",
+            f"budget_remaining={self._budget_remaining()}",
+        )
+        try:
+            result = await cast(Callable[..., Any], fn)(*args, **kwargs)
+        except Exception as exc:
+            elapsed_ms = round((time.perf_counter() - started) * 1000, 2)
+            _debug_log(
+                "runtime_helper:error",
+                helper_name,
+                type(exc).__name__,
+                str(exc),
+                f"elapsed_ms={elapsed_ms}",
+            )
+            raise
+        elapsed_ms = round((time.perf_counter() - started) * 1000, 2)
+        ok = result.get("ok") if isinstance(result, dict) else None
+        _debug_log(
+            "runtime_helper:end",
+            helper_name,
+            f"ok={ok}",
+            f"elapsed_ms={elapsed_ms}",
+            f"budget_remaining={self._budget_remaining()}",
+        )
+        return result
+
+
+for name, value in {
+    "_helper_meta": _helper_meta,
+    "_derive_limit_metadata": _derive_limit_metadata,
+    "_derive_more_available": _derive_more_available,
+    "_derive_truncated_by": _derive_truncated_by,
+    "_derive_can_request_more": _derive_can_request_more,
+    "_derive_next_request_hint": _derive_next_request_hint,
+    "_resolve_exhaustive_limits": _resolve_exhaustive_limits,
+    "_build_exhaustive_meta": _build_exhaustive_meta,
+    "_overview_count_only_success": _overview_count_only_success,
+    "_build_exhaustive_result_meta": _build_exhaustive_result_meta,
+    "_helper_success": _helper_success,
+    "_helper_error": _helper_error,
+    "_project_items": _project_items,
+    "_project_repo_items": _project_repo_items,
+    "_project_collection_items": _project_collection_items,
+    "_project_discussion_items": _project_discussion_items,
+    "_project_discussion_detail_items": _project_discussion_detail_items,
+    "_project_daily_paper_items": _project_daily_paper_items,
+    "_project_user_items": _project_user_items,
+    "_project_actor_items": _project_actor_items,
+    "_project_user_like_items": _project_user_like_items,
+    "_project_activity_items": _project_activity_items,
+    "_normalize_where": _normalize_where,
+    "_item_matches_where": _item_matches_where,
+    "_apply_where": _apply_where,
+    "_helper_item": _helper_item,
+    "_overview_count": _overview_count,
+    "_as_int": staticmethod(_as_int),
+    "_author_from_any": staticmethod(_author_from_any),
+    "_canonical_repo_type": staticmethod(_canonical_repo_type),
+    "_clamp_int": staticmethod(_clamp_int),
+    "_coerce_str_list": staticmethod(_coerce_str_list),
+    "_dt_to_str": staticmethod(_dt_to_str),
+    "_extract_author_names": staticmethod(_extract_author_names),
+    "_extract_num_params": staticmethod(_extract_num_params),
+    "_extract_profile_name": staticmethod(_extract_profile_name),
+    "_load_token": staticmethod(_load_token),
+    "_normalize_collection_repo_item": staticmethod(_normalize_collection_repo_item),
+    "_normalize_daily_paper_row": staticmethod(_normalize_daily_paper_row),
+    "_normalize_repo_detail_row": staticmethod(_normalize_repo_detail_row),
+    "_normalize_repo_search_row": staticmethod(_normalize_repo_search_row),
+    "_normalize_repo_sort_key": staticmethod(_normalize_repo_sort_key),
+    "_normalize_trending_row": staticmethod(_normalize_trending_row),
+    "_optional_str_list": staticmethod(_optional_str_list),
+    "_repo_detail_call": staticmethod(_repo_detail_call),
+    "_repo_list_call": staticmethod(_repo_list_call),
+    "_repo_web_url": staticmethod(_repo_web_url),
+    "_sort_repo_rows": staticmethod(_sort_repo_rows),
+}.items():
+    setattr(RuntimeContext, name, value)
+
+
+def build_runtime_helper_environment(
+    *,
+    max_calls: int,
+    strict_mode: bool,
+    timeout_sec: int,
+) -> RuntimeHelperEnvironment:
+    ctx = RuntimeContext(
+        max_calls=max(1, min(int(max_calls), MAX_CALLS_LIMIT)),
+        strict_mode=strict_mode,
+        timeout_sec=timeout_sec,
+    )
+
+    for registration in (
+        register_profile_helpers,
+        register_repo_helpers,
+        register_activity_helpers,
+        register_collection_helpers,
+        register_introspection_helpers,
+    ):
+        ctx.helper_registry.update(registration(ctx))
+
+    helper_functions = _resolve_helper_functions(ctx.helper_registry)
+    return RuntimeHelperEnvironment(
+        context=ctx,
+        call_count=ctx.call_count,
+        trace=ctx.trace,
+        limit_summaries=ctx.limit_summaries,
+        latest_helper_error_box=ctx.latest_helper_error_box,
+        internal_helper_used=ctx.internal_helper_used,
+        helper_functions=helper_functions,
+    )

monty_api/runtime_envelopes.py

@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .http_runtime import _as_int, _clamp_int
+
+
+def _helper_meta(
+    self: Any, start_calls: int, *, source: str, **extra: Any
+) -> dict[str, Any]:
+    out = {
+        "source": source,
+        "normalized": True,
+        "budget_used": max(0, self.call_count["n"] - start_calls),
+        "budget_remaining": self._budget_remaining(),
+    }
+    out.update(extra)
+    return out
+
+
+def _derive_limit_metadata(
+    self: Any,
+    *,
+    requested_limit: int | None,
+    applied_limit: int,
+    default_limit_used: bool,
+    requested_scan_limit: int | None = None,
+    applied_scan_limit: int | None = None,
+    requested_max_pages: int | None = None,
+    applied_max_pages: int | None = None,
+) -> dict[str, Any]:
+    meta: dict[str, Any] = {
+        "requested_limit": requested_limit,
+        "applied_limit": applied_limit,
+        "default_limit_used": default_limit_used,
+    }
+    if requested_scan_limit is not None or applied_scan_limit is not None:
+        meta["requested_scan_limit"] = requested_scan_limit
+        meta["scan_limit"] = applied_scan_limit
+        meta["scan_limit_applied"] = requested_scan_limit != applied_scan_limit
+    if requested_max_pages is not None or applied_max_pages is not None:
+        meta["requested_max_pages"] = requested_max_pages
+        meta["applied_max_pages"] = applied_max_pages
+        meta["page_limit_applied"] = requested_max_pages != applied_max_pages
+    if requested_limit is not None:
+        meta["hard_cap_applied"] = applied_limit < requested_limit
+    return meta
+
+
+def _derive_more_available(
+    self: Any,
+    *,
+    sample_complete: bool,
+    exact_count: bool,
+    returned: int,
+    total: int | None,
+) -> bool | str:
+    if sample_complete:
+        return False
+    if exact_count and total is not None and returned < total:
+        return True
+    return "unknown"
+
+
+def _derive_truncated_by(
+    self: Any,
+    *,
+    hard_cap: bool = False,
+    scan_limit_hit: bool = False,
+    page_limit_hit: bool = False,
+    limit_hit: bool = False,
+) -> str:
+    causes = [hard_cap, scan_limit_hit, page_limit_hit, limit_hit]
+    if sum(1 for cause in causes if cause) > 1:
+        return "multiple"
+    if hard_cap:
+        return "hard_cap"
+    if scan_limit_hit:
+        return "scan_limit"
+    if page_limit_hit:
+        return "page_limit"
+    if limit_hit:
+        return "limit"
+    return "none"
+
+
+def _derive_can_request_more(
+    self: Any, *, sample_complete: bool, truncated_by: str
+) -> bool:
+    if sample_complete:
+        return False
+    return truncated_by in {"limit", "scan_limit", "page_limit", "multiple"}
+
+
+def _derive_next_request_hint(
+    self: Any,
+    *,
+    truncated_by: str,
+    more_available: bool | str,
+    applied_limit: int,
+    applied_scan_limit: int | None = None,
+    applied_max_pages: int | None = None,
+) -> str:
+    if truncated_by == "limit":
+        return f"Ask for limit>{applied_limit} to see more rows"
+    if truncated_by == "scan_limit" and applied_scan_limit is not None:
+        return f"Increase scan_limit above {applied_scan_limit} for broader coverage"
+    if truncated_by == "page_limit" and applied_max_pages is not None:
+        return f"Increase max_pages above {applied_max_pages} to continue paging"
+    if truncated_by == "hard_cap":
+        return "No more rows can be returned in a single call because a hard cap was applied"
+    if truncated_by == "multiple":
+        return "Increase the relevant return/page/scan bounds to improve coverage"
+    if more_available is False:
+        return "No more results available"
+    if more_available == "unknown":
+        return "More results may exist; narrow filters or raise scan/page bounds for better coverage"
+    return "Ask for a larger limit to see more rows"
+
+
+def _resolve_exhaustive_limits(
+    self: Any,
+    *,
+    limit: int | None,
+    count_only: bool,
+    default_limit: int,
+    max_limit: int,
+    scan_limit: int | None = None,
+    scan_cap: int | None = None,
+) -> dict[str, Any]:
+    requested_limit = None if count_only else limit
+    effective_requested_limit = 0 if count_only else requested_limit
+    out: dict[str, Any] = {
+        "requested_limit": requested_limit,
+        "applied_limit": _clamp_int(
+            effective_requested_limit,
+            default=default_limit,
+            minimum=0,
+            maximum=max_limit,
+        ),
+        "default_limit_used": requested_limit is None and not count_only,
+    }
+    out["hard_cap_applied"] = (
+        requested_limit is not None and out["applied_limit"] < requested_limit
+    )
+    if scan_cap is not None:
+        out["requested_scan_limit"] = scan_limit
+        out["applied_scan_limit"] = _clamp_int(
+            scan_limit,
+            default=scan_cap,
+            minimum=1,
+            maximum=scan_cap,
+        )
+    return out
+
+
+def _build_exhaustive_meta(
+    self: Any,
+    *,
+    base_meta: dict[str, Any],
+    limit_plan: dict[str, Any],
+    sample_complete: bool,
+    exact_count: bool,
+    truncated_by: str,
+    more_available: bool | str,
+    requested_max_pages: int | None = None,
+    applied_max_pages: int | None = None,
+) -> dict[str, Any]:
+    meta = dict(base_meta)
+    applied_limit = int(limit_plan["applied_limit"])
+    applied_scan_limit = limit_plan.get("applied_scan_limit")
+    meta.update(
+        {
+            "complete": sample_complete,
+            "exact_count": exact_count,
+            "sample_complete": sample_complete,
+            "more_available": more_available,
+            "can_request_more": _derive_can_request_more(
+                self,
+                sample_complete=sample_complete,
+                truncated_by=truncated_by,
+            ),
+            "truncated_by": truncated_by,
+            "next_request_hint": _derive_next_request_hint(
+                self,
+                truncated_by=truncated_by,
+                more_available=more_available,
+                applied_limit=applied_limit,
+                applied_scan_limit=applied_scan_limit
+                if isinstance(applied_scan_limit, int)
+                else None,
+                applied_max_pages=applied_max_pages,
+            ),
+        }
+    )
+    meta.update(
+        _derive_limit_metadata(
+            self,
+            requested_limit=limit_plan["requested_limit"],
+            applied_limit=applied_limit,
+            default_limit_used=bool(limit_plan["default_limit_used"]),
+            requested_scan_limit=limit_plan.get("requested_scan_limit"),
+            applied_scan_limit=applied_scan_limit
+            if isinstance(applied_scan_limit, int)
+            else None,
+            requested_max_pages=requested_max_pages,
+            applied_max_pages=applied_max_pages,
+        )
+    )
+    return meta
+
+
+def _overview_count_only_success(
+    self: Any,
+    *,
+    start_calls: int,
+    source: str,
+    total: int,
+    limit_plan: dict[str, Any],
+    base_meta: dict[str, Any],
+) -> dict[str, Any]:
+    meta = _build_exhaustive_meta(
+        self,
+        base_meta={
+            **base_meta,
+            "matched": total,
+            "returned": 0,
+            "total": total,
+            "total_available": total,
+            "total_matched": total,
+            "truncated": False,
+        },
+        limit_plan=limit_plan,
+        sample_complete=True,
+        exact_count=True,
+        truncated_by="none",
+        more_available=False,
+    )
+    return _helper_success(
+        self,
+        start_calls=start_calls,
+        source=source,
+        items=[],
+        meta=meta,
+    )
+
+
+def _build_exhaustive_result_meta(
+    self: Any,
+    *,
+    base_meta: dict[str, Any],
+    limit_plan: dict[str, Any],
+    matched_count: int,
+    returned_count: int,
+    exact_count: bool,
+    count_only: bool = False,
+    sample_complete: bool | None = None,
+    more_available: bool | str | None = None,
+    scan_limit_hit: bool = False,
+    page_limit_hit: bool = False,
+    truncated_extra: bool = False,
+    requested_max_pages: int | None = None,
+    applied_max_pages: int | None = None,
+) -> dict[str, Any]:
+    applied_limit = int(limit_plan["applied_limit"])
+    if count_only:
+        effective_sample_complete = exact_count
+    else:
+        effective_sample_complete = (
+            sample_complete
+            if isinstance(sample_complete, bool)
+            else exact_count and matched_count <= applied_limit
+        )
+    limit_hit = (
+        False
+        if count_only
+        else (applied_limit > 0 and matched_count > applied_limit)
+    )
+    truncated_by = _derive_truncated_by(
+        self,
+        hard_cap=bool(limit_plan.get("hard_cap_applied")),
+        scan_limit_hit=scan_limit_hit,
+        page_limit_hit=page_limit_hit,
+        limit_hit=limit_hit,
+    )
+    truncated = truncated_by != "none" or truncated_extra
+    total_value = _as_int(base_meta.get("total"))
+    effective_more_available = more_available
+    if count_only and exact_count:
+        effective_more_available = False
+    if effective_more_available is None:
+        effective_more_available = _derive_more_available(
+            self,
+            sample_complete=effective_sample_complete,
+            exact_count=exact_count,
+            returned=returned_count,
+            total=total_value,
+        )
+
+    return _build_exhaustive_meta(
+        self,
+        base_meta={
+            **base_meta,
+            "matched": matched_count,
+            "returned": returned_count,
+            "truncated": truncated,
+        },
+        limit_plan=limit_plan,
+        sample_complete=effective_sample_complete,
+        exact_count=exact_count,
+        truncated_by=truncated_by,
+        more_available=effective_more_available,
+        requested_max_pages=requested_max_pages,
+        applied_max_pages=applied_max_pages,
+    )
+
+
+def _helper_success(
+    self: Any,
+    *,
+    start_calls: int,
+    source: str,
+    items: list[dict[str, Any]],
+    cursor: str | None = None,
+    meta: dict[str, Any] | None = None,
+    **extra_meta: Any,
+) -> dict[str, Any]:
+    merged_meta = dict(meta or {})
+    merged_meta.update(extra_meta)
+    if cursor is not None:
+        merged_meta["cursor"] = cursor
+    return {
+        "ok": True,
+        "item": items[0] if len(items) == 1 else None,
+        "items": items,
+        "meta": _helper_meta(self, start_calls, source=source, **merged_meta),
+        "error": None,
+    }
+
+
+def _helper_error(
+    self: Any,
+    *,
+    start_calls: int,
+    source: str,
+    error: Any,
+    **meta: Any,
+) -> dict[str, Any]:
+    envelope = {
+        "ok": False,
+        "item": None,
+        "items": [],
+        "meta": _helper_meta(self, start_calls, source=source, **meta),
+        "error": str(error),
+    }
+    self.latest_helper_error_box["value"] = envelope
+    return envelope

monty_api/runtime_filtering.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from .constants import (
+    ACTIVITY_CANONICAL_FIELDS,
+    ACTOR_CANONICAL_FIELDS,
+    COLLECTION_CANONICAL_FIELDS,
+    DAILY_PAPER_CANONICAL_FIELDS,
+    DISCUSSION_CANONICAL_FIELDS,
+    DISCUSSION_DETAIL_CANONICAL_FIELDS,
+    REPO_CANONICAL_FIELDS,
+    USER_CANONICAL_FIELDS,
+    USER_LIKES_CANONICAL_FIELDS,
+)
+from .http_runtime import _as_int
+
+
+def _as_datetime(value: Any) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    if text.endswith("Z"):
+        text = f"{text[:-1]}+00:00"
+    try:
+        parsed = datetime.fromisoformat(text)
+    except Exception:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=UTC)
+    return parsed
+
+
+def _allowed_field_set(allowed_fields: tuple[str, ...] | list[str] | set[str]) -> set[str]:
+    return {str(field).strip() for field in allowed_fields if str(field).strip()}
+
+
+def _project_items(
+    self: Any,
+    items: list[dict[str, Any]],
+    fields: list[str] | None,
+    *,
+    allowed_fields: tuple[str, ...] | list[str] | set[str] | None = None,
+) -> list[dict[str, Any]]:
+    if not isinstance(fields, list) or not fields:
+        return items
+    wanted = [str(field).strip() for field in fields if str(field).strip()]
+    if not wanted:
+        return items
+    if allowed_fields is not None:
+        allowed = _allowed_field_set(allowed_fields)
+        invalid = sorted(field for field in wanted if field not in allowed)
+        if invalid:
+            raise ValueError(
+                f"Unsupported fields {invalid}. Allowed fields: {sorted(allowed)}"
+            )
+    projected: list[dict[str, Any]] = []
+    for row in items:
+        out: dict[str, Any] = {}
+        for key in wanted:
+            value = row.get(key)
+            if value is None:
+                continue
+            out[key] = value
+        projected.append(out)
+    return projected
+
+
+def _project_repo_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(self, items, fields, allowed_fields=REPO_CANONICAL_FIELDS)
+
+
+def _project_collection_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(
+        self, items, fields, allowed_fields=COLLECTION_CANONICAL_FIELDS
+    )
+
+
+def _project_daily_paper_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(
+        self, items, fields, allowed_fields=DAILY_PAPER_CANONICAL_FIELDS
+    )
+
+
+def _project_user_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(self, items, fields, allowed_fields=USER_CANONICAL_FIELDS)
+
+
+def _project_actor_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(self, items, fields, allowed_fields=ACTOR_CANONICAL_FIELDS)
+
+
+def _project_user_like_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(
+        self, items, fields, allowed_fields=USER_LIKES_CANONICAL_FIELDS
+    )
+
+
+def _project_activity_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(
+        self, items, fields, allowed_fields=ACTIVITY_CANONICAL_FIELDS
+    )
+
+
+def _project_discussion_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(
+        self, items, fields, allowed_fields=DISCUSSION_CANONICAL_FIELDS
+    )
+
+
+def _project_discussion_detail_items(
+    self: Any, items: list[dict[str, Any]], fields: list[str] | None
+) -> list[dict[str, Any]]:
+    return _project_items(
+        self, items, fields, allowed_fields=DISCUSSION_DETAIL_CANONICAL_FIELDS
+    )
+
+
+def _normalize_where(
+    self: Any,
+    where: dict[str, Any] | None,
+    *,
+    allowed_fields: tuple[str, ...] | list[str] | set[str] | None = None,
+) -> dict[str, Any] | None:
+    if not isinstance(where, dict) or not where:
+        return where
+    allowed = _allowed_field_set(allowed_fields) if allowed_fields is not None else None
+    normalized: dict[str, Any] = {}
+    for key, value in where.items():
+        raw_key = str(key).strip()
+        if not raw_key:
+            continue
+        if allowed is not None and raw_key not in allowed:
+            raise ValueError(
+                f"Unsupported filter fields {[raw_key]}. Allowed fields: {sorted(allowed)}"
+            )
+        normalized[raw_key] = value
+    return normalized
+
+
+def _item_matches_where(
+    self: Any, item: dict[str, Any], where: dict[str, Any] | None
+) -> bool:
+    if not isinstance(where, dict) or not where:
+        return True
+    for key, cond in where.items():
+        value = item.get(str(key))
+        if isinstance(cond, dict):
+            if "eq" in cond and value != cond.get("eq"):
+                return False
+            if "in" in cond:
+                allowed = cond.get("in")
+                if isinstance(allowed, (list, tuple, set)) and value not in allowed:
+                    return False
+            if "contains" in cond:
+                needle = cond.get("contains")
+                if (
+                    not isinstance(value, str)
+                    or not isinstance(needle, str)
+                    or needle not in value
+                ):
+                    return False
+            if "icontains" in cond:
+                needle = cond.get("icontains")
+                if (
+                    not isinstance(value, str)
+                    or not isinstance(needle, str)
+                    or needle.lower() not in value.lower()
+                ):
+                    return False
+            if "gte" in cond:
+                left = _as_int(value)
+                right = _as_int(cond.get("gte"))
+                if left is not None and right is not None:
+                    if left < right:
+                        return False
+                else:
+                    left_dt = _as_datetime(value)
+                    right_dt = _as_datetime(cond.get("gte"))
+                    if left_dt is None or right_dt is None or left_dt < right_dt:
+                        return False
+            if "lte" in cond:
+                left = _as_int(value)
+                right = _as_int(cond.get("lte"))
+                if left is not None and right is not None:
+                    if left > right:
+                        return False
+                else:
+                    left_dt = _as_datetime(value)
+                    right_dt = _as_datetime(cond.get("lte"))
+                    if left_dt is None or right_dt is None or left_dt > right_dt:
+                        return False
+            continue
+        if isinstance(cond, (list, tuple, set)):
+            if value not in cond:
+                return False
+            continue
+        if value != cond:
+            return False
+    return True
+
+
+def _apply_where(
+    self: Any,
+    items: list[dict[str, Any]],
+    where: dict[str, Any] | None,
+    *,
+    allowed_fields: tuple[str, ...] | list[str] | set[str] | None = None,
+) -> list[dict[str, Any]]:
+    normalized_where = _normalize_where(self, where, allowed_fields=allowed_fields)
+    if not isinstance(normalized_where, dict) or not normalized_where:
+        return items
+    return [row for row in items if _item_matches_where(self, row, normalized_where)]
+
+
+def _helper_item(self: Any, resp: dict[str, Any]) -> dict[str, Any] | None:
+    item = resp.get("item")
+    if isinstance(item, dict):
+        return item
+    items = resp.get("items")
+    if isinstance(items, list) and items and isinstance(items[0], dict):
+        return items[0]
+    return None
+
+
+def _overview_count(self: Any, item: dict[str, Any] | None, key: str) -> int | None:
+    if not isinstance(item, dict):
+        return None
+    return _as_int(item.get(key))

monty_api/tool_entrypoints.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""File-based function tool entrypoints for the production Monty runtime."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_ROOT_DIR = _PACKAGE_DIR.parent
+for candidate in (_ROOT_DIR, _PACKAGE_DIR):
+    candidate_str = str(candidate)
+    if candidate_str not in sys.path:
+        sys.path.insert(0, candidate_str)
+
+from monty_api import (  # noqa: E402
+    HELPER_EXTERNALS,
+    hf_hub_query as _hf_hub_query,
+    hf_hub_query_raw as _hf_hub_query_raw,
+    main,
+)
+
+
+async def hf_hub_query(
+    code: str,
+    query: str | None = None,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
+) -> dict[str, Any]:
+    return await _hf_hub_query(
+        code=code,
+        query=query,
+        max_calls=max_calls,
+        timeout_sec=timeout_sec,
+    )
+
+
+async def hf_hub_query_raw(
+    code: str,
+    query: str | None = None,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
+) -> Any:
+    return await _hf_hub_query_raw(
+        code=code,
+        query=query,
+        max_calls=max_calls,
+        timeout_sec=timeout_sec,
+    )
+
+__all__ = [
+    "HELPER_EXTERNALS",
+    "hf_hub_query",
+    "hf_hub_query_raw",
+    "main",
+]
+
+if __name__ == "__main__":
+    raise SystemExit(main())

monty_api/validation.py

@@ -0,0 +1,376 @@
+from __future__ import annotations
+
+import ast
+import os
+import re
+import tokenize
+from io import StringIO
+from typing import Any, Callable, cast
+
+from .constants import (
+    GRAPH_SCAN_LIMIT_CAP,
+    LIKES_SCAN_LIMIT_CAP,
+    OUTPUT_ITEMS_TRUNCATION_LIMIT,
+    SELECTIVE_ENDPOINT_RETURN_HARD_CAP,
+    TRENDING_ENDPOINT_MAX_LIMIT,
+)
+from .registry import (
+    ALLOWLIST_PATTERNS,
+    HELPER_EXTERNALS,
+    STRICT_ALLOWLIST_PATTERNS,
+)
+
+
+def _resolve_helper_functions(
+    namespace: dict[str, Any],
+) -> dict[str, Callable[..., Any]]:
+    resolved: dict[str, Callable[..., Any]] = {}
+    for helper_name in HELPER_EXTERNALS:
+        candidate = namespace.get(helper_name)
+        if not callable(candidate):
+            raise RuntimeError(f"Helper '{helper_name}' is not defined or not callable")
+        resolved[helper_name] = cast(Callable[..., Any], candidate)
+    return resolved
+
+
+def _normalize_endpoint(endpoint: str) -> str:
+    ep = (endpoint or "").strip()
+    if not ep:
+        raise ValueError("endpoint is required")
+    if "?" in ep:
+        raise ValueError("endpoint must not include query string; use params")
+    if ep.startswith("http://") or ep.startswith("https://"):
+        raise ValueError("endpoint must be path-only")
+    if not ep.startswith("/"):
+        ep = "/" + ep
+    if not ep.startswith("/api/"):
+        ep = "/api" + ep
+    if ep in {"/api/collections/search", "/api/collections/search/"}:
+        ep = "/api/collections"
+    if ".." in ep:
+        raise ValueError("path traversal not allowed")
+    return ep
+
+
+def _endpoint_allowed(endpoint: str, strict_mode: bool) -> bool:
+    path = endpoint.split("?", 1)[0]
+    patterns = STRICT_ALLOWLIST_PATTERNS if strict_mode else ALLOWLIST_PATTERNS
+    return any(re.match(p, path) for p in patterns)
+
+
+def _sanitize_params(endpoint: str, params: dict[str, Any] | None) -> dict[str, Any]:
+    clean = dict(params or {})
+    path = endpoint.split("?", 1)[0]
+
+    if path == "/api/collections":
+        if "q" not in clean and "search" in clean:
+            clean["q"] = clean.get("search")
+        clean.pop("search", None)
+
+    if path == "/api/trending":
+        t = str(clean.get("type") or "").strip().lower()
+        aliases = {"models": "model", "datasets": "dataset", "spaces": "space"}
+        if t in aliases:
+            clean["type"] = aliases[t]
+        lim = clean.get("limit")
+        if lim is not None:
+            try:
+                n = int(lim)
+            except Exception:
+                n = TRENDING_ENDPOINT_MAX_LIMIT
+            clean["limit"] = max(1, min(n, TRENDING_ENDPOINT_MAX_LIMIT))
+        return clean
+
+    lim = clean.get("limit")
+    if lim is None:
+        return clean
+    try:
+        n = int(lim)
+    except Exception:
+        return clean
+
+    endpoint_limit_max = SELECTIVE_ENDPOINT_RETURN_HARD_CAP
+    if re.match(r"^/api/users/[^/]+/(followers|following)$", path):
+        endpoint_limit_max = GRAPH_SCAN_LIMIT_CAP
+    elif re.match(r"^/api/users/[^/]+/likes$", path):
+        endpoint_limit_max = LIKES_SCAN_LIMIT_CAP
+
+    clean["limit"] = max(1, min(n, endpoint_limit_max))
+    return clean
+
+
+def _truncate_result_payload(output: Any) -> Any:
+    if not isinstance(output, dict):
+        return output
+
+    items = output.get("items")
+    if not isinstance(items, list) or len(items) <= OUTPUT_ITEMS_TRUNCATION_LIMIT:
+        return output
+
+    trimmed = dict(output)
+    trimmed_items = items[:OUTPUT_ITEMS_TRUNCATION_LIMIT]
+    trimmed["items"] = trimmed_items
+    trimmed["item"] = trimmed_items[0] if len(trimmed_items) == 1 else None
+    note = f"truncated items to first {OUTPUT_ITEMS_TRUNCATION_LIMIT} rows for token efficiency"
+    steps = trimmed.get("steps")
+    if isinstance(steps, list):
+        trimmed["steps"] = [*steps, note]
+    else:
+        trimmed["steps"] = [note]
+    return trimmed
+
+
+def _verbose_result_meta_enabled() -> bool:
+    value = os.environ.get("MONTY_VERBOSE_RESULT_META", "")
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _is_helper_meta_dict(value: Any) -> bool:
+    return (
+        isinstance(value, dict)
+        and isinstance(value.get("source"), str)
+        and (
+            value.get("normalized") is True
+            or "budget_used" in value
+            or "budget_remaining" in value
+        )
+    )
+
+
+def _helper_meta_is_partial(value: dict[str, Any]) -> bool:
+    return any(
+        [
+            value.get("truncated") is True,
+            value.get("more_available") not in {False, None},
+            value.get("limit_boundary_hit") is True,
+            value.get("sample_complete") is False,
+            value.get("exact_count") is False,
+            value.get("ranking_complete") is False,
+            value.get("ranking_window_hit") is True,
+            value.get("hard_cap_applied") is True,
+        ]
+    )
+
+
+def _compact_helper_meta(value: dict[str, Any]) -> dict[str, Any]:
+    partial = _helper_meta_is_partial(value)
+    compact: dict[str, Any] = {
+        "partial": partial,
+    }
+    for key in (
+        "source",
+        "returned",
+        "total",
+        "matched",
+        "more_available",
+        "truncated",
+        "truncated_by",
+        "exact_count",
+        "sample_complete",
+        "hard_cap_applied",
+        "limit_boundary_hit",
+        "can_request_more",
+        "next_request_hint",
+        "ranking_window",
+        "ranking_window_hit",
+        "ranking_complete",
+        "ranking_next_request_hint",
+        "relation",
+        "username",
+        "organization",
+        "entity",
+        "entity_type",
+        "handle",
+    ):
+        if value.get(key) is not None:
+            compact[key] = value.get(key)
+    if compact.get("total") is None and value.get("total_available") is not None:
+        compact["total"] = value.get("total_available")
+    return compact
+
+
+def _compact_result_metadata(value: Any) -> Any:
+    if _verbose_result_meta_enabled():
+        return value
+    if _is_helper_meta_dict(value):
+        return _compact_helper_meta(value)
+    if isinstance(value, dict):
+        return {key: _compact_result_metadata(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_compact_result_metadata(item) for item in value]
+    return value
+
+
+def _is_helper_envelope(output: Any) -> bool:
+    return (
+        isinstance(output, dict)
+        and isinstance(output.get("ok"), bool)
+        and "items" in output
+        and "meta" in output
+        and "error" in output
+    )
+
+
+def _summarize_limit_hit(helper_name: str, result: Any) -> dict[str, Any] | None:
+    if not _is_helper_envelope(result):
+        return None
+    meta = result.get("meta") if isinstance(result.get("meta"), dict) else {}
+    if not isinstance(meta, dict):
+        return None
+
+    truncated_by = str(meta.get("truncated_by") or "")
+    limit_hit = any(
+        [
+            _helper_meta_is_partial(meta),
+            truncated_by in {"scan_limit", "page_limit", "multiple"},
+        ]
+    )
+    if not limit_hit:
+        return None
+
+    summary: dict[str, Any] = {
+        "helper": helper_name,
+        "source": meta.get("source"),
+        "returned": meta.get("returned"),
+        "total": meta.get("total"),
+        "truncated": meta.get("truncated"),
+        "truncated_by": meta.get("truncated_by"),
+        "more_available": meta.get("more_available"),
+        "requested_limit": meta.get("requested_limit"),
+        "applied_limit": meta.get("applied_limit"),
+        "next_request_hint": meta.get("next_request_hint"),
+        "limit_boundary_hit": meta.get("limit_boundary_hit"),
+    }
+    if meta.get("scan_limit") is not None:
+        summary["scan_limit"] = meta.get("scan_limit")
+    if meta.get("applied_max_pages") is not None:
+        summary["applied_max_pages"] = meta.get("applied_max_pages")
+    for key in (
+        "ranking_window",
+        "requested_ranking_window",
+        "ranking_window_applied",
+        "ranking_window_hit",
+        "ranking_complete",
+        "ranking_next_request_hint",
+    ):
+        if meta.get(key) is not None:
+            summary[key] = meta.get(key)
+    return summary
+
+
+def _wrap_raw_result(
+    result: Any,
+    *,
+    ok: bool,
+    api_calls: int,
+    elapsed_ms: int,
+    limit_summaries: list[dict[str, Any]] | None = None,
+    error: str | None = None,
+) -> dict[str, Any]:
+    hits = [dict(summary) for summary in (limit_summaries or [])[:10]]
+    meta: dict[str, Any] = {
+        "ok": ok,
+        "api_calls": api_calls,
+        "elapsed_ms": elapsed_ms,
+        "limits_reached": bool(hits),
+        "limit_summary": hits,
+    }
+    if error is not None:
+        meta["error"] = error
+    return {
+        "result": result,
+        "meta": meta,
+    }
+
+
+def _validate_generated_code(code: str) -> None:
+    if not code.strip():
+        raise ValueError("Generated code is empty")
+
+    blocked_patterns: list[tuple[str, str]] = [
+        (r"(?m)^\s*import\s+\S", "import statement"),
+        (r"(?m)^\s*from\s+\S+\s+import\s+\S", "from-import statement"),
+        (r"\bexec\s*\(", "exec("),
+        (r"\beval\s*\(", "eval("),
+        (r"\bopen\s*\(", "open("),
+        (r"\b__import__\b", "__import__"),
+        (r"(?i)\bwhile\s+true\b", "while true"),
+    ]
+    for pattern, label in blocked_patterns:
+        if re.search(pattern, code):
+            raise ValueError(f"Generated code contains blocked pattern: {label}")
+
+    try:
+        parsed = compile(  # noqa: S102 - compile is used for AST validation only.
+            code,
+            "<generated-monty-code>",
+            "exec",
+            flags=ast.PyCF_ONLY_AST | ast.PyCF_ALLOW_TOP_LEVEL_AWAIT,
+            dont_inherit=True,
+        )
+    except SyntaxError as e:
+        message = e.msg or "invalid syntax"
+        raise ValueError(f"Generated code is not valid Python: {message}") from e
+
+    if not isinstance(parsed, ast.Module):
+        raise ValueError("Generated code must be a Python module")
+    if not parsed.body:
+        raise ValueError("Generated code is empty")
+
+    final_stmt = parsed.body[-1]
+    final_is_result = (
+        isinstance(final_stmt, ast.Expr)
+        and isinstance(final_stmt.value, ast.Name)
+        and final_stmt.value.id == "result"
+    )
+    if not final_is_result:
+        raise ValueError(
+            "Generated code must assign the final output to `result` and end with a final line containing only `result` (do not stop after `result = ...`)."
+        )
+
+    has_result_assignment = any(
+        isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store) and node.id == "result"
+        for node in ast.walk(parsed)
+    )
+    if not has_result_assignment:
+        raise ValueError(
+            "Generated code must assign the final output to `result` before the final `result` line."
+        )
+
+    for node in ast.walk(parsed):
+        if not isinstance(node, ast.Call):
+            continue
+        if isinstance(node.func, ast.Name) and node.func.id == "call_api":
+            raise ValueError(
+                "Generated code must use documented hf_* helpers only; raw `call_api(...)` is not part of the prompt contract."
+            )
+
+    helper_name_set = set(HELPER_EXTERNALS)
+    has_external_call = any(
+        isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id in helper_name_set
+        for node in ast.walk(parsed)
+    )
+    if not has_external_call:
+        raise ValueError(
+            "Generated code must call at least one documented hf_* helper."
+        )
+
+
+def _coerce_jsonish_python_literals(code: str) -> str:
+    """Normalize common JSON literals into valid Python names in generated code."""
+    replacements = {
+        "true": "True",
+        "false": "False",
+        "null": "None",
+    }
+
+    out_tokens: list[tuple[int, str]] = []
+    for tok in tokenize.generate_tokens(StringIO(code).readline):
+        tok_type = tok.type
+        tok_str = tok.string
+        if tok_type == tokenize.NAME and tok_str in replacements:
+            tok_str = replacements[tok_str]
+        out_tokens.append((tok_type, tok_str))
+    return tokenize.untokenize(out_tokens)

tool_entrypoints.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""File-based function tool entrypoints for the production Monty runtime."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_ROOT_DIR = _PACKAGE_DIR.parent
+for candidate in (_ROOT_DIR, _PACKAGE_DIR):
+    candidate_str = str(candidate)
+    if candidate_str not in sys.path:
+        sys.path.insert(0, candidate_str)
+
+from monty_api import (  # noqa: E402
+    HELPER_EXTERNALS,
+    hf_hub_query as _hf_hub_query,
+    hf_hub_query_raw as _hf_hub_query_raw,
+    main,
+)
+
+
+async def hf_hub_query(
+    code: str,
+    query: str | None = None,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
+) -> dict[str, Any]:
+    return await _hf_hub_query(
+        code=code,
+        query=query,
+        max_calls=max_calls,
+        timeout_sec=timeout_sec,
+    )
+
+
+async def hf_hub_query_raw(
+    code: str,
+    query: str | None = None,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
+) -> Any:
+    return await _hf_hub_query_raw(
+        code=code,
+        query=query,
+        max_calls=max_calls,
+        timeout_sec=timeout_sec,
+    )
+
+__all__ = [
+    "HELPER_EXTERNALS",
+    "hf_hub_query",
+    "hf_hub_query_raw",
+    "main",
+]
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wheels/.gitkeep

@@ -0,0 +1 @@
+

wheels/fast_agent_mcp-0.7.18-py3-none-any.whl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5eea5680f3cfcaf9ead6638044570ae5bbe40a60d36f18614902453d7f65b4f5
+size 1901319