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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: praisonai-code
-Version: 0.0.44
+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.44 → 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.44"
+__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.44 → praisonai_code-0.0.46}/praisonai_code/cli/app.py

@@ -149,6 +149,8 @@ _LAZY_COMMANDS: Dict[str, Tuple[str, str, str]] = {
     "session": (".commands.session", "app", "Session management"),
     "completion": (".commands.completion", "app", "Shell completion scripts"),
     "version": (".commands.version", "app", "Version information"),
+    "upgrade": (".commands.upgrade", "app", "Update the managed PraisonAI CLI install"),
+    "uninstall": (".commands.uninstall", "app", "Remove the managed PraisonAI CLI install"),
     "debug": (".commands.debug", "app", "Debug and test interactive flows"),
     "lsp": (".commands.lsp", "app", "LSP service lifecycle"),
     "diag": (".commands.diag", "app", "Diagnostics export"),
@@ -262,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",
@@ -285,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
 
@@ -297,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):
@@ -312,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())
         
@@ -361,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
@@ -787,7 +802,26 @@ def main_callback(
         trace_id=context.trace_id,
     )
     set_output_controller(state.output_controller)
-    
+
+    # Non-blocking "update available" hint from the cached background check.
+    # Text-mode only, opt-out via PRAISONAI_NO_UPDATE_CHECK; never blocks or
+    # raises (only reads a time-boxed cache, never performs network I/O here).
+    if mode == OutputMode.TEXT and not state.quiet:
+        try:
+            from .features.self_manage import (
+                maybe_schedule_update_check,
+                read_cached_hint,
+            )
+
+            hint = read_cached_hint()
+            if hint:
+                typer.echo(hint, err=True)
+            # Warm the cache in a detached child for the next invocation. Never
+            # performs network I/O here and never blocks or raises.
+            maybe_schedule_update_check()
+        except Exception:
+            pass
+
     # If no command provided, start interactive mode
     if ctx.invoked_subcommand is None:
         # Check for credentials before starting TUI

{praisonai_code-0.0.44 → 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.44 → praisonai_code-0.0.46}/praisonai_code/cli/commands/init.py

@@ -8,9 +8,12 @@ Project scaffolding command for the `.praisonai/` convention.
       config.yaml            # sensible defaults (model, output mode)
       agents/assistant.md    # working starter agent (frontmatter + body)
       commands/review.md     # working starter command using $ARGUMENTS / @file
+      tools/example.py       # commented @tool example, auto-discovered on run
 
 The scaffolded files are immediately discoverable and runnable via
 `praisonai run --agent assistant ...` and `praisonai run --command review ...`.
+Tools dropped in `.praisonai/tools/*.py` are auto-loaded on every `run`
+(gated by PRAISONAI_ALLOW_LOCAL_TOOLS).
 """
 
 from pathlib import Path
@@ -62,6 +65,29 @@ If a file path is provided, here are its contents:
 @$ARGUMENTS
 """
 
+STARTER_TOOL_PY = '''\
+"""Project-local tools for this .praisonai/ project.
+
+Every public callable in this directory is auto-discovered and made available
+to the agent on `praisonai run` — no --tools flag required. Decorate a function
+with @tool for a rich schema, or just define a plain function.
+
+Loading executes this file, so it is gated by the PRAISONAI_ALLOW_LOCAL_TOOLS
+opt-in (set PRAISONAI_ALLOW_LOCAL_TOOLS=true to enable local tool loading).
+Uncomment the example below to try it:
+
+    praisonai run "use the greet tool to greet Ada"
+"""
+
+# from praisonaiagents import tool
+#
+#
+# @tool
+# def greet(name: str) -> str:
+#     """Return a friendly greeting for the given name."""
+#     return f"Hello, {name}!"
+'''
+
 
 def _any_provider_credential() -> bool:
     """Return True if any supported provider credential is present in env."""
@@ -136,6 +162,7 @@ def init(
         (base / "config.yaml", STARTER_CONFIG.format(model=scaffold_model)),
         (base / "agents" / "assistant.md", STARTER_AGENT_MD.format(model=scaffold_model)),
         (base / "commands" / "review.md", STARTER_COMMAND_MD),
+        (base / "tools" / "example.py", STARTER_TOOL_PY),
     ]
 
     written = []