tangle-cli 0.0.1a1__py3-none-any.whl

tangle_cli/artifacts.py

@@ -0,0 +1,293 @@
+"""Read-only artifact lookup helpers for Tangle pipeline runs.
+
+This module intentionally resolves artifact metadata only. It does not fetch
+signed URLs, download remote objects, write local files, or mutate artifacts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field, is_dataclass
+from typing import Any, Protocol
+
+from .handler import TangleCliHandler
+
+
+class ArtifactClient(Protocol):
+    """Subset of the static API client used for read-only artifact lookup."""
+
+    def get_run_details(self, run_id: str) -> Any: ...
+
+    def get_execution_details(self, execution_id: str) -> Any: ...
+
+    def artifacts_get(self, artifact_id: str) -> Any: ...
+
+
+@dataclass
+class ArtifactComponentQuery:
+    """Filter for selecting artifacts by component name or digest."""
+
+    name: str | None = None
+    digest: str | None = None
+    outputs: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ArtifactInfo:
+    """Resolved artifact metadata from GET /api/artifacts/{id}.
+
+    This dataclass intentionally lives in this native-free module. Generated
+    response objects are accepted structurally via ``from_response`` so no
+    ``tangle_api`` import is required.
+    """
+
+    id: str
+    uri: str
+    key: str = ""
+    total_size: int = 0
+    is_dir: bool = False
+    hash: str | None = None
+    created_at: str | None = None
+    error: str | None = None
+    local_path: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], key: str = "") -> ArtifactInfo:
+        ad = data.get("artifact_data", {})
+        return cls(
+            id=data.get("id", ""),
+            uri=_mapping_or_attr(ad, "uri", ""),
+            key=key,
+            total_size=_mapping_or_attr(ad, "total_size", 0),
+            is_dir=_mapping_or_attr(ad, "is_dir", False),
+            hash=_optional_str(_mapping_or_attr(ad, "hash")),
+            created_at=_optional_str(_mapping_or_attr(ad, "created_at")),
+        )
+
+    @classmethod
+    def from_response(cls, response: Any, *, key: str = "") -> ArtifactInfo:
+        """Create a flattened artifact DTO from a generated or duck-typed response."""
+
+        artifact_data = getattr(response, "artifact_data", None)
+        total_size = _mapping_or_attr(artifact_data, "total_size", 0)
+        is_dir = _mapping_or_attr(artifact_data, "is_dir", False)
+        return cls(
+            id=str(getattr(response, "id", "") or ""),
+            uri=str(_mapping_or_attr(artifact_data, "uri", "") or ""),
+            key=key,
+            total_size=total_size if isinstance(total_size, int) else 0,
+            is_dir=is_dir if isinstance(is_dir, bool) else False,
+            hash=_optional_str(_mapping_or_attr(artifact_data, "hash")),
+            created_at=_optional_str(_mapping_or_attr(artifact_data, "created_at")),
+        )
+
+
+class ArtifactManager(TangleCliHandler):
+    """Read-only artifact metadata manager.
+
+    Downstream packages can inject an already-authenticated client or a lazy
+    ``client_factory`` (for example, one that applies provider auth). The manager
+    keeps the same read-only constraints as the module-level helpers: it never
+    downloads artifact contents, signs URLs, writes files, or mutates artifacts.
+    """
+
+    def __init__(
+        self,
+        client: ArtifactClient | None = None,
+        *,
+        client_factory: Any | None = None,
+        logger: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(client=client, client_factory=client_factory, logger=logger, **kwargs)
+
+    def collect_artifacts(
+        self,
+        execution: Any,
+        tasks_query: dict[str, list[str]],
+        components_query: list[ArtifactComponentQuery],
+        prefix: str = "",
+    ) -> dict[str, str]:
+        """Collect artifact IDs by walking an enriched execution tree."""
+
+        artifact_ids: dict[str, str] = {}
+        task_spec = _mapping_or_attr(execution, "task_spec")
+        graph_tasks = _mapping_or_attr(task_spec, "graph_tasks", {})
+        if not isinstance(graph_tasks, dict):
+            return artifact_ids
+
+        for task_name, child_task in graph_tasks.items():
+            task_name = str(task_name)
+            key_prefix = f"{prefix}{task_name}" if prefix else task_name
+            output_filters: list[list[str]] = []
+
+            for query_name in (task_name, key_prefix):
+                if query_name in tasks_query:
+                    output_filters.append(tasks_query[query_name])
+                    break
+
+            child_digest = _mapping_or_attr(child_task, "digest")
+            child_name = _mapping_or_attr(child_task, "name")
+            for component in components_query:
+                if (component.digest and child_digest == component.digest) or (
+                    component.name and child_name == component.name
+                ):
+                    output_filters.append(component.outputs)
+
+            out_artifacts = _artifact_id_map(_mapping_or_attr(child_task, "execution_output_artifacts", {}))
+            if output_filters and out_artifacts:
+                include_all = any(not output_filter for output_filter in output_filters)
+                requested_outputs = {
+                    output_name
+                    for output_filter in output_filters
+                    for output_name in output_filter
+                }
+                for output_name, artifact_id in out_artifacts.items():
+                    if include_all or output_name in requested_outputs:
+                        artifact_ids[f"{key_prefix}/{output_name}"] = artifact_id
+
+            if _mapping_or_attr(child_task, "is_graph", False):
+                child_executions = _mapping_or_attr(execution, "child_executions", {})
+                child_execution = child_executions.get(task_name) if isinstance(child_executions, dict) else None
+                if child_execution:
+                    artifact_ids.update(
+                        self.collect_artifacts(
+                            child_execution,
+                            tasks_query,
+                            components_query,
+                            prefix=f"{key_prefix}/",
+                        )
+                    )
+
+        return artifact_ids
+
+    def collect_execution_artifacts(
+        self,
+        execution_ids: dict[str, list[str]],
+    ) -> dict[str, str]:
+        """Collect artifact IDs directly from execution IDs."""
+
+        artifact_ids: dict[str, str] = {}
+        client = self._require_client()
+        for execution_id, output_filter in execution_ids.items():
+            execution = client.get_execution_details(execution_id)
+            output_artifacts = _artifact_id_map(_mapping_or_attr(execution, "output_artifacts", {}))
+            for output_name, artifact_id in output_artifacts.items():
+                if not output_filter or output_name in output_filter:
+                    artifact_ids[f"{execution_id}/{output_name}"] = artifact_id
+        return artifact_ids
+
+    def get_artifacts(
+        self,
+        run_id: str,
+        query: dict[str, Any],
+    ) -> dict[str, ArtifactInfo]:
+        """Get artifact metadata for tasks/components in a pipeline run.
+
+        Query keys:
+          - ``tasks``: ``{<task_name>: [<output_names>]}``
+          - ``components``: ``[{"name"|"digest": ..., "outputs": [...]}]``
+          - ``executions``: ``{<execution_id>: [<output_names>]}``
+          - ``artifact_ids``: ``[<artifact_id>, ...]``
+
+        Empty output lists mean all outputs. Per-artifact lookup failures are
+        returned as ``ArtifactInfo(error=...)`` entries instead of failing the
+        whole command.
+        """
+
+        artifact_ids: dict[str, str] = {}
+
+        for artifact_id in query.get("artifact_ids", []) or []:
+            artifact_ids[str(artifact_id)] = str(artifact_id)
+
+        executions_query = query.get("executions", {}) or {}
+        if executions_query:
+            artifact_ids.update(self.collect_execution_artifacts(executions_query))
+
+        tasks_query = query.get("tasks", {}) or {}
+        components_query_raw = query.get("components", []) or []
+        if tasks_query or components_query_raw:
+            details = self._require_client().get_run_details(run_id)
+            execution = _mapping_or_attr(details, "execution")
+            if not execution:
+                raise RuntimeError("No execution details found for run")
+            artifact_ids.update(
+                self.collect_artifacts(
+                    execution,
+                    tasks_query,
+                    _component_queries(components_query_raw),
+                )
+            )
+
+        artifacts: dict[str, ArtifactInfo] = {}
+        for key, artifact_id in artifact_ids.items():
+            try:
+                response = self._require_client().artifacts_get(artifact_id)
+                artifacts[key] = _artifact_info_from_response(response, artifact_id=artifact_id, key=key)
+            except Exception as exc:
+                artifacts[key] = ArtifactInfo(id=artifact_id, uri="", key=key, error=str(exc))
+
+        return artifacts
+
+    @staticmethod
+    def serialize_artifacts(artifacts: dict[str, ArtifactInfo]) -> list[dict[str, Any]]:
+        """Serialize artifact dict to a JSON-friendly list, dropping ``None`` fields."""
+
+        result: list[dict[str, Any]] = []
+        for artifact in artifacts.values():
+            data = asdict(artifact) if is_dataclass(artifact) else dict(artifact)
+            result.append({key: value for key, value in data.items() if value is not None})
+        return result
+
+
+def _mapping_or_attr(value: Any, key: str, default: Any = None) -> Any:
+    if isinstance(value, dict):
+        return value.get(key, default)
+    return getattr(value, key, default)
+
+
+def _optional_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def _artifact_id_map(raw_artifacts: Any) -> dict[str, str]:
+    """Normalize API artifact maps to ``{output_name: artifact_id}``."""
+
+    if not isinstance(raw_artifacts, dict):
+        return {}
+
+    artifact_ids: dict[str, str] = {}
+    for output_name, value in raw_artifacts.items():
+        if isinstance(value, str):
+            artifact_ids[str(output_name)] = value
+        elif isinstance(value, dict) and value.get("id"):
+            artifact_ids[str(output_name)] = str(value["id"])
+        elif getattr(value, "id", None):
+            artifact_ids[str(output_name)] = str(value.id)
+    return artifact_ids
+
+
+def _component_queries(raw_components: list[dict[str, Any]]) -> list[ArtifactComponentQuery]:
+    return [
+        ArtifactComponentQuery(
+            name=component.get("name"),
+            digest=component.get("digest"),
+            outputs=component.get("outputs") or [],
+        )
+        for component in raw_components
+    ]
+
+
+def _artifact_info_from_response(response: Any, *, artifact_id: str, key: str) -> ArtifactInfo:
+    if isinstance(response, dict):
+        return ArtifactInfo.from_dict(response, key=key)
+    return ArtifactInfo.from_response(response, key=key)
+
+
+__all__ = [
+    "ArtifactClient",
+    "ArtifactComponentQuery",
+    "ArtifactInfo",
+    "ArtifactManager",
+]

tangle_cli/artifacts_cli.py

@@ -0,0 +1,108 @@
+"""`tangle sdk artifacts` read-only artifact commands."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from cyclopts import App, Parameter
+
+from .cli_helpers import (
+    LazyTangleApiClient,
+    api_arg_specs,
+    include_env_credentials_for_args,
+    load_args_or_exit,
+    print_json,
+)
+from .cli_options import (
+    AuthHeaderOption,
+    BaseUrlOption,
+    ConfigOption,
+    HeaderOption,
+    LogTypeOption,
+    TokenOption,
+)
+from .logger import logger_for_log_type
+
+QueryOption = Annotated[
+    str | None,
+    Parameter(
+        name="--query",
+        alias="-q",
+        help=(
+            "JSON query with optional keys: "
+            "'tasks', 'components', 'executions', and 'artifact_ids'. "
+            "Empty output lists mean all outputs."
+        ),
+    ),
+]
+
+app = App(
+    name="artifacts",
+    help="Read artifact metadata for Tangle pipeline runs.",
+)
+
+
+@app.command(name="get")
+def artifacts_get(
+    run_id: str | None = None,
+    *,
+    query: QueryOption = None,
+    base_url: BaseUrlOption = None,
+    token: TokenOption = None,
+    auth_header: AuthHeaderOption = None,
+    header: HeaderOption = None,
+    config: ConfigOption = None,
+    log_type: LogTypeOption = "console",
+) -> None:
+    """Get artifact metadata for tasks/components in a pipeline run."""
+
+    all_args = load_args_or_exit(
+        config,
+        run_id=("run_id", run_id, None, False, True),
+        query=("query", query, None, True, True),
+        log_type=(log_type, "console"),
+        **api_arg_specs(
+            base_url=base_url,
+            token=token,
+            auth_header=auth_header,
+            header=header,
+        ),
+    )
+
+    results: list[dict[str, Any]] = []
+    for args in all_args:
+        logger, finalize_logs = logger_for_log_type(args.log_type)
+        try:
+            client = LazyTangleApiClient(
+                base_url=args.base_url,
+                token=args.token,
+                auth_header=args.auth_header,
+                header=args.header,
+                include_env_credentials=include_env_credentials_for_args(args, base_url),
+                command_name="artifact commands",
+            )
+            if require_available := getattr(client, "require_available", None):
+                require_available()
+            from .artifacts import ArtifactManager
+
+            manager = ArtifactManager(client=client)
+            try:
+                artifacts = manager.get_artifacts(args.run_id, args.query)
+            except RuntimeError as exc:
+                print_json({"status": "error", "error": str(exc)})
+                raise SystemExit(1) from exc
+
+            results.append(
+                {
+                    "status": "success",
+                    "run_id": args.run_id,
+                    "count": len(artifacts),
+                    "artifacts": ArtifactManager.serialize_artifacts(artifacts),
+                }
+            )
+        finally:
+            finalize_logs()
+
+    print_json(
+        results[0] if len(results) == 1 else {"status": "success", "results": results}
+    )

tangle_cli/cli.py

@@ -0,0 +1,57 @@
+from cyclopts import App
+
+from . import (
+    __version__,
+    api_cli,
+    artifacts_cli,
+    components_cli,
+    pipeline_runs_cli,
+    pipelines_cli,
+    published_components_cli,
+    quickstart,
+    secrets_cli,
+)
+
+
+def version() -> None:
+    """Print the installed tangle-cli package version."""
+
+    print(__version__)
+
+
+def build_sdk_app() -> App:
+    """Build the SDK command group."""
+
+    sdk_app = App(
+        name="sdk",
+        help="Work with local Tangle SDK resources and scaffolding.",
+    )
+    sdk_app.command(artifacts_cli.app)
+    sdk_app.command(components_cli.app)
+    sdk_app.command(pipelines_cli.app)
+    sdk_app.command(pipeline_runs_cli.app)
+    sdk_app.command(published_components_cli.app)
+    sdk_app.command(secrets_cli.app)
+    return sdk_app
+
+
+def build_app() -> App:
+    """Build the root CLI app lazily for the current invocation."""
+
+    app = App(
+        help="CLI for Tangle, the open-source ML pipeline orchestration platform.",
+        version=__version__,
+    )
+    app.command(name="version")(version)
+    app.command(quickstart.app)
+    app.command(api_cli.build_app())
+    app.command(build_sdk_app())
+    return app
+
+
+def main() -> None:
+    build_app()()
+
+
+if __name__ == "__main__":
+    main()

