agentnode-sdk 0.21.0__tar.gz → 0.23.0__tar.gz

{agentnode_sdk-0.21.0 → agentnode_sdk-0.23.0}/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.23.0 — Prove MCP package ownership from the terminal
+
+### Added
+
+- `agentnode mcp ownership challenge --registry npm|pypi <package>` issues a
+  one-time challenge: the server returns a token and a keyword
+  (`agentnode-ownership-<token>`). Add the keyword to your package's metadata
+  and publish a new version — only someone with publish rights can do that. The
+  token is shown once and is stored server-side only as a hash; it is never
+  written to local config.
+- `agentnode mcp ownership verify --registry npm|pypi <package>` checks the
+  latest published version for the keyword and, on a match, records strong
+  ownership evidence. It reports `verified` / `pending` / expired / no-challenge
+  / package-not-found / registry-unavailable clearly, and exits non-zero until
+  ownership is verified (CI-gateable).
+
+Verifying ownership does **not** publish anything: MCP listings still remain
+review-gated until the sandbox-smoke gate is built. The same flow is available
+in the browser on `/mcp/submit`.
+
+## 0.22.0 — MCP from the terminal + refreshed compatibility
+
+### Added
+
+- `agentnode init --type mcp` scaffolds an MCP server listing: a schema-valid
+  manifest (runtime `mcp`, a pinned `mcp_server` command with an npm/PyPI
+  package and `source_repo`, honest permissions) plus a README that walks
+  `agentnode mcp verify` → `agentnode mcp submit`. MCP now has the same
+  terminal starting point as toolpacks, skills, and agents.
+
+### Changed
+
+- `agentnode publish` detects an MCP manifest (runtime `mcp` or an `mcp_server`
+  block) and routes you to `agentnode mcp verify` / `agentnode mcp submit`
+  instead of failing deep in toolpack validation. Non-MCP manifests are
+  unaffected.
+- Refreshed model compatibility data: 246 scored models (222 S-tier), current
+  flagships added, models untestable in the latest batch kept with their prior
+  result marked legacy, and only hard-evidence removals delisted.
+
 ## 0.21.0 — Community agents run sandboxed by default
 
 ### Changed

