Deploy gen-ui Space bundle

.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/prefab_ui-0.13.2.dev5+a585463-py3-none-any.whl filter=lfs diff=lfs merge=lfs -text

.prefab/README.md

@@ -0,0 +1,58 @@
+# .prefab environment
+
+Dedicated Prefab UI environment for Hub search.
+
+## Purpose
+
+Keep the raw live-service contract separate from Prefab UI rendering.
+The active path is deterministic:
+
+1. generate Hub query code with the modern `.prod`-aligned Monty prompt
+2. execute it in raw mode
+3. render the runtime payload into high-quality Prefab wire JSON in Python
+
+## Cards
+
+- `agent-cards/hub_search_raw.md`
+  - raw live-style Hub search card
+  - returns runtime-owned `{result, meta}`
+
+## Runtime shape
+
+Recommended service split:
+
+- `hub_search_raw`
+  - raw JSON service
+  - no Prefab
+
+- `hub_search_prefab`
+  - Prefab UI service
+  - deterministic raw rendering
+  - no model-authored UI step
+
+## Canonical server entrypoints
+
+- `scripts/hub_search_prefab_server.py`
+- `scripts/run_hub_search_prefab_server.sh`
+
+Older `..._demo_server...` script names remain only as thin compatibility wrappers.
+
+## Removed legacy surface
+
+The older one-pass native Prefab card and the two-pass LLM UI chain were removed
+from the active `.prefab` surface. In practice they were less reliable than the
+deterministic renderer and no longer fit the simplified `.prod`-aligned design.
+
+## Runtime shims
+
+- `.prefab/monty_api/tool_entrypoints.py`
+  - thin Prefab-local shim over `.prod/monty_api/tool_entrypoints.py`
+  - mirrors the modern `.prod` runtime layout instead of the old monolithic tool-card path
+
+- `.prefab/agent-cards/_monty_codegen_shared.md`
+  - compatibility include wrapper over `.prod/agent-cards/shared/_monty_codegen_shared.md`
+  - keeps Prefab cards aligned with the live production Monty prompt
+
+- `.prefab/tool-cards/monty_api_tool_v2.py`
+  - compatibility alias to the modern Prefab-local shim
+  - retained only so older references do not break

.prefab/agent-cards/.hub_search_raw.expanded.md

@@ -0,0 +1,709 @@
+---
+type: agent
+name: hub_search_raw
+model: $system.raw
+use_history: false
+default: true
+description: "Raw live-service card for Hub search. Returns runtime-owned JSON without UI postprocessing."
+shell: false
+skills: []
+function_tools:
+  - ../monty_api/tool_entrypoints.py:hf_hub_query_raw
+request_params:
+  tool_result_mode: passthrough
+---
+
+reasoning: high
+
+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 must define `async def solve(query, max_calls): ...` and end with `await solve(query, max_calls)`.
+- Use the original user request, or a tight restatement, as the tool `query`.
+- 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 return value of `solve(...)` is the user-facing payload.
+- Return a dict/list when JSON is appropriate; return 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.
+- Do **not** rename `results` to `likes`, `liked_models`, `items`, `rows`, or similar in those composed outputs.
+- Runtime will wrap the `solve(...)` return value 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: ...}` inside `solve(...)`.
+
+Compatibility wrapper over the live `.prod` Monty prompt:
+
+## 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`.
+- Use this exact outer shape:
+
+```py
+async def solve(query, max_calls):
+    ...
+
+await solve(query, max_calls)
+```
+
+- `max_calls` is the total external-call budget for the whole program.
+- Use only documented `hf_*` helpers.
+- Return plain Python data only: `dict`, `list`, `str`, `int`, `float`, `bool`, or `None`.
+- Do **not** hand-build JSON strings or markdown strings inside `solve(...)` unless the user explicitly asked for prose.
+- Do **not** build your own transport wrapper like `{result: ..., meta: ...}`.
+- If the user says "return only" some fields, return exactly that final shape.
+- If a helper already returns the requested row shape, return `resp["items"]` directly **only when helper coverage is clearly complete**. If helper `meta` suggests partial/unknown coverage, return `{"results": resp["items"], "coverage": resp["meta"]}` instead of bare items.
+- For current-user prompts (`my`, `me`), try helpers with `username=None` / `handle=None` first.
+- If a current-user helper returns `ok=false`, return that helper response directly.
+
+## 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.
+- 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.
+- 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.
+- Owner/user/org handles may arrive with different casing in the user message; when a handle spelling is uncertain, prefer owner-oriented logic and, if needed, add fallback inside `solve(...)` that broadens to `query=...` and filters owners case-insensitively.
+- 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.
+- Keep `post_filter` simple:
+  - exact match or `in` for returned fields like `runtime_stage`
+  - `gte` / `lte` for normalized numeric fields like `num_params`, `downloads`, and `likes`
+- `num_params` is one of the main valid reasons to use `post_filter` on model search today.
+- Do **not** use `post_filter` for things that already have first-class upstream params like `author`, `pipeline_tag`, `dataset_name`, `language`, `models`, or `datasets`.
+
+Examples:
+
+```py
+await hf_models_search(pipeline_tag="text-to-image", limit=10)
+await hf_datasets_search(search="speech", sort="downloads", limit=10)
+await hf_spaces_search(post_filter={"runtime_stage": {"in": ["BUILD_ERROR", "RUNTIME_ERROR"]}})
+await hf_models_search(
+    pipeline_tag="text-generation",
+    sort="trending_score",
+    limit=50,
+    post_filter={"num_params": {"gte": 20_000_000_000, "lte": 80_000_000_000}},
+)
+await hf_collections_search(owner="Qwen", limit=10)
+```
+
+Field-only pattern:
+
+```py
+resp = await hf_models_search(
+    pipeline_tag="text-to-image",
+    fields=["repo_id", "author", "likes", "downloads", "repo_url"],
+    limit=3,
+)
+return resp["items"]
+```
+
+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"],
+)
+return {"results": resp["items"], "coverage": resp["meta"]}
+```
+
+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}:
+    return {"results": resp["items"], "coverage": {**meta, "profile_spaces_count": count}}
+return resp["items"]
+```
+
+Profile-count pattern:
+
+```py
+profile = await hf_profile_summary(handle="mishig")
+item = profile["item"] or {}
+return {
+    "followers_count": item.get("followers_count"),
+    "following_count": item.get("following_count"),
+}
+```
+
+Pro-followers pattern:
+
+```py
+followers = await hf_user_graph(
+    relation="followers",
+    pro_only=True,
+    limit=20,
+    fields=["username"],
+)
+return followers["items"]
+```
+
+## 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 / 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.
+- When helper-owned coverage matters, prefer returning the helper envelope directly.
+
+## High-signal output rules
+
+- Prefer compact dict/list outputs over prose when the user asked for fields.
+- Prefer summary helpers before detail hydration.
+- Use canonical snake_case keys in generated code and structured output.
+- Use `repo_id` as the display label for repos.
+- Use `hf_profile_summary(...)['item']` for aggregate counts such as followers, following, models, datasets, and spaces.
+- For selective one-shot search helpers, treat `meta.limit_boundary_hit=true` as a partial/unknown-coverage warning even if `meta.truncated` is still `false`.
+- 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' = 20, 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, emissions_thresholds: 'tuple[float, float] | None' = None, sort: 'str | None' = None, limit: 'int' = 20, 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' = 20, 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' = 20, 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: `20`
+  - 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`, `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: `20`
+  - 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: `20`
+  - 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: `20`
+  - 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.
+
+

.prefab/agent-cards/_monty_codegen_shared.md

@@ -1,609 +1,3 @@
-## Runtime rules for generated code
+Compatibility wrapper over the live `.prod` Monty prompt:
 
