praisonai-code 0.0.45__tar.gz → 0.0.46__tar.gz

{praisonai_code-0.0.45 → praisonai_code-0.0.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praisonai-code
-Version: 0.0.45
+Version: 0.0.46
 Summary: Agentic terminal CLI for PraisonAI — the terminal-native agent (run, chat, code, runtime, cli backends) extracted from the praisonai wrapper.
 Author: Mervin Praison
 License: MIT

{praisonai_code-0.0.45 → praisonai_code-0.0.46}/praisonai_code/__init__.py

@@ -12,6 +12,6 @@ the remaining terminal-agent modules, with PEP 562 shims left behind at the
 old ``praisonai.*`` paths for backward compatibility.
 """
 
-__version__ = "0.0.45"
+__version__ = "0.0.46"
 
 __all__ = ["__version__"]

praisonai_code-0.0.46/praisonai_code/_train_bridge.py

@@ -0,0 +1,35 @@
+"""Lazy access to ``praisonai-train`` from ``praisonai-code``."""
+
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+_INSTALL_HINT = "Install the training package: pip install praisonai-train"
+
+
+def train_package_available() -> bool:
+    import importlib.util
+
+    return importlib.util.find_spec("praisonai_train") is not None
+
+
+def import_train_module(name: str) -> ModuleType:
+    if not name.startswith("praisonai_train"):
+        raise ValueError(f"Expected praisonai_train module name, got {name!r}")
+    try:
+        return importlib.import_module(name)
+    except ImportError as exc:
+        raise ImportError(f"{name} requires praisonai-train. {_INSTALL_HINT}") from exc
+
+
+def optional_train_attr(module_name: str, attr: str, default: T | None = None) -> Any | T | None:
+    if not train_package_available():
+        return default
+    try:
+        return getattr(import_train_module(module_name), attr)
+    except (ImportError, AttributeError):
+        return default

{praisonai_code-0.0.45 → praisonai_code-0.0.46}/praisonai_code/cli/app.py

@@ -264,8 +264,7 @@ _WRAPPER_RESIDENT_COMMANDS = frozenset({
     "flow",
     "n8n",
     "replay",
-    # C8.2 Batch B — training / managed / examples
-    "train",
+    # C8.2 Batch B — managed / examples (train extracted to praisonai-train in C10)
     "managed",
     "examples",
     "standardise",
@@ -287,6 +286,13 @@ _WRAPPER_RESIDENT_COMMANDS = frozenset({
     "validate",
 })
 
+# C10: Training commands implemented in ``praisonai_train.cli.commands.*``.
+# ``get_command()`` loads them via ``praisonai_train.cli.commands.{name}`` when the
+# train package is installed; standalone ``praisonai-code`` hides them from ``--help``.
+_TRAIN_RESIDENT_COMMANDS = frozenset({
+    "train",
+})
+
 # Backward-compatible alias (C7.1 name).
 _WRAPPER_COMMANDS = _WRAPPER_RESIDENT_COMMANDS
 
@@ -299,6 +305,7 @@ _SPECIAL_COMMANDS = {
 
 from praisonai_code._wrapper_bridge import wrapper_available
 from praisonai_code._bot_bridge import bot_package_available
+from praisonai_code._train_bridge import train_package_available
 
 
 class LazyCommandGroup(TyperGroup):
@@ -314,10 +321,12 @@ class LazyCommandGroup(TyperGroup):
         # install does not surface commands it cannot resolve.
         wrapper_ok = wrapper_available()
         bot_ok = bot_package_available()
+        train_ok = train_package_available()
         commands.update(
             name for name in _LAZY_COMMANDS
             if (wrapper_ok or name not in _WRAPPER_RESIDENT_COMMANDS)
             and (bot_ok or name not in _BOT_RESIDENT_COMMANDS)
+            and (train_ok or name not in _TRAIN_RESIDENT_COMMANDS)
         )
         commands.update(_SPECIAL_COMMANDS.keys())
         
@@ -363,6 +372,10 @@ class LazyCommandGroup(TyperGroup):
                     if not bot_package_available():
                         return None
                     module = importlib.import_module(f"praisonai_bot.cli.commands.{name}")
+                elif name in _TRAIN_RESIDENT_COMMANDS:
+                    if not train_package_available():
+                        return None
+                    module = importlib.import_module(f"praisonai_train.cli.commands.{name}")
                 elif name in _WRAPPER_RESIDENT_COMMANDS:
                     if not wrapper_available():
                         return None

{praisonai_code-0.0.45 → praisonai_code-0.0.46}/praisonai_code/cli/commands/auth.py

@@ -21,6 +21,85 @@ from ..configuration.credentials import CredentialStore, redact_key, validate_ap
 app = typer.Typer(help="Manage API credentials")
 
 
+# Provider id -> environment variable holding its API key. Used to fold active
+# env-sourced credentials into `auth list`/`status` so users can tell which
+# credential is live (env vs stored).
+_PROVIDER_ENV_KEYS = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "google": "GOOGLE_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+    "mistral": "MISTRAL_API_KEY",
+    "deepseek": "DEEPSEEK_API_KEY",
+    "xai": "XAI_API_KEY",
+    "cohere": "COHERE_API_KEY",
+    "together": "TOGETHER_API_KEY",
+    "perplexity": "PERPLEXITYAI_API_KEY",
+}
+
+
+def _env_credentials() -> dict[str, tuple[str, str]]:
+    """Return ``{provider: (env_var, api_key)}`` for env-sourced keys present."""
+    found = {}
+    for provider, env_var in _PROVIDER_ENV_KEYS.items():
+        value = os.environ.get(env_var)
+        if value:
+            found[provider] = (env_var, value)
+    return found
+
+
+def _select_provider_interactively(output) -> Optional[str]:
+    """Catalogue-driven provider picker for when no provider id is supplied.
+
+    Returns the chosen provider id, or ``None`` if selection is unavailable
+    (non-tty / rich missing) so the caller can prompt for a free-form id.
+    """
+    try:
+        from praisonai_code.llm.catalogue import ModelCatalogue
+
+        providers = ModelCatalogue().list_providers()
+    except Exception:
+        providers = []
+
+    ordered = [p for p in ("openai", "anthropic", "google", "ollama") if p in providers]
+    for p in providers:
+        if p not in ordered:
+            ordered.append(p)
+    ordered.append("custom")
+
+    try:
+        from rich.prompt import Prompt
+    except Exception:
+        return None
+
+    output.console.print("[bold]Choose your LLM provider:[/bold]")
+    choices = {}
+    for idx, pid in enumerate(ordered, start=1):
+        choices[str(idx)] = pid
+        label = "Other/custom" if pid == "custom" else pid
+        output.console.print(f"  {idx}) {label}")
+
+    selected = Prompt.ask("Select provider", choices=list(choices.keys()), default="1")
+    pid = choices[selected]
+    if pid == "custom":
+        return Prompt.ask("Enter provider id").strip() or None
+    return pid
+
+
+def _print_key_url_hint(provider: str, output) -> None:
+    """Print a one-line 'Get your key' hint for well-known providers."""
+    try:
+        from praisonai_code.llm.catalogue import key_url_for_provider
+
+        url = key_url_for_provider(provider)
+    except Exception:
+        url = None
+    if url:
+        output.print_info(f"Get your key: {url}")
+
+
 def _format_expiry(cred) -> str:
     """Format an OAuth credential's expiry for display ('(n/a)' for keys)."""
     if not getattr(cred, "auth_method", "apikey") == "oauth":
@@ -148,7 +227,7 @@ def _run_oauth_login(
 
 @app.command("login")
 def auth_login(
-    provider: str = typer.Argument(help="Provider name (e.g., openai, anthropic)"),
+    provider: Optional[str] = typer.Argument(None, help="Provider name (e.g., openai, anthropic); prompts a picker if omitted"),
     method: str = typer.Option("auto", "--method", help="Auth method: auto, apikey, or oauth"),
     key: Optional[str] = typer.Option(None, "--key", help="API key (will prompt if not provided)"),
     key_stdin: bool = typer.Option(False, "--key-stdin", help="Read API key from stdin"),
@@ -173,6 +252,15 @@ def auth_login(
     """
     output = get_output_controller()
 
+    # Provider is optional: when omitted, present a catalogue-driven picker so
+    # users don't need to know the exact provider id up front. The positional
+    # argument still works for scripts.
+    if not provider:
+        provider = _select_provider_interactively(output)
+        if not provider:
+            output.print_error("A provider is required")
+            raise typer.Exit(1)
+
     # Assemble any OAuth endpoint overrides supplied on the command line. These
     # let users sign in to a built-in provider that needs an app client id, or
     # to a provider not in the registry (e.g. a self-hosted gateway).
@@ -232,6 +320,7 @@ def auth_login(
         api_key = key
     else:
         # Prompt for key
+        _print_key_url_hint(provider, output)
         try:
             api_key = typer.prompt(
                 f"Enter API key for {provider}",
@@ -357,46 +446,74 @@ def auth_list():
     try:
         store = CredentialStore()
         providers = store.list_providers()
-        
-        if not providers:
-            output.print_info("No stored credentials")
-            if output.is_json_mode:
-                output.print_json({"providers": []})
-            return
-        
-        # Get detailed info for each provider
+
+        # Get detailed info for each stored provider.
         provider_info = []
+        stored_names = set()
         for provider_name in providers:
             cred = store.get_credential(provider_name)
             if cred:
-                info = {
+                stored_names.add(provider_name.lower())
+                provider_info.append({
                     "provider": provider_name,
                     "auth_method": cred.auth_method,
+                    "source": "stored",
+                    "env_var": None,
                     "key_redacted": redact_key(cred.api_key),
                     "base_url": cred.base_url,
                     "model": cred.model,
                     "expires_at": cred.expires_at,
                     "expires": _format_expiry(cred),
-                }
-                provider_info.append(info)
-        
+                })
+
+        # Fold in active environment-variable keys (redacted) so the live
+        # credential is unambiguous. An env key is ALWAYS surfaced when present
+        # — even if the provider also has a stored key — because the env value
+        # overrides the stored one at runtime, so hiding it would point users at
+        # the wrong secret when they inspect or rotate credentials.
+        for provider_name, (env_var, value) in _env_credentials().items():
+            provider_info.append({
+                "provider": provider_name,
+                "auth_method": "apikey",
+                "source": "env",
+                "env_var": env_var,
+                "key_redacted": redact_key(value),
+                "base_url": None,
+                "model": None,
+                "expires_at": None,
+                "expires": "(n/a)",
+                "overrides_stored": provider_name in stored_names,
+            })
+
+        if not provider_info:
+            output.print_info("No stored credentials")
+            if output.is_json_mode:
+                output.print_json({"providers": []})
+            return
+
         if output.is_json_mode:
             output.print_json({"providers": provider_info})
         else:
             # Create table
-            headers = ["Provider", "Method", "Secret", "Expires", "Base URL", "Model"]
+            headers = ["Provider", "Method", "Source", "Secret", "Expires", "Base URL", "Model"]
             rows = []
             for info in provider_info:
+                source = info["source"]
+                if source == "env" and info.get("env_var"):
+                    source = f"env ({info['env_var']})"
+                    if info.get("overrides_stored"):
+                        source += " [live, overrides stored]"
                 rows.append([
                     info["provider"],
                     info["auth_method"],
+                    source,
                     info["key_redacted"],
                     info["expires"],
                     info["base_url"] or "(default)",
                     info["model"] or "(none)"
                 ])
             
-            output.print_table(headers, rows, title="Stored Credentials")
+            output.print_table(headers, rows, title="Credentials")
             
     except Exception as e:
         output.print_error(f"Failed to list credentials: {e}")
@@ -425,6 +542,40 @@ def auth_status(
             # Check specific provider
             cred = store.get_credential(provider)
             if not cred:
+                # Fall back to an active environment-variable key so the user
+                # can tell the credential is live from the env, not just missing
+                # from the store.
+                env_var = _PROVIDER_ENV_KEYS.get(provider.lower())
+                env_value = os.environ.get(env_var) if env_var else None
+                if env_value:
+                    format_valid, format_msg = validate_api_key(provider, env_value)
+                    status_info = {
+                        "provider": provider,
+                        "status": "found",
+                        "auth_method": "apikey",
+                        "source": "env",
+                        "env_var": env_var,
+                        "key_redacted": redact_key(env_value),
+                        "format_valid": format_valid,
+                        "format_message": format_msg,
+                        "base_url": None,
+                        "model": None,
+                        "expires_at": None,
+                        "expires": "(n/a)",
+                    }
+                    if output.is_json_mode:
+                        output.print_json(status_info)
+                    else:
+                        output.print_panel(
+                            f"Provider: {provider}\n"
+                            f"Method: apikey\n"
+                            f"Source: env ({env_var})\n"
+                            f"Secret: {redact_key(env_value)}\n"
+                            f"Format: {'✅' if format_valid else '❌'} {format_msg}",
+                            title=f"Credentials Status: {provider}"
+                        )
+                    return
+
                 output.print_warning(f"No credentials found for {provider}")
                 if output.is_json_mode:
                     output.print_json({
@@ -433,17 +584,34 @@ def auth_status(
                     })
                 raise typer.Exit(1)
             
-            # Basic format validation (OAuth tokens have no static format)
+            # A live env var overrides the stored credential at runtime. When
+            # both exist, validate/report the env key (the credential actually
+            # in effect) so status never claims the wrong secret is active.
+            env_var = _PROVIDER_ENV_KEYS.get(provider.lower())
+            env_value = os.environ.get(env_var) if env_var else None
+            active_from_env = bool(env_value) and not cred.is_oauth()
+
             if cred.is_oauth():
                 format_valid, format_msg = True, "OAuth token"
+                secret = cred.api_key
+                source = "stored"
+            elif active_from_env:
+                format_valid, format_msg = validate_api_key(provider, env_value)
+                secret = env_value
+                source = f"env ({env_var})"
             else:
                 format_valid, format_msg = validate_api_key(provider, cred.api_key)
-            
+                secret = cred.api_key
+                source = "stored"
+
             status_info = {
                 "provider": provider,
                 "status": "found",
                 "auth_method": cred.auth_method,
-                "key_redacted": redact_key(cred.api_key),
+                "source": source,
+                "env_var": env_var if active_from_env else None,
+                "overrides_stored": active_from_env,
+                "key_redacted": redact_key(secret),
                 "format_valid": format_valid,
                 "format_message": format_msg,
                 "base_url": cred.base_url,
@@ -454,9 +622,11 @@ def auth_status(
             
             # Live validation if requested
             if validate:
-                # Use a freshly-refreshed token for OAuth so we don't validate a
-                # stale mirrored access token.
-                live_secret = store.get_valid_token(provider) if cred.is_oauth() else cred.api_key
+                if cred.is_oauth():
+                    # Freshly-refreshed token so we don't validate a stale mirror.
+                    live_secret = store.get_valid_token(provider)
+                else:
+                    live_secret = secret
                 live_valid, live_msg = _validate_with_live_call(provider, live_secret, cred.base_url)
                 status_info["live_valid"] = live_valid
                 status_info["live_message"] = live_msg
@@ -467,7 +637,9 @@ def auth_status(
                 output.print_panel(
                     f"Provider: {provider}\n"
                     f"Method: {cred.auth_method}\n"
-                    f"Secret: {redact_key(cred.api_key)}\n"
+                    f"Source: {source}\n"
+                    + ("Note: env var overrides stored key at runtime\n" if active_from_env else "") +
+                    f"Secret: {redact_key(secret)}\n"
                     + (f"Expires: {_format_expiry(cred)}\n" if cred.is_oauth() else "") +
                     f"Format: {'✅' if format_valid else '❌'} {format_msg}\n"
                     + (f"Live Test: {'✅' if status_info.get('live_valid') else '❌'} {status_info.get('live_message', 'Not tested')}\n" if validate else "") +
@@ -479,17 +651,13 @@ def auth_status(
         else:
             # Check all providers
             providers = store.list_providers()
-            
-            if not providers:
-                output.print_info("No stored credentials")
-                if output.is_json_mode:
-                    output.print_json({"providers": []})
-                return
-            
+
             all_status = []
+            stored_names = set()
             for provider_name in providers:
                 cred = store.get_credential(provider_name)
                 if cred:
+                    stored_names.add(provider_name.lower())
                     if cred.is_oauth():
                         format_valid, format_msg = True, "OAuth token"
                     else:
@@ -498,6 +666,7 @@ def auth_status(
                     status = {
                         "provider": provider_name,
                         "auth_method": cred.auth_method,
+                        "source": "stored",
                         "key_redacted": redact_key(cred.api_key),
                         "format_valid": format_valid,
                         "format_message": format_msg,
@@ -516,12 +685,42 @@ def auth_status(
                         status["live_message"] = live_msg
                     
                     all_status.append(status)
-            
+
+            # Fold in active env-var keys (redacted), marked env-sourced. Always
+            # surfaced even when the provider also has a stored key, since the
+            # env value is the credential in effect at runtime.
+            for provider_name, (env_var, value) in _env_credentials().items():
+                format_valid, format_msg = validate_api_key(provider_name, value)
+                source = f"env ({env_var})"
+                if provider_name in stored_names:
+                    source += " [live, overrides stored]"
+                status = {
+                    "provider": provider_name,
+                    "auth_method": "apikey",
+                    "source": source,
+                    "key_redacted": redact_key(value),
+                    "format_valid": format_valid,
+                    "format_message": format_msg,
+                    "expires_at": None,
+                    "expires": "(n/a)",
+                }
+                if validate:
+                    live_valid, live_msg = _validate_with_live_call(provider_name, value, None)
+                    status["live_valid"] = live_valid
+                    status["live_message"] = live_msg
+                all_status.append(status)
+
+            if not all_status:
+                output.print_info("No stored credentials")
+                if output.is_json_mode:
+                    output.print_json({"providers": []})
+                return
+
             if output.is_json_mode:
                 output.print_json({"providers": all_status})
             else:
                 # Create table
-                headers = ["Provider", "Method", "Secret", "Expires", "Format"]
+                headers = ["Provider", "Method", "Source", "Secret", "Expires", "Format"]
                 if validate:
                     headers.append("Live Test")
                 
@@ -530,6 +729,7 @@ def auth_status(
                     row = [
                         status["provider"],
                         status["auth_method"],
+                        status.get("source", "stored"),
                         status["key_redacted"],
                         status["expires"],
                         "✅" if status["format_valid"] else "❌"

{praisonai_code-0.0.45 → praisonai_code-0.0.46}/praisonai_code/cli/features/setup/handler.py

@@ -87,16 +87,18 @@ class SetupHandler(CommandHandler):
             return 1
         
         providers = self._provider_defaults()
-        
-        if provider not in providers:
-            output.print_error(f"Unknown provider: {provider}")
-            output.console.print("Valid providers: openai, anthropic, google, ollama, custom")
-            return 1
-        
-        provider_info = providers[provider]
-        provider_name = provider_info[0]
-        env_key = provider_info[1]
-        default_model = provider_info[2]
+
+        if provider in providers:
+            provider_info = providers[provider]
+            provider_name = provider_info[0]
+            env_key = provider_info[1]
+            default_model = provider_info[2]
+        else:
+            # Accept any catalogue-known provider (Groq, OpenRouter, Mistral, …)
+            # by deriving its env-var/default rather than rejecting it.
+            env_key, default_model, provider_name = self._provider_setup_info(
+                provider, providers
+            )
         
         # Validate API key requirement
         if env_key:
@@ -173,26 +175,24 @@ class SetupHandler(CommandHandler):
         
         # 2. Provider selection (only if nothing detected / accepted)
         if provider_id is None:
+            menu = self._catalogue_provider_choices()
             output.console.print("[bold]1. Choose your LLM provider:[/bold]")
-            output.console.print("  1) OpenAI (GPT-4o, GPT-4, GPT-3.5)")
-            output.console.print("  2) Anthropic (Claude)")
-            output.console.print("  3) Google (Gemini)")
-            output.console.print("  4) Ollama (Local models)")
-            output.console.print("  5) Custom provider")
-            
+            for choice, (pid, _env_key, _model, name) in menu.items():
+                label = "Custom provider" if pid == "custom" else name
+                output.console.print(f"  {choice}) {label}")
+
             provider_choice = Prompt.ask(
                 "\nSelect provider",
-                choices=["1", "2", "3", "4", "5"],
+                choices=list(menu.keys()),
                 default="1"
             )
             
-            provider_id, env_key, default_model, provider_name = (
-                self._provider_menu()[provider_choice]
-            )
+            provider_id, env_key, default_model, provider_name = menu[provider_choice]
             
             # API key input with live validation + re-prompt loop
             if env_key:
                 output.console.print(f"\n[bold]2. Enter your {provider_name} API key:[/bold]")
+                self._print_key_url_hint(provider_id, output)
                 
                 existing_key = os.getenv(env_key)
                 if existing_key and Confirm.ask(
@@ -291,7 +291,12 @@ class SetupHandler(CommandHandler):
         }
 
     def _provider_menu(self) -> Dict[str, tuple]:
-        """Numeric provider menu → (provider_id, env_key, default_model, name)."""
+        """Numeric provider menu → (provider_id, env_key, default_model, name).
+
+        Retained for backward compatibility / non-interactive callers. The
+        interactive wizard now uses the catalogue-driven picker in
+        ``_catalogue_provider_choices``.
+        """
         defaults = self._provider_defaults()
         ordered = ["openai", "anthropic", "google", "ollama", "custom"]
         menu = {}
@@ -300,6 +305,96 @@ class SetupHandler(CommandHandler):
             menu[str(idx)] = (pid, env_key, model, name)
         return menu
 
+    def _catalogue_provider_choices(self) -> Dict[str, tuple]:
+        """Numeric picker keyed "1".. → (provider_id, env_key, default_model, name).
+
+        Catalogue-driven: unions the curated ``_provider_defaults`` entries with
+        every provider enumerated by ``ModelCatalogue`` so onboarding covers the
+        full set of supported providers (Groq, OpenRouter, Mistral, DeepSeek,
+        xAI, …) rather than a hardcoded five. Always ends with a "custom"
+        escape hatch.
+        """
+        defaults = self._provider_defaults()
+
+        ordered = ["openai", "anthropic", "google", "ollama"]
+
+        catalogue_providers = []
+        try:
+            from praisonai_code.llm.catalogue import ModelCatalogue
+
+            catalogue_providers = ModelCatalogue().list_providers()
+        except Exception:
+            catalogue_providers = []
+
+        for pid in catalogue_providers:
+            if pid not in ordered and pid not in ("custom",):
+                ordered.append(pid)
+
+        menu: Dict[str, tuple] = {}
+        idx = 1
+        for pid in ordered:
+            env_key, default_model, name = self._provider_setup_info(pid, defaults)
+            menu[str(idx)] = (pid, env_key, default_model, name)
+            idx += 1
+
+        # Custom escape hatch is always last.
+        menu[str(idx)] = ("custom", None, None, "Custom")
+        return menu
+
+    # Providers whose canonical API-key env-var is NOT ``<PROVIDER>_API_KEY``.
+    # Kept in sync with auth's ``_PROVIDER_ENV_KEYS`` so setup writes the same
+    # env-var name that auth (and the runtime) reads back.
+    _PROVIDER_ENV_KEY_OVERRIDES = {
+        "google": "GEMINI_API_KEY",
+        "gemini": "GEMINI_API_KEY",
+        "perplexity": "PERPLEXITYAI_API_KEY",
+    }
+
+    def _provider_setup_info(self, provider_id: str, defaults: Dict[str, tuple]) -> tuple:
+        """Resolve ``(env_key, default_model, name)`` for a provider id.
+
+        Prefers a curated ``_provider_defaults`` row; otherwise derives a
+        usable env-var, default model, and display name from the catalogue so
+        catalogue-only providers (Groq, OpenRouter, …) get a working
+        non-interactive path rather than falling through to the custom branch.
+        """
+        if provider_id in defaults:
+            name, env_key, model = defaults[provider_id]
+            return env_key, model, name
+        env_key = self._PROVIDER_ENV_KEY_OVERRIDES.get(
+            provider_id, f"{provider_id.upper()}_API_KEY"
+        )
+        default_model = self._catalogue_default_model(provider_id)
+        return env_key, default_model, provider_id.capitalize()
+
+    def _catalogue_default_model(self, provider_id: str) -> Optional[str]:
+        """Return a sensible default model for a catalogue provider, or ``None``.
+
+        Picks the first model the catalogue lists for the provider so
+        catalogue-known providers get a non-interactive default instead of
+        being rejected like a custom provider.
+        """
+        try:
+            from praisonai_code.llm.catalogue import ModelCatalogue
+
+            models = ModelCatalogue().list_models(provider=provider_id)
+        except Exception:
+            return None
+        if not models:
+            return None
+        return models[0].get("id")
+
+    def _print_key_url_hint(self, provider_id: str, output) -> None:
+        """Print a one-line 'Get your key' hint for well-known providers."""
+        try:
+            from praisonai_code.llm.catalogue import key_url_for_provider
+
+            url = key_url_for_provider(provider_id)
+        except Exception:
+            url = None
+        if url:
+            output.console.print(f"[dim]Get your key: {url}[/dim]")
+
     def _detect_provider_from_env(self) -> Optional[tuple]:
         """Detect a provider whose ``*_API_KEY`` is already in the environment.