quantikmind-cli 0.1.0__tar.gz → 1.0.0__tar.gz

quantikmind_cli-1.0.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: quantikmind-cli
+Version: 1.0.0
+Summary: Command line tools for Quantik Mind test selection and runtime signal collection
+Author: Quantik Mind
+Keywords: quantik-mind,testing,ci,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click
+Requires-Dist: requests
+Requires-Dist: PyYAML
+Requires-Dist: rich
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# Quantik Mind CLI
+
+The canonical installation, command and CI/CD guide is [the integration CLI guide](../docs/integration/03-cli-guide.md). It describes the intended final 1.0.0 release. This source prepares 1.0.0rc1 for local release verification; it is not a published final release. Publication and backend compatibility approval remain separate release gates.
+
+For local development: `python -m pip install -e .` from this directory.

quantikmind_cli-1.0.0/README.md

@@ -0,0 +1,5 @@
+# Quantik Mind CLI
+
+The canonical installation, command and CI/CD guide is [the integration CLI guide](../docs/integration/03-cli-guide.md). It describes the intended final 1.0.0 release. This source prepares 1.0.0rc1 for local release verification; it is not a published final release. Publication and backend compatibility approval remain separate release gates.
+
+For local development: `python -m pip install -e .` from this directory.

quantikmind_cli-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools==80.9.0", "wheel==0.45.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quantikmind-cli"
+version = "1.0.0"
+description = "Command line tools for Quantik Mind test selection and runtime signal collection"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Quantik Mind" },
+]
+keywords = ["quantik-mind", "testing", "ci", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "click",
+    "requests",
+    "PyYAML",
+    "rich",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+]
+
+[project.scripts]
+qmind = "quantikmind_cli.cli:cli"
+
+[tool.setuptools.packages.find]
+include = ["quantikmind_cli*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{quantikmind_cli-0.1.0 → quantikmind_cli-1.0.0}/quantikmind_cli/agent/prometheus.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import math
 from dataclasses import dataclass
 from typing import Any, Mapping
 
@@ -17,11 +18,22 @@ class MetricCheck:
     warning: str | None = None
 
 
+# v2 histogram is service_response_time_seconds_bucket: p95 is seconds.
+AGENT_METRICS_CONTRACT_VERSION = "service-metrics-v2"
+
+# Both counters must describe the same eligible request population. Missing
+# numerator series remain absent; filtering the denominator excludes no traffic.
 SERVICE_METRIC_QUERIES = {
     "cpu_load": "avg by (service)(service_cpu_load)",
-    "error_rate": "rate(service_errors_total[5m])",
-    "request_rate": "rate(service_requests_total[5m])",
-    "latency_p95": "histogram_quantile(0.95, rate(service_response_time_seconds_bucket[5m]))",
+    "error_rate": (
+        "sum by (service) (rate(service_errors_total[5m]))"
+        " / (sum by (service) (rate(service_requests_total[5m])) > 0)"
+    ),
+    "request_rate": "sum by (service) (rate(service_requests_total[5m]))",
+    "latency_p95": (
+        "histogram_quantile(0.95, sum by (le, service) "
+        "(rate(service_response_time_seconds_bucket[5m])))"
+    ),
 }
 
 
@@ -78,15 +90,26 @@ class PrometheusClient:
     def collect_service_metrics(self) -> dict[str, dict[str, float]]:
         metrics: dict[str, dict[str, float]] = {}
         for payload_key, query in SERVICE_METRIC_QUERIES.items():
+            seen: set[str] = set()
             for sample in self.query(query):
                 service = _sample_service(sample)
                 if not service:
                     continue
+                if service in seen:
+                    raise PrometheusError(f"Duplicate service result for {payload_key}: {service}")
+                seen.add(service)
                 value = _sample_value(sample)
                 if value is None:
                     continue
+                if payload_key == "error_rate" and not 0 <= value <= 1:
+                    continue
+                if payload_key in {"request_rate", "latency_p95"} and value < 0:
+                    continue
                 metrics.setdefault(service, {})[payload_key] = value
-        return metrics
+        for values in metrics.values():
+            if values.get("request_rate", 0) <= 0:
+                values.pop("error_rate", None)
+        return {service: values for service, values in metrics.items() if values}
 
 
 def normalize_prometheus_url(value: str) -> str:
@@ -112,6 +135,7 @@ def _sample_value(sample: Mapping[str, Any]) -> float | None:
     if not isinstance(value, list) or len(value) < 2:
         return None
     try:
-        return float(value[1])
+        numeric = float(value[1])
+        return numeric if math.isfinite(numeric) else None
     except (TypeError, ValueError):
         return None

{quantikmind_cli-0.1.0 → quantikmind_cli-1.0.0}/quantikmind_cli/api.py

@@ -1,10 +1,13 @@
 from __future__ import annotations
 
 from typing import Any, Mapping
+import os
+import math
+import re
 
 import requests
 
-from .config import DEFAULT_BASE_URL, resolve_base_url
+from .config import ConfigError, DEFAULT_BASE_URL, resolve_base_url
 
 
 class ApiError(RuntimeError):
@@ -32,6 +35,7 @@ class QuantikMindApiClient:
         token: str | None = None,
         auth_mode: str = "auto",
         timeout: float = 30.0,
+        selection_read_timeout_seconds: float = 120.0,
         session: requests.Session | None = None,
     ) -> None:
         self.base_url = base_url.rstrip("/")