-- You **MUST NOT** use any imports.
-- All helper functions are already in scope.
-- All helper/API calls are async: always use `await`.
-- `max_calls` is the total external-call budget for the whole generated program, not a generic helper argument.
-- The outer wrapper is an exact contract. You **MUST** use this exact skeleton and only change the body:
-
-```py
-async def solve(query, max_calls):
-    ...
-    # body goes here
-
-await solve(query, max_calls)
-```
-
-- Always prefer helper functions. Use `call_api('/api/...')` only when no helper fits.
-- `call_api` must receive a raw path starting with `/api/...`; never call helper names through `call_api`.
-- `call_api(...)` returns `{ok, status, url, data, error}`. Always check `resp["ok"]` before reading `resp["data"]`. Do not read `resp["items"]` or `resp["meta"]` directly from `call_api(...)`.
-- `call_api(...)` only accepts `endpoint`, `params`, `method`, and `json_body`. Do not guess extra kwargs.
-- Use `call_api(...)` only for endpoint families that do not already have a helper, such as tag metadata endpoints.
-- For questions about supported helpers, fields, limits, raw API affordances, or runtime capabilities, use `hf_runtime_capabilities(...)` instead of hand-authoring a static answer from memory.
-- Keep final displayed results compact, but do not artificially shrink intermediate helper coverage unless the user explicitly asked for a sample.
-- Prefer canonical snake_case keys in generated code and in JSON output.
-- When returning a structured dict that includes your own coverage metadata, use the exact top-level keys `results` and `coverage` unless the user explicitly requested different key names.
-- Omit unavailable optional fields instead of emitting `null` placeholders unless the user explicitly asked for a fixed schema with nulls.
-- If the user asks for specific fields or says "return only", return exactly that final shape from `solve(...)`.
-- For current-user prompts (`my`, `me`), use helpers with `username=None` first. Only ask for identity if that fails.
-- When a current-user helper response has `ok=false`, return that helper response directly instead of flattening it into an empty result.
-
-## Common helper signature traps
-These are high-priority rules. Do not guess helper arguments.
-
-- `hf_repo_search(...)` uses `limit`, **not** `return_limit`, and does **not** accept `count_only`.
-- `hf_trending(...)` uses `limit`, **not** `return_limit`.
-- `hf_daily_papers(...)` uses `limit`, **not** `return_limit`.
-- `hf_repo_discussions(...)` uses `limit`, **not** `return_limit`.
-- `hf_user_graph(...)`, `hf_user_likes(...)`, `hf_org_members(...)`, `hf_recent_activity(...)`, and `hf_collection_items(...)` use `return_limit`.
-- `hf_profile_summary(include=...)` supports only `"likes"` and `"activity"`.
-- Do **not** guess `hf_profile_summary(include=[...])` values such as `"followers"`, `"following"`, `"models"`, `"datasets"`, or `"spaces"`.
-- `followers_count`, `following_count`, `models_count`, `datasets_count`, `spaces_count`, and similar aggregate counts already come from the base `hf_profile_summary(...)["item"]`.
-- `return_limit=None` does **not** mean exhaustive or "all rows". It means the helper uses its documented default.
-- When `count_only=True`, omit `return_limit`; count-only requests ignore row-return limits and return no items.
-- For "how many models/datasets/spaces does org/user X have?" prefer `hf_profile_summary(...)["item"]` instead of trying to count with `hf_repo_search(...)`.
-- Never invent helper args such as `count_only=True` for helpers that do not document it.
-
-## 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 only a singleton convenience.
-- `meta` contains helper-owned execution, coverage, and limit information.
-- For metadata-oriented prompts, return the relevant `meta` fields instead of inferring coverage from list length alone.
-- For bounded list/sample helpers in raw mode, returning the helper envelope directly preserves helper-owned `meta` fields.
-
-## Routing guide
-
-### Summary vs detail
-- Summary helpers are the default for list/search/trending questions: `hf_repo_search(...)`, `hf_trending(...)`, `hf_daily_papers(...)`, `hf_user_likes(...)`, `hf_recent_activity(...)`, `hf_collections_search(...)`, `hf_collection_items(...)`, `hf_org_members(...)`, `hf_user_graph(...)`.
-- Use `hf_repo_details(...)` when the user needs exact repo metadata rather than a cheap summary row.
-- Do **not** invent follow-up detail calls unless the user explicitly needs fields that are not already available in the current helper response.
-
-### Runtime self-description
-- Supported helpers / default fields / limits / raw API affordances → `hf_runtime_capabilities(...)`
-- If the question is specifically about helper defaults or cost behavior, prefer `hf_runtime_capabilities(section="helper_defaults")`.
-
-### Repo questions
-- Exact `owner/name` details → `hf_repo_details(repo_type="auto", ...)`
-- Search/discovery/list/top repos → `hf_repo_search(...)`
-- True trending requests → `hf_trending(...)`
-- Daily papers → `hf_daily_papers(...)`
-- Repo discussions → `hf_repo_discussions(...)`
-- Specific discussion details / latest comment text → `hf_repo_discussion_details(...)`
-- Users who liked a specific repo → `hf_repo_likers(...)`
-
-### User questions
-- Profile / overview / "tell me about user X" → `hf_profile_summary(...)`
-- Follower/following **counts** for a user → prefer `hf_profile_summary(...)`
-- Followers / following **lists**, graph samples, and social joins → `hf_user_graph(...)`
-- Repos a user liked → `hf_user_likes(...)`
-- Recent actions / activity feed → `hf_recent_activity(feed_type="user", entity=...)`
-
-### Organization questions
-- Organization details and counts → `hf_profile_summary(...)`
-- Organization members → `hf_org_members(...)`
-- Organization repos → `hf_repo_search(author="<org>", repo_types=[...])`
-- Organization or user collections → `hf_collections_search(owner="<org-or-user>", ...)`
-- Repos inside a known collection → `hf_collection_items(collection_id=...)`
-
-### Direction reminders
-- `hf_user_likes(...)` = **user → repos**
-- `hf_repo_likers(...)` = **repo → users**
-- `hf_user_graph(...)` = **user/org → followers/following**
-- `"who follows X"` → `hf_user_graph(username="X", relation="followers", ...)`
-- `"who does X follow"` → `hf_user_graph(username="X", relation="following", ...)`
-- If the author/org is already known, start with `hf_repo_search(author=...)` instead of semantic search.
-- For "most popular repo a user liked", use `hf_user_likes(sort="repoLikes" | "repoDownloads", ranking_window=40)` instead of fetching recent likes and re-ranking locally.
-
-### Join / intersection guidance
-- For set-intersection questions, prefer **one helper call per side + local set logic**.
-- Example: `"who in the huggingface org follows evalstate"` should use:
-  1. `hf_org_members(organization="huggingface", ...)`
-  2. `hf_user_graph(username="evalstate", relation="followers", ...)`
-  3. intersect `username` locally
-- Example: `"who in the huggingface org does evalstate follow"` should use:
-  1. `hf_org_members(organization="huggingface", ...)`
-  2. `hf_user_graph(username="evalstate", relation="following", ...)`
-  3. intersect `username` locally
-- Do **not** invert follower/following direction when restating the prompt.
-- Do **not** do one graph call per org member for these intersection questions unless you explicitly need a bounded fallback.
-
-## Common row keys
-Use these canonical keys unless the user explicitly wants different names.
-
-- Repo rows: `repo_id`, `repo_type`, `author`, `likes`, `downloads`, `created_at`, `last_modified`, `pipeline_tag`, `num_params`, `library_name`, `repo_url`, `tags`
-- Daily paper rows: `paper_id`, `title`, `published_at`, `authors`, `organization`, `repo_id`, `rank`
-- User graph/member rows: `username`, `fullname`, `isPro`, `role`, `type`
-- Activity rows: `event_type`, `repo_id`, `repo_type`, `timestamp`
-- Collection rows: `collection_id`, `slug`, `title`, `owner`, `owner_type`, `description`, `last_updated`, `item_count`
-- `hf_profile_summary(...)["item"]`: `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`, `is_pro`, `likes_sample`, `activity_sample`
-
-Common aliases in `fields=[...]` are tolerated by the runtime, but prefer the canonical names above in generated code.
-
-## Common repo fields
-- `repo_id`
-- `repo_type`
-- `author`
-- `likes`
-- `downloads`
-- `created_at`
-- `last_modified`
-- `pipeline_tag`
-- `num_params`
-- `repo_url`
-- model: `library_name`
-- dataset: `description`, `paperswithcode_id`
-- space: `sdk`, `models`, `datasets`, `subdomain`
-- trending: `trending_rank`, `trending_score` when present
-- prefer `repo_id` as the display label for repos; `title` may be absent or may just mirror `repo_id`
-
-Common aliases tolerated in `fields=[...]`:
-- `repoId` → `repo_id`
-- `repoType` → `repo_type`
-- `repoUrl` → `repo_url`
-- `createdAt` → `created_at`
-- `lastModified` → `last_modified`
-- `numParams` → `num_params`
-
-## Common collection fields
-- `collection_id`
-- `slug`
-- `title`
-- `owner`
-- `owner_type`
-- `description`
-- `last_updated`
-- `item_count`
-
-Common aliases tolerated in `fields=[...]`:
-- `collectionId` → `collection_id`
-- `lastUpdated` → `last_updated`
-- `ownerType` → `owner_type`
-- `itemCount` → `item_count`
-- `author` → `owner`
-
-## High-signal usage notes
-- `hf_repo_search(...)` defaults to models if no repo type is specified. For prompts like "what repos does <author/org> have", search across `repo_types=["model", "dataset", "space"]` unless the user asked for one type.
-- `hf_repo_search(...)` and `hf_trending(...)` are summary helpers. Use `hf_repo_details(...)` when the user explicitly needs exact repo metadata.
-- For models, datasets, and spaces, do **not** rely on a separate repo `title` field in summary outputs. Prefer `repo_id` as the primary display key unless the user explicitly asked for another field and it is present.
-- `hf_repo_search(...)` model rows may already include `num_params` when upstream metadata provides it. Use that cheap summary field before considering detail hydration.
-- `hf_trending(...)` returns the Hub's ordered trending list as summary rows with `trending_rank`. `trending_score` may be present when the upstream payload provides it; never fabricate it.
-- `hf_daily_papers(...)` is the normal path for today's daily papers. `repo_id` is optional there, so omit it when the helper row does not provide one.
-- `hf_profile_summary(...)` is the fastest way to answer common profile prompts. Read profile/social fields directly from `summary["item"]`.
-- For prompts like "how many followers do I have?" or "how many users does X follow?", prefer `hf_profile_summary(...)["item"]` for the aggregate count.
-- For prompts like "who follows me?", "who does X follow?", or any follower/following intersection, use `hf_user_graph(...)` with the correct `relation`.
-- For "how many models/datasets/spaces does user/org X have?" prompts, prefer `hf_profile_summary(...)["item"]` over `hf_repo_search(..., limit=1)` or invented `count_only` args.
-- Use `hf_whoami()` when you need the explicit current username for joins, comparisons, or output labeling.
-- For overlap/comparison/ranking/join tasks, fetch a broad enough **working set** first and compute locally in code.
-- It is good to use a larger internal working set than the final user-facing output. Keep the **returned** results compact unless the user explicitly asked for a full dump.
-- For completeness-sensitive joins over followers/members/likers, use an explicit large `return_limit` on the seed helpers rather than `return_limit=None`.
-- Good pattern: use larger limits internally for coverage, then return only the compact final intersection/ranking/projection the user asked for.
-- Avoid per-row hydration calls unless you truly need exact metadata that is not already present in the current helper response.
-- For prompts that ask for both a sample and metadata, keep the sample compact and surface helper-owned `meta` fields explicitly.
-- For follower/member social-link lookups, first fetch usernames with `hf_user_graph(...)` or `hf_org_members(...)`, then fetch profile/social data with `hf_profile_summary(handle=...)`.
-- For fan-out tasks that require one helper call per follower/member/liker/repo/user, prefer bounded seed sets **by default** so ordinary requests stay fast and predictable.
-- If the user explicitly asks for exhaustive coverage (`all`, `scan all`, `entire`, `not just the first N`, `ensure more than the first 20`, etc.), do **not** silently cap the seed at a small sample such as 20 or 50.
-- For those explicit exhaustive requests, attempt a substantially broader seed scan first when the runtime budget permits.
-- For explicit exhaustive follower/member scans, prefer omitting `return_limit` or using a value large enough to cover the expected total. Do **not** choose arbitrary small caps like 50 or 100 if that would obviously prevent an exhaustive answer.
-- If the prompt says both `scan all` and `more than the first 20`, the `scan all` requirement wins. Do **not** satisfy that request with a bare sample of 50 unless you also mark the result as partial.
-- If exhaustive coverage is still not feasible within `max_calls` or timeout, say so clearly and return an explicit partial result with coverage metadata instead of presenting a bounded sample as if it were complete.
-- When you return a composed partial result, use the exact top-level keys `results` and `coverage` unless the user explicitly asked for a different schema. Do **not** rename `results` to `items`, `rows`, `liked_models`, or similar.
-- Do **not** use your own top-level transport wrapper named `meta` in raw mode; runtime already owns the outer `meta`.
-- Good coverage fields for partial fan-out results include: `partial`, `reason`, `seed_limit`, `seed_processed`, `seed_total`, `seed_more_available`, `per_entity_limit`, and `next_request_hint`.
-- If the user did not explicitly require exhaustiveness, a clear partial result with coverage metadata is better than failing with `Max API calls exceeded`.
-- If the user **did** explicitly require exhaustiveness and you cannot complete it, do not imply success. Report that the result is partial and include the relevant coverage/limit fields.
-- For explicit exhaustive follower/member prompts, if `meta.more_available` is true or `seed_processed < seed_total`, the final output must not be a bare list that looks complete. Include explicit partial/coverage information.
-- For compact join outputs, it is fine for the internal seed helpers to use larger limits than the final returned list. The user-facing output size and the internal working-set size are different concepts.
-- Use `hf_recent_activity(...)` for activity feeds instead of raw `call_api('/api/recent-activity', ...)`.
-- Use `hf_repo_search(author=..., repo_type="space", ...)` for Spaces by author; there is no separate spaces-by-author helper.
-- Use `hf_collections_search(owner=...)` for "what collections does this org/user have?" prompts.
-- `hf_collections_search(...)` is for finding/listing collections. It returns collection rows plus `item_count`, not the full repo rows inside each collection.
-- Use `hf_collection_items(collection_id=...)` for "what repos/models/datasets/spaces are in this collection?" prompts.
-- Do **not** guess raw collection item endpoints such as `/api/collections/.../items`.
-
-## Helper API
-```py
-await hf_runtime_capabilities(section: str | None = None)
-
-await hf_profile_summary(
-  handle: str | None = None,
-  include: list[str] | None = None,
-  likes_limit: int = 10,
-  activity_limit: int = 10,
-)
-# include supports only: ["likes"], ["activity"], or ["likes", "activity"]
-# aggregate counts like followers_count / following_count / models_count are already in item
-
-await hf_org_members(
-  organization: str,
-  return_limit: int | None = None,
-  scan_limit: int | None = None,
-  count_only: bool = False,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-)
-
-await hf_repo_search(
-  query: str | None = None,
-  repo_type: str | None = None,
-  repo_types: list[str] | None = None,
-  author: str | None = None,
-  filters: list[str] | None = None,
-  sort: str | None = None,
-  limit: int = 20,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-  advanced: dict | None = None,
-)
-
-await hf_repo_details(
-  repo_id: str | None = None,
-  repo_ids: list[str] | None = None,
-  repo_type: str = "auto",
-  fields: list[str] | None = None,
-)
-
-await hf_trending(
-  repo_type: str = "model",
-  limit: int = 20,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-)
-
-await hf_daily_papers(
-  limit: int = 20,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-)
-
-await hf_user_graph(
-  username: str | None = None,
-  relation: str = "followers",
-  return_limit: int | None = None,
-  scan_limit: int | None = None,
-  count_only: bool = False,
-  pro_only: bool | None = None,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-)
-
-await hf_repo_likers(
-  repo_id: str,
-  repo_type: str,
-  return_limit: int | None = None,
-  count_only: bool = False,
-  pro_only: bool | None = None,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-)
-
-await hf_user_likes(
-  username: str | None = None,
-  repo_types: list[str] | None = None,
-  return_limit: int | None = None,
-  scan_limit: int | None = None,
-  count_only: bool = False,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-  sort: str | None = None,
-  ranking_window: int | None = None,
-)
-
-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,
-  return_limit: int | None = None,
-  max_pages: int | None = None,
-  start_cursor: str | None = None,
-  count_only: bool = False,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-)
-
-await hf_repo_discussions(repo_type: str, repo_id: str, limit: int = 20)
-await hf_repo_discussion_details(repo_type: str, repo_id: str, discussion_num: int)
-
-await hf_collections_search(
-  query: str | None = None,
-  owner: str | None = None,
-  return_limit: int = 20,
-  count_only: bool = False,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-)
-
-await hf_collection_items(
-  collection_id: str,
-  repo_types: list[str] | None = None,
-  return_limit: int = 100,
-  count_only: bool = False,
-  where: dict | None = None,
-  fields: list[str] | None = None,
-)
-
-await hf_whoami()
-await call_api(endpoint: str, params: dict | None = None, method: str = "GET", json_body: dict | None = None)
-```
-
-## Minimal patterns
-```py
-# Exact repo details
-info = await hf_repo_details(
-    repo_id="black-forest-labs/FLUX.1-dev",
-    repo_type="auto",
-    fields=["repo_id", "repo_type", "author", "pipeline_tag", "library_name", "num_params", "likes", "downloads", "repo_url"],
-)
-item = info["item"] or (info["items"][0] if info["items"] else None)
-return {
-    "repo_id": item["repo_id"],
-    "repo_type": item["repo_type"],
-    "author": item["author"],
-    "pipeline_tag": item.get("pipeline_tag"),
-    "library_name": item.get("library_name"),
-    "num_params": item.get("num_params"),
-    "likes": item.get("likes"),
-    "downloads": item.get("downloads"),
-    "repo_url": item.get("repo_url"),
-}
-
-# Runtime capability / supported-field introspection
-caps = await hf_runtime_capabilities(section="fields")
-if not caps["ok"]:
-    return caps
-item = caps["item"] or (caps["items"][0] if caps["items"] else None)
-return item["content"]
-
-# Compact profile summary
-summary = await hf_profile_summary(
-    handle="mishig",
-    include=["likes", "activity"],
-    likes_limit=10,
-    activity_limit=10,
-)
-item = summary["item"] or (summary["items"][0] if summary["items"] else None)
-return {
-    "followers_count": item["followers_count"],
-    "following_count": item.get("following_count"),
-    "activity_sample": item.get("activity_sample", []),
-    "likes_sample": item.get("likes_sample", []),
-}
-
-# Current user's pro followers and their recent liked repos
-followers = await hf_user_graph(
-    relation="followers",
-    pro_only=True,
-    fields=["username"],
-)
-if not followers["ok"]:
-    return followers
-result = {}
-for row in followers["items"]:
-    uname = row.get("username")
-    if not uname:
-        continue
-    likes = await hf_user_likes(
-        username=uname,
-        return_limit=3,
-        fields=["repo_id", "repo_type", "liked_at", "repo_url"],
-    )
-    repos = []
-    for item in likes["items"]:
-        repo = {}
-        for key in ["repo_id", "repo_type", "liked_at", "repo_url"]:
-            if item.get(key) is not None:
-                repo[key] = item[key]
-        if repo:
-            repos.append(repo)
-    if repos:
-        result[uname] = repos
-return result
-
-# Fan-out query with bounded partial coverage metadata
-followers = await hf_user_graph(
-    relation="followers",
-    return_limit=20,
-    fields=["username"],
-)
-if not followers["ok"]:
-    return followers
-result = {}
-processed = 0
-for row in followers["items"]:
-    uname = row.get("username")
-    if not uname:
-        continue
-    likes = await hf_user_likes(
-        username=uname,
-        repo_types=["model"],
-        return_limit=3,
-        fields=["repo_id", "repo_author", "liked_at"],
-    )
-    processed += 1
-    items = []
-    for item in likes["items"]:
-        liked = {}
-        for key in ["repo_id", "repo_author", "liked_at"]:
-            if item.get(key) is not None:
-                liked[key] = item[key]
-        if liked:
-            items.append(liked)
-    if items:
-        result[uname] = items
-return {
-    "results": result,
-    "coverage": {
-        "partial": bool(followers["meta"].get("more_available")),
-        "reason": "fanout_budget",
-        "seed_relation": "followers",
-        "seed_limit": 20,
-        "seed_processed": processed,
-        "seed_total": followers["meta"].get("total"),
-        "seed_more_available": followers["meta"].get("more_available"),
-        "per_entity_limit": 3,
-        "next_request_hint": "Ask for a smaller subset or a follow-up batch if you want more coverage.",
-    },
-}
-
-# Popularity-ranked likes with metadata
-likes = await hf_user_likes(
-    username="julien-c",
-    return_limit=1,
-    sort="repoLikes",
-    ranking_window=40,
-    fields=["repo_id", "repo_type", "repo_author", "likes", "repo_url", "liked_at"],
-)
-item = likes["item"] or (likes["items"][0] if likes["items"] else None)
-if item is None:
-    return {"error": "No liked repositories found"}
-repo = {}
-for key in ["repo_id", "repo_type", "repo_author", "likes", "repo_url", "liked_at"]:
-    if item.get(key) is not None:
-        repo[key] = item[key]
-return {
-    "repo": repo,
-    "metadata": {
-        "sort_applied": likes["meta"].get("sort_applied"),
-        "ranking_window": likes["meta"].get("ranking_window"),
-        "ranking_complete": likes["meta"].get("ranking_complete"),
-    },
-}
-
-# Recent activity with compact snake_case rows
-activity = await hf_recent_activity(
-    feed_type="user",
-    entity="mishig",
-    return_limit=15,
-    fields=["event_type", "repo_id", "repo_type", "timestamp"],
-)
-result = []
-for row in activity["items"]:
-    item = {}
-    for key in ["event_type", "repo_id", "repo_type", "timestamp"]:
-        if row.get(key) is not None:
-            item[key] = row[key]
-    if item:
-        result.append(item)
-return result
-
-# Repo discussions
-rows = await hf_repo_discussions(
-    repo_type="model",
-    repo_id="Qwen/Qwen3.5-35B-A3B",
-    limit=10,
-)
-return [
-    {
-        "num": row["num"],
-        "title": row["title"],
-        "author": row["author"],
-        "status": row["status"],
-    }
-    for row in rows["items"]
-]
-
-# Collections owned by an org or user
-collections = await hf_collections_search(
-    owner="Qwen",
-    return_limit=20,
-    fields=["collection_id", "title", "owner", "description", "last_updated", "item_count"],
-)
-return collections["items"]
-
-# Daily papers via the helper
-papers = await hf_daily_papers(
-    limit=20,
-    fields=["title", "repo_id"],
-)
-return papers["items"]
-
-# Organization repo counts
-org = await hf_profile_summary("unsloth")
-item = org["item"] or (org["items"][0] if org["items"] else None)
-return {
-    "organization": item["handle"],
-    "models_count": item.get("models_count"),
-    "datasets_count": item.get("datasets_count"),
-    "spaces_count": item.get("spaces_count"),
-}
-
-# Do any authors of the top trending spaces follow me?
-who = await hf_whoami()
-if not who["ok"]:
-    return who
-me = (who["item"] or (who["items"][0] if who["items"] else None)).get("username")
-spaces = await hf_trending(
-    repo_type="space",
-    limit=20,
-    fields=["repo_id", "author", "repo_url"],
-)
-authors = []
-seen = set()
-for row in spaces["items"]:
-    author = row.get("author")
-    if isinstance(author, str) and author and author not in seen:
-        seen.add(author)
-        authors.append(author)
-
-results = []
-processed = 0
-for author in authors[:20]:
-    graph = await hf_user_graph(
-        username=author,
-        relation="following",
-        return_limit=200,
-        fields=["username"],
-    )
-    processed += 1
-    if not graph["ok"]:
-        continue
-    if any(item.get("username") == me for item in graph["items"]):
-        results.append(author)
-
-return {
-    "results": results,
-    "coverage": {
-        "partial": False,
-        "reason": None,
-        "seed_relation": "trending_space_authors",
-        "seed_limit": 20,
-        "seed_processed": processed,
-        "seed_total": len(authors),
-        "seed_more_available": False,
-        "per_entity_limit": 200,
-    },
-}
-
-# Models inside an org's collections
-collections = await hf_collections_search(
-    owner="openai",
-    return_limit=20,
-    fields=["collection_id", "title"],
-)
-result = {}
-for coll in collections["items"]:
-    collection_id = coll.get("collection_id")
-    title = coll.get("title") or collection_id
-    if not collection_id:
-        continue
-    items = await hf_collection_items(
-        collection_id=collection_id,
-        repo_types=["model"],
-        fields=["repo_id", "repo_type", "repo_url"],
-    )
-    if items["items"]:
-        result[title] = items["items"]
-return result
-```
+{{file:.prod/agent-cards/shared/_monty_codegen_shared.md}}