{agentnode_sdk-0.21.0 → agentnode_sdk-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentnode-sdk
-Version: 0.21.0
+Version: 0.23.0
 Summary: Python SDK for AgentNode — the open upgrade and discovery infrastructure for AI agents.
 Project-URL: Homepage, https://agentnode.net
 Project-URL: Repository, https://github.com/agentnode-ai/agentnode

{agentnode_sdk-0.21.0 → agentnode_sdk-0.23.0}/agentnode_sdk/__init__.py

@@ -38,7 +38,7 @@ from agentnode_sdk.runtime import AgentNodeRuntime
 Client = AgentNodeClient
 ToolError = AgentNodeToolError
 
-__version__ = "0.21.0"
+__version__ = "0.23.0"
 __all__ = [
     "AgentNode",
     "AsyncAgentNode",

{agentnode_sdk-0.21.0 → agentnode_sdk-0.23.0}/agentnode_sdk/cli/commands.py

@@ -2338,9 +2338,14 @@ def cmd_init(name: str | None = None, template_type: str | None = None) -> int:
     print()
     print(dim("  Next steps:"))
     print(dim(f"    cd {pkg_id}"))
-    print(dim("    # Edit the tool code and manifest"))
-    print(dim("    agentnode validate ."))
-    print(dim("    # Publish via web UI at agentnode.net/publish"))
+    if chosen == "mcp":
+        print(dim("    # Fill in npm_package/pypi_package, pin the version, set source_repo"))
+        print(dim("    agentnode mcp verify . --test    # check ownership, package, pinning"))
+        print(dim("    agentnode mcp submit .           # submit for the catalog"))
+    else:
+        print(dim("    # Edit the tool code and manifest"))
+        print(dim("    agentnode validate ."))
+        print(dim("    agentnode publish .              # or publish via agentnode.net/publish"))
     print()
     return 0
 

{agentnode_sdk-0.21.0 → agentnode_sdk-0.23.0}/agentnode_sdk/cli/main.py

@@ -61,6 +61,19 @@ def main(argv: list[str] | None = None) -> int:
     mcp_revoke_p.add_argument("--key", default=None, help="Revoke only this consent_key")
     mcp_grants_p = mcp_sub.add_parser("grants", help="List stored consent grants (metadata only)")
     mcp_grants_p.add_argument("--json", dest="json_output", action="store_true", help="JSON output")
+    # Slice 2b-2: prove package ownership via a publish-challenge (npm/PyPI).
+    mcp_own_p = mcp_sub.add_parser("ownership", help="Prove package ownership (publish-challenge)")
+    mcp_own_sub = mcp_own_p.add_subparsers(dest="ownership_command")
+    mcp_own_ch = mcp_own_sub.add_parser("challenge", help="Issue a one-time publish-challenge token")
+    mcp_own_ch.add_argument("package", help="Package name on the registry")
+    mcp_own_ch.add_argument("--registry", required=True, choices=["npm", "pypi"], help="Package registry")
+    mcp_own_ch.add_argument("--token", default=None, help="API key (default: AGENTNODE_API_KEY)")
+    mcp_own_ch.add_argument("--json", dest="json_output", action="store_true", help="JSON output")
+    mcp_own_vf = mcp_own_sub.add_parser("verify", help="Verify a pending publish-challenge")
+    mcp_own_vf.add_argument("package", help="Package name on the registry")
+    mcp_own_vf.add_argument("--registry", required=True, choices=["npm", "pypi"], help="Package registry")
+    mcp_own_vf.add_argument("--token", default=None, help="API key (default: AGENTNODE_API_KEY)")
+    mcp_own_vf.add_argument("--json", dest="json_output", action="store_true", help="JSON output")
 
     # reset
     sub.add_parser("reset", help="Reset configuration")
@@ -149,7 +162,7 @@ def main(argv: list[str] | None = None) -> int:
     # init
     init_parser = sub.add_parser("init", help="Create a new package from template")
     init_parser.add_argument("name", nargs="?", default=None, help="Package ID (optional, prompted if omitted)")
-    init_parser.add_argument("--type", dest="template_type", choices=["local", "api", "file", "agent", "skill"], default=None)
+    init_parser.add_argument("--type", dest="template_type", choices=["local", "api", "file", "agent", "skill", "mcp"], default=None)
 
     # validate
     validate_parser = sub.add_parser("validate", help="Validate package before publishing")
@@ -268,6 +281,21 @@ def main(argv: list[str] | None = None) -> int:
             if args.mcp_command == "grants":
                 from agentnode_sdk.cli.mcp_commands import cmd_mcp_grants
                 return cmd_mcp_grants(json_output=args.json_output)
+            if args.mcp_command == "ownership":
+                from agentnode_sdk.cli.mcp_ownership import (
+                    cmd_mcp_ownership_challenge,
+                    cmd_mcp_ownership_verify,
+                )
+                if args.ownership_command == "challenge":
+                    return cmd_mcp_ownership_challenge(
+                        args.registry, args.package, token=args.token, json_output=args.json_output
+                    )
+                if args.ownership_command == "verify":
+                    return cmd_mcp_ownership_verify(
+                        args.registry, args.package, token=args.token, json_output=args.json_output
+                    )
+                mcp_own_p.print_help()
+                return 0
             mcp_parser.print_help()
             return 0
         if args.command == "sandbox":

agentnode_sdk-0.23.0/agentnode_sdk/cli/mcp_ownership.py

@@ -0,0 +1,207 @@
+"""Publish-challenge ownership for MCP packages (Slice 2b-2 UX).
+
+Two verbs let a publisher prove they control an npm/PyPI package:
+
+  agentnode mcp ownership challenge --registry npm|pypi <package>
+  agentnode mcp ownership verify    --registry npm|pypi <package>
+
+`challenge` asks the backend for a one-time token + keyword; the publisher adds
+the keyword to their package's metadata and publishes a new version. `verify`
+then asks the backend to look at the latest published version and confirm the
+keyword -- only someone with publish rights can put it there, so a match is
+strong ownership evidence.
+
+The token is never written to disk here -- it is shown once, straight from the
+API response. Verifying ownership does NOT publish anything: MCP listings stay
+review-gated until the sandbox-smoke gate is built.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import httpx
+
+_REVIEW_NOTE = (
+    "  Ownership can be verified, but MCP listings still remain review-gated\n"
+    "  until the sandbox-smoke gate is built."
+)
+
+
+def _resolve_api_base() -> str:
+    from agentnode_sdk.client import DEFAULT_BASE_URL
+    return os.environ.get("AGENTNODE_API_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def _api_key(token: str | None) -> str:
+    return token or os.environ.get("AGENTNODE_API_KEY", "")
+
+
+def _no_key() -> int:
+    print(
+        "  Error: No AgentNode API key configured.\n"
+        "  Set AGENTNODE_API_KEY or pass --token <key>.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+def _handle_error(resp: httpx.Response, json_output: bool) -> int:
+    """Print a clear error for a non-2xx response and return 1.
+
+    Backend error messages are already user-facing (expired challenge, no
+    challenge, package not found, registry unavailable), so we surface them
+    directly rather than re-inventing copy per status code.
+    """
+    try:
+        err = resp.json()
+        code = err.get("code", "")
+        message = err.get("message", resp.text)
+    except Exception:
+        err = None
+        code = ""
+        message = resp.text
+
+    if json_output and err is not None:
+        print(json.dumps(err, indent=2))
+        return 1
+
+    if resp.status_code == 401:
+        print("  Error: Authentication failed. Check your API key.", file=sys.stderr)
+    elif resp.status_code == 403:
+        if "PUBLISHER" in code:
+            print("  Error: You need a publisher profile.", file=sys.stderr)
+            print("  Create one at https://agentnode.net/dashboard", file=sys.stderr)
+        else:
+            print(f"  Error: {message}", file=sys.stderr)
+    else:
+        print(f"  Error ({resp.status_code}): {message}", file=sys.stderr)
+    return 1
+
+
+def cmd_mcp_ownership_challenge(
+    registry: str,
+    package: str,
+    *,
+    token: str | None = None,
+    json_output: bool = False,
+) -> int:
+    """Issue a one-time publish-challenge for a package."""
+    api_key = _api_key(token)
+    if not api_key:
+        return _no_key()
+
+    registry = (registry or "").strip().lower()
+    url = f"{_resolve_api_base()}/v1/mcp/ownership/challenge"
+    try:
+        resp = httpx.post(
+            url,
+            json={"registry": registry, "package_name": package},
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=30,
+        )
+    except Exception as e:
+        print(f"  Error: Connection failed: {e}", file=sys.stderr)
+        return 1
+
+    if resp.status_code != 200:
+        return _handle_error(resp, json_output)
+
+    data = resp.json()
+    if json_output:
+        print(json.dumps(data, indent=2))
+        return 0
+
+    keyword = data.get("keyword", "")
+    tok = data.get("token", "")
+    expires = (data.get("expires_at") or "")[:10]
+    verify_cmd = f"agentnode mcp ownership verify --registry {registry} {package}"
+
+    print()
+    print("  AgentNode Ownership Challenge")
+    print("  " + "-" * 29)
+    print(f"  Registry: {registry}")
+    print(f"  Package:  {package}")
+    print()
+    print("  Prove package ownership by publishing this keyword in your package")
+    print("  metadata. Only someone with publish rights can do that.")
+    print()
+    print(f"  Token (shown once):  {tok}")
+    print(f"  Keyword:             {keyword}")
+    if expires:
+        print(f"  Expires:             {expires}")
+    print()
+    print("  Next steps:")
+    print(f'    1. Add "{keyword}" to your package\'s keywords.')
+    print(f"    2. Publish a new version to {registry}.")
+    print(f"    3. Run: {verify_cmd}")
+    print()
+    print("  The token is shown only once and is stored only as a hash. If you")
+    print("  lose it, just issue a new challenge -- that replaces the old one.")
+    print()
+    print(_REVIEW_NOTE)
+    print()
+    return 0
+
+
+def cmd_mcp_ownership_verify(
+    registry: str,
+    package: str,
+    *,
+    token: str | None = None,
+    json_output: bool = False,
+) -> int:
+    """Verify a pending publish-challenge against the published package."""
+    api_key = _api_key(token)
+    if not api_key:
+        return _no_key()
+
+    registry = (registry or "").strip().lower()
+    url = f"{_resolve_api_base()}/v1/mcp/ownership/challenge/verify"
+    try:
+        resp = httpx.post(
+            url,
+            json={"registry": registry, "package_name": package},
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=30,
+        )
+    except Exception as e:
+        print(f"  Error: Connection failed: {e}", file=sys.stderr)
+        return 1
+
+    if resp.status_code != 200:
+        return _handle_error(resp, json_output)
+
+    data = resp.json()
+    verified = bool(data.get("verified"))
+    if json_output:
+        print(json.dumps(data, indent=2))
+        return 0 if verified else 1
+
+    status = data.get("status", "?")
+    message = data.get("message", "")
+    version = data.get("version")
+
+    print()
+    print("  AgentNode Ownership Verify")
+    print("  " + "-" * 26)
+    print(f"  Registry: {registry}")
+    print(f"  Package:  {package}")
+    print(f"  Status:   {status}")
+    if version:
+        print(f"  Version:  {version}")
+    print()
+    if message:
+        print(f"  {message}")
+    if verified:
+        print("  Strong ownership evidence recorded for this package.")
+    else:
+        print(
+            f"  Not verified yet. Publish a version carrying the challenge keyword, "
+            f"then run:\n    agentnode mcp ownership verify --registry {registry} {package}"
+        )
+    print()
+    print(_REVIEW_NOTE)
+    print()
+    return 0 if verified else 1

{agentnode_sdk-0.21.0 → agentnode_sdk-0.23.0}/agentnode_sdk/cli/publish.py

@@ -389,6 +389,20 @@ def cmd_publish(
         print("  Error: package_id and version are required in agentnode.yaml.", file=sys.stderr)
         return 1
 
+    # MCP listings go through the dedicated submit flow (registry re-verification
+    # + ownership), not the toolpack/skill/agent publish path. Route the user
+    # cleanly instead of failing deep in validation.
+    if manifest.get("runtime") == "mcp" or manifest.get("mcp_server"):
+        print()
+        print(section("  This is an MCP server listing"))
+        print("  MCP servers are listed with a dedicated command, not `publish`:")
+        print()
+        print("      agentnode mcp verify .        # check ownership, package, pinning")
+        print("      agentnode mcp submit .        # submit for the catalog")
+        print()
+        print("  (`publish` is for toolpacks, skills, and agents.)")
+        return 1
+
     print()
     print(section("  AgentNode Publish"))
     print(kv("Package", f"{pkg_id}@{version}"))

{agentnode_sdk-0.21.0 → agentnode_sdk-0.23.0}/agentnode_sdk/cli/templates.py

@@ -598,6 +598,92 @@ This is an example of the expected output quality and format.
 ## Summary
 
 A concise summary of the analysis.
+""",
+        },
+    },
+    "mcp": {
+        "label": "MCP server (list an existing npm/PyPI MCP server)",
+        "description": "A listing for an MCP server already published to npm or PyPI. No code is uploaded — you point AgentNode at the package. Submit with `agentnode mcp submit` after `agentnode mcp verify`.",
+        "files": {
+            "agentnode.yaml": """\
+manifest_version: "0.3"
+package_id: "{package_id}"
+package_type: "toolpack"
+name: "{name}"
+publisher: "{publisher}"
+version: "1.0.0"
+summary: "{summary}"
+description: |
+  {description}
+
+runtime: "mcp"
+install_mode: "package"
+hosting_type: "agentnode_hosted"
+
+# The MCP server to run. Fill in ONE of npm_package / pypi_package and pin the
+# EXACT version in the command (e.g. @0.1.0 for npm, ==0.1.0 for PyPI) — an
+# unpinned command is not reproducible and is flagged on submit.
+mcp_server:
+  # npm example (delete the pypi_package line):
+  command: ["npx", "-y", "REPLACE_ME_PACKAGE@REPLACE_VERSION"]
+  npm_package: "REPLACE_ME_PACKAGE"
+  # pypi example (swap the command + use pypi_package instead of npm_package):
+  #   command: ["uvx", "REPLACE_ME_PACKAGE==REPLACE_VERSION"]
+  #   pypi_package: "REPLACE_ME_PACKAGE"
+  # Ownership is checked against this repo — it must match the package's
+  # registry metadata (npm/PyPI "repository" / homepage).
+  source_repo: "https://github.com/REPLACE_ME_OWNER/REPLACE_ME_REPO"
+
+tags: []
+categories: []
+
+compatibility:
+  frameworks: ["generic"]
+
+# Declare honestly what the MCP server needs. Verification compares these
+# against what the server actually requests.
+permissions:
+  network:
+    level: "restricted"
+    allowed_domains: []
+  filesystem:
+    level: "none"
+  code_execution:
+    level: "none"
+  data_access:
+    level: "input_only"
+  user_approval:
+    required: "high_risk_only"
+  external_integrations: []
+""",
+            "README.md": """\
+# {name} (MCP server listing)
+
+This package LISTS an existing MCP server (published on npm or PyPI) in the
+AgentNode catalog. No code is uploaded — AgentNode points at the upstream
+package.
+
+## Before you submit
+
+1. Edit `agentnode.yaml`:
+   - Set `mcp_server.npm_package` OR `mcp_server.pypi_package` (not both).
+   - Pin the EXACT version in `mcp_server.command` (npm `@x.y.z`, PyPI `==x.y.z`).
+   - Set `mcp_server.source_repo` to the repo that owns the package.
+   - Declare `permissions` honestly.
+2. Verify locally:
+
+   ```
+   agentnode mcp verify . --test
+   ```
+
+3. Submit for the catalog (server re-verifies authoritatively):
+
+   ```
+   agentnode mcp submit . --token $AGENTNODE_API_KEY
+   ```
+
+`agentnode publish` is for toolpacks / skills / agents; MCP listings go
+through `agentnode mcp submit`.
 """,
         },
     },

