nooa-cli 0.0.7__py3-none-any.whl

nooa_cli/AGENTS.md

@@ -0,0 +1,162 @@
+# nooa CLI — Adding New Commands
+
+## Quick Start
+
+```bash
+cd src/nooa_cli/commands/
+cp _template.py mycommand.py    # copy the template
+# edit mycommand.py              # add your logic
+nooa mycommand              # it just works
+```
+
+That's it. No registration, no config files, no editing other files.
+
+## How It Works
+
+The CLI auto-discovers every `.py` file in `src/nooa_cli/commands/` at startup.
+Files starting with `_` are ignored (private helpers, templates).
+
+### The Contract
+
+Your command module must export **one thing**: a module-level variable named `command`
+that is a Click command or group.
+
+```python
+# commands/mycommand.py
+import click
+
+@click.command()
+@click.argument("name")
+def command(name: str):
+    """One-line description shown in `nooa --help`."""
+    click.echo(f"Hello, {name}!")
+```
+
+The filename becomes the subcommand name: `mycommand.py` → `nooa mycommand`.
+
+### Override the Name
+
+Add `NAME` at module level if the filename doesn't match what you want:
+
+```python
+NAME = "my-command"  # nooa my-command (instead of nooa mycommand)
+```
+
+## Patterns
+
+### Simple Command (leaf, no subcommands)
+
+```python
+import click
+
+@click.command()
+@click.argument("target", type=click.Path(exists=True))
+@click.option("--verbose", "-v", is_flag=True)
+def command(target: str, verbose: bool):
+    """Do something to TARGET."""
+    click.echo(f"Processing {target}")
+```
+
+### Group with Subcommands
+
+For `nooa things list` / `nooa things create`:
+
+```python
+import click
+
+@click.group()
+def command():
+    """Manage things."""
+
+@command.command()
+def list():
+    """List all things."""
+    click.echo("thing-1\nthing-2")
+
+@command.command()
+@click.argument("name")
+def create(name: str):
+    """Create a new thing."""
+    click.echo(f"Created: {name}")
+```
+
+### Passthrough to Another CLI
+
+For wrapping an existing tool without duplicating its options:
+
+```python
+import click
+
+@click.command(
+    add_help_option=False,
+    context_settings=dict(
+        ignore_unknown_options=True,
+        allow_extra_args=True,
+    ),
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def command(args: tuple[str, ...]):
+    """Run some-other-tool (all args forwarded)."""
+    import subprocess, sys
+    subprocess.run([sys.executable, "-m", "some_other_tool", *args])
+```
+
+## Shared Utilities
+
+Common helpers live in `src/nooa_cli/_common.py`:
+
+```python
+from nooa_cli._common import find_project_root, format_size
+
+root = find_project_root()           # Path to project root (where pyproject.toml is)
+format_size(1_500_000)               # "1.4 MB"
+```
+
+For API keys / env vars, use `nooa.secrets.load_secrets_into_env()`
+(reads the layered `secrets.yaml`); for any layered config file use
+`nooa.layered_config.load_layered_yaml(filename, env_var)`.
+
+## Performance Rule
+
+**Keep imports lazy.** The CLI starts in ~0.3s because it doesn't import the
+heavy `nooa` framework at module level. Only import heavy dependencies
+inside your command handler function:
+
+```python
+@click.command()
+def command():
+    """Do something that needs the framework."""
+    # These imports happen only when the command actually runs,
+    # not when `nooa --help` loads the CLI.
+    from nooa import Agent
+    import pandas as pd
+```
+
+## File Layout
+
+```
+src/nooa_cli/
+├── __init__.py              # Root CLI group + auto-discovery wiring
+├── __main__.py              # python -m nooa_cli
+├── _common.py               # Shared utilities
+├── completion.py            # Shell completion (bash/zsh/fish)
+├── AGENTS.md                # ← You are here
+└── commands/
+    ├── __init__.py          # Auto-discovery engine
+    ├── _template.py         # Copy-paste starter for new commands
+    ├── eval.py              # nooa eval ...
+    ├── traces.py            # nooa traces cleanup/list/stats
+    └── start_dev.py         # nooa start-dev
+```
+
+## Shell Completion
+
+New commands get tab-completion automatically. To enable it:
+
+```bash
+nooa completion install   # auto-detects your shell
+
+# Or manually:
+eval "$(_NEMO_COMPLETE=zsh_source nemo)"   # zsh
+eval "$(_NEMO_COMPLETE=bash_source nemo)"  # bash
+```

nooa_cli/__init__.py

