deepctl-core 0.2.3__tar.gz → 0.2.4__tar.gz

{deepctl_core-0.2.3 → deepctl_core-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl-core
-Version: 0.2.3
+Version: 0.2.4
 Summary: Core components for deepctl
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>

{deepctl_core-0.2.3 → deepctl_core-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-core"
-version = "0.2.3" # x-release-please-version
+version = "0.2.4" # x-release-please-version
 description = "Core components for deepctl"
 readme = "README.md"
 license = "MIT"

{deepctl_core-0.2.3 → deepctl_core-0.2.4}/src/deepctl_core/base_command.py

@@ -9,6 +9,7 @@ from rich.console import Console
 from .auth import AuthManager
 from .client import DeepgramClient
 from .config import Config
+from .output import _agentic, print_error, print_info, print_warning, stderr_console
 from .timing import TimingContext
 
 console = Console()
@@ -21,6 +22,7 @@ class BaseCommand(ABC):
     name: str = ""
     help: str = ""
     short_help: str | None = None
+    hidden: bool = False  # set True to hide from dg --help (e.g. deprecated aliases)
 
     # Command requirements
     requires_auth: bool = False
@@ -80,17 +82,11 @@ class BaseCommand(ABC):
                                 "explicit flags",
                                 "environment variables",
                             ]:
-                                console.print(
-                                    f"[dim]Using credentials from {source}[/dim]"
-                                )
+                                print_info(f"Using credentials from {source}")
                                 if project_id:
-                                    console.print(
-                                        f"[dim]Affecting project: {project_id}[/dim]"
-                                    )
+                                    print_info(f"Affecting project: {project_id}")
                                 else:
-                                    console.print(
-                                        "[yellow]Warning: No project ID specified[/yellow]"
-                                    )
+                                    print_warning("No project ID specified")
 
                     except Exception:
                         # guard() already printed helpful error messages;
@@ -102,12 +98,9 @@ class BaseCommand(ABC):
                 with TimingContext("project_validation"):
                     project_id = auth_manager.get_project_id()
                     if not project_id:
-                        console.print(
-                            "[red]Error:[/red] Project ID is required for this command"
-                        )
-                        console.print(
-                            "Set DEEPGRAM_PROJECT_ID environment variable or "
-                            "configure via profile"
+                        print_error(
+                            "Project ID is required for this command. "
+                            "Set DEEPGRAM_PROJECT_ID or configure via profile."
                         )
                         raise click.ClickException("Project ID required")
 
@@ -122,13 +115,13 @@ class BaseCommand(ABC):
                         self.output_result(result, config)
 
             except KeyboardInterrupt:
-                console.print("\n[yellow]Command cancelled by user[/yellow]")
+                stderr_console.print("\n[yellow]Command cancelled by user[/yellow]")
                 raise click.Abort()
 
             except Exception as e:
-                console.print(f"[red]Command failed:[/red] {e}")
+                print_error(f"Command failed: {e}")
                 if config.get("output.verbose", False):
-                    console.print_exception()
+                    stderr_console.print_exception()
                 raise click.ClickException(str(e))
 
     @abstractmethod
@@ -301,8 +294,7 @@ class BaseCommand(ABC):
         Returns:
             True if confirmed, False otherwise
         """
-        if not self.ci_friendly:
-            # In CI environments, always return the default
+        if _agentic or not self.ci_friendly:
             return default
 
         try:
@@ -326,8 +318,7 @@ class BaseCommand(ABC):
         Returns:
             User input
         """
-        if not self.ci_friendly and default is not None:
-            # In CI environments, return the default
+        if (_agentic or not self.ci_friendly) and default is not None:
             return default
 
         try:

{deepctl_core-0.2.3 → deepctl_core-0.2.4}/src/deepctl_core/output.py

@@ -22,25 +22,48 @@ from rich.table import Table
 
 # ── Agentic / non-TTY detection ──────────────────────────────────
 
-_AGENTIC_ENV_VARS = (
-    "CLAUDE_CODE",
-    "CODEX_CLI",
-    "GEMINI_CLI",
-    "AIDER",
-    "CONTINUE_GLOBAL_DIR",
-)
-
 
 def is_agentic() -> bool:
-    """Detect if running inside an AI coding tool or non-interactive pipe.
+    """Detect if running inside an AI coding tool or non-interactive context.
+
+    Uses a layered signal approach:
+    - Hard signals: known AI-tool environment variables (high confidence)
+    - Soft signals: score-based TTY/CI heuristics (3+ = probable agent)
 
-    Returns True when stdout is not a terminal OR a known agentic
-    environment variable is set.  This lets commands produce
-    machine-friendly output automatically.
+    Returns True when the context is likely non-interactive or AI-driven.
     """
-    if not sys.stdout.isatty():
+    env = os.environ
+
+    # Hard signals: explicit agent mode flag or known AI tool env vars
+    if "--agent-friendly" in sys.argv:
+        return True
+    if env.get("CLAUDECODE"):
+        return True
+    if env.get("CLAUDE_CODE_ENTRYPOINT"):
+        return True
+    if env.get("CODEX_SANDBOX"):
+        return True
+    if env.get("CODEX_SANDBOX_NETWORK_DISABLED"):
         return True
-    return any(os.environ.get(v) for v in _AGENTIC_ENV_VARS)
+    if env.get("OR_APP_NAME") == "Aider":
+        return True
+    if "aider" in env.get("OR_SITE_URL", ""):
+        return True
+
+    # Soft signals — score-based; none is conclusive alone
+    score = 0
+    if not sys.stdin.isatty():
+        score += 1
+    if not sys.stdout.isatty():
+        score += 1
+    if env.get("CI") in ("true", "1"):
+        score += 1
+    if not env.get("TERM") or env.get("TERM") == "dumb":
+        score += 1
+    if "NO_COLOR" in env:
+        score += 1
+
+    return score >= 3
 
 
 _agentic = is_agentic()
@@ -345,7 +368,10 @@ def print_debug(message: str) -> None:
         message: Debug message
     """
     if _output_config["verbose"]:
-        console.print(f"[dim]DEBUG:[/dim] {message}")
+        if _output_config["agentic"]:
+            stderr_console.print(f"DEBUG: {message}")
+        else:
+            console.print(f"[dim]DEBUG:[/dim] {message}")
 
 
 def create_progress_bar(description: str = "Processing...") -> Progress:
@@ -418,7 +444,7 @@ def confirm_action(message: str, default: bool = False) -> bool:
     Returns:
         True if confirmed, False otherwise
     """
-    if _output_config["quiet"]:
+    if _output_config["quiet"] or _output_config["agentic"]:
         return default
 
     try:
@@ -443,7 +469,7 @@ def prompt_input(message: str, default: str | None = None) -> str:
     Returns:
         User input
     """
-    if _output_config["quiet"] and default is not None:
+    if (_output_config["quiet"] or _output_config["agentic"]) and default is not None:
         return default
 
     try:

{deepctl_core-0.2.3 → deepctl_core-0.2.4}/src/deepctl_core/plugin_manager.py

@@ -1,5 +1,6 @@
 """Plugin manager for deepctl command discovery and loading."""
 
+import json
 import sys
 from importlib import metadata
 from pathlib import Path
@@ -211,7 +212,7 @@ class PluginManager:
         command_func.__name__ = command_instance.name.replace("-", "_")
         command_func.__doc__ = command_instance.help
 
-        # Build help text with examples
+        # Build help text with examples (+ AI hint when in agentic context)
         help_text = self._build_help_text(command_instance)
 
         # Create base command
@@ -220,11 +221,33 @@ class PluginManager:
             callback=command_func,
             help=help_text,
             short_help=command_instance.short_help or command_instance.help,
+            hidden=command_instance.hidden,
         )
 
         # Add arguments and options
         cmd = self._add_command_arguments(cmd, command_instance)
 
+        # Add --agent-friendly as an eager option so it fires before argument
+        # validation (like --help does), allowing AI agents to query metadata
+        # without supplying required positional arguments.
+        manager_ref = self
+
+        def _agent_friendly_callback(
+            ctx: click.Context, _param: click.Parameter, value: bool
+        ) -> None:
+            if value:
+                manager_ref._output_command_ai_metadata(command_instance)
+                ctx.exit()
+
+        cmd = click.option(
+            "--agent-friendly",
+            is_flag=True,
+            is_eager=True,
+            expose_value=False,
+            help="Output machine-readable JSON metadata for this command and exit.",
+            callback=_agent_friendly_callback,
+        )(cmd)
+
         return cmd
 
     def _build_help_text(self, instance: Any) -> str:
@@ -242,8 +265,47 @@ class PluginManager:
             help_text += "\n\nExamples:\n"
             for ex in examples:
                 help_text += f"  {ex}\n"
+        help_text += "\n\nFor agents, use --agent-friendly."
         return help_text
 
+    def _output_command_ai_metadata(self, instance: Any) -> None:
+        """Output AI-friendly JSON metadata for a command to stdout."""
+
+        def _type_name(t: Any) -> str:
+            return t.__name__ if hasattr(t, "__name__") else str(t)
+
+        arguments = (
+            instance.get_arguments() if hasattr(instance, "get_arguments") else []
+        )
+        metadata_doc = {
+            "command": instance.name,
+            "description": instance.help,
+            "agent_hints": getattr(instance, "agent_help", "") or instance.help,
+            "examples": list(getattr(instance, "examples", [])),
+            "requires_auth": bool(getattr(instance, "requires_auth", False)),
+            "requires_project": bool(getattr(instance, "requires_project", False)),
+            "non_interactive": True,
+            "output_formats": ["json", "yaml", "table", "csv"],
+            "parameters": [
+                {
+                    "name": arg.get("name")
+                    or (arg.get("names", [""])[0] if arg.get("names") else ""),
+                    "help": arg.get("help", ""),
+                    "required": bool(
+                        arg.get("required", not arg.get("is_option", False))
+                    ),
+                    "type": "bool"
+                    if arg.get("is_flag")
+                    else _type_name(arg.get("type", str)),
+                    "is_option": bool(arg.get("is_option", False)),
+                    "is_flag": bool(arg.get("is_flag", False)),
+                    "default": arg.get("default"),
+                }
+                for arg in arguments
+            ],
+        }
+        click.echo(json.dumps(metadata_doc, indent=2, default=str))
+
     def _create_click_group(self, group_instance: BaseGroupCommand) -> click.Group:
         """Create a Click group from a BaseGroupCommand instance.
 

{deepctl_core-0.2.3 → deepctl_core-0.2.4}/src/deepctl_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepctl-core
-Version: 0.2.3
+Version: 0.2.4
 Summary: Core components for deepctl
 Author-email: Deepgram <devrel@deepgram.com>
 Maintainer-email: Deepgram <devrel@deepgram.com>