.prefab/agent-cards/_prefab_wire_shared.md

@@ -181,6 +181,46 @@ Prefer:
 - structure over decoration
 - a few confident sections over many tiny widgets
 - built-in variants over custom color classes
+- app-like restraint over marketing chrome
+- a strong primary workspace over a wall of cards
+
+## Frontend-friendly defaults
+
+Bias toward calm product UI rather than raw data dumps.
+
+Prefer these compositions:
+- search / browse pages:
+  - one summary card or slim header row
+  - optional KPI grid (`Grid` + `Metric`) for 2-4 headline numbers
+  - one main results surface, usually `DataTable`
+- grouped counts / proportions:
+  - split layout with a donut `PieChart` and a compact `DataTable`
+- forms / filters:
+  - short option lists → `Select`
+  - long option lists or tags / categories → `Combobox`
+  - multi-value tags / categories → `MultiSelect`
+  - model-driven forms should feel like compact operator UI, not generic CRUD dumps
+
+For tables:
+- if there are more than ~8 rows, prefer `search: true`
+- if there are more than ~10 rows, prefer `paginated: true` with a sensible `pageSize`
+- if a numeric column is clearly a metric, align it right and use `format: "number"`
+- if a short categorical column should work like a facet (tags, repo type, status), set `DataTableColumn.filterable: true`
+- hide long raw URL columns when `onRowClick` or action buttons communicate the destination better
+
+For charts:
+- use donut charts for 2-8 grouped categories with one obvious label key and one obvious numeric key
+- prefer `innerRadius: 60`, `paddingAngle: 2`, `showLegend: true`, `showTooltip: true`
+- when combining charts and tables, usually stack the chart above the table rather than placing them side-by-side, because tables are wide and charts stay legible in a narrower vertical slot
+- only use a horizontal chart+table split when both are compact and the table has very few columns
+- avoid charts when the answer is just a long ranking table
+
+Avoid:
+- giant dashboards made of many small cards
+- decorative heroes, gradient marketing sections, or center-column landing-page layouts
+- repeated `Separator` stacks where a `Card`, `Tabs`, or `Grid` would create clearer hierarchy
+- noisy badge soup; badges should be short and sparse
+- dumping every field just because it exists
 
 If `theme` is omitted, the default renderer styling should look mostly good out of the box.
 Do not hand-author lots of colors unless the user explicitly asks for branding.