@@ -39,6 +43,13 @@ class QuantikMindApiClient:
         self.token = token
         self.auth_mode = auth_mode
         self.timeout = timeout
+        try:
+            reference = float(selection_read_timeout_seconds)
+        except (TypeError, ValueError) as exc:
+            raise ConfigError("selection_read_timeout_seconds must be positive and finite") from exc
+        if isinstance(selection_read_timeout_seconds, bool) or not math.isfinite(reference) or reference <= 0:
+            raise ConfigError("selection_read_timeout_seconds must be positive and finite")
+        self.selection_read_timeout_seconds = reference
         self.session = session or requests.Session()
 
     @classmethod
@@ -53,6 +64,7 @@ class QuantikMindApiClient:
             api_key=credentials.get("api_key"),
             token=credentials.get("token") or credentials.get("access_token"),
             auth_mode=str(credentials.get("auth_mode") or "auto"),
+            selection_read_timeout_seconds=(repo_config or {}).get("selection_read_timeout_seconds", 120.0),
         )
 
     def auth_headers(self) -> dict[str, str]:
@@ -65,6 +77,16 @@ class QuantikMindApiClient:
             return {"X-QM-API-Key": self.api_key}
         return {"Authorization": f"Bearer {credential}"}
 
+    def safe_error(self, message: str) -> str:
+        for value in (self.api_key, self.token):
+            if value:
+                message = message.replace(value, "[REDACTED]")
+        message = re.sub(r"https?://\S+", "[URL omitted]", message)
+        message = re.sub(r"qm_(?:live|dev)_[A-Za-z0-9_-]+", "[REDACTED]", message)
+        if re.search(r"<\s*(?:html|!doctype)", message, re.I):
+            return "API returned an error page; raw response omitted."
+        return message[:2000]
+
     def request(
         self,
         method: str,
@@ -73,6 +95,7 @@ class QuantikMindApiClient:
         json: Any | None = None,
         params: Mapping[str, Any] | None = None,
         headers: Mapping[str, str] | None = None,
+        timeout: float | tuple[float, float] | None = None,
     ) -> Any:
         url = f"{self.base_url}/{path.lstrip('/')}"
         merged_headers = {"Accept": "application/json"}
@@ -87,15 +110,22 @@ class QuantikMindApiClient:
                 json=json,
                 params=dict(params or {}),
                 headers=merged_headers,
-                timeout=self.timeout,
+                timeout=self.timeout if timeout is None else timeout,
             )
+        except requests.ReadTimeout as exc:
+            if path == "/api/v1/functional/select":
+                raise NetworkError(
+                    "Selection read timed out. The backend may still complete the run. "
+                    "Check existing runs before requesting another selection; this request was not retried."
+                ) from exc
+            raise NetworkError(self.safe_error(f"Unable to reach Quantik Mind API: {exc}")) from exc
         except requests.RequestException as exc:
-            raise NetworkError(f"Unable to reach Quantik Mind API: {exc}") from exc
+            raise NetworkError(self.safe_error(f"Unable to reach Quantik Mind API: {exc}")) from exc
 
         if response.status_code in {401, 403}:
-            raise AuthenticationError(_error_message(response, "Authentication failed"))
+            raise AuthenticationError(self.safe_error(_error_message(response, "Authentication failed")))
         if response.status_code >= 400:
-            raise ApiError(_error_message(response, f"API request failed with {response.status_code}"))
+            raise ApiError(self.safe_error(_error_message(response, f"API request failed with {response.status_code}")))
 
         if not response.content:
             return None
@@ -179,14 +209,20 @@ class QuantikMindApiClient:
         project_id: str,
         *,
         changed_files: list[str] | None = None,
+        tau: float | None = None,
     ) -> dict[str, Any]:
         params: dict[str, Any] = {"project_id": project_id}
         if changed_files:
             params["changed_files"] = changed_files
+        if tau is not None:
+            if not math.isfinite(float(tau)) or not 0.05 <= float(tau) <= 0.95:
+                raise ApiError("tau must be a finite number between 0.05 and 0.95")
+            params["tau"] = float(tau)
         payload = self.request(
             "GET",
             "/api/v1/functional/select",
             params=params,
+            timeout=(self.timeout, self.selection_read_timeout_seconds),
         )
         if not isinstance(payload, dict):
             raise ApiError("API returned an unexpected functional selection response")
@@ -265,6 +301,12 @@ class QuantikMindApiClient:
             raise ApiError("API returned an unexpected observability configuration response")
         return response
 
+    def track_funnel_event(self, event_type: str, metadata: Mapping[str, Any] | None = None) -> None:
+        self.request("POST", "/api/v1/funnel/event", json={
+            "eventType": event_type, "eventSource": "ci" if os.getenv("CI") else "cli",
+            "metadata": dict(metadata or {}),
+        })
+
     def get_observability_status(self, project_id: str) -> dict[str, Any]:
         response = self.request(
             "GET",

{quantikmind_cli-0.1.0 → quantikmind_cli-1.0.0}/quantikmind_cli/cli.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from datetime import datetime, timezone
 import json
+import math
 import os
 from pathlib import Path
 import time
@@ -13,7 +14,7 @@ from rich.table import Table
 import yaml
 
 from .api import AgentMetricsEndpointUnavailable, ApiError, AuthenticationError, NetworkError, QuantikMindApiClient
-from .agent.prometheus import PrometheusClient, PrometheusError
+from .agent.prometheus import AGENT_METRICS_CONTRACT_VERSION, PrometheusClient, PrometheusError
 from .config import (
     DEFAULT_BASE_URL,
     ConfigError,
@@ -39,6 +40,7 @@ from .subset import (
     selected_test_selectors,
     selection_stats,
 )
+from .telemetry import track_cli_event
 
 
 console = Console(width=120)
@@ -234,6 +236,7 @@ def init(
         {"api_key": api_key, "auth_mode": _auth_mode_for_api_key(api_key, existing_credentials)},
         path=credentials_path(),
     )
+    track_cli_event(client, "cli_initialized", {"command": "init"})
 
     table = Table(title="Quantik Mind setup")
     table.add_column("Setting")
@@ -423,12 +426,32 @@ def record_tests(results_dir: Path | None) -> None:
     is_flag=True,
     help="Print the complete selection payload as machine-readable JSON.",
 )
+@click.option("--wait", "wait_for_run", is_flag=True, help="Wait for saved sync/async completion without resubmitting.")
+@click.option("--timeout-seconds", type=click.FloatRange(min=0.1), default=600)
+@click.option("--poll-interval-seconds", type=click.FloatRange(min=0.1), default=3)
+@click.option("--receipt-file", type=click.Path(path_type=Path, dir_okay=False))
+@click.option("--expected-influence", type=click.Choice(["off", "on"]))
+@click.option(
+    "--tau",
+    type=float,
+    default=None,
+    help=(
+        "Per-run selection breadth (0.05-0.95). Lower is more restrictive; "
+        "actual size also depends on the probability distribution and coverage guardrails."
+    ),
+)
 def subset(
     framework: str | None,
     internal_ids: bool,
     changed_files: tuple[str, ...],
     changed_files_file: Path | None,
     json_output: bool,
+    wait_for_run: bool,
+    timeout_seconds: float,
+    poll_interval_seconds: float,
+    receipt_file: Path | None,
+    expected_influence: str | None,
+    tau: float | None,
 ) -> None:
     """Request or inspect selected test subsets."""
     try:
@@ -452,16 +475,43 @@ def subset(
     except ConfigError as exc:
         raise click.ClickException(f"{exc}. Run `qmind init` or set up ~/.qmind/credentials.yaml.") from exc
 
-    client = QuantikMindApiClient.from_config(repo_config, credentials)
+    try:
+        client = QuantikMindApiClient.from_config(repo_config, credentials)
+    except ConfigError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if tau is not None and (not math.isfinite(tau) or not 0.05 <= tau <= 0.95):
+        raise click.BadParameter(
+            "must be a finite number between 0.05 and 0.95", param_hint="--tau"
+        )
+    if wait_for_run or receipt_file or expected_influence:
+        from .runs import submit, emit
+        explicit = _resolve_subset_changed_files(changed_files=changed_files, changed_files_file=changed_files_file)
+        result = submit(client, project_id, explicit, tau=tau, wait=wait_for_run, timeout=timeout_seconds,
+                        poll_interval=poll_interval_seconds, receipt_file=receipt_file, expected=expected_influence)
+        emit(result)
+        return
+    telemetry_state = load_agent_state()
+    is_first_run = not bool(telemetry_state.get("first_selection_completed"))
+    if is_first_run:
+        track_cli_event(client, "first_run_started", {"command": "subset"})
+    started_at = time.monotonic()
     try:
         explicit_changed_files = _resolve_subset_changed_files(
             changed_files=changed_files,
             changed_files_file=changed_files_file,
         )
-        response = client.select_functional_tests(
-            project_id,
-            changed_files=explicit_changed_files,
-        )
+        selection_kwargs = {"changed_files": explicit_changed_files}
+        if tau is not None:
+            selection_kwargs["tau"] = tau
+        response = client.select_functional_tests(project_id, **selection_kwargs)
+        if "selected" not in response and response.get("status") in {"pending", "queued", "running"} and response.get("run_id"):
+            from .runs import RunError, uuid_value, write_json
+            run_id = uuid_value(response["run_id"])
+            receipt = Path.cwd() / ".qmind" / "receipts" / (run_id + ".json")
+            write_json(receipt, {"schema_version": 1, "run_id": run_id, "project_id": project_id, "status": response["status"], "submission_outcome": "known"})
+            if json_output:
+                click.echo(json.dumps(response, sort_keys=True))
+            raise RunError(f"Selection accepted as {run_id}. Receipt: {receipt}. Use qmind runs wait/export; do not resubmit.", 3)
         selectors = selected_test_selectors(response, use_internal_ids=internal_ids)
         if json_output:
             formatted = json.dumps(
@@ -472,12 +522,28 @@ def subset(
         else:
             formatted = format_test_selectors(selected_framework, selectors)
     except AuthenticationError as exc:
+        track_cli_event(client, "test_selection_failed", {"command": "subset", "error_code": "authentication_error"})
         raise click.ClickException(f"Invalid Quantik Mind credentials: {exc}. Run `qmind init` with a valid API key.") from exc
     except (NetworkError, ApiError) as exc:
+        track_cli_event(client, "test_selection_failed", {"command": "subset", "error_code": "api_error"})
         raise click.ClickException(f"Could not select tests: {exc}") from exc
     except SubsetError as exc:
+        track_cli_event(client, "test_selection_failed", {"command": "subset", "error_code": "response_error"})
         raise click.ClickException(str(exc)) from exc
 
+    counts = response.get("counts", {}) if isinstance(response, dict) else {}
+    event_metadata = {"command": "subset", "run_id": response.get("run_id"),
+        "test_count": counts.get("total"), "selected_test_count": counts.get("selected"),
+        "skipped_test_count": counts.get("skipped"), "duration_ms": int((time.monotonic()-started_at)*1000)}
+    if is_first_run:
+        track_cli_event(client, "first_run_completed", event_metadata)
+        telemetry_state["first_selection_completed"] = True
+        try:
+            write_agent_state(telemetry_state)
+        except Exception:
+            pass
+    track_cli_event(client, "test_selection_executed", event_metadata)
+
     stats = selection_stats(response)
     if stats and not json_output:
         click.echo(stats, err=True)
@@ -1035,6 +1101,7 @@ def _run_agent_cycle(
     payload = {
         "project_id": project_id,
         "timestamp": timestamp,
+        "contract_version": AGENT_METRICS_CONTRACT_VERSION,
         "metrics": metrics,
     }
     try:
@@ -1668,5 +1735,9 @@ def _display_value(value: object) -> str:
     return "unknown" if value is None else str(value)
 
 
+from .runs import register as _register_saved_runs
+
+_register_saved_runs(cli)
+
 if __name__ == "__main__":
     cli()

{quantikmind_cli-0.1.0 → quantikmind_cli-1.0.0}/quantikmind_cli/config.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 from pathlib import Path
 from typing import Any, Mapping
 
@@ -23,6 +24,9 @@ def repo_config_path(root: str | Path = ".") -> Path:
 
 
 def credentials_path(home: str | Path | None = None) -> Path:
+    override = os.environ.get("QMIND_CREDENTIALS_PATH") if home is None else None
+    if override:
+        return Path(override).expanduser()
     base = Path(home) if home is not None else Path.home()
     return base / CREDENTIALS_DIR / CREDENTIALS_FILE