tangle_cli/cli_helpers.py

@@ -0,0 +1,116 @@
+"""Shared helpers for Tangle CLI command modules."""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any
+
+from .args_container import ArgsContainer, ConfigFileError
+
+
+def load_args_or_exit(config: str | None, **kwargs: Any) -> list[ArgsContainer]:
+    """Load ArgsContainer values from CLI/config specs, exiting with CLI errors."""
+
+    try:
+        return ArgsContainer.load(config, **kwargs)
+    except ConfigFileError as exc:
+        raise SystemExit(f"Config error: {exc}") from exc
+
+
+def print_json(payload: object) -> None:
+    """Print a stable pretty JSON payload for CLI output."""
+
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+def load_config_or_exit(config: str | None) -> dict[str, object]:
+    """Load the first YAML/JSON config mapping for commands with custom merging."""
+
+    if config is None:
+        return {}
+    try:
+        configs = ArgsContainer._load_config_file(config)
+    except ConfigFileError as exc:
+        raise SystemExit(f"Config error: {exc}") from exc
+    return configs[0] if configs else {}
+
+
+def optional_path(value: str | pathlib.Path | object | None) -> pathlib.Path | None:
+    """Convert a CLI/config path value to Path when present."""
+
+    if isinstance(value, pathlib.Path):
+        return value
+    if isinstance(value, str):
+        return pathlib.Path(value)
+    return None
+
+
+def api_arg_specs(
+    *,
+    base_url: str | None = None,
+    token: str | None = None,
+    auth_header: str | None = None,
+    header: list[str] | None = None,
+) -> dict[str, tuple[Any, ...]]:
+    """Build ArgsContainer specs for common API connection options."""
+
+    return {
+        "base_url": (base_url, None),
+        "token": (token, None),
+        "auth_header": (auth_header, None),
+        "header": (header, None),
+    }
+
+
+class LazyTangleApiClient:
+    """Instantiate the generated API client only when a command uses it.
+
+    Importing CLI modules must stay native-free so local-only commands can run
+    without the generated ``tangle_api`` package. This proxy delays importing and
+    constructing ``TangleApiClient`` until an API method is actually accessed,
+    while keeping CLI-friendly error wording in the CLI helper layer.
+    """
+
+    def __init__(self, *, command_name: str, **client_kwargs: Any) -> None:
+        self.command_name = command_name
+        self.client_kwargs = client_kwargs
+        self._client: Any | None = None
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            try:
+                from .api_transport import DEFAULT_TIMEOUT_SECONDS
+                from .client import TangleApiClient
+            except ModuleNotFoundError as exc:
+                if exc.name == "tangle_api":
+                    raise SystemExit(
+                        "Native generated Tangle API bindings are required for "
+                        f"{self.command_name}. Install tangle-cli[native] or provide "
+                        "a local tangle_api.generated package."
+                    ) from exc
+                raise
+
+            kwargs = dict(self.client_kwargs)
+            kwargs.setdefault("timeout", DEFAULT_TIMEOUT_SECONDS)
+            self._client = TangleApiClient(**kwargs)
+        return self._client
+
+    def require_available(self) -> None:
+        """Materialize the client so CLI commands fail before native helper imports."""
+
+        self._get_client()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._get_client(), name)
+
+
+def include_env_credentials_for_args(args: ArgsContainer, cli_base_url: str | None) -> bool:
+    """Suppress ambient credentials when base_url came from config, not CLI.
+
+    Explicit config/CLI token/auth/header values remain present on *args* and are
+    passed through by callers. This helper only controls environment fallback.
+    """
+
+    config_base_url = getattr(args, "_config", {}).get("base_url")
+    return not (cli_base_url is None and config_base_url is not None)