@@ -253,6 +293,9 @@ Prefer this palette first:
 - `PieChart`
 - `LineChart`
 - `BarChart`
+- `Select`
+- `Combobox`
+- `MultiSelect`
 
 Useful but secondary:
 - `ButtonGroup`
@@ -438,6 +481,7 @@ For Hugging Face Hub-style results, these defaults are especially good:
 
 For Hub search/navigation results:
 - preserve important names, ids, counts, dates, and URLs exactly from the payload
+- avatar urls should be displayed as icons
 - do not invent values or smooth over missing fields
 - highlight a few useful summary metrics before the full table
 - preserve ranking/order clearly when ranking matters

.prefab/agent-cards/hub_search_raw.md

@@ -8,7 +8,7 @@ description: "Raw live-service card for Hub search. Returns runtime-owned JSON w
 shell: false
 skills: []
 function_tools:
-  - ../tool-cards/monty_api_tool_v2.py:hf_hub_query_raw
+  - ../monty_api/tool_entrypoints.py:hf_hub_query_raw
 request_params:
   tool_result_mode: passthrough
 ---

.prefab/fastagent.config.yaml

@@ -3,9 +3,7 @@ default_model: "$system.raw"
 model_references:
   system:
     default: "$system.raw"
-    raw: hf.openai/gpt-oss-120b:sambanova
-    prefab_native: minimax25
-    prefab_llm: gpt-oss
+    raw: qwen35instruct
 
 logger:
   truncate_tools: false

.prefab/monty_api/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from .tool_entrypoints import HELPER_EXTERNALS, hf_hub_query, hf_hub_query_raw, main
+
+__all__ = [
+    "HELPER_EXTERNALS",
+    "hf_hub_query",
+    "hf_hub_query_raw",
+    "main",
+]

.prefab/monty_api/tool_entrypoints.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Prefab-local shim over the live production Monty entrypoints."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from typing import Any
+
+_SOURCE = (
+    Path(__file__).resolve().parents[2]
+    / ".prod"
+    / "monty_api"
+    / "tool_entrypoints.py"
+)
+_SPEC = importlib.util.spec_from_file_location("_prefab_prod_tool_entrypoints", _SOURCE)
+if _SPEC is None or _SPEC.loader is None:
+    raise RuntimeError(f"could not load source tool entrypoints from {_SOURCE}")
+
+_MODULE = importlib.util.module_from_spec(_SPEC)
+_SPEC.loader.exec_module(_MODULE)
+
+HELPER_EXTERNALS = _MODULE.HELPER_EXTERNALS
+main = _MODULE.main
+
+
+async def hf_hub_query(
+    query: str,
+    code: str,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
+) -> dict[str, Any]:
+    return await _MODULE.hf_hub_query(
+        query=query,
+        code=code,
+        max_calls=max_calls,
+        timeout_sec=timeout_sec,
+    )
+
+
+async def hf_hub_query_raw(
+    query: str,
+    code: str,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
+) -> Any:
+    return await _MODULE.hf_hub_query_raw(
+        query=query,
+        code=code,
+        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())

.prefab/tool-cards/monty_api_tool_v2.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from typing import Any
 
 _SOURCE = (
-    Path(__file__).resolve().parents[2] / ".prod" / "tool-cards" / "monty_api_tool_v2.py"
+    Path(__file__).resolve().parents[1] / "monty_api" / "tool_entrypoints.py"
 )
 _SPEC = importlib.util.spec_from_file_location("_prefab_monty_api_tool_v2", _SOURCE)
 if _SPEC is None or _SPEC.loader is None:
@@ -14,12 +14,15 @@ if _SPEC is None or _SPEC.loader is None:
 _MODULE = importlib.util.module_from_spec(_SPEC)
 _SPEC.loader.exec_module(_MODULE)
 
