maxc-cli 0.6.1__tar.gz → 0.8.0__tar.gz

{maxc_cli-0.6.1 → maxc_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.6.1
+Version: 0.8.0
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -311,3 +311,18 @@ Metadata edits lack server CAS; publication lacks idempotency keys. An uncertain
 write must be reconciled before retrying. Publication checks are not SQL or
 business validation. History lists the latest 20 summaries, and an immutable
 revision read does not guarantee historical DataBridge analysis.
+
+### Task metrics and worker logs
+
+```bash
+aliyun maxc job task-detail <instance_id> --task-name AnonymousSQLTask --json
+aliyun maxc job task-summary <instance_id> --task-name AnonymousSQLTask --json
+aliyun maxc job workers <instance_id> --task-name AnonymousSQLTask --json
+aliyun maxc job worker-log <instance_id> <log_id> --log-type stdout --size 1048576 --json
+```
+
+These read-only commands use the same project and saved job context as `job status`.
+Task detail preserves the service payload (including `mapReduce.jsonSummary`).
+Select `log_id` from `data.workers`; logs are returned as `data.content` in the JSON
+envelope. The requested size defaults to 1 MiB and must be positive; returned logs
+may be partial. Use `--project` to select the owning project explicitly.

{maxc_cli-0.6.1 → maxc_cli-0.8.0}/README.md

@@ -289,3 +289,18 @@ Metadata edits lack server CAS; publication lacks idempotency keys. An uncertain
 write must be reconciled before retrying. Publication checks are not SQL or
 business validation. History lists the latest 20 summaries, and an immutable
 revision read does not guarantee historical DataBridge analysis.
+
+### Task metrics and worker logs
+
+```bash
+aliyun maxc job task-detail <instance_id> --task-name AnonymousSQLTask --json
+aliyun maxc job task-summary <instance_id> --task-name AnonymousSQLTask --json
+aliyun maxc job workers <instance_id> --task-name AnonymousSQLTask --json
+aliyun maxc job worker-log <instance_id> <log_id> --log-type stdout --size 1048576 --json
+```
+
+These read-only commands use the same project and saved job context as `job status`.
+Task detail preserves the service payload (including `mapReduce.jsonSummary`).
+Select `log_id` from `data.workers`; logs are returned as `data.content` in the JSON
+envelope. The requested size defaults to 1 MiB and must be positive; returned logs
+may be partial. Use `--project` to select the owning project explicitly.

{maxc_cli-0.6.1 → maxc_cli-0.8.0}/src/maxc_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.6.1"
+__version__ = "0.8.0"

{maxc_cli-0.6.1 → maxc_cli-0.8.0}/src/maxc_cli/_samples.py

@@ -59,6 +59,10 @@ SAMPLES: dict[str, str] = {
         "maxc job wait <job_id>\n"
         "maxc job wait <job_id> --timeout 600 --stream"
     ),
+    "job.task-detail": "maxc job task-detail <job_id> --task-name AnonymousSQLTask --json",
+    "job.task-summary": "maxc job task-summary <job_id> --task-name AnonymousSQLTask --json",
+    "job.workers": "maxc job workers <job_id> --task-name AnonymousSQLTask --json",
+    "job.worker-log": "maxc job worker-log <job_id> <log_id> --log-type stdout --size 1048576 --json",
     "job.diagnose": "maxc job diagnose <job_id>\nmaxc job diagnose <job_id> --json",
     "job.result": (
         "maxc job result <job_id>\n"
@@ -84,6 +88,22 @@ SAMPLES: dict[str, str] = {
         "maxc meta search orders\n"
         "maxc meta search user --project my_proj --json"
     ),
+    # ── kb ─────────────────────────────────────────────────────────────────
+    "kb": "maxc kb ask \"How do I set a split size hint?\" --json\nmaxc kb search \"dynamic filter\" --json",
+    "kb.ask": (
+        "maxc kb ask \"How do I set a split size hint?\"\n"
+        "maxc kb ask \"What does ODPS-0123144 mean?\" --max-docs 3 --json"
+    ),
+    "kb.search": (
+        "maxc kb search \"clustered table bucket\"\n"
+        "maxc kb search \"dynamic filter\" --limit 5 --context-lines 3 --json"
+    ),
+    # ── mcp ────────────────────────────────────────────────────────────────
+    "mcp": 'maxc mcp serve   # point an MCP client at {"command": "maxc", "args": ["mcp", "serve"]}',
+    "mcp.serve": (
+        'maxc mcp serve\n'
+        '# MCP client config: {"command": "maxc", "args": ["mcp", "serve"]}'
+    ),
     "meta.search-columns": (
         "maxc meta search-columns user_id\n"
         "maxc meta search-columns dt --project my_proj --json"

{maxc_cli-0.6.1 → maxc_cli-0.8.0}/src/maxc_cli/app.py

@@ -1811,6 +1811,30 @@ class MaxCApp:
         self.log("job.cancel", envelope.status, envelope.metadata)
         return envelope
 
+    def job_inspect(
+        self, job_id: 'str', *, section: 'str', project: 'str | None' = None,
+        task_name: 'str | None' = None, log_id: 'str | None' = None,
+        log_type: 'str' = "stdout", size: 'int' = 1048576,
+    ) -> 'Envelope':
+        if not self.remote_jobs:
+            raise FeatureUnavailableError("Task diagnostics require a MaxCompute backend.")
+        resolved = self._resolve_remote_job_id(job_id, project=project)
+        payload = self.backend.inspect_job(
+            resolved.instance_id, section=section, project=resolved.project,
+            session_context=resolved.session_context, task_name=task_name,
+            log_id=log_id, log_type=log_type, size=size,
+        )
+        envelope = Envelope(
+            command=f"job.{section}", status="success",
+            data={"job_id": resolved.external_job_id, **payload},
+            metadata={"project": resolved.project, "job_id": resolved.external_job_id},
+            agent_hints=AgentHints(warnings=[
+                "The service may return only part of the log; requested_size does not prove completeness."
+            ] if section == "worker-log" else []),
+        )
+        self.log(envelope.command, envelope.status, envelope.metadata)
+        return envelope
+
     def job_diagnose(self, job_id: 'str', *, project: 'str | None' = None) -> 'Envelope':
         if self.remote_jobs:
             resolved = self._resolve_remote_job_id(job_id, project=project)
@@ -3836,6 +3860,288 @@ class MaxCApp:
         self.log("meta.list-projects", envelope.status, envelope.metadata)
         return envelope
 
+    # --- Knowledge base (public MCP) ------------------------------------
+
+    def _mcp_client(self):
+        """Build a stateless MCP client authorized by the already-resolved credentials.
+
+        Raises ``FeatureUnavailableError`` rather than silently falling back: an agent
+        that reads "no results" and "KB unreachable" as the same signal would conclude
+        the documentation does not cover its question.
+        """
+        from .backend.mcp import (
+            CatalogMcpTokenProvider,
+            McpError,
+            McpHttpClient,
+            build_catalog_mint,
+            default_endpoint,
+        )
+
+        if not self.config.mcp.enabled:
+            raise FeatureUnavailableError(
+                "Knowledge-base commands need the MaxCompute MCP endpoint enabled.",
+                suggestion=(
+                    "Set `mcp.enabled: true` in the maxc config. The bearer is minted "
+                    "from your existing MaxCompute credentials, so no separate login "
+                    "is required."
+                ),
+            )
+        if self.backend is None or not hasattr(self.backend, "_catalog_rest"):
+            raise FeatureUnavailableError(
+                "Knowledge-base commands need an authenticated backend to mint an MCP token.",
+                suggestion="Configure credentials first: `maxc auth whoami --json`.",
+            )
+        catalog_rest = self.backend._catalog_rest
+        if catalog_rest is None:
+            raise BackendConnectionError(
+                "Could not reach CatalogAPI, which mints the MCP access token.",
+                suggestion=(
+                    "Verify connectivity and identity: `maxc agent doctor --online --json`."
+                ),
+            )
+        endpoint = (self.config.mcp.endpoint or "").strip() or default_endpoint(
+            self.config.default_region
+        )
+        try:
+            tokens = CatalogMcpTokenProvider(
+                build_catalog_mint(catalog_rest, catalog_rest.endpoint or "")
+            )
+            return McpHttpClient(
+                endpoint,
+                tokens,
+                timeout=self.config.mcp.timeout_seconds,
+                client_version=__version__,
+            )
+        except McpError as exc:
+            raise BackendConnectionError(str(exc)) from exc
+
+    @staticmethod
+    def _kb_structured(result: 'dict[str, Any]') -> 'dict[str, Any]':
+        structured = result.get("structuredContent")
+        if not isinstance(structured, dict):
+            raise BackendConnectionError(
+                "The knowledge-base tool returned no structured content.",
+                suggestion="Retry, or fall back to `maxc meta search` for metadata lookups.",
+            )
+        return structured
+
+    @staticmethod
+    def _kb_payload(
+        structured: 'dict[str, Any]',
+        *,
+        answer_from: 'tuple[str, ...] | None' = None,
+        nested_citation: bool = False,
+        package: bool = False,
+    ) -> 'dict[str, Any]':
+        """Carry the server's fields through rather than rebuilding them.
+
+        Only two transformations happen here: citations are flattened to a stable
+        ``uri`` key (the server nests it under ``source`` for search and puts it
+        top-level for ask), and an answer string is wrapped so its provenance is
+        explicit. Everything else is passed by reference on purpose — a field the
+        service adds starts appearing in maxc output with no CLI change, which is
+        the behaviour worth having when the upstream schema is not ours to pin.
+        """
+        data = structured.get("data") if isinstance(structured.get("data"), dict) else {}
+        payload: dict[str, Any] = {}
+        if answer_from is not None:
+            text = next(
+                (data[key] for key in answer_from if data.get(key) is not None), None
+            )
+            payload["answer"] = {"query": data.get("query"), "text": text}
+        else:
+            search: dict[str, Any] = {
+                "query": data.get("query"),
+                "matches": [],
+            }
+            if package:
+                search["package"] = data.get("package")
+            raw_items = data.get("results") or data.get("matches") or []
+            matches = []
+            for item in raw_items:
+                if not isinstance(item, dict):
+                    continue
+                entry = dict(item)
+                uri = entry.get("uri") or entry.get("url")
+                if uri is None and nested_citation:
+                    source = entry.get("source")
+                    if isinstance(source, dict):
+                        uri = source.get("uri") or source.get("url")
+                    elif isinstance(source, str):
+                        uri = source
+                if uri is not None:
+                    entry["uri"] = uri
+                matches.append(entry)
+            search["matches"] = matches
+            payload["search"] = search
+        raw_citations = structured.get("citations")
+        if isinstance(raw_citations, list):
+            flattened = []
+            for item in raw_citations:
+                if not isinstance(item, dict):
+                    continue
+                entry = dict(item)
+                uri = entry.get("uri") or entry.get("url")
+                if uri is not None:
+                    entry["uri"] = uri
+                flattened.append(entry)
+            payload["citations"] = flattened
+        payload["pagination"] = {
+            "has_more": bool(structured.get("has_more", False)),
+            "next_cursor": structured.get("next_cursor"),
+        }
+        # `request_id` is the only handle for correlating a metered model call with
+        # a service-side incident, so keep it at a predictable location.
+        payload["request_id"] = structured.get("request_id")
+        return payload
+
+    def kb_ask(
+        self,
+        question: 'str',
+        *,
+        max_docs: 'int | None' = None,
+        region: 'str | None' = None,
+    ) -> 'Envelope':
+        """Answer from retrieved documentation, with citations kept as first-class output.
+
+        The two kb tools return different shapes (ask yields ``data.answer`` plus a
+        top-level ``citations[]``; search yields ``data.results[]`` with the URI nested
+        under ``source``), so each is projected explicitly instead of sharing one guess.
+        """
+        started = monotonic()
+        arguments: dict[str, Any] = {"question": question}
+        if max_docs is not None:
+            arguments["max_docs"] = max_docs
+        effective_region = region or self.config.default_region
+        if effective_region:
+            arguments["region"] = effective_region
+        structured = self._call_kb_tool("maxcompute_kb_ask", arguments)
+        payload = self._kb_payload(
+            structured,
+            answer_from=("answer", "text"),
+        )
+        envelope = self._kb_envelope(
+            "kb.ask",
+            payload,
+            started,
+            effective_region,
+            follow_up="kb.search",
+            warnings=self._kb_warnings(structured),
+            insights=[
+                "The answer text is model-generated from the cited documents; attribute "
+                "product claims to `citations[].uri` rather than restating them as fact.",
+                "An empty or thin citation list means retrieval found little, which is "
+                "not evidence that the behaviour is undocumented.",
+            ],
+        )
+        self.log("kb.ask", envelope.status, envelope.metadata)
+        return envelope
+
+    def kb_search(
+        self,
+        query: 'str',
+        *,
+        limit: 'int' = 5,
+        context_lines: 'int | None' = None,
+        region: 'str | None' = None,
+    ) -> 'Envelope':
+        started = monotonic()
+        arguments: dict[str, Any] = {"query": query, "limit": limit}
+        if context_lines is not None:
+            arguments["before_lines"] = context_lines
+            arguments["after_lines"] = context_lines
+        effective_region = region or self.config.default_region
+        if effective_region:
+            arguments["region"] = effective_region
+        structured = self._call_kb_tool("maxcompute_kb_search", arguments)
+        payload = self._kb_payload(
+            structured,
+            nested_citation=True,
+            package=True,
+        )
+        envelope = self._kb_envelope(
+            "kb.search",
+            payload,
+            started,
+            effective_region,
+            follow_up="kb.ask",
+            warnings=self._kb_warnings(structured),
+            insights=[
+                "Snippets are truncated server-side; open the cited `uri` before quoting "
+                "a passage as complete.",
+            ],
+        )
+        self.log("kb.search", envelope.status, envelope.metadata)
+        return envelope
+
+    @staticmethod
+    def _kb_warnings(structured: 'dict[str, Any]') -> 'list[str]':
+        """Surface retrieval degradation that still answered HTTP 200 and ok=true-looking.
+
+        Negative inference is the specific risk here: an agent reading an empty result
+        as "the platform cannot do this" produces a confident, wrong answer.
+        """
+        warnings = [str(item) for item in (structured.get("warnings") or [])]
+        if structured.get("ok") is False:
+            warnings.append(
+                "The knowledge-base tool reported ok=false; treat this response as unverified."
+            )
+        return warnings
+
+    def _kb_envelope(
+        self,
+        command: 'str',
+        payload: 'dict[str, Any]',
+        started: float,
+        region: 'str | None',
+        *,
+        follow_up: 'str',
+        warnings: 'list[str]',
+        insights: 'list[str]',
+    ) -> 'Envelope':
+        metadata = {
+            "elapsed_ms": int((monotonic() - started) * 1000),
+            "region": region or None,
+            "backend": "mcp",
+        }
+        return Envelope(
+            command=command,
+            status="success",
+            data=payload,
+            metadata=metadata,
+            agent_hints=AgentHints(
+                actions=[action(follow_up, data=payload, metadata=metadata)],
+                warnings=warnings,
+                insights=insights,
+            ),
+        )
+
+    def _call_kb_tool(self, tool: 'str', arguments: 'dict[str, Any]') -> 'dict[str, Any]':
+        from .backend.mcp import McpError
+
+        client = self._mcp_client()
+        try:
+            result = client.call_tool(tool, arguments)
+        except McpError as exc:
+            raise BackendConnectionError(
+                str(exc),
+                suggestion=(
+                    "Confirm the MCP endpoint is reachable for your region, then retry. "
+                    "Do not conclude from this failure that the documentation lacks an answer."
+                ),
+            ) from exc
+        # A tool-level error still answers HTTP 200, so it must not read as success.
+        if result.get("isError"):
+            content = result.get("content") or []
+            detail = ""
+            if content and isinstance(content[0], dict):
+                detail = str(content[0].get("text") or "")
+            raise BackendConnectionError(
+                "The knowledge-base tool failed: "
+                + (detail[:300] or "no detail returned")
+            )
+        return self._kb_structured(result)
+
     def meta_list_schemas(self, *, project: 'str | None' = None) -> 'Envelope':
         """List all schemas in a project."""
         target_project = project or self.config.default_project
@@ -5677,6 +5983,9 @@ class MaxCApp:
             "remote_jobs": getattr(self.backend, "supports_remote_jobs", True) if self.backend else True,
             "cost_check": getattr(self.backend, "supports_cost_check", True) if self.backend else True,
             "lineage": False,  # Always false for current ODPS backend
+            # Reported from configuration only; probing the MCP endpoint would make
+            # this local command reach the network.
+            "knowledge_base": bool(self.config.mcp.enabled),
         }
 
         # Keep agent.context strictly local. Report Catalog search capability

{maxc_cli-0.6.1 → maxc_cli-0.8.0}/src/maxc_cli/auth_providers.py

@@ -66,8 +66,12 @@ class ResolvedAuthConnection:
     _MINIMUM_PYODPS = "0.12.0"
 
     def create_client(self):
+        from .enterprise_tls import configure_enterprise_tls_env
         from .odps_runtime import configure_user_agent
 
+        # requests resolves SSL_CERT_FILE when a Session is constructed, so
+        # this must run before ODPS builds its REST and tunnel clients.
+        configure_enterprise_tls_env()
         configure_user_agent()
         try:
             from odps import ODPS

{maxc_cli-0.6.1 → maxc_cli-0.8.0}/src/maxc_cli/backend/job.py

@@ -5,7 +5,7 @@ from itertools import islice
 from time import monotonic, sleep
 from typing import Any
 
-from ..exceptions import BackendConnectionError, JobTimeoutError, ValidationError
+from ..exceptions import BackendConnectionError, JobTimeoutError, MaxCError, ValidationError
 from ..helpers import (
     OdpsNoSuchObject,
     _dt_to_iso,
@@ -301,6 +301,71 @@ class JobMixin(QueryMixin):
             "task_results": task_results,
         }
 
+    def inspect_job(
+        self, job_id: 'str', *, section: 'str', project: 'str | None' = None,
+        task_name: 'str | None' = None, log_id: 'str | None' = None,
+        log_type: 'str' = "stdout", size: 'int' = 1048576,
+        session_context: 'dict[str, Any] | None' = None,
+    ) -> 'dict[str, Any]':
+        """Read task diagnostics without hiding service errors or raw metrics.
+
+        Args:
+            job_id: Instance ID resolved by the application.
+            section: task-detail, task-summary, workers, or worker-log.
+            project: Project owning the instance.
+            task_name: Explicit task name, or SDK single-task selection.
+            log_id: Worker log ID returned by worker discovery.
+            log_type: Supported PyODPS worker log type.
+            size: Positive requested log size in bytes.
+            session_context: Saved SQLRT routing context.
+        """
+        if section not in {"task-detail", "task-summary", "workers", "worker-log"}:
+            raise ValidationError("Unknown job inspection section.")
+        if section == "worker-log":
+            from odps.models.worker import LOG_TYPES_MAPPING
+
+            if not log_id or not log_id.strip():
+                raise ValidationError("A non-empty worker log ID is required.")
+            if log_type not in LOG_TYPES_MAPPING or not isinstance(size, int) or size <= 0:
+                raise ValidationError("Choose a supported log type and a positive log size.")
+        instance = self._get_instance(job_id, project=project, session_context=session_context)
+        try:
+            if section == "worker-log":
+                return {"log_id": log_id, "log_type": log_type, "requested_size": size,
+                        "content": instance.get_worker_log(log_id, log_type, size=size)}
+            if section == "task-summary":
+                if self._raw_attr(instance, "_subquery_id") is not None:
+                    from ..exceptions import FeatureUnavailableError
+
+                    raise FeatureUnavailableError(
+                        "Task summaries are not scoped to SQLRT subqueries by PyODPS.",
+                        suggestion="Use `job task-detail` for subquery-scoped metrics.",
+                    )
+                summary = instance.get_task_summary(task_name)
+                return {"task_name": task_name, "available": summary is not None,
+                        "summary": dict(summary) if summary is not None else None,
+                        "summary_text": getattr(summary, "summary_text", None)}
+            detail = instance.get_task_detail2(task_name)
+            if section == "task-detail":
+                return {"task_name": task_name, "detail": detail}
+            if not isinstance(detail, (dict, list)):
+                from ..exceptions import FeatureUnavailableError
+
+                raise FeatureUnavailableError(
+                    "Task detail is not structured JSON; worker discovery is unavailable.",
+                    suggestion="Read `job task-detail` to inspect the returned detail.",
+                )
+            workers = instance.get_task_workers(task_name, json_obj=detail)
+            fields = ("id", "log_id", "type", "status", "start_time", "end_time",
+                      "input_bytes", "input_records", "output_bytes", "output_records")
+            return {"task_name": task_name, "workers": [
+                {field: getattr(worker, field, None) for field in fields} for worker in workers
+            ]}
+        except MaxCError:
+            raise
+        except Exception as exc:
+            raise translate_odps_error(exc, context="job") from exc
+
     def list_jobs(
         self, *, project: 'str | None' = None, limit: 'int' = 20
     ) -> 'tuple[list[JobInfo], bool]':