tangle_cli/cli_options.py

@@ -0,0 +1,52 @@
+"""Shared Cyclopts option annotations for Tangle CLI commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import Parameter
+
+from .api_transport import DEFAULT_API_URL
+
+BaseUrlOption = Annotated[
+    str | None,
+    Parameter(
+        help=(
+            "Tangle API base URL. Defaults to TANGLE_API_URL, then "
+            f"{DEFAULT_API_URL}."
+        )
+    ),
+]
+TokenOption = Annotated[
+    str | None,
+    Parameter(help="Bearer token. Defaults to TANGLE_API_TOKEN."),
+]
+AuthHeaderOption = Annotated[
+    str | None,
+    Parameter(
+        help=(
+            "Authorization header value, e.g. 'Bearer TOKEN' or 'Basic BASE64'. "
+            "Defaults to TANGLE_API_AUTH_HEADER or TANGLE_AUTH_HEADER."
+        )
+    ),
+]
+HeaderOption = Annotated[
+    list[str] | None,
+    Parameter(
+        name="--header",
+        alias="-H",
+        help=(
+            "Custom request header as 'Name: value'. Repeat for multiple. "
+            "Applied after TANGLE_API_HEADERS."
+        ),
+        negative_iterable=(),
+    ),
+]
+ConfigOption = Annotated[
+    str | None,
+    Parameter(help="YAML/JSON config file providing command defaults."),
+]
+LogTypeOption = Annotated[
+    str,
+    Parameter(help="Log output: console, none, file."),
+]