+HELPER_EXTERNALS = _MODULE.HELPER_EXTERNALS
+main = _MODULE.main
+
 
 async def hf_hub_query(
     query: str,
     code: str,
-    max_calls: int | None = _MODULE.DEFAULT_MAX_CALLS,
-    timeout_sec: int | None = _MODULE.DEFAULT_TIMEOUT_SEC,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
 ) -> dict[str, Any]:
     return await _MODULE.hf_hub_query(
         query=query,
@@ -32,8 +35,8 @@ async def hf_hub_query(
 async def hf_hub_query_raw(
     query: str,
     code: str,
-    max_calls: int | None = _MODULE.DEFAULT_MAX_CALLS,
-    timeout_sec: int | None = _MODULE.DEFAULT_TIMEOUT_SEC,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
 ) -> Any:
     return await _MODULE.hf_hub_query_raw(
         query=query,
@@ -41,3 +44,14 @@ async def hf_hub_query_raw(
         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())

.prod/agent-cards/shared/_monty_codegen_shared.md

@@ -0,0 +1,666 @@
+## 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`.
+- Use this exact outer shape:
+
+```py
+async def solve(query, max_calls):
+    ...
+
+await solve(query, max_calls)
+```
+
+- `max_calls` is the total external-call budget for the whole program.
+- Use only documented `hf_*` helpers.
+- Return plain Python data only: `dict`, `list`, `str`, `int`, `float`, `bool`, or `None`.
+- Do **not** hand-build JSON strings or markdown strings inside `solve(...)` unless the user explicitly asked for prose.
+- Do **not** build your own transport wrapper like `{result: ..., meta: ...}`.
+- If the user says "return only" some fields, return exactly that final shape.
+- If a helper already returns the requested row shape, return `resp["items"]` directly **only when helper coverage is clearly complete**. If helper `meta` suggests partial/unknown coverage, return `{"results": resp["items"], "coverage": resp["meta"]}` instead of bare items.
+- For current-user prompts (`my`, `me`), try helpers with `username=None` / `handle=None` first.
+- If a current-user helper returns `ok=false`, return that helper response directly.
+
+## 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.
+- 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.
+- 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.
+- Owner/user/org handles may arrive with different casing in the user message; when a handle spelling is uncertain, prefer owner-oriented logic and, if needed, add fallback inside `solve(...)` that broadens to `query=...` and filters owners case-insensitively.
+- 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.
+- Keep `post_filter` simple:
+  - exact match or `in` for returned fields like `runtime_stage`
+  - `gte` / `lte` for normalized numeric fields like `num_params`, `downloads`, and `likes`
+- `num_params` is one of the main valid reasons to use `post_filter` on model search today.
+- Do **not** use `post_filter` for things that already have first-class upstream params like `author`, `pipeline_tag`, `dataset_name`, `language`, `models`, or `datasets`.
+
+Examples:
+
+```py
+await hf_models_search(pipeline_tag="text-to-image", limit=10)
+await hf_datasets_search(search="speech", sort="downloads", limit=10)
+await hf_spaces_search(post_filter={"runtime_stage": {"in": ["BUILD_ERROR", "RUNTIME_ERROR"]}})
+await hf_models_search(
+    pipeline_tag="text-generation",
+    sort="trending_score",
+    limit=50,
+    post_filter={"num_params": {"gte": 20_000_000_000, "lte": 80_000_000_000}},
+)
+await hf_collections_search(owner="Qwen", limit=10)
+```
+
+Field-only pattern:
+
+```py
+resp = await hf_models_search(
+    pipeline_tag="text-to-image",
+    fields=["repo_id", "author", "likes", "downloads", "repo_url"],
+    limit=3,
+)
+return resp["items"]
+```
+
+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"],
+)
+return {"results": resp["items"], "coverage": resp["meta"]}
+```
+
+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}:
+    return {"results": resp["items"], "coverage": {**meta, "profile_spaces_count": count}}
+return resp["items"]
+```
+
+Profile-count pattern:
+
+```py
+profile = await hf_profile_summary(handle="mishig")
+item = profile["item"] or {}
+return {
+    "followers_count": item.get("followers_count"),
+    "following_count": item.get("following_count"),
+}
+```
+
+Pro-followers pattern:
+
+```py
+followers = await hf_user_graph(
+    relation="followers",
+    pro_only=True,
+    limit=20,
+    fields=["username"],
+)
+return followers["items"]
+```
+
+## 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 / 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.
+- When helper-owned coverage matters, prefer returning the helper envelope directly.
+
+## High-signal output rules
+
+- Prefer compact dict/list outputs over prose when the user asked for fields.
+- Prefer summary helpers before detail hydration.
+- Use canonical snake_case keys in generated code and structured output.
+- Use `repo_id` as the display label for repos.
+- Use `hf_profile_summary(...)['item']` for aggregate counts such as followers, following, models, datasets, and spaces.
+- For selective one-shot search helpers, treat `meta.limit_boundary_hit=true` as a partial/unknown-coverage warning even if `meta.truncated` is still `false`.
+- 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' = 20, 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, emissions_thresholds: 'tuple[float, float] | None' = None, sort: 'str | None' = None, limit: 'int' = 20, 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' = 20, 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' = 20, 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: `20`
+  - 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`, `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: `20`
+  - 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: `20`
+  - 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: `20`
+  - 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.

.prod/agent-cards/shared/_monty_codegen_shared.template.md

@@ -0,0 +1,200 @@
+## 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`.
+- Use this exact outer shape:
+
+```py
+async def solve(query, max_calls):
+    ...
+
+await solve(query, max_calls)
+```
+
+- `max_calls` is the total external-call budget for the whole program.
+- Use only documented `hf_*` helpers.
+- Return plain Python data only: `dict`, `list`, `str`, `int`, `float`, `bool`, or `None`.
+- Do **not** hand-build JSON strings or markdown strings inside `solve(...)` unless the user explicitly asked for prose.
+- Do **not** build your own transport wrapper like `{result: ..., meta: ...}`.
+- If the user says "return only" some fields, return exactly that final shape.
+- If a helper already returns the requested row shape, return `resp["items"]` directly **only when helper coverage is clearly complete**. If helper `meta` suggests partial/unknown coverage, return `{"results": resp["items"], "coverage": resp["meta"]}` instead of bare items.
+- For current-user prompts (`my`, `me`), try helpers with `username=None` / `handle=None` first.
+- If a current-user helper returns `ok=false`, return that helper response directly.
+
+## 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.
+- 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.
+- 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.
+- Owner/user/org handles may arrive with different casing in the user message; when a handle spelling is uncertain, prefer owner-oriented logic and, if needed, add fallback inside `solve(...)` that broadens to `query=...` and filters owners case-insensitively.
+- 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.
+- Keep `post_filter` simple:
+  - exact match or `in` for returned fields like `runtime_stage`
+  - `gte` / `lte` for normalized numeric fields like `num_params`, `downloads`, and `likes`
+- `num_params` is one of the main valid reasons to use `post_filter` on model search today.
+- Do **not** use `post_filter` for things that already have first-class upstream params like `author`, `pipeline_tag`, `dataset_name`, `language`, `models`, or `datasets`.
+
+Examples:
+
+```py
+await hf_models_search(pipeline_tag="text-to-image", limit=10)
+await hf_datasets_search(search="speech", sort="downloads", limit=10)
+await hf_spaces_search(post_filter={"runtime_stage": {"in": ["BUILD_ERROR", "RUNTIME_ERROR"]}})
+await hf_models_search(
+    pipeline_tag="text-generation",
+    sort="trending_score",
+    limit=50,
+    post_filter={"num_params": {"gte": 20_000_000_000, "lte": 80_000_000_000}},
+)
+await hf_collections_search(owner="Qwen", limit=10)
+```
+
+Field-only pattern:
+
+```py
+resp = await hf_models_search(
+    pipeline_tag="text-to-image",
+    fields=["repo_id", "author", "likes", "downloads", "repo_url"],
+    limit=3,
+)
+return resp["items"]
+```
+
+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"],
+)
+return {"results": resp["items"], "coverage": resp["meta"]}
+```
+
+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}:
+    return {"results": resp["items"], "coverage": {**meta, "profile_spaces_count": count}}
+return resp["items"]
+```
+
+Profile-count pattern:
+
+```py
+profile = await hf_profile_summary(handle="mishig")
+item = profile["item"] or {}
+return {
+    "followers_count": item.get("followers_count"),
+    "following_count": item.get("following_count"),
+}
+```
+
+Pro-followers pattern:
+
+```py
+followers = await hf_user_graph(
+    relation="followers",
+    pro_only=True,
+    limit=20,
+    fields=["username"],
+)
+return followers["items"]
+```
+
+## 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 / 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.
+- When helper-owned coverage matters, prefer returning the helper envelope directly.
+
+## High-signal output rules
+
+- Prefer compact dict/list outputs over prose when the user asked for fields.
+- Prefer summary helpers before detail hydration.
+- Use canonical snake_case keys in generated code and structured output.
+- Use `repo_id` as the display label for repos.
+- Use `hf_profile_summary(...)['item']` for aggregate counts such as followers, following, models, datasets, and spaces.
+- For selective one-shot search helpers, treat `meta.limit_boundary_hit=true` as a partial/unknown-coverage warning even if `meta.truncated` is still `false`.
+- 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`.
+
+{{GENERATED_HELPER_SIGNATURES}}
+
+{{GENERATED_HELPER_CONTRACTS}}

.prod/agent-cards/shared/_monty_helper_contracts.md

@@ -0,0 +1,424 @@
+## 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: `20`
+  - 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`, `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: `20`
+  - 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: `20`
+  - 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: `20`
+  - 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.

.prod/agent-cards/shared/_monty_helper_signatures.md

@@ -0,0 +1,44 @@
+## 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' = 20, 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, emissions_thresholds: 'tuple[float, float] | None' = None, sort: 'str | None' = None, limit: 'int' = 20, 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' = 20, 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' = 20, 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]'
+```

.prod/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",
+]

.prod/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",
+    },
+}

.prod/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",
+)

.prod/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: ...

.prod/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"

.prod/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",
+]

.prod/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)}

.prod/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),
+    }

.prod/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

.prod/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)}

.prod/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),
+    }

.prod/monty_api/helpers/repos.py

@@ -0,0 +1,1359 @@
+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 {"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", 20)
+    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,
+    emissions_thresholds: tuple[float, float] | None = None,
+    sort: str | None = None,
+    limit: int = 20,
+    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,
+                "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 = 20,
+    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 = 20,
+    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 = 20,
+    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),
+    }

.prod/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}",
+        }

.prod/monty_api/query_entrypoints.py

