mammoth-cli 1.0.0__py3-none-any.whl

mammoth_cli/commands/agent.py

@@ -0,0 +1,199 @@
+"""Handlers for the ``agent`` command family (workspace-scoped).
+
+The backing SDK methods never accept a ``project_id`` or ``workspace_id``
+keyword argument — a chat scope names its own target (project, dataset, and so
+on) and sessions are identified by an opaque ``session_id`` — so handlers here
+never forward either explicitly, even though the active project id is still
+reported in the envelope metadata. Handlers dispatch through the generic
+:meth:`~mammoth_cli.services.protocol.MammothService.call` seam to the public
+SDK method named by the command's reviewed manifest ``sdk_symbol``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mammoth_cli.errors.envelope import (
+    CODE_MISSING_ARGUMENT,
+    CODE_MISSING_FIELD,
+    CODE_SDK_SYMBOL_UNRESOLVED,
+    EXIT_USAGE,
+    CliError,
+)
+from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime.confirm import POLICY_PROMPT_OR_YES, enforce_confirmation
+from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.session import open_service, resolved_project
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+
+def _symbol(invocation: Invocation) -> str:
+    """Return the reviewed backing SDK symbol for this command.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The dotted SDK symbol recorded in the command's manifest entry.
+
+    Raises:
+        CliError: ``sdk_symbol_unresolved`` when no symbol is recorded.
+    """
+    record = command_by_id(invocation.command_id)
+    if record is None or not record.get("sdk_symbol"):
+        raise CliError(
+            code=CODE_SDK_SYMBOL_UNRESOLVED,
+            message=f"No SDK symbol is recorded for '{invocation.command_id}'.",
+            exit_status=EXIT_USAGE,
+        )
+    return str(record["sdk_symbol"])
+
+
+def _string_positional(invocation: Invocation) -> str | None:
+    """Return the first positional argument, or None if absent.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The first extra argument, or None when none was given.
+    """
+    return invocation.extra_args[0] if invocation.extra_args else None
+
+
+def _require_string_positional(invocation: Invocation, name: str) -> str:
+    """Return the first positional argument, raising when absent.
+
+    Args:
+        invocation: The current command's resolved global options.
+        name: A human-readable name for the argument, used in error messages.
+
+    Returns:
+        The first extra argument.
+
+    Raises:
+        CliError: ``missing_argument`` when no positional was given.
+    """
+    value = _string_positional(invocation)
+    if value is None:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message=f"This command requires a {name} argument.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass the {name} as a positional argument.",
+        )
+    return value
+
+
+def _require_field(document: dict[str, Any] | None, field: str) -> Any:
+    """Return a required field from the ``--input`` document, or raise usage.
+
+    Args:
+        document: The parsed ``--input`` document, or None when absent.
+        field: The required field name.
+
+    Returns:
+        The field's value.
+
+    Raises:
+        CliError: ``missing_field`` when the document is absent or lacks
+            ``field``.
+    """
+    if document is None or field not in document:
+        raise CliError(
+            code=CODE_MISSING_FIELD,
+            message=f"This command requires the '{field}' input field.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass it via --input, for example: --input '{{\"{field}\": ...}}'.",
+        )
+    return document[field]
+
+
+def _forward_optional(
+    document: dict[str, Any], kwargs: dict[str, Any], fields: tuple[str, ...]
+) -> None:
+    """Copy each present field from ``document`` into ``kwargs``, unchanged.
+
+    Args:
+        document: The parsed ``--input`` document.
+        kwargs: The keyword-argument mapping being built for the SDK call.
+        fields: The optional field names to forward when present.
+    """
+    for field in fields:
+        if field in document:
+            kwargs[field] = document[field]
+
+
+def _meta(invocation: Invocation, workspace_id: int, project_id: int | None) -> dict[str, Any]:
+    """Build the common envelope metadata for an agent command.
+
+    Args:
+        invocation: The current command's resolved global options.
+        workspace_id: The authenticated workspace id.
+        project_id: The active project id, or None when not resolved.
+
+    Returns:
+        The envelope metadata mapping.
+    """
+    return {
+        "profile": invocation.profile,
+        "workspace_id": workspace_id,
+        "project_id": project_id,
+    }
+
+
+def agent_chat(invocation: Invocation) -> HandlerResult:
+    """Send a chat message to an agent. ``message``/``scope`` are required."""
+    document = invocation.load_input()
+    message = _require_field(document, "message")
+    scope = _require_field(document, "scope")
+    assert document is not None
+    kwargs: dict[str, Any] = {"message": message, "scope": scope}
+    _forward_optional(document, kwargs, ("agent_key", "session_id", "client_context", "selection"))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def agent_session_delete(invocation: Invocation) -> HandlerResult:
+    """Delete one agent session by id. Prompt or ``--yes`` required."""
+    session_id = _require_string_positional(invocation, "session id")
+    enforce_confirmation(
+        invocation, policy=POLICY_PROMPT_OR_YES, action=f"delete agent session {session_id}"
+    )
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), session_id=session_id)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def agent_session_list(invocation: Invocation) -> HandlerResult:
+    """List agent sessions. All fields are optional and come from ``--input``.
+
+    ``workspace_id`` is never forwarded even if present in the input document:
+    the authenticated client already scopes every call to its own workspace.
+    """
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, ("agent_key", "limit", "offset", "include_shared"))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def agent_session_messages(invocation: Invocation) -> HandlerResult:
+    """Get the messages of one agent session by id."""
+    session_id = _require_string_positional(invocation, "session id")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), session_id=session_id)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def agent_session_set_visibility(invocation: Invocation) -> HandlerResult:
+    """Set an agent session's visibility. ``visibility`` comes from ``--input``."""
+    session_id = _require_string_positional(invocation, "session id")
+    document = invocation.load_input()
+    visibility = _require_field(document, "visibility")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), session_id=session_id, visibility=visibility)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))