@@ -0,0 +1,70 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""NVIDIA OO Agents CLI — extensible command-line toolkit.
+
+Usage:
+    nooa eval --config config.yaml  # Run an eval-pipeline job
+    nooa start-dev                  # Start the viewer
+    nooa traces delete              # Delete traces
+    nooa completion install         # Set up shell completions
+
+Adding new commands:
+    Drop a .py file in nooa_cli/commands/ — see commands/_template.py
+
+Shell completion:
+    eval "$(_NOOA_COMPLETE=bash_source nooa)"    # bash
+    eval "$(_NOOA_COMPLETE=zsh_source nooa)"     # zsh
+"""
+
+import click
+
+from .commands import discover_commands
+from .completion import completion
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+# `completion` just emits a shell script and doesn't need the ~1.5s core
+# import cost or secrets preload.
+_SKIP_SECRETS_PRELOAD = {"completion"}
+
+
+@click.group(context_settings=CONTEXT_SETTINGS)
+@click.version_option(package_name="nooa-cli")
+@click.pass_context
+def oo(ctx):
+    """OO Agents — agent toolkit.
+
+    Extensible CLI for running agents, evaluations, and trace management.
+    Add new commands by dropping a .py file in nooa_cli/commands/.
+    """
+    if ctx.invoked_subcommand in _SKIP_SECRETS_PRELOAD:
+        return
+    # Load secrets.yaml into the process env before any subcommand runs so
+    # all commands (config show, eval, …) see the same API keys.
+    # Non-clobbering (shell env wins) and best-effort: a broken or missing
+    # secrets file must never block the CLI — but log the failure at debug
+    # so it's recoverable rather than silently swallowed.
+    try:
+        from nooa.secrets import load_secrets_into_env
+
+        load_secrets_into_env()
+    except Exception:
+        import logging
+
+        logging.getLogger(__name__).debug(
+            "Failed to preload secrets.yaml into the environment", exc_info=True
+        )
+
+
+# -- Auto-discover and register all commands from commands/ -----------------
+for _name, _cmd in discover_commands():
+    oo.add_command(_cmd, name=_name)
+
+# -- Built-in infrastructure commands (not in commands/ because they're meta) -
+oo.add_command(completion)
+
+
+def main():
+    """Entry point for console_scripts: nooa <subcommand>."""
+    oo()

nooa_cli/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Enable running as: python -m nooa_cli"""
+
+from . import main
+
+if __name__ == "__main__":
+    main()