@@ -0,0 +1,388 @@
+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,
+    _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 _log_generated_query(
+    *, query: str, code: str, max_calls: int | None, timeout_sec: int | None
+) -> None:
+    if not _query_debug_enabled():
+        return
+    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,
+    max_calls: int,
+    strict_mode: bool,
+    timeout_sec: int,
+) -> dict[str, Any]:
+    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:
+            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)
+            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:
+        result = await pydantic_monty.run_monty_async(
+            m,
+            inputs={"query": query, "max_calls": max_calls},
+            external_functions={
+                name: _collecting_wrapper(name, fn)
+                for name, fn in env.helper_functions.items()
+            },
+            limits=limits,
+        )
+    except Exception as 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,
+    code: str,
+    max_calls: int | None,
+    timeout_sec: int | None,
+) -> tuple[str, str, int, int]:
+    if not query or not query.strip():
+        raise ValueError("query is required")
+    if not code or not code.strip():
+        raise ValueError("code is required")
+
+    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 query, normalized_code, normalized_max_calls, normalized_timeout_sec
+
+
+async def _execute_query(
+    *,
+    query: str,
+    code: str,
+    max_calls: int | None,
+    timeout_sec: int | None,
+) -> dict[str, Any]:
+    prepared_query, prepared_code, prepared_max_calls, prepared_timeout = (
+        _prepare_query_inputs(
+            query=query,
+            code=code,
+            max_calls=max_calls,
+            timeout_sec=timeout_sec,
+        )
+    )
+    _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(
+    query: str,
+    code: str,
+    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": 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(
+    query: str,
+    code: str,
+    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 direct ``solve(...)`` output 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(
+            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", required=True, help="Natural language query")
+    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(
+                query=args.query,
+                code=code,
+                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

.prod/monty_api/registry.py

@@ -0,0 +1,681 @@
+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",
+        "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=20,
+            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": 20, "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=20,
+            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": 20, "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=20,
+            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": 20, "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=20,
+            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": 20, "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"
+    ),
+}

.prod/monty_api/runtime_context.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, NamedTuple, cast
+
+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]]
+
+
+@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)
+        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),
+                )
+            return resp
+        except Exception as exc:
+            self._trace_err(idx, endpoint, exc, method=method, status=0)
+            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("/")
+            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")
+        try:
+            out = fn()
+            self._trace_ok(idx, endpoint, method="GET", status=200)
+            return out
+        except Exception as exc:
+            self._trace_err(idx, endpoint, exc, method="GET", status=0)
+            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")
+        return await cast(Callable[..., Any], fn)(*args, **kwargs)
+
+
+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,
+    )

.prod/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

.prod/monty_api/runtime_filtering.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+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 _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 None or right is None or left < right:
+                    return False
+            if "lte" in cond:
+                left = _as_int(value)
+                right = _as_int(cond.get("lte"))
+                if left is None or right is None or left > right:
+                    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))

.prod/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(
+    query: str,
+    code: str,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
+) -> dict[str, Any]:
+    return await _hf_hub_query(
+        query=query,
+        code=code,
+        max_calls=max_calls,
+        timeout_sec=timeout_sec,
+    )
+
+
+async def hf_hub_query_raw(
+    query: str,
+    code: str,
+    max_calls: int | None = None,
+    timeout_sec: int | None = None,
+) -> Any:
+    return await _hf_hub_query_raw(
+        query=query,
+        code=code,
+        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())

.prod/monty_api/validation.py