mammoth_cli/commands/ai.py

@@ -0,0 +1,274 @@
+"""Handlers for the ``ai`` command family (AI-assisted generation, project-scoped).
+
+Every command in this family operates against the active project. For
+``ai.condition.generate`` and ``ai.expression.generate`` the dataset id comes
+from a positional argument, the natural-language ``intent`` (and, for
+expressions, ``mode``) come from the strict ``--input`` document, and the
+project id is forwarded explicitly because the backing SDK method accepts it.
+``ai.sql.generate`` and ``ai.suggestion.list`` call SDK methods with no
+``project_id`` parameter at all: the project is instead bound on the SDK
+client when the service is opened, so these handlers still call
+:func:`~mammoth_cli.runtime.session.require_project` to raise a friendly error
+when no project is active, but do not forward ``project_id`` as a keyword
+argument. Handlers dispatch through the generic
+:meth:`~mammoth_cli.services.protocol.MammothService.call` seam to the public
+SDK method named by the command's reviewed manifest ``sdk_symbol``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mammoth_cli.errors.envelope import (
+    CODE_INVALID_ARGUMENT,
+    CODE_MISSING_ARGUMENT,
+    CODE_MISSING_FIELD,
+    CODE_SDK_SYMBOL_UNRESOLVED,
+    EXIT_USAGE,
+    CliError,
+)
+from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.session import open_service, require_project
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+
+def _symbol(invocation: Invocation) -> str:
+    """Return the reviewed backing SDK symbol for this command.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The dotted SDK symbol recorded in the manifest for this command.
+
+    Raises:
+        CliError: ``sdk_symbol_unresolved`` when the manifest has no symbol.
+    """
+    record = command_by_id(invocation.command_id)
+    if record is None or not record.get("sdk_symbol"):
+        raise CliError(
+            code=CODE_SDK_SYMBOL_UNRESOLVED,
+            message=f"No SDK symbol is recorded for '{invocation.command_id}'.",
+            exit_status=EXIT_USAGE,
+        )
+    return str(record["sdk_symbol"])
+
+
+def _int_positional(invocation: Invocation, name: str) -> int | None:
+    """Parse the first positional argument as an int, or return None if absent.
+
+    Args:
+        invocation: The current command's resolved global options.
+        name: A human-readable name for the argument, used in error messages.
+
+    Returns:
+        The parsed integer, or None when no positional argument was given.
+
+    Raises:
+        CliError: ``invalid_argument`` when the positional is not an integer.
+    """
+    if not invocation.extra_args:
+        return None
+    raw = invocation.extra_args[0]
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message=f"The {name} argument '{raw}' is not an integer.",
+            exit_status=EXIT_USAGE,
+        ) from exc
+
+
+def _require_int_positional(invocation: Invocation, name: str) -> int:
+    """Parse the first positional argument as an int, or raise usage.
+
+    Args:
+        invocation: The current command's resolved global options.
+        name: A human-readable name for the argument, used in error messages.
+
+    Returns:
+        The parsed positive integer.
+
+    Raises:
+        CliError: ``missing_argument`` when no positional was given;
+            ``invalid_argument`` when it is not an integer.
+    """
+    value = _int_positional(invocation, name)
+    if value is None:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message=f"This command requires a {name} argument.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass the {name} as a positional argument.",
+        )
+    return value
+
+
+def _require_field(document: dict[str, Any] | None, field: str) -> Any:
+    """Return a required field from the ``--input`` document, or raise usage.
+
+    Args:
+        document: The parsed ``--input`` request document, or None.
+        field: The required field name.
+
+    Returns:
+        The field's value.
+
+    Raises:
+        CliError: ``missing_field`` when ``document`` is None or lacks ``field``.
+    """
+    if document is None or field not in document:
+        raise CliError(
+            code=CODE_MISSING_FIELD,
+            message=f"This command requires the '{field}' input field.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass it via --input, for example: --input '{{\"{field}\": ...}}'.",
+        )
+    return document[field]
+
+
+def _forward_optional(
+    document: dict[str, Any], kwargs: dict[str, Any], fields: tuple[str, ...]
+) -> None:
+    """Copy any present ``fields`` from ``document`` into ``kwargs``.
+
+    Args:
+        document: The parsed ``--input`` request document.
+        kwargs: The keyword argument mapping being built for ``service.call``.
+        fields: The optional field names to forward when present.
+    """
+    for field in fields:
+        if field in document:
+            kwargs[field] = document[field]
+
+
+def _meta(invocation: Invocation, workspace_id: int, project_id: int) -> dict[str, Any]:
+    """Build the common envelope metadata for an ``ai`` command.
+
+    Args:
+        invocation: The current command's resolved global options.
+        workspace_id: The resolved auth's workspace id.
+        project_id: The resolved active project id.
+
+    Returns:
+        The envelope metadata mapping.
+    """
+    return {
+        "profile": invocation.profile,
+        "workspace_id": workspace_id,
+        "project_id": project_id,
+    }
+
+
+def ai_condition_generate(invocation: Invocation) -> HandlerResult:
+    """Generate a filter condition from a natural language intent.
+
+    The dataset id is a positional argument; ``intent`` is a required
+    ``--input`` field; ``dataview_id`` and ``sequence_number`` are forwarded
+    when present.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The raw generated-condition response and envelope metadata.
+    """
+    project_id = require_project(invocation)
+    dataset_id = _require_int_positional(invocation, "dataset id")
+    document = invocation.load_input()
+    intent = _require_field(document, "intent")
+    kwargs: dict[str, Any] = {
+        "intent": intent,
+        "dataset_id": dataset_id,
+        "project_id": project_id,
+    }
+    assert document is not None
+    _forward_optional(document, kwargs, ("dataview_id", "sequence_number"))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def ai_expression_generate(invocation: Invocation) -> HandlerResult:
+    """Generate a math/metric expression from a natural language intent.
+
+    The dataset id is a positional argument; ``intent`` and ``mode`` are
+    required ``--input`` fields; ``dataview_id`` and ``sequence_number`` are
+    forwarded when present.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The raw generated-expression response and envelope metadata.
+    """
+    project_id = require_project(invocation)
+    dataset_id = _require_int_positional(invocation, "dataset id")
+    document = invocation.load_input()
+    intent = _require_field(document, "intent")
+    mode = _require_field(document, "mode")
+    kwargs: dict[str, Any] = {
+        "intent": intent,
+        "mode": mode,
+        "dataset_id": dataset_id,
+        "project_id": project_id,
+    }
+    assert document is not None
+    _forward_optional(document, kwargs, ("dataview_id", "sequence_number"))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def ai_sql_generate(invocation: Invocation) -> HandlerResult:
+    """Generate SQL from a natural language intent.
+
+    ``intent`` comes from the first positional argument or an ``intent``
+    ``--input`` field; ``sequence_number`` is forwarded when present. The
+    backing SDK method has no ``project_id`` parameter — it resolves the
+    project bound on the client — so an active project is required but not
+    forwarded as a keyword argument.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The raw generated-SQL response and envelope metadata.
+    """
+    project_id = require_project(invocation)
+    document = invocation.load_input() or {}
+    intent = (invocation.extra_args[0] if invocation.extra_args else None) or document.get("intent")
+    if not intent:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message="An intent is required.",
+            exit_status=EXIT_USAGE,
+            hint="Pass the intent as a positional argument or an 'intent' input field.",
+        )
+    kwargs: dict[str, Any] = {"intent": intent}
+    _forward_optional(document, kwargs, ("sequence_number",))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def ai_suggestion_list(invocation: Invocation) -> HandlerResult:
+    """List AI-powered transformation suggestions for the active project.
+
+    The backing SDK method takes no arguments — it resolves the project bound
+    on the client — so an active project is required but not forwarded as a
+    keyword argument.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The raw suggestions response and envelope metadata.
+    """
+    project_id = require_project(invocation)
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation))
+    return data, _meta(invocation, auth.workspace_id, project_id)

mammoth_cli/commands/annotation.py

@@ -0,0 +1,166 @@
+"""Handlers for the ``annotation`` command family (project-scoped).
+
+Every annotation operation runs inside a resolved project: the project id
+comes from ``--project`` or the active project. An existing annotation is
+addressed by a positional ``annotation_id``; creating one addresses its
+target via the strict ``--input`` document (``target_type``/``target_id``).
+Handlers dispatch through the generic
+:meth:`~mammoth_cli.services.protocol.MammothService.call` seam to the public
+SDK method named by the command's reviewed manifest ``sdk_symbol``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mammoth_cli.errors.envelope import (
+    CODE_INVALID_ARGUMENT,
+    CODE_MISSING_ARGUMENT,
+    CODE_MISSING_FIELD,
+    CODE_SDK_SYMBOL_UNRESOLVED,
+    EXIT_USAGE,
+    CliError,
+)
+from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime.confirm import POLICY_PROMPT_OR_YES, enforce_confirmation
+from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.session import open_service, require_project
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+
+def _symbol(invocation: Invocation) -> str:
+    """Return the reviewed backing SDK symbol for this command."""
+    record = command_by_id(invocation.command_id)
+    if record is None or not record.get("sdk_symbol"):
+        raise CliError(
+            code=CODE_SDK_SYMBOL_UNRESOLVED,
+            message=f"No SDK symbol is recorded for '{invocation.command_id}'.",
+            exit_status=EXIT_USAGE,
+        )
+    return str(record["sdk_symbol"])
+
+
+def _int_positional(invocation: Invocation, name: str) -> int | None:
+    """Parse the first positional argument as an int, or return None if absent."""
+    if not invocation.extra_args:
+        return None
+    raw = invocation.extra_args[0]
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message=f"The {name} argument '{raw}' is not an integer.",
+            exit_status=EXIT_USAGE,
+        ) from exc
+
+
+def _require_int_positional(invocation: Invocation, name: str) -> int:
+    """Parse the first positional argument as an int, or raise usage."""
+    value = _int_positional(invocation, name)
+    if value is None:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message=f"This command requires a {name} argument.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass the {name} as a positional argument.",
+        )
+    return value
+
+
+def _require_field(document: dict[str, Any] | None, field: str) -> Any:
+    """Return a required field from the ``--input`` document, or raise usage."""
+    if document is None or field not in document:
+        raise CliError(
+            code=CODE_MISSING_FIELD,
+            message=f"This command requires the '{field}' input field.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass it via --input, for example: --input '{{\"{field}\": ...}}'.",
+        )
+    return document[field]
+
+
+def _meta(invocation: Invocation, workspace_id: int, project_id: int) -> dict[str, Any]:
+    """Build the common envelope metadata for an annotation command."""
+    return {
+        "profile": invocation.profile,
+        "workspace_id": workspace_id,
+        "project_id": project_id,
+    }
+
+
+def _forward_optional(
+    document: dict[str, Any], kwargs: dict[str, Any], fields: tuple[str, ...]
+) -> None:
+    """Copy each present field from ``document`` into ``kwargs`` unchanged."""
+    for field in fields:
+        if field in document:
+            kwargs[field] = document[field]
+
+
+def annotation_comment_add(invocation: Invocation) -> HandlerResult:
+    """Add a comment to an annotation. Annotation id is positional; body is required input."""
+    project_id = require_project(invocation)
+    annotation_id = _require_int_positional(invocation, "annotation id")
+    document = invocation.load_input()
+    body = _require_field(document, "body")
+    with open_service(invocation) as (service, auth):
+        data = service.call(
+            _symbol(invocation), annotation_id=annotation_id, body=body, project_id=project_id
+        )
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def annotation_create(invocation: Invocation) -> HandlerResult:
+    """Create an annotation on a target. Target and body come from ``--input``."""
+    project_id = require_project(invocation)
+    document = invocation.load_input()
+    target_type = _require_field(document, "target_type")
+    target_id = _require_field(document, "target_id")
+    body = _require_field(document, "body")
+    with open_service(invocation) as (service, auth):
+        data = service.call(
+            _symbol(invocation),
+            target_type=target_type,
+            target_id=target_id,
+            body=body,
+            project_id=project_id,
+        )
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def annotation_delete(invocation: Invocation) -> HandlerResult:
+    """Delete one annotation by id. Prompt or ``--yes`` required."""
+    project_id = require_project(invocation)
+    annotation_id = _require_int_positional(invocation, "annotation id")
+    enforce_confirmation(
+        invocation, policy=POLICY_PROMPT_OR_YES, action=f"delete annotation {annotation_id}"
+    )
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), annotation_id=annotation_id, project_id=project_id)
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def annotation_list(invocation: Invocation) -> HandlerResult:
+    """List annotations in the active project, optionally filtered by target."""
+    project_id = require_project(invocation)
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {"project_id": project_id}
+    _forward_optional(document, kwargs, ("target_type", "target_id"))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+def annotation_update(invocation: Invocation) -> HandlerResult:
+    """Update an annotation's status. Annotation id is positional; status is required input."""
+    project_id = require_project(invocation)
+    annotation_id = _require_int_positional(invocation, "annotation id")
+    document = invocation.load_input()
+    status = _require_field(document, "status")
+    with open_service(invocation) as (service, auth):
+        data = service.call(
+            _symbol(invocation), annotation_id=annotation_id, status=status, project_id=project_id
+        )
+    return data, _meta(invocation, auth.workspace_id, project_id)