agentnode_sdk-0.23.0/agentnode_sdk/compatibility.py

@@ -0,0 +1,144 @@
+"""AgentNode compatibility data and model recommendations.
+
+Auto-generated by sdk/scripts/generate_compatibility_artifacts.py
+Manual edits to _RECOMMENDED are preserved across regeneration.
+"""
+from __future__ import annotations
+
+
+_TIER_ORDER = {"S": 0, "A": 1, "B": 2, "C": 3, "F": 4}
+
+
+def _tier_passes(tier: str, minimum: str) -> bool:
+    """Check if a tier meets the minimum requirement."""
+    return _TIER_ORDER.get(tier, 99) <= _TIER_ORDER.get(minimum, 0)
+
+
+# Generated from current.json — provider -> [(model, tier), ...]
+_TIER_DATA: dict[str, list[tuple[str, str]]] = {
+    "ai21": [("jamba-large-1.7", "C")],
+    "aion-labs": [("aion-2.0", "S"), ("aion-3.0", "S"), ("aion-3.0-mini", "S")],
+    "amazon": [("nova-2-lite-v1", "S"), ("nova-lite-v1", "S"), ("nova-micro-v1", "S"), ("nova-premier-v1", "S"), ("nova-pro-v1", "S")],
+    "anthropic": [("claude-3-haiku", "S"), ("claude-fable-5", "S"), ("claude-haiku-4.5", "S"), ("claude-opus-4", "S"), ("claude-opus-4.1", "S"), ("claude-opus-4.5", "S"), ("claude-opus-4.6", "S"), ("claude-opus-4.7", "S"), ("claude-opus-4.8", "S"), ("claude-opus-4.8-fast", "S"), ("claude-sonnet-4", "S"), ("claude-sonnet-4.5", "S"), ("claude-sonnet-4.6", "S"), ("claude-sonnet-5", "A")],
+    "arcee-ai": [("trinity-large-thinking", "A"), ("trinity-mini", "C")],
+    "bytedance-seed": [("seed-1.6", "S"), ("seed-1.6-flash", "S"), ("seed-2.0-lite", "S"), ("seed-2.0-mini", "S")],
+    "cohere": [("command-r-08-2024", "S"), ("command-r-plus-08-2024", "S"), ("north-mini-code:free", "S")],
+    "deepseek": [("deepseek-chat", "S"), ("deepseek-chat-v3-0324", "S"), ("deepseek-chat-v3.1", "S"), ("deepseek-r1", "S"), ("deepseek-r1-0528", "A"), ("deepseek-v3.1-terminus", "S"), ("deepseek-v3.2", "S"), ("deepseek-v3.2-exp", "S"), ("deepseek-v4-flash", "S"), ("deepseek-v4-pro", "A")],
+    "google": [("gemini-2.5-flash", "S"), ("gemini-2.5-flash-lite", "S"), ("gemini-2.5-flash-lite-preview-09-2025", "S"), ("gemini-2.5-pro", "S"), ("gemini-2.5-pro-preview", "S"), ("gemini-2.5-pro-preview-05-06", "S"), ("gemini-3-flash-preview", "A"), ("gemini-3-pro-image", "S"), ("gemini-3.1-flash-lite", "S"), ("gemini-3.1-flash-lite-preview", "S"), ("gemini-3.1-pro-preview", "A"), ("gemini-3.1-pro-preview-customtools", "S"), ("gemini-3.5-flash", "S"), ("gemma-3-12b-it", "F"), ("gemma-3-27b-it", "C"), ("gemma-4-26b-a4b-it", "S"), ("gemma-4-26b-a4b-it:free", "F"), ("gemma-4-31b-it", "S")],
+    "ibm-granite": [("granite-4.1-8b", "S")],
+    "inception": [("mercury-2", "S")],
+    "inclusionai": [("ling-2.6-1t", "S"), ("ling-2.6-flash", "A"), ("ring-2.6-1t", "S")],
+    "kwaipilot": [("kat-coder-pro-v2", "S")],
+    "meta-llama": [("llama-3-8b-instruct", "S"), ("llama-3.1-70b-instruct", "S"), ("llama-3.1-8b-instruct", "S"), ("llama-3.3-70b-instruct", "S"), ("llama-4-maverick", "S"), ("llama-4-scout", "S")],
+    "minimax": [("minimax-m1", "S"), ("minimax-m2", "S"), ("minimax-m2.1", "S"), ("minimax-m2.5", "S"), ("minimax-m2.7", "S"), ("minimax-m3", "S")],
+    "mistralai": [("codestral-2508", "S"), ("devstral-2512", "S"), ("ministral-14b-2512", "S"), ("ministral-3b-2512", "S"), ("ministral-8b-2512", "S"), ("mistral-large", "S"), ("mistral-large-2407", "S"), ("mistral-large-2512", "S"), ("mistral-medium-3", "S"), ("mistral-medium-3-5", "S"), ("mistral-medium-3.1", "S"), ("mistral-nemo", "S"), ("mistral-saba", "S"), ("mistral-small-2603", "S"), ("mistral-small-3.2-24b-instruct", "S"), ("mixtral-8x22b-instruct", "S"), ("voxtral-small-24b-2507", "S")],
+    "moonshotai": [("kimi-k2", "S"), ("kimi-k2-0905", "S"), ("kimi-k2-thinking", "S"), ("kimi-k2.5", "S"), ("kimi-k2.6", "S"), ("kimi-k2.7-code", "S")],
+    "nex-agi": [("nex-n2-mini", "S"), ("nex-n2-pro", "S")],
+    "nvidia": [("llama-3.3-nemotron-super-49b-v1.5", "S"), ("nemotron-3-nano-30b-a3b", "S"), ("nemotron-3-nano-30b-a3b:free", "A"), ("nemotron-3-nano-omni-30b-a3b-reasoning:free", "S"), ("nemotron-3-super-120b-a12b", "S"), ("nemotron-3-super-120b-a12b:free", "A"), ("nemotron-3-ultra-550b-a55b", "S"), ("nemotron-3-ultra-550b-a55b:free", "S"), ("nemotron-nano-12b-v2-vl:free", "C"), ("nemotron-nano-9b-v2:free", "A")],
+    "openai": [("gpt-3.5-turbo", "S"), ("gpt-3.5-turbo-0613", "S"), ("gpt-3.5-turbo-16k", "S"), ("gpt-4", "S"), ("gpt-4-turbo", "S"), ("gpt-4.1", "S"), ("gpt-4.1-mini", "S"), ("gpt-4.1-nano", "S"), ("gpt-4o", "S"), ("gpt-4o-2024-05-13", "S"), ("gpt-4o-2024-08-06", "S"), ("gpt-4o-2024-11-20", "S"), ("gpt-4o-mini", "S"), ("gpt-4o-mini-2024-07-18", "S"), ("gpt-5", "S"), ("gpt-5-codex", "S"), ("gpt-5-mini", "S"), ("gpt-5-nano", "S"), ("gpt-5-pro", "S"), ("gpt-5.1", "S"), ("gpt-5.1-chat", "S"), ("gpt-5.1-codex", "S"), ("gpt-5.1-codex-max", "S"), ("gpt-5.1-codex-mini", "S"), ("gpt-5.2", "S"), ("gpt-5.2-chat", "S"), ("gpt-5.2-codex", "S"), ("gpt-5.3-chat", "S"), ("gpt-5.3-codex", "S"), ("gpt-5.4", "S"), ("gpt-5.4-mini", "S"), ("gpt-5.4-nano", "S"), ("gpt-5.5", "S"), ("gpt-audio", "F"), ("gpt-chat-latest", "S"), ("gpt-oss-120b", "S"), ("gpt-oss-120b:free", "C"), ("gpt-oss-20b", "S"), ("gpt-oss-20b:free", "S"), ("gpt-oss-safeguard-20b", "B"), ("o1", "S"), ("o3", "S"), ("o3-mini", "S"), ("o3-mini-high", "S"), ("o3-pro", "S"), ("o4-mini", "S"), ("o4-mini-high", "S")],
+    "openrouter": [("auto", "S"), ("free", "S")],
+    "poolside": [("laguna-m.1", "S"), ("laguna-m.1:free", "A"), ("laguna-xs-2.1", "S"), ("laguna-xs-2.1:free", "S"), ("laguna-xs.2", "S"), ("laguna-xs.2:free", "S")],
+    "qwen": [("qwen-2.5-72b-instruct", "S"), ("qwen-2.5-7b-instruct", "S"), ("qwen-plus", "S"), ("qwen-plus-2025-07-28", "S"), ("qwen-plus-2025-07-28:thinking", "S"), ("qwen3-14b", "S"), ("qwen3-235b-a22b", "S"), ("qwen3-235b-a22b-2507", "S"), ("qwen3-235b-a22b-thinking-2507", "C"), ("qwen3-30b-a3b", "S"), ("qwen3-30b-a3b-instruct-2507", "S"), ("qwen3-30b-a3b-thinking-2507", "S"), ("qwen3-32b", "S"), ("qwen3-8b", "S"), ("qwen3-coder", "S"), ("qwen3-coder-30b-a3b-instruct", "S"), ("qwen3-coder-flash", "S"), ("qwen3-coder-next", "S"), ("qwen3-coder-plus", "S"), ("qwen3-max", "S"), ("qwen3-max-thinking", "S"), ("qwen3-next-80b-a3b-instruct", "S"), ("qwen3-next-80b-a3b-thinking", "S"), ("qwen3-vl-235b-a22b-instruct", "S"), ("qwen3-vl-235b-a22b-thinking", "S"), ("qwen3-vl-30b-a3b-instruct", "S"), ("qwen3-vl-30b-a3b-thinking", "S"), ("qwen3-vl-32b-instruct", "S"), ("qwen3-vl-8b-instruct", "S"), ("qwen3-vl-8b-thinking", "S"), ("qwen3.5-122b-a10b", "S"), ("qwen3.5-27b", "S"), ("qwen3.5-35b-a3b", "S"), ("qwen3.5-397b-a17b", "S"), ("qwen3.5-9b", "S"), ("qwen3.5-flash-02-23", "S"), ("qwen3.5-plus-02-15", "S"), ("qwen3.5-plus-20260420", "S"), ("qwen3.6-27b", "S"), ("qwen3.6-35b-a3b", "S"), ("qwen3.6-flash", "S"), ("qwen3.6-max-preview", "S"), ("qwen3.6-plus", "S"), ("qwen3.7-max", "S"), ("qwen3.7-plus", "S")],
+    "rekaai": [("reka-edge", "A")],
+    "relace": [("relace-search", "S")],
+    "stepfun": [("step-3.5-flash", "S"), ("step-3.7-flash", "S")],
+    "tencent": [("hy3", "S"), ("hy3-preview", "S"), ("hy3:free", "S")],
+    "thedrummer": [("unslopnemo-12b", "F")],
+    "upstage": [("solar-pro-3", "S")],
+    "x-ai": [("grok-4.20", "S"), ("grok-build-0.1", "S")],
+    "xiaomi": [("mimo-v2.5", "S"), ("mimo-v2.5-pro", "S")],
+    "z-ai": [("glm-4.5", "S"), ("glm-4.5-air", "S"), ("glm-4.5v", "S"), ("glm-4.6", "S"), ("glm-4.6v", "S"), ("glm-4.7", "S"), ("glm-4.7-flash", "S"), ("glm-5", "S"), ("glm-5-turbo", "S"), ("glm-5.1", "S"), ("glm-5.2", "S"), ("glm-5v-turbo", "S")],
+    "~anthropic": [("claude-haiku-latest", "S"), ("claude-opus-latest", "S"), ("claude-sonnet-latest", "S")],
+    "~google": [("gemini-flash-latest", "S")],
+    "~moonshotai": [("kimi-latest", "S")],
+    "~openai": [("gpt-latest", "S"), ("gpt-mini-latest", "A")],
+    "~x-ai": [("grok-latest", "S")],
+}
+
+# Curated recommendations — override layer
+_RECOMMENDED: dict[str | None, dict[str, str]] = {
+    None: {"best": "gpt-4o", "cheapest": "gpt-4o-mini"},
+    "openai": {"best": "gpt-4o", "cheapest": "gpt-4o-mini"},
+    "anthropic": {"best": "claude-sonnet-4.6", "cheapest": "claude-haiku-4.5"},
+    "google": {"best": "gemini-2.5-flash", "cheapest": "gemini-2.0-flash-001"},
+    "mistralai": {"best": "mistral-large", "cheapest": "mistral-nemo"},
+    "meta-llama": {"best": "llama-4-maverick", "cheapest": "llama-3.1-8b-instruct"},
+    "deepseek": {"best": "deepseek-chat", "cheapest": "deepseek-chat"},
+    "qwen": {"best": "qwen3-235b-a22b", "cheapest": "qwen3-30b-a3b"},
+    "x-ai": {"best": "grok-4", "cheapest": "grok-3-mini"},
+    "cohere": {"best": "command-r-plus-08-2024", "cheapest": "command-r-08-2024"},
+    "nvidia": {"best": "llama-3.3-nemotron-super-49b-v1.5", "cheapest": "nemotron-nano-9b-v2"},
+    "amazon": {"best": "nova-pro-v1", "cheapest": "nova-micro-v1"},
+    "minimax": {"best": "minimax-m2.7", "cheapest": "minimax-m1"},
+    "z-ai": {"best": "glm-5", "cheapest": "glm-4.7-flash"},
+    "inception": {"best": "mercury-2", "cheapest": "mercury"},
+    "moonshotai": {"best": "kimi-k2.5", "cheapest": "kimi-k2"},
+    "xiaomi": {"best": "mimo-v2-pro", "cheapest": "mimo-v2-flash"},
+    "bytedance-seed": {"best": "seed-1.6", "cheapest": "seed-2.0-mini"},
+}
+
+
+def recommend_model(
+    provider: str | None = None,
+    *,
+    prefer: str = "best",
+    minimum_tier: str = "S",
+) -> str | None:
+    """Recommend a model for a given provider.
+
+    Args:
+        provider: Provider name (e.g. "openai", "anthropic"). None for overall best.
+        prefer: "best" or "cheapest".
+        minimum_tier: Minimum acceptable tier ("S", "A", "B", "C", "F").
+
+    Returns:
+        Model name string, or None if no model meets the criteria.
+
+    Raises:
+        ValueError: If prefer or minimum_tier is invalid.
+    """
+    if prefer not in ("best", "cheapest"):
+        raise ValueError(f"Unknown prefer value: {prefer!r}. Use 'best' or 'cheapest'.")
+    if minimum_tier not in _TIER_ORDER:
+        raise ValueError(
+            f"Unknown minimum_tier: {minimum_tier!r}. Use one of: {', '.join(_TIER_ORDER)}."
+        )
+
+    if provider is not None:
+        provider = provider.lower()
+
+    # Try curated recommendation first
+    recs = _RECOMMENDED.get(provider)
+    if recs:
+        candidate = recs.get(prefer)
+        if candidate:
+            # Verify the candidate meets the minimum tier
+            tier_list = _TIER_DATA.get(provider, [])
+            for model_name, tier in tier_list:
+                if model_name == candidate and _tier_passes(tier, minimum_tier):
+                    return candidate
+
+    # Fallback: find best model from tier data that meets minimum
+    if provider is None:
+        # Overall: check all providers
+        for prov, models in _TIER_DATA.items():
+            for model_name, tier in models:
+                if _tier_passes(tier, minimum_tier):
+                    # Return overall curated default if available
+                    overall = _RECOMMENDED.get(None, {})
+                    fallback = overall.get(prefer)
+                    if fallback:
+                        return fallback
+                    return model_name
+        return None
+
+    tier_list = _TIER_DATA.get(provider, [])
+    if not tier_list:
+        return None
+
+    # Find any model meeting the minimum tier
+    for model_name, tier in tier_list:
+        if _tier_passes(tier, minimum_tier):
+            return model_name
+
+    return None