@@ -0,0 +1,322 @@
+from __future__ import annotations
+
+import ast
+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 _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(
+        [
+            meta.get("truncated") is True,
+            meta.get("hard_cap_applied") is True,
+            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")
+
+    solve_defs = [
+        node
+        for node in parsed.body
+        if isinstance(node, ast.AsyncFunctionDef) and node.name == "solve"
+    ]
+    if not solve_defs:
+        raise ValueError(
+            "Generated code must define `async def solve(query, max_calls): ...`."
+        )
+
+    def _valid_solve_signature(node: ast.AsyncFunctionDef) -> bool:
+        args = node.args
+        return (
+            not args.posonlyargs
+            and len(args.args) == 2
+            and [arg.arg for arg in args.args] == ["query", "max_calls"]
+            and args.vararg is None
+            and not args.kwonlyargs
+            and args.kwarg is None
+            and not args.defaults
+            and not args.kw_defaults
+        )
+
+    if not any(_valid_solve_signature(node) for node in solve_defs):
+        raise ValueError(
+            "`solve` must have signature `async def solve(query, max_calls): ...`."
+        )
+
+    if not parsed.body:
+        raise ValueError("Generated code is empty")
+
+    final_stmt = parsed.body[-1]
+    valid_final_await = (
+        isinstance(final_stmt, ast.Expr)
+        and isinstance(final_stmt.value, ast.Await)
+        and isinstance(final_stmt.value.value, ast.Call)
+        and isinstance(final_stmt.value.value.func, ast.Name)
+        and final_stmt.value.value.func.id == "solve"
+        and len(final_stmt.value.value.args) == 2
+        and not final_stmt.value.value.keywords
+        and all(isinstance(arg, ast.Name) for arg in final_stmt.value.value.args)
+        and [cast(ast.Name, arg).id for arg in final_stmt.value.value.args]
+        == ["query", "max_calls"]
+    )
+    if not valid_final_await:
+        raise ValueError(
+            "Generated code must end with `await solve(query, max_calls)`."
+        )
+
+    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)

Dockerfile

@@ -11,11 +11,13 @@ 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 \
-    fast-agent-mcp==0.6.1 \
-    prefab-ui \
+    "fast-agent-mcp==0.6.1" \
+    /tmp/wheels/prefab_ui-0.13.2.dev5+a585463-py3-none-any.whl \
     huggingface_hub \
-    pydantic-monty
+    "pydantic-monty==0.0.8"
 
 COPY --link ./ /app
 RUN chown -R 1000:1000 /app

scripts/card_includes.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_FILE_PLACEHOLDER_RE = re.compile(r"\{\{file:([^}]+)\}\}")
+
+
+
+def expand_file_placeholders(
+    text: str,
+    *,
+    workspace_root: Path,
+    seen: set[Path] | None = None,
+) -> str:
+    workspace_root = workspace_root.resolve()
+    active = set() if seen is None else set(seen)
+
+    def replace(match: re.Match[str]) -> str:
+        raw_ref = match.group(1).strip()
+        include_path = Path(raw_ref)
+        if not include_path.is_absolute():
+            include_path = workspace_root / include_path
+        include_path = include_path.resolve()
+        if include_path in active:
+            raise ValueError(f"cyclic {{file:...}} include detected at {include_path}")
+        included = include_path.read_text(encoding="utf-8")
+        return expand_file_placeholders(
+            included,
+            workspace_root=workspace_root,
+            seen={*active, include_path},
+        )
+
+    return _FILE_PLACEHOLDER_RE.sub(replace, text)
+
+
+
+def materialize_expanded_card(
+    card_path: Path,
+    *,
+    workspace_root: Path,
+    out_dir: Path,
+) -> Path:
+    card_path = card_path.resolve()
+    expanded = expand_file_placeholders(
+        card_path.read_text(encoding="utf-8"),
+        workspace_root=workspace_root,
+        seen={card_path},
+    )
+    out_dir.mkdir(parents=True, exist_ok=True)
+    output_path = out_dir / f".{card_path.stem}.expanded{card_path.suffix}"
+    output_path.write_text(expanded, encoding="utf-8")
+    return output_path

scripts/hub_search_prefab_server.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+# ruff: noqa: E402
+
 import json
 import os
 import sys
@@ -10,6 +12,7 @@ from starlette.middleware import Middleware
 from starlette.middleware.cors import CORSMiddleware
 from starlette.responses import PlainTextResponse
 
+
 def _discover_workspace_root() -> Path:
     env_root = os.getenv("CODE_TOOLS_ROOT")
     if env_root:
@@ -29,13 +32,8 @@ SCRIPTS_DIR = Path(__file__).resolve().parent
 CARDS_DIR = PREFAB_ROOT / "agent-cards"
 CONFIG_PATH = PREFAB_ROOT / "fastagent.config.yaml"
 RAW_CARD_FILE = CARDS_DIR / "hub_search_raw.md"
-PREFAB_NATIVE_CARD_FILE = CARDS_DIR / "hub_search_prefab_native.md"
-PREFAB_LLM_RAW_CARD_FILE = CARDS_DIR / "hub_search_prefab_llm_raw.md"
-PREFAB_LLM_CODEGEN_CARD_FILE = CARDS_DIR / "hub_search_prefab_llm_codegen.md"
-PREFAB_LLM_CHAIN_CARD_FILE = CARDS_DIR / "hub_search_prefab_llm_chain.md"
+EXPANDED_CARDS_DIR = CARDS_DIR
 RAW_AGENT = "hub_search_raw"
-PREFAB_NATIVE_AGENT = "hub_search_prefab_native"
-PREFAB_LLM_CHAIN_AGENT = "hub_search_prefab_llm_chain"
 
 HOST = os.getenv("HOST", "0.0.0.0")
 PORT = int(os.getenv("PORT", "9999"))
@@ -66,12 +64,8 @@ from fastmcp.server.dependencies import get_access_token
 from fastmcp.tools import ToolResult
 from mcp.types import TextContent
 from pydantic import AnyHttpUrl
-from prefab_hub_ui import (
-    build_runtime_wire,
-    error_wire,
-    parse_passthrough_wire,
-    parse_runtime_payload,
-)
+from card_includes import materialize_expanded_card
+from prefab_hub_ui import build_runtime_wire, error_wire, parse_runtime_payload
 
 
 class _RootResourceRemoteAuthProvider(RemoteAuthProvider):
@@ -82,6 +76,7 @@ class _RootResourceRemoteAuthProvider(RemoteAuthProvider):
         return self.base_url
 
 
+
 def _get_oauth_config() -> tuple[str | None, list[str], str]:
     oauth_provider = os.environ.get("FAST_AGENT_SERVE_OAUTH", "").lower()
     if oauth_provider in ("hf", "huggingface"):
@@ -98,16 +93,18 @@ def _get_oauth_config() -> tuple[str | None, list[str], str]:
     return oauth_provider, oauth_scopes, resource_url
 
 
+EXPANDED_RAW_CARD_FILE = materialize_expanded_card(
+    RAW_CARD_FILE,
+    workspace_root=WORKSPACE_ROOT,
+    out_dir=EXPANDED_CARDS_DIR,
+)
+
 fast = FastAgent(
     "hub-search-prefab",
     config_path=str(CONFIG_PATH),
     parse_cli_args=False,
 )
-fast.load_agents(RAW_CARD_FILE)
-fast.load_agents(PREFAB_NATIVE_CARD_FILE)
-fast.load_agents(PREFAB_LLM_RAW_CARD_FILE)
-fast.load_agents(PREFAB_LLM_CODEGEN_CARD_FILE)
-fast.load_agents(PREFAB_LLM_CHAIN_CARD_FILE)
+fast.load_agents(EXPANDED_RAW_CARD_FILE)
 
 _oauth_provider, _oauth_scopes, _oauth_resource_url = _get_oauth_config()
 _auth_provider = None
@@ -142,13 +139,6 @@ async def _run_raw(query: str) -> str:
     return await _run_agent(RAW_AGENT, query)
 
 
-async def _run_prefab_native(query: str) -> str:
-    return await _run_agent(PREFAB_NATIVE_AGENT, query)
-
-
-async def _run_prefab_llm_chain(query: str) -> str:
-    return await _run_agent(PREFAB_LLM_CHAIN_AGENT, query)
-
 
 def _get_request_bearer_token() -> str | None:
     access_token = get_access_token()
@@ -166,6 +156,7 @@ async def _run_agent(agent_name: str, query: str) -> str:
         request_bearer_token.reset(saved_token)
 
 
+
 def _wire_tool_result(wire: dict[str, object]) -> ToolResult:
     return ToolResult(
         content=[TextContent(type="text", text="[Rendered Prefab UI]")],
@@ -173,23 +164,16 @@ def _wire_tool_result(wire: dict[str, object]) -> ToolResult:
     )
 
 
+
 def _render_query_wire(query: str, raw_text: str) -> dict[str, object]:
     payload = parse_runtime_payload(raw_text)
     return build_runtime_wire(query, payload)
 
 
-def _render_prefab_wire(prefab_text: str) -> dict[str, object]:
-    return parse_passthrough_wire(prefab_text)
-
-
 async def _build_query_wire(query: str) -> dict[str, object]:
-    prefab_response = await _run_prefab_native(query)
-    try:
-        return _render_prefab_wire(prefab_response)
-    except Exception:
-        traceback.print_exc()
-        raw = await _run_raw(query)
-        return _render_query_wire(query, raw)
+    raw = await _run_raw(query)
+    return _render_query_wire(query, raw)
+
 
 
 def _missing_query_json() -> str:
@@ -206,7 +190,7 @@ def _missing_query_json() -> str:
 
 @mcp.tool(app=True)
 async def hub_search_prefab(query: str) -> ToolResult:
-    """Run the Prefab UI service: model-authored Prefab first, raw deterministic fallback second."""
+    """Run the Prefab UI service with deterministic rendering over raw Hub output."""
     try:
         wire = await _build_query_wire(query)
     except Exception as exc:  # noqa: BLE001
@@ -215,21 +199,9 @@ async def hub_search_prefab(query: str) -> ToolResult:
     return _wire_tool_result(wire)
 
 
-@mcp.tool
-async def hub_search_prefab_native_debug(query: str | None = None) -> str:
-    """Return the one-pass native Prefab agent payload, before fallback rendering."""
-    if not query:
-        return _missing_query_json()
-    try:
-        return await _run_prefab_native(query)
-    except Exception as exc:  # noqa: BLE001
-        traceback.print_exc()
-        return json.dumps({"result": None, "meta": {"ok": False, "error": str(exc)}})
-
-
 @mcp.tool
 async def hub_search_prefab_wire(query: str | None = None) -> str:
-    """Return final Prefab wire JSON after active-path parse and fallback logic."""
+    """Return final deterministic Prefab wire JSON for a Hub query."""
     if not query:
         return json.dumps(error_wire("Missing required argument: query"), ensure_ascii=False)
     try:
@@ -252,17 +224,6 @@ async def hub_search_raw_debug(query: str | None = None) -> str:
         return json.dumps({"result": None, "meta": {"ok": False, "error": str(exc)}})
 
 
-@mcp.tool
-async def hub_search_prefab_llm_debug(query: str | None = None) -> str:
-    """Return the two-pass LLM chain payload for comparison/debugging."""
-    if not query:
-        return _missing_query_json()
-    try:
-        return await _run_prefab_llm_chain(query)
-    except Exception as exc:  # noqa: BLE001
-        traceback.print_exc()
-        return json.dumps({"result": None, "meta": {"ok": False, "error": str(exc)}})
-
 
 def main() -> None:
     mcp.run(

scripts/prefab_hub_ui.py

@@ -5,10 +5,11 @@ import json
 from copy import deepcopy
 from typing import Any
 
-from prefab_ui.themes import blue
+from prefab_ui.themes import Basic
 
 PAGE_CSS_CLASS = "w-full max-w-6xl mx-auto p-4 md:p-6 lg:px-8"
-DEFAULT_THEME: dict[str, Any] = blue.to_json()
+WIDE_PAGE_CSS_CLASS = "w-full max-w-[90rem] mx-auto p-4 md:p-6 lg:px-8"
+DEFAULT_THEME: dict[str, Any] = Basic(accent="blue").to_json()
 
 _COMPONENT_KEY_ALIASES: dict[str, str] = {
     "bar_radius": "barRadius",
@@ -100,6 +101,19 @@ _PREFERRED_METRIC_KEYS: tuple[str, ...] = (
     "normal_likers",
 )
 
+_PREFERRED_LABEL_KEYS: tuple[str, ...] = (
+    "label",
+    "name",
+    "title",
+    "repo_type",
+    "status",
+    "task",
+    "pipeline_tag",
+    "kind",
+    "owner",
+    "username",
+)
+
 _URL_KEYS: tuple[str, ...] = (
     "repo_url",
     "url",
@@ -109,6 +123,62 @@ _URL_KEYS: tuple[str, ...] = (
     "github_repo_url",
 )
 
+_FILTERABLE_COLUMN_KEYS: tuple[str, ...] = (
+    "repo_type",
+    "pipeline_tag",
+    "pipeline_tags",
+    "tags",
+    "status",
+    "license",
+    "author",
+    "owner",
+    "username",
+    "user",
+    "users",
+    "handle",
+    "organization",
+    "organizations",
+)
+
+_FILTERABLE_COLUMN_SUFFIXES: tuple[str, ...] = (
+    "_type",
+    "_tag",
+    "_tags",
+    "_status",
+    "_license",
+    "_author",
+    "_owner",
+    "_username",
+    "_user",
+    "_users",
+    "_handle",
+    "_organization",
+    "_organizations",
+)
+
+_USER_NAME_KEYS: tuple[str, ...] = (
+    "full_name",
+    "display_name",
+    "name",
+    "username",
+    "handle",
+)
+
+_USER_AVATAR_KEYS: tuple[str, ...] = (
+    "avatar_url",
+    "avatar",
+    "image_url",
+)
+
+_USER_SOCIAL_LINK_KEYS: tuple[tuple[str, str], ...] = (
+    ("hf_url", "Hugging Face"),
+    ("profile_url", "Profile"),
+    ("website_url", "Website"),
+    ("blog_url", "Blog"),
+    ("github_url", "GitHub"),
+    ("twitter_url", "Twitter"),
+)
+
 
 def _copy_default_theme() -> dict[str, Any]:
     return deepcopy(DEFAULT_THEME)
@@ -457,14 +527,45 @@ def _is_scalar(value: Any) -> bool:
     return False
 
 
-def _normalize_cell(value: Any) -> Any:
+def _normalize_cell(value: Any, *, key: str) -> Any:
     if value is None or isinstance(value, (str, int, float, bool)):
         return value
+    if isinstance(value, list):
+        if value and all(isinstance(item, str) for item in value):
+            return [_compact_text(item, limit=40) for item in value[:8]]
     return _compact_text(value)
 
 
 def _normalize_row(row: dict[str, Any]) -> dict[str, Any]:
-    return {str(key): _normalize_cell(value) for key, value in row.items()}
+    return {
+        str(key): _normalize_cell(value, key=str(key)) for key, value in row.items()
+    }
+
+
+def _is_badge_friendly_key(key: str) -> bool:
+    return key in _FILTERABLE_COLUMN_KEYS or key.endswith(_FILTERABLE_COLUMN_SUFFIXES)
+
+
+def _should_make_filterable(key: str, rows: list[dict[str, Any]]) -> bool:
+    if not _is_badge_friendly_key(key):
+        return False
+
+    values = [row.get(key) for row in rows]
+    if any(isinstance(value, list) for value in values):
+        return True
+
+    scalar_values = [
+        value
+        for value in values
+        if isinstance(value, (str, int, float, bool))
+    ]
+    if not scalar_values:
+        return False
+
+    if any(isinstance(value, (int, float)) and not isinstance(value, bool) for value in scalar_values):
+        return False
+
+    return 0 < len({str(value) for value in scalar_values}) <= 12
 
 
 def _column_rank(key: str) -> tuple[int, str]:
@@ -481,6 +582,13 @@ def _metric_rank(key: str) -> tuple[int, str]:
         return (len(_PREFERRED_METRIC_KEYS), key)
 
 
+def _label_rank(key: str) -> tuple[int, str]:
+    try:
+        return (_PREFERRED_LABEL_KEYS.index(key), key)
+    except ValueError:
+        return (len(_PREFERRED_LABEL_KEYS), key)
+
+
 def _build_row_click(rows: list[dict[str, Any]]) -> dict[str, Any] | None:
     for key in _URL_KEYS:
         if any(isinstance(row.get(key), str) and row.get(key) for row in rows):
@@ -491,6 +599,198 @@ def _build_row_click(rows: list[dict[str, Any]]) -> dict[str, Any] | None:
     return None
 
 
+def _select_distribution_fields(
+    rows: list[dict[str, Any]],
+) -> tuple[str, str] | None:
+    if not 2 <= len(rows) <= 8:
+        return None
+
+    shared_keys = set(rows[0])
+    for row in rows[1:]:
+        shared_keys &= set(row)
+    if not shared_keys:
+        return None
+
+    numeric_keys = [
+        key
+        for key in shared_keys
+        if all(isinstance(row.get(key), (int, float)) for row in rows)
+    ]
+    if not numeric_keys:
+        return None
+
+    count_key = sorted(numeric_keys, key=_metric_rank)[0]
+    label_candidates = [
+        key
+        for key in shared_keys
+        if key != count_key
+        and all(isinstance(row.get(key), str) and row.get(key).strip() for row in rows)
+    ]
+    if not label_candidates:
+        return None
+
+    label_key = sorted(label_candidates, key=_label_rank)[0]
+    return label_key, count_key
+
+
+def _build_distribution_card(
+    title: str,
+    rows: list[dict[str, Any]],
+    *,
+    label_key: str,
+    count_key: str,
+) -> dict[str, Any]:
+    return {
+        "type": "Card",
+        "children": [
+            {
+                "type": "CardHeader",
+                "children": [
+                    {"type": "CardTitle", "content": f"{title} distribution"},
+                    {
+                        "type": "CardDescription",
+                        "content": f'{_titleize(count_key)} by {_titleize(label_key).lower()}',
+                    },
+                ],
+            },
+            {
+                "type": "CardContent",
+                "children": [
+                    {
+                        "type": "PieChart",
+                        "data": rows,
+                        "dataKey": count_key,
+                        "nameKey": label_key,
+                        "innerRadius": 60,
+                        "paddingAngle": 2,
+                        "showLegend": True,
+                        "showTooltip": True,
+                        "showLabel": False,
+                        "height": 260,
+                    }
+                ],
+            },
+        ],
+    }
+
+
+def _looks_like_user_profile(values: dict[str, Any]) -> bool:
+    return any(key in values for key in ("username", "handle", "avatar_url", "hf_url", "profile_url"))
+
+
+def _first_present(values: dict[str, Any], keys: tuple[str, ...]) -> str | None:
+    for key in keys:
+        value = values.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _user_profile_links(values: dict[str, Any]) -> list[tuple[str, str]]:
+    links: list[tuple[str, str]] = []
+    for key, label in _USER_SOCIAL_LINK_KEYS:
+        value = values.get(key)
+        if isinstance(value, str) and value.strip():
+            links.append((label, value.strip()))
+
+    username = _first_present(values, ("username", "handle"))
+    if username and not any(label == "Hugging Face" for label, _ in links):
+        links.insert(0, ("Hugging Face", f"https://huggingface.co/{username.lstrip('@')}"))
+
+    github = values.get("github")
+    if isinstance(github, str) and github.strip() and not any(label == "GitHub" for label, _ in links):
+        links.append(("GitHub", f"https://github.com/{github.strip().lstrip('@')}"))
+
+    twitter = values.get("twitter")
+    if isinstance(twitter, str) and twitter.strip() and not any(label == "Twitter" for label, _ in links):
+        links.append(("Twitter", f"https://x.com/{twitter.strip().lstrip('@')}"))
+
+    deduped: list[tuple[str, str]] = []
+    seen_urls: set[str] = set()
+    for label, url in links:
+        if url in seen_urls:
+            continue
+        seen_urls.add(url)
+        deduped.append((label, url))
+    return deduped[:4]
+
+
+def _build_user_profile_card(title: str, values: dict[str, Any]) -> dict[str, Any] | None:
+    name = _first_present(values, _USER_NAME_KEYS)
+    if not name:
+        return None
+
+    username = _first_present(values, ("username", "handle"))
+    subtitle = f"@{username.lstrip('@')}" if username else title
+    avatar = _first_present(values, _USER_AVATAR_KEYS)
+    bio = _first_present(values, ("bio", "description", "headline"))
+    links = _user_profile_links(values)
+
+    row_children: list[dict[str, Any]] = []
+    if avatar:
+        row_children.append(
+            {
+                "type": "Image",
+                "src": avatar,
+                "alt": name,
+                "width": "64px",
+                "height": "64px",
+                "cssClass": "rounded-full border object-cover",
+            }
+        )
+
+    body_children: list[dict[str, Any]] = [
+        {"type": "H3", "content": name},
+        {"type": "Muted", "content": subtitle},
+    ]
+    if bio:
+        body_children.append({"type": "Text", "content": bio})
+    if links:
+        body_children.append(
+            {
+                "type": "Row",
+                "gap": 2,
+                "cssClass": "flex-wrap",
+                "children": [
+                    {
+                        "type": "Button",
+                        "label": "View profile" if index == 0 else label,
+                        "variant": "default" if index == 0 else "outline",
+                        "buttonType": "button",
+                        "onClick": {"action": "openLink", "url": url},
+                    }
+                    for index, (label, url) in enumerate(links)
+                ],
+            }
+        )
+
+    row_children.append({"type": "Column", "gap": 2, "children": body_children})
+
+    return {
+        "type": "Card",
+        "children": [
+            {
+                "type": "CardContent",
+                "cssClass": "p-6",
+                "children": [{"type": "Row", "gap": 4, "align": "center", "children": row_children}],
+            }
+        ],
+    }
+
+
+def _prefers_wide_layout(value: Any) -> bool:
+    if isinstance(value, list):
+        return bool(value) and all(isinstance(item, dict) for item in value)
+    if isinstance(value, dict):
+        items = value.get("items")
+        if isinstance(items, list) and items and all(isinstance(item, dict) for item in items):
+            return True
+        results = value.get("results")
+        if isinstance(results, list) and results and all(isinstance(item, dict) for item in results):
+            return True
+    return False
+
+
 def _build_table_card(
     title: str,
     rows: list[dict[str, Any]],
@@ -531,7 +831,13 @@ def _build_table_card(
 
     normalized_rows = [_normalize_row(row) for row in rows]
     all_keys = {key for row in normalized_rows for key in row}
-    visible_keys = sorted(all_keys, key=_column_rank)[:8]
+    row_click = _build_row_click(rows)
+    visible_keys = sorted(all_keys, key=_column_rank)
+    if row_click is not None:
+        non_url_keys = [key for key in visible_keys if key not in _URL_KEYS]
+        if non_url_keys:
+            visible_keys = non_url_keys
+    visible_keys = visible_keys[:8]
     columns: list[dict[str, Any]] = []
     for key in visible_keys:
         column: dict[str, Any] = {
@@ -539,8 +845,11 @@ def _build_table_card(
             "header": _titleize(key),
             "sortable": key not in {"description"},
         }
+        if _should_make_filterable(key, normalized_rows):
+            column["filterable"] = True
         if any(isinstance(row.get(key), (int, float)) for row in normalized_rows):
-            column["align"] = "right"
+            column["headerClass"] = "text-right"
+            column["cellClass"] = "text-right"
             column["format"] = "number"
         if key in {"description"}:
             column["maxWidth"] = "28rem"
@@ -556,7 +865,6 @@ def _build_table_card(
         "pageSize": 10,
     }
 
-    row_click = _build_row_click(rows)
     if row_click is not None:
         data_table["onRowClick"] = row_click
 
@@ -588,7 +896,10 @@ def _build_key_value_card(
     *,
     description: str | None = None,
 ) -> dict[str, Any]:
-    rows = [{"field": _titleize(key), "value": _normalize_cell(value)} for key, value in values.items()]
+    rows = [
+        {"field": _titleize(key), "value": _normalize_cell(value, key=str(key))}
+        for key, value in values.items()
+    ]
     return _build_table_card(
         title,
         rows,
@@ -742,12 +1053,31 @@ def _render_list(
 
     if all(isinstance(item, dict) for item in value):
         rows = [item for item in value if isinstance(item, dict)]
-        return [_build_table_card(title, rows, description=description)]
+        table_card = _build_table_card(title, rows, description=description)
+        distribution_fields = _select_distribution_fields(rows)
+        if distribution_fields is None:
+            return [table_card]
+        label_key, count_key = distribution_fields
+        return [
+            {
+                "type": "Column",
+                "gap": 4,
+                "children": [
+                    _build_distribution_card(
+                        title,
+                        rows,
+                        label_key=label_key,
+                        count_key=count_key,
+                    ),
+                    table_card,
+                ],
+            }
+        ]
 
     rows = [
         {
             "index": index + 1,
-            "value": _normalize_cell(item),
+            "value": _normalize_cell(item, key="value"),
         }
         for index, item in enumerate(value)
     ]
@@ -764,6 +1094,35 @@ def _render_dict(
     if depth > 2:
         return [_build_key_value_card(title, value, description=description)]
 
+    if depth <= 1 and _looks_like_user_profile(value):
+        sections: list[dict[str, Any]] = []
+        user_card = _build_user_profile_card(title, value)
+        if user_card is not None:
+            sections.append(user_card)
+        remaining = {
+            key: item
+            for key, item in value.items()
+            if key
+            not in {
+                *_USER_NAME_KEYS,
+                *_USER_AVATAR_KEYS,
+                "bio",
+                "description",
+                "headline",
+                "hf_url",
+                "profile_url",
+                "website_url",
+                "blog_url",
+                "github_url",
+                "twitter_url",
+                "github",
+                "twitter",
+            }
+        }
+        if remaining:
+            sections.extend(_render_dict(title, remaining, description=description, depth=depth + 1))
+        return sections
+
     if "results" in value or "coverage" in value:
         sections: list[dict[str, Any]] = []
         results = value.get("results")
@@ -909,6 +1268,19 @@ def _build_summary_card(
             }
         )
 
+    if isinstance(runtime_meta, dict) and runtime_meta.get("elapsed_ms") is not None:
+        summary_children.append(
+            {
+                "type": "CardFooter",
+                "children": [
+                    {
+                        "type": "Muted",
+                        "content": f'Runtime: {runtime_meta["elapsed_ms"]} ms',
+                    }
+                ],
+            }
+        )
+
     return {"type": "Card", "children": summary_children}
 
 
@@ -924,7 +1296,7 @@ def build_runtime_wire(query: str, payload: dict[str, Any]) -> dict[str, Any]:
     helper_meta: dict[str, Any] | None = None
     body_children: list[dict[str, Any]] = []
 
-    if _looks_like_helper_envelope(result):
+    if isinstance(result, dict) and _looks_like_helper_envelope(result):
         helper_meta = result.get("meta") if isinstance(result.get("meta"), dict) else None
         if result.get("ok") is False:
             message = str(result.get("error") or "Helper query failed")
@@ -953,10 +1325,11 @@ def build_runtime_wire(query: str, payload: dict[str, Any]) -> dict[str, Any]:
     else:
         body_children.extend(_render_value("Results", result))
 
+    page_css_class = WIDE_PAGE_CSS_CLASS if _prefers_wide_layout(result) else PAGE_CSS_CLASS
     body_view = {
         "type": "Column",
         "gap": 6,
-        "cssClass": PAGE_CSS_CLASS,
+        "cssClass": page_css_class,
         "children": [
             _build_summary_card(
                 query,

wheels/prefab_ui-0.13.2.dev5+a585463-py3-none-any.whl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:20a94bcc2a2fd2bd31f2430ee7fd8f04f2ac410afb2932f03014a8609bce5fb3
+size 896909