nooa_cli/_common.py

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Shared utilities for nooa CLI commands.
+
+Import from here instead of duplicating helpers across command modules:
+
+    from nooa_cli._common import find_project_root, format_size
+"""
+
+from pathlib import Path
+
+
+def find_project_root() -> Path:
+    """Find the user's project root by walking up from the current directory.
+
+    Starts at :func:`Path.cwd` — the directory the CLI was invoked from — and
+    walks upward, returning the first ancestor (including the cwd itself) that
+    contains a ``pyproject.toml``. Falls back to the current working directory
+    if none is found.
+
+    Walking up from the cwd (rather than from this module's ``__file__``) ensures
+    the *user's* project is resolved. Resolving from ``__file__`` would instead
+    find the installed CLI package's own ``pyproject.toml`` in an editable or
+    monorepo install, which is never what a user of ``nooa`` wants.
+
+    Uses a local implementation to keep CLI startup fast (avoids importing
+    the heavy nooa core package at module level).
+    """
+    cwd = Path.cwd().resolve()
+    for candidate in (cwd, *cwd.parents):
+        if (candidate / "pyproject.toml").exists():
+            return candidate
+    return cwd
+
+
+def format_size(size_bytes: int) -> str:
+    """Format a byte count as human-readable (e.g. '4.2 MB')."""
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    elif size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    elif size_bytes < 1024 * 1024 * 1024:
+        return f"{size_bytes / (1024 * 1024):.1f} MB"
+    else:
+        return f"{size_bytes / (1024 * 1024 * 1024):.1f} GB"

nooa_cli/commands/__init__.py

@@ -0,0 +1,106 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Auto-discovered command modules for the nooa CLI.
+
+╔══════════════════════════════════════════════════════════════════════╗
+║                    HOW TO ADD A NEW COMMAND                         ║
+╠══════════════════════════════════════════════════════════════════════╣
+║                                                                      ║
+║  1. Create a new .py file in this directory (commands/)              ║
+║  2. Define a click command or group                                  ║
+║  3. Assign it to a module-level variable named `command`             ║
+║  4. That's it — it's automatically registered.                       ║
+║                                                                      ║
+║  See _template.py for a copy-paste starter.                          ║
+║                                                                      ║
+╚══════════════════════════════════════════════════════════════════════╝
+
+Convention
+----------
+
+Each Python file in this directory that does NOT start with ``_`` is
+auto-discovered and registered as a top-level subcommand of ``nooa``.
+
+A command module **must** export a module-level variable named ``command``
+that is a ``click.BaseCommand`` (either a ``@click.command()`` or a
+``@click.group()``).
+
+Optionally, you can set:
+    NAME = "custom-name"      # Override the command name (default: filename)
+
+The file name (minus ``.py``) becomes the subcommand name by default::
+
+    commands/start_dev.py →  nooa start-dev ...
+
+Files starting with ``_`` are ignored (private helpers, templates, etc.).
+
+Minimal example (commands/hello.py)::
+
+    import click
+
+    @click.command()
+    @click.argument("name", default="world")
+    def command(name):
+        \"\"\"Say hello.\"\"\"
+        click.echo(f"Hello, {name}!")
+
+Full example with a group (commands/things.py)::
+
+    import click
+
+    @click.group()
+    def command():
+        \"\"\"Manage things.\"\"\"
+
+    @command.command()
+    def list():
+        \"\"\"List all things.\"\"\"
+        click.echo("thing-1\\nthing-2")
+
+    @command.command()
+    @click.argument("name")
+    def create(name):
+        \"\"\"Create a new thing.\"\"\"
+        click.echo(f"Created {name}")
+"""
+
+import importlib
+import pkgutil
+from collections.abc import Iterator
+
+import click
+
+
+def discover_commands() -> Iterator[tuple[str, click.Command]]:
+    """Yield (name, command) pairs from all command modules in this package.
+
+    Scans this directory for Python modules, imports each one, and looks
+    for a ``command`` attribute that is a ``click.Command`` or ``click.Group``.
+
+    Modules starting with ``_`` are skipped (private / template files).
+    """
+    package_path = __path__
+    package_name = __name__
+
+    for module_info in pkgutil.iter_modules(package_path):
+        # Skip private modules (_template, _helpers, etc.)
+        if module_info.name.startswith("_"):
+            continue
+
+        module = importlib.import_module(f"{package_name}.{module_info.name}")
+
+        # The module must export `command`
+        cmd = getattr(module, "command", None)
+        if cmd is None:
+            continue
+
+        if not isinstance(cmd, click.Command):
+            raise TypeError(
+                f"commands/{module_info.name}.py: `command` must be a click.Command or click.Group, "
+                f"got {type(cmd).__name__}. Use @click.command() or @click.group()."
+            )
+
+        # Allow overriding the command name
+        name = getattr(module, "NAME", module_info.name)
+
+        yield name, cmd

nooa_cli/commands/_otlp_helpers.py

@@ -0,0 +1,122 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Shared utilities for OTLP trace import commands."""
+
+import json
+import urllib.parse
+import urllib.request
+
+import click
+
+
+def validate_endpoint(endpoint: str) -> None:
+    """Validate that the endpoint uses an HTTP(S) scheme."""
+    parsed = urllib.parse.urlparse(endpoint)
+    if parsed.scheme not in ("http", "https"):
+        raise click.BadParameter(
+            f"Endpoint must use http:// or https:// scheme, got: {endpoint}",
+            param_hint="'--endpoint'",
+        )
+
+
+def inject_resource_attrs(body: dict, attrs: dict[str, str | bool | int]) -> dict:
+    """Inject additional resource attributes into an OTLP body (skips existing keys).
+
+    Values are typed: str → stringValue, bool → boolValue, int → intValue.
+    """
+    for rs in body.get("resourceSpans", []):
+        resource = rs.setdefault("resource", {})
+        existing = resource.setdefault("attributes", [])
+        existing_keys = {a["key"] for a in existing}
+        for key, val in attrs.items():
+            if key not in existing_keys:
+                if isinstance(val, bool):
+                    otlp_val = {"boolValue": val}
+                elif isinstance(val, int):
+                    otlp_val = {"intValue": val}
+                else:
+                    otlp_val = {"stringValue": val}
+                existing.append({"key": key, "value": otlp_val})
+    return body
+
+
+def post_trace(endpoint: str, body: dict, timeout: float = 30) -> bool:
+    """POST a single OTLP trace body to the viewer endpoint.
+
+    ``timeout`` defaults to 30s so large batched bodies (see ``post_traces_batch``)
+    don't spuriously time out; per-line callers are unaffected.
+    """
+    url = f"{endpoint.rstrip('/')}/v1/traces"
+    data = json.dumps(body, separators=(",", ":")).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status < 300
+    except Exception:
+        return False
+
+
+def post_traces_batch(endpoint: str, bodies: list[dict]) -> bool:
+    """POST multiple OTLP bodies as one request by merging their ``resourceSpans``.
+
+    Combines the ``resourceSpans`` arrays of every body into a single OTLP envelope
+    and posts it once, drastically reducing HTTP round-trips for large imports.
+    Returns True (a no-op success) when there are no spans to send.
+    """
+    merged: dict = {"resourceSpans": []}
+    for body in bodies:
+        # Guard against malformed bodies whose ``resourceSpans`` is missing or
+        # not a list (e.g. None or a dict); skip rather than raise on extend.
+        spans = body.get("resourceSpans")
+        if isinstance(spans, list):
+            merged["resourceSpans"].extend(spans)
+    if not merged["resourceSpans"]:
+        return True
+    return post_trace(endpoint, merged)
+
+
+def post_annotations(endpoint: str, annotations: list[dict]) -> int:
+    """POST annotations to the viewer endpoint. Returns count of successfully imported."""
+    url = f"{endpoint.rstrip('/')}/api/annotations"
+    imported = 0
+    for ann in annotations:
+        ann = {k: v for k, v in ann.items() if k != "id"}
+        data = json.dumps(ann, separators=(",", ":")).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                if resp.status < 300:
+                    imported += 1
+        except Exception:
+            pass
+    return imported
+
+
+def session_exists(endpoint: str, session_id: str) -> bool:
+    """Check whether a session already exists in the viewer."""
+    url = f"{endpoint.rstrip('/')}/api/trace-count?session_id={urllib.parse.quote(session_id)}"
+    req = urllib.request.Request(url, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            return resp.status == 200
+    except Exception:
+        return False
+
+
+def check_endpoint_reachable(endpoint: str) -> bool:
+    """Return True if the viewer API is reachable."""
+    try:
+        with urllib.request.urlopen(f"{endpoint.rstrip('/')}/api/version", timeout=5):
+            return True
+    except Exception:
+        return False

nooa_cli/commands/_template.py

@@ -0,0 +1,89 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""<One-line description of what this command does.>
+
+Copy this file as a starting point for a new nooa CLI command.
+
+    1. Copy this file:     cp _template.py mycommand.py
+    2. Rename `command` if needed (it stays as `command`)
+    3. Add your logic
+    4. Done — it's automatically discovered.
+
+The filename becomes the subcommand name:
+    mycommand.py  →  nooa mycommand ...
+
+To override the name, add at module level:
+    NAME = "custom-name"
+
+Usage:
+    nooa mycommand
+    nooa mycommand --verbose
+"""
+
+import click
+
+# Optional: override the subcommand name (default: filename without .py)
+# NAME = "custom-name"
+
+
+# ---------------------------------------------------------------------------
+# SIMPLE COMMAND — use this for leaf commands (no subcommands)
+# ---------------------------------------------------------------------------
+
+
+@click.command()
+@click.argument("target", default="world")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output.")
+def command(target: str, verbose: bool):
+    """Short description shown in `nooa --help`.
+
+    TARGET is the thing to operate on.
+
+    \b
+    Examples:
+        nooa mycommand
+        nooa mycommand foo --verbose
+    """
+    click.echo(f"Hello, {target}!")
+    if verbose:
+        click.echo("(verbose mode)")
+
+
+# ---------------------------------------------------------------------------
+# GROUP COMMAND — uncomment this instead if you need subcommands
+#                 (e.g. nooa things list / nooa things create)
+# ---------------------------------------------------------------------------
+
+# @click.group()
+# def command():
+#     """Manage things."""
+#
+#
+# @command.command()
+# def list():
+#     """List all things."""
+#     click.echo("thing-1")
+#     click.echo("thing-2")
+#
+#
+# @command.command()
+# @click.argument("name")
+# def create(name: str):
+#     """Create a new thing."""
+#     click.echo(f"Created: {name}")
+
+
+# ---------------------------------------------------------------------------
+# TIPS
+# ---------------------------------------------------------------------------
+#
+# Shared utilities:
+#     from nooa_cli._common import find_project_root, format_size
+#
+# Lazy imports (keep CLI startup fast — only import heavy deps inside handlers):
+#     def command(...):
+#         import pandas as pd    # ← lazy, not at module level
+#
+# Import the nooa framework (lazy — only when the command actually runs):
+#     def command(...):
+#         from nooa import Agent