ontora-cli 0.1.0__tar.gz → 0.3.0__tar.gz

ontora_cli-0.3.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: ontora-cli
+Version: 0.3.0
+Summary: Ontora CLI — manage campaigns, run privacy-safe analysis, and export verified confidential corpora.
+Author: Ontora
+License-Expression: LicenseRef-Proprietary
+Project-URL: Documentation, https://docs.ontora.com/cli/install
+Project-URL: API, https://docs.ontora.com/api-reference/introduction
+Project-URL: Homepage, https://docs.ontora.com
+Keywords: ontora,interviews,research,synthesis,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.6.0
+
+Ontora CLI for managing interview campaigns, transcripts, reports, queries, people, contacts, webhooks, privacy-safe analysis, and campaign-bound verified confidential-corpus exports.

ontora_cli-0.3.0/ontora_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Ontora CLI."""
+
+__version__ = "0.3.0"

ontora_cli-0.3.0/ontora_cli/client.py

@@ -0,0 +1,136 @@
+"""Thin httpx wrapper around the Ontora REST API."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Self
+
+import httpx
+
+from ontora_cli import __version__
+from ontora_cli.config import CliConfig
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, detail: Any):
+        self.status = status
+        self.detail = detail
+        super().__init__(f"HTTP {status}: {detail}")
+
+
+class OntoraClient:
+    def __init__(self, cfg: CliConfig, api_key: str):
+        self.cfg = cfg
+        self._client = httpx.Client(
+            base_url=cfg.base_url,
+            headers={
+                "X-API-Key": api_key,
+                "User-Agent": f"ontora-cli/{__version__}",
+            },
+            timeout=60.0,
+            # Workspace keys use the REST API's X-API-Key contract. Never
+            # auto-follow redirects: custom auth headers can otherwise be
+            # forwarded to a different origin by the HTTP client.
+            follow_redirects=False,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _raise(self, r: httpx.Response) -> None:
+        if r.is_success:
+            return
+        try:
+            detail = r.json()
+        except json.JSONDecodeError:
+            detail = r.text
+        raise ApiError(r.status_code, detail)
+
+    # ------------------------------------------------------------------ HTTP
+    def get(self, path: str, params: dict | None = None) -> Any:
+        r = self._client.get(path, params=params)
+        self._raise(r)
+        return r.json() if r.content else None
+
+    def post(
+        self, path: str, json_body: dict | None = None, params: dict | None = None
+    ) -> Any:
+        r = self._client.post(path, json=json_body, params=params)
+        self._raise(r)
+        return r.json() if r.content else None
+
+    def patch(self, path: str, json_body: dict) -> Any:
+        r = self._client.patch(path, json=json_body)
+        self._raise(r)
+        return r.json() if r.content else None
+
+    def delete(self, path: str) -> None:
+        r = self._client.delete(path)
+        self._raise(r)
+
+    def get_raw(
+        self,
+        path: str,
+        params: dict | None = None,
+        *,
+        timeout: float | None = None,
+        max_bytes: int | None = None,
+    ) -> httpx.Response:
+        """Return a downloaded response, optionally enforcing a streaming size cap."""
+
+        request_options = {"timeout": timeout} if timeout is not None else {}
+        deadline = time.monotonic() + timeout if timeout is not None else None
+        if max_bytes is None:
+            r = self._client.get(path, params=params, **request_options)
+            self._raise(r)
+            return r
+        if max_bytes <= 0:
+            raise ValueError("max_bytes must be greater than zero")
+
+        with self._client.stream(
+            "GET", path, params=params, **request_options
+        ) as streamed:
+            if deadline is not None and time.monotonic() > deadline:
+                raise RuntimeError(
+                    f"download exceeded the {timeout:g}-second total deadline"
+                )
+            if not streamed.is_success:
+                streamed.read()
+                self._raise(streamed)
+
+            content_length = streamed.headers.get("Content-Length")
+            if content_length is not None:
+                try:
+                    declared_size = int(content_length)
+                except ValueError:
+                    declared_size = None
+                if declared_size is not None and declared_size > max_bytes:
+                    raise RuntimeError(
+                        f"download exceeds the {max_bytes // (1024 * 1024)} MiB safety limit"
+                    )
+
+            content = bytearray()
+            for chunk in streamed.iter_bytes():
+                if deadline is not None and time.monotonic() > deadline:
+                    raise RuntimeError(
+                        f"download exceeded the {timeout:g}-second total deadline"
+                    )
+                if len(content) + len(chunk) > max_bytes:
+                    raise RuntimeError(
+                        f"download exceeds the {max_bytes // (1024 * 1024)} MiB safety limit"
+                    )
+                content.extend(chunk)
+
+            return httpx.Response(
+                status_code=streamed.status_code,
+                headers=streamed.headers,
+                content=bytes(content),
+                request=streamed.request,
+            )

ontora_cli-0.3.0/ontora_cli/commands/analysis.py

@@ -0,0 +1,490 @@
+"""Privacy-safe full-corpus analysis commands."""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from enum import Enum
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from ontora_cli.client import OntoraClient
+from ontora_cli.config import load_config, require_api_key
+
+app = typer.Typer(help="Run privacy-safe analyses over every answer in a campaign.")
+
+_TERMINAL_STATUSES = frozenset({"ready", "partial", "failed", "cancelled"})
+_SUCCESS_STATUS = "ready"
+
+
+class InvalidApiResponse(RuntimeError):
+    """Raised when the API violates the CLI's documented response contract."""
+
+
+class ResultFormat(str, Enum):
+    markdown = "md"
+    json = "json"
+
+
+def _status(run: dict[str, Any]) -> str:
+    return str(run.get("status") or "unknown").strip().lower()
+
+
+def _stale_reason(run: dict[str, Any]) -> str | None:
+    value = run.get("stale_reason")
+    return str(value).strip() if value else None
+
+
+def _coverage(run: dict[str, Any]) -> dict[str, Any]:
+    value = run.get("coverage")
+    return value if isinstance(value, dict) else {}
+
+
+def _added_since_snapshot(run: dict[str, Any]) -> int:
+    try:
+        return max(0, int(_coverage(run).get("added_since_snapshot") or 0))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _is_terminal(run: dict[str, Any]) -> bool:
+    return _status(run) in _TERMINAL_STATUSES or _stale_reason(run) is not None
+
+
+def _run_problem(run: dict[str, Any]) -> str | None:
+    stale_reason = _stale_reason(run)
+    if stale_reason:
+        return f"stale analysis ({stale_reason}); start a new analysis run"
+
+    added = _added_since_snapshot(run)
+    if added:
+        current = _coverage(run).get("current_completed")
+        current_detail = (
+            f" ({current} answers are now eligible)" if current is not None else ""
+        )
+        return (
+            f"analysis snapshot excludes {added} newly completed answer(s){current_detail}; "
+            "start a new analysis run"
+        )
+
+    status = _status(run)
+    if status == _SUCCESS_STATUS:
+        return None
+    if status == "partial":
+        prefix = "analysis completed only partially"
+    elif status == "failed":
+        prefix = "analysis failed"
+    elif status == "cancelled":
+        prefix = "analysis was cancelled"
+    else:
+        return None
+
+    code = str(run.get("error_code") or "").strip()
+    message = str(run.get("error_message") or "").strip()
+    details = ": ".join(value for value in (code, message) if value)
+    return f"{prefix}: {details}" if details else prefix
+
+
+def _progress(run: dict[str, Any]) -> tuple[Any, Any]:
+    coverage = _coverage(run)
+    progress = run.get("progress") if isinstance(run.get("progress"), dict) else {}
+    processed = coverage.get("processed", progress.get("processed"))
+    total = coverage.get("total", progress.get("total"))
+    return processed, total
+
+
+def _state_signature(run: dict[str, Any]) -> tuple[Any, ...]:
+    processed, total = _progress(run)
+    return (
+        _status(run),
+        run.get("phase"),
+        processed,
+        total,
+        _stale_reason(run),
+        _added_since_snapshot(run),
+        _coverage(run).get("current_completed"),
+        run.get("error_code"),
+        run.get("error_message"),
+    )
+
+
+def _state_line(run: dict[str, Any]) -> str:
+    status = _status(run)
+    phase = str(run.get("phase") or status)
+    processed, total = _progress(run)
+    progress = ""
+    if processed is not None or total is not None:
+        progress = f"  progress={processed if processed is not None else '?'}"
+        if total is not None:
+            progress += f"/{total}"
+    added = _added_since_snapshot(run)
+    if added:
+        current = _coverage(run).get("current_completed")
+        progress += f"  snapshot_outdated=+{added}"
+        if current is not None:
+            progress += f" current={current}"
+    return f"status={status}  phase={phase}{progress}"
+
+
+def _print_run(run: dict[str, Any], *, session_id: str, run_id: str) -> None:
+    typer.echo(f"session_id: {session_id}")
+    typer.echo(f"run_id: {run_id}")
+    typer.echo(_state_line(run))
+    problem = _run_problem(run)
+    if problem:
+        typer.secho(f"Problem: {problem}", fg=typer.colors.RED, err=True)
+
+
+def _wait_for_terminal(
+    client: OntoraClient,
+    *,
+    session_id: str,
+    run_id: str,
+    initial: dict[str, Any],
+    poll_interval: float,
+    show_progress: bool,
+) -> dict[str, Any]:
+    run = initial
+    last_signature = _state_signature(run)
+    while not _is_terminal(run):
+        time.sleep(poll_interval)
+        run = client.get(
+            f"/v1/insights-chat/sessions/{session_id}/analysis-runs/{run_id}"
+        )
+        if not isinstance(run, dict):
+            raise InvalidApiResponse(
+                "The analysis status endpoint returned an invalid response."
+            )
+        signature = _state_signature(run)
+        if show_progress and signature != last_signature:
+            typer.echo(_state_line(run))
+        last_signature = signature
+    return run
+
+
+def _citation_markers(item: dict[str, Any]) -> str:
+    evidence = item.get("evidence")
+    if not isinstance(evidence, list):
+        return ""
+    keys = []
+    for value in evidence[:2]:
+        if not isinstance(value, dict):
+            continue
+        key = value.get("citation_key")
+        if key:
+            keys.append(f"[{key}]")
+    return f" {' '.join(keys)}" if keys else ""
+
+
+def _result_markdown(result: Any, coverage: dict[str, Any]) -> str:
+    if isinstance(result, str) and result.strip():
+        return result.strip()
+    if not isinstance(result, dict):
+        return json.dumps(result, indent=2, ensure_ascii=False, default=str)
+
+    for key in ("markdown", "content", "answer", "text"):
+        direct = result.get(key)
+        if isinstance(direct, str) and direct.strip():
+            return direct.strip()
+
+    summary = result.get("management_summary")
+    summary = summary if isinstance(summary, dict) else {}
+    lines = [f"## {summary.get('headline') or 'Management Summary'}"]
+    if summary.get("summary"):
+        lines.extend(("", str(summary["summary"])))
+
+    key_points = summary.get("key_points")
+    if isinstance(key_points, list):
+        for point in key_points:
+            if isinstance(point, dict):
+                text = point.get("text") or point.get("summary") or point.get("title")
+                if text:
+                    lines.append(f"- {text}{_citation_markers(point)}")
+            elif point:
+                lines.append(f"- {point}")
+
+    priorities = result.get("priorities")
+    if isinstance(priorities, list) and priorities:
+        lines.extend(("", "## Priorities"))
+        for index, priority in enumerate(priorities, start=1):
+            if not isinstance(priority, dict):
+                lines.append(f"{index}. {priority}")
+                continue
+            rank = priority.get("rank") or index
+            title = priority.get("title") or "Priority"
+            rationale = priority.get("rationale")
+            suffix = f": {rationale}" if rationale else ""
+            lines.append(f"{rank}. **{title}**{suffix}{_citation_markers(priority)}")
+            next_steps = priority.get("next_steps")
+            if isinstance(next_steps, list):
+                lines.extend(f"   - {step}" for step in next_steps if step)
+
+    themes = result.get("themes")
+    if isinstance(themes, list) and themes:
+        lines.extend(("", "## Themes"))
+        for theme in themes:
+            if not isinstance(theme, dict):
+                lines.append(f"- {theme}")
+                continue
+            title = theme.get("title") or "Theme"
+            summary_text = theme.get("summary")
+            suffix = f": {summary_text}" if summary_text else ""
+            lines.append(f"- **{title}**{suffix}{_citation_markers(theme)}")
+
+    divergences = result.get("divergences")
+    if isinstance(divergences, list) and divergences:
+        lines.extend(("", "## Divergences"))
+        for divergence in divergences:
+            if not isinstance(divergence, dict):
+                lines.append(f"- {divergence}")
+                continue
+            topic = (
+                divergence.get("topic")
+                or divergence.get("title")
+                or "Different perspectives"
+            )
+            description = divergence.get("description") or divergence.get("summary")
+            suffix = f": {description}" if description else ""
+            lines.append(f"- **{topic}**{suffix}{_citation_markers(divergence)}")
+
+    caveats = result.get("caveats")
+    if isinstance(caveats, list) and caveats:
+        lines.extend(("", "## Caveats"))
+        lines.extend(f"- {caveat}" for caveat in caveats if caveat)
+
+    processed = coverage.get("processed", 0)
+    total = coverage.get("total", 0)
+    citable = coverage.get("citable", 0)
+    aggregate_processed = coverage.get("aggregate_only_processed", 0)
+    aggregate_total = coverage.get("aggregate_only", 0)
+    aggregate_contributing = coverage.get("aggregate_only_contributing", 0)
+    added = coverage.get("added_since_snapshot", 0)
+    current_completed = coverage.get("current_completed", total)
+    lines.extend(
+        (
+            "",
+            "## Coverage",
+            (
+                f"{processed}/{total} answers processed; {citable} citable sources; "
+                f"{aggregate_processed}/{aggregate_total} protected sources processed; "
+                f"{aggregate_contributing} protected sources contributed to publishable shared patterns."
+            ),
+            (
+                f"Snapshot is outdated: {added} newly completed answer(s) are not included "
+                f"({current_completed} currently eligible). Start a new analysis run."
+                if added
+                else f"Snapshot includes all {current_completed} currently eligible answers."
+            ),
+        )
+    )
+    return "\n".join(lines).strip()
+
+
+@app.command("start")
+def start_cmd(
+    interview_id: Annotated[str, typer.Argument(help="Campaign/interview ID.")],
+    objective: Annotated[
+        str,
+        typer.Argument(help="Question or objective for the complete-corpus analysis."),
+    ],
+    model: Annotated[
+        str | None, typer.Option("--model", help="Analysis model ID.")
+    ] = None,
+    request_id: Annotated[
+        uuid.UUID | None,
+        typer.Option(
+            "--request-id", help="Caller-supplied UUID for the client message."
+        ),
+    ] = None,
+    wait: Annotated[
+        bool,
+        typer.Option("--wait", help="Poll until the run reaches a terminal state."),
+    ] = False,
+    poll_interval: Annotated[
+        float,
+        typer.Option(
+            "--poll-interval",
+            min=0.1,
+            help="Seconds between status requests with --wait.",
+        ),
+    ] = 2.0,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Print machine-readable JSON.")
+    ] = False,
+) -> None:
+    """Start an exhaustive, privacy-safe analysis over every campaign answer."""
+    objective = objective.strip()
+    if not objective:
+        raise typer.BadParameter("must not be empty", param_hint="OBJECTIVE")
+
+    cfg = load_config()
+    key = require_api_key(cfg)
+    message_id = request_id or uuid.uuid4()
+
+    with OntoraClient(cfg, key) as client:
+        chat_session = client.post(
+            f"/v1/interviews/{interview_id}/chat/sessions",
+            json_body={"title": None},
+        )
+        if not isinstance(chat_session, dict) or not chat_session.get("id"):
+            raise InvalidApiResponse(
+                "The chat session endpoint returned an invalid response."
+            )
+        session_id = str(chat_session["id"])
+
+        user_message = client.post(
+            f"/v1/insights-chat/sessions/{session_id}/messages",
+            json_body={
+                "role": "user",
+                "content": objective,
+                "client_message_id": str(message_id),
+            },
+        )
+        if not isinstance(user_message, dict) or not user_message.get("message_id"):
+            raise InvalidApiResponse(
+                "The chat message endpoint returned an invalid response."
+            )
+
+        body: dict[str, Any] = {
+            "objective": objective,
+            "user_message_id": str(user_message["message_id"]),
+        }
+        if model:
+            body["model"] = model
+        run = client.post(
+            f"/v1/insights-chat/sessions/{session_id}/analysis-runs",
+            json_body=body,
+        )
+        if not isinstance(run, dict) or not run.get("id"):
+            raise InvalidApiResponse(
+                "The analysis start endpoint returned an invalid response."
+            )
+        run_id = str(run["id"])
+
+        if not json_output:
+            _print_run(run, session_id=session_id, run_id=run_id)
+        if wait:
+            run = _wait_for_terminal(
+                client,
+                session_id=session_id,
+                run_id=run_id,
+                initial=run,
+                poll_interval=poll_interval,
+                show_progress=not json_output,
+            )
+
+    if json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "session_id": session_id,
+                    "run_id": run_id,
+                    "request_id": str(message_id),
+                    "run": run,
+                },
+                indent=2,
+                ensure_ascii=False,
+                default=str,
+            )
+        )
+
+    if wait:
+        problem = _run_problem(run)
+        if problem:
+            if not json_output:
+                typer.secho(f"Problem: {problem}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(1)
+        if not json_output:
+            typer.secho("Analysis completed.", fg=typer.colors.GREEN)
+
+
+@app.command("status")
+def status_cmd(
+    session_id: Annotated[
+        str, typer.Argument(help="Chat session ID returned by analysis start.")
+    ],
+    run_id: Annotated[
+        str, typer.Argument(help="Analysis run ID returned by analysis start.")
+    ],
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Print the complete run as JSON.")
+    ] = False,
+) -> None:
+    """Show progress, terminal failures, and stale-run details."""
+    cfg = load_config()
+    key = require_api_key(cfg)
+    with OntoraClient(cfg, key) as client:
+        run = client.get(
+            f"/v1/insights-chat/sessions/{session_id}/analysis-runs/{run_id}"
+        )
+    if not isinstance(run, dict):
+        raise InvalidApiResponse(
+            "The analysis status endpoint returned an invalid response."
+        )
+    if json_output:
+        typer.echo(json.dumps(run, indent=2, ensure_ascii=False, default=str))
+    else:
+        _print_run(run, session_id=session_id, run_id=run_id)
+    if _added_since_snapshot(run):
+        raise typer.Exit(1)
+
+
+@app.command("result")
+def result_cmd(
+    session_id: Annotated[
+        str, typer.Argument(help="Chat session ID returned by analysis start.")
+    ],
+    run_id: Annotated[
+        str, typer.Argument(help="Analysis run ID returned by analysis start.")
+    ],
+    format: Annotated[
+        ResultFormat, typer.Option("--format", "-f")
+    ] = ResultFormat.markdown,
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Write to a file instead of stdout."),
+    ] = None,
+) -> None:
+    """Read the server-sanitized analysis result without fetching raw transcripts."""
+    cfg = load_config()
+    key = require_api_key(cfg)
+    with OntoraClient(cfg, key) as client:
+        run = client.get(
+            f"/v1/insights-chat/sessions/{session_id}/analysis-runs/{run_id}"
+        )
+    if not isinstance(run, dict):
+        raise InvalidApiResponse(
+            "The analysis result endpoint returned an invalid response."
+        )
+
+    stale_reason = _stale_reason(run)
+    added_since_snapshot = _added_since_snapshot(run)
+    result = run.get("result")
+    if stale_reason or added_since_snapshot or result is None:
+        problem = _run_problem(run)
+        if problem is None:
+            problem = f"no result is available while status is {_status(run)}"
+        typer.secho(f"Error: {problem}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    if format is ResultFormat.json:
+        text = json.dumps(result, indent=2, ensure_ascii=False, default=str)
+    else:
+        coverage = run.get("coverage") if isinstance(run.get("coverage"), dict) else {}
+        text = _result_markdown(result, coverage)
+
+    if output:
+        output.write_text(f"{text}\n", encoding="utf-8")
+        typer.echo(f"Wrote {output}")
+    else:
+        typer.echo(text)
+
+    if _status(run) == "partial":
+        typer.secho(
+            "Warning: this is a partial analysis result.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )