ando-ai 0.4.0__py3-none-any.whl

ando_ai/__init__.py

@@ -0,0 +1,147 @@
+"""Ando Platform API — official Python SDK (sync, httpx-based).
+
+Public surface:
+    AndoPlatform      — the client (context manager)
+    ApiError          — envelope errors (stable ``code`` + HTTP ``status``)
+    NetworkError      — transport failures (DNS/connect/TLS/timeout)
+    JobFailed         — ingest job ended ``failed`` (carries ``error_code``)
+    JobTimeout        — ``wait_for_job`` deadline exceeded
+    AndoPlatformError — common base class of all of the above
+
+Three levels of the same stack (docs/PLATFORM_API_CONTRACT.md):
+    ando.query(...)          — chunks + scores, you generate
+    ando.answer(...)         — grounded synthesis over those chunks
+    ando.agentic_answer(...) — PREVIEW: the full agent loop (T1/T2/T3 +
+                               text-to-SQL over published structured
+                               sources), read-only
+
+Higher-order surfaces, all methods on the client:
+    ando.generate(...)        — render a docx/pptx/xlsx/pdf/md from your data
+                                (async; wait_for_generation + download_generation)
+    ando.cad_analyze(...) / cad_dfm_check / cad_convert / cad_find_similar
+                              — STEP/DXF analysis, DFM, conversion (async;
+                                wait_for_cad_job + get_cad_result)
+    ando.list_sources()       — what this key can query (discovery)
+    ando.get_source_schema / curate_source_schema / publish_source_schema
+                              — the structured-source K-Schema + publish gate
+    ando.create_webhook / list_webhooks / delete_webhook / test_webhook
+                              — outbound webhook endpoints
+
+    DownloadedFile    — a fetched binary artifact (content/content_type/filename,
+                        with ``.json()`` and ``.save(path)``)
+    GenerationFailed  — a generation ended ``failed`` (carries ``error_code``)
+    GenerationTimeout — ``wait_for_generation`` deadline exceeded
+
+Connector Push API (docs/PLATFORM_CONNECTOR_SDK.md):
+    AndoConnector     — batching/retrying push helper bound to one slug
+    SyncSession       — one open run; context manager, aborts on exception
+    SyncResult        — counters of a completed run
+    RecordRejected    — one refused record (absolute index, field, reason)
+    SyncAborted       — pushing into an aborted/completed run
+    list_connectors   — every connector of the project (also
+                        ``ando.connectors()`` / ``ando.connector(slug)``)
+
+Actions write-loop (the symmetric write half):
+    AndoActions       — ergonomic helper bound to a client (``ando.actions()``);
+                        ``run(...)`` proposes + executes in one call
+    declare_connector_action / list_connector_actions /
+    delete_connector_action  — the declared-action surface on a connector
+                        (``binding=`` declares the optional HTTP binding)
+    invoke_connector_action — synchronous invoke of an HTTP-bound capability
+                        (same params validation + risk gate as execute)
+    propose_action / execute_action / complete_action /
+    get_action / list_actions — the request lifecycle (also as ``ando.*``)
+    ActionBinding     — the HTTP binding shape ({method, path, body_template?,
+                        headers?, response?, timeout_seconds?})
+    ACTION_RISK_LEVELS — informational risk vocabulary (never validated
+                        client-side)
+"""
+
+from ando_ai.actions import (
+    ACTION_RISK_LEVELS,
+    ActionBinding,
+    AndoActions,
+    complete_action,
+    declare_connector_action,
+    delete_connector_action,
+    execute_action,
+    get_action,
+    invoke_connector_action,
+    list_actions,
+    list_connector_actions,
+    propose_action,
+)
+from ando_ai.client import (
+    AGENTIC_TIMEOUT,
+    DEFAULT_BASE_URL,
+    DEFAULT_K,
+    FILTER_SOURCES,
+    GENERATE_FORMATS,
+    MAX_K,
+    WEBHOOK_EVENTS,
+    AndoPlatform,
+    AndoPlatformError,
+    ApiError,
+    DownloadedFile,
+    GenerationFailed,
+    GenerationTimeout,
+    JobFailed,
+    JobTimeout,
+    NetworkError,
+)
+from ando_ai.connectors import (
+    DEFAULT_BATCH_SIZE,
+    MAX_BATCH_SIZE,
+    AndoConnector,
+    RecordRejected,
+    SyncAborted,
+    SyncResult,
+    SyncSession,
+    connector_kinds,
+    list_connectors,
+    validate_records,
+)
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "AndoPlatform",
+    "AndoPlatformError",
+    "ApiError",
+    "JobFailed",
+    "JobTimeout",
+    "GenerationFailed",
+    "GenerationTimeout",
+    "NetworkError",
+    "DownloadedFile",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_K",
+    "MAX_K",
+    "FILTER_SOURCES",
+    "GENERATE_FORMATS",
+    "WEBHOOK_EVENTS",
+    "AGENTIC_TIMEOUT",
+    "AndoConnector",
+    "SyncSession",
+    "SyncResult",
+    "RecordRejected",
+    "SyncAborted",
+    "list_connectors",
+    "connector_kinds",
+    "validate_records",
+    "DEFAULT_BATCH_SIZE",
+    "MAX_BATCH_SIZE",
+    "AndoActions",
+    "ActionBinding",
+    "ACTION_RISK_LEVELS",
+    "declare_connector_action",
+    "list_connector_actions",
+    "delete_connector_action",
+    "invoke_connector_action",
+    "propose_action",
+    "execute_action",
+    "complete_action",
+    "get_action",
+    "list_actions",
+    "__version__",
+]

ando_ai/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m ando_ai`` → the ``ando`` CLI."""
+
+from ando_ai.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ando_ai/actions.py

@@ -0,0 +1,502 @@
+"""Actions helper for the Ando Platform write-loop.
+
+The Actions API is the symmetric WRITE half of the Push API — where the
+Push API lets a connector send records IN, the Actions API lets a caller
+ask the project's own app to DO something (open a ticket, post a message,
+move a deal) and audit the outcome. Four moves, connector-agnostic and
+white-label by construction (only the developer's own slug + action names
+ever appear):
+
+  * A connector DECLARES the actions it supports —
+    ``POST /connectors/{slug}/actions`` (name + a JSON Schema of params + a
+    risk level + optionally an HTTP ``binding``). Requires ``sources:manage``.
+  * A caller PROPOSES an action — ``POST /actions`` — params validated
+    against the declared schema, persisted with a preview, NO side effect
+    yet. Requires ``actions:write``.
+  * EXECUTE — ``POST /actions/{id}/execute`` — dispatches a signed
+    ``action.requested`` webhook to the project's app. ``high``/``critical``
+    actions require ``confirm_risk``. Requires ``actions:write``.
+  * The app reports back — ``POST /actions/{id}/complete``. Requires
+    ``actions:write``.
+
+A capability declared WITH a ``binding`` (:class:`ActionBinding`) also has a
+synchronous path — ``POST /connectors/{slug}/actions/{name}/invoke``
+(:func:`invoke_connector_action`): Ando calls the bound endpoint and returns
+the outcome in one round trip, same params validation, same risk gate.
+
+Read paths (``GET /actions``, ``GET /actions/{id}``,
+``GET /connectors/{slug}/actions``) use ``actions:read``.
+
+This module is the thin, DRY glue over that surface: every call goes through
+:meth:`AndoPlatform._request`, so auth, the stable error envelope and the
+transport (including the ``MockTransport`` used in tests) have exactly ONE
+implementation. The module functions take a client as their first argument
+(mirroring :func:`ando.connectors.list_connectors`); the
+:class:`AndoActions` helper binds a client so you drop it, and adds
+:meth:`AndoActions.run` — propose + execute in one call, the write-loop's
+happy path.
+
+Usage:
+
+    from ando_ai import AndoPlatform
+
+    with AndoPlatform("ando_sk_live_...") as ando:
+        actions = ando.actions()
+        # One-time, with a sources:manage key:
+        actions.declare(
+            "acme-desk",
+            "create_ticket",
+            params_schema={
+                "type": "object",
+                "properties": {"subject": {"type": "string"}},
+                "required": ["subject"],
+            },
+            risk="medium",
+        )
+        # Per request, with an actions:write key:
+        dispatched = actions.run(
+            "acme-desk",
+            "create_ticket",
+            {"subject": "Refund request"},
+        )
+        print(dispatched["id"], dispatched["status"])  # ... "dispatched"
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, TypedDict
+
+from ando_ai.client import AndoPlatform
+
+#: Risk levels a declared action can carry, in ascending order. ``high`` and
+#: ``critical`` require ``confirm_risk`` on execute. Informational ONLY: the
+#: SDK never validates ``risk`` client-side — the server is the authority, so
+#: a server-side addition needs no SDK release (the same stance the client
+#: takes on ``k`` and ``filters.sources``).
+ACTION_RISK_LEVELS: tuple[str, ...] = ("low", "medium", "high", "critical")
+
+
+class _ActionBindingRequired(TypedDict):
+    """The required half of :class:`ActionBinding` (see there)."""
+
+    method: str
+    path: str
+
+
+class ActionBinding(_ActionBindingRequired, total=False):
+    """HTTP binding of a declared capability — how Ando calls YOUR system.
+
+    Declared alongside the action (:func:`declare_connector_action`
+    ``binding=``) and consumed by :func:`invoke_connector_action`. ``method``
+    (``POST``/``PUT``/``PATCH``/``GET``/``DELETE``) and ``path`` (relative,
+    starts with ``/``, e.g. ``"/orders"``) are required; the rest is optional:
+    ``body_template`` (a JSON object with ``{{param}}`` placeholders),
+    ``headers``, ``response`` (``{"id_field": "id"}`` — where the created
+    resource id lives in your response) and ``timeout_seconds`` (1..60).
+    A plain ``dict`` with these keys is accepted wherever an
+    :class:`ActionBinding` is — only structure is typed here, the server is
+    the authority on the exact rules (the SDK's usual stance).
+    """
+
+    body_template: Dict[str, Any]
+    headers: Dict[str, str]
+    response: Dict[str, Any]
+    timeout_seconds: int
+
+#: Header that opts a propose into idempotent replay (see :func:`propose_action`).
+_IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
+
+
+# ---------------------------------------------------------------------------
+# Action definitions (declared on a connector) — sources:manage / actions:read
+# ---------------------------------------------------------------------------
+
+
+def declare_connector_action(
+    client: AndoPlatform,
+    connector: str,
+    name: str,
+    description: Optional[str] = None,
+    params_schema: Optional[dict] = None,
+    risk: Optional[str] = None,
+    binding: Optional[ActionBinding] = None,
+) -> dict:
+    """``POST /connectors/{slug}/actions`` — declare an action (sources:manage).
+
+    Declare (or re-declare — it is idempotent on ``name``) an action the
+    connector can perform. ``params_schema`` is the JSON Schema (Draft
+    2020-12) that :func:`propose_action` validates the caller's params
+    against; omit it for an unconstrained action. ``risk`` gates the
+    confirmation: ``high``/``critical`` need ``confirm_risk`` on execute
+    (see :data:`ACTION_RISK_LEVELS`). ``binding`` is the optional HTTP
+    binding (:class:`ActionBinding` — ``{method, path, body_template?,
+    headers?, response?, timeout_seconds?}``) that lets Ando call your
+    system for this capability via :func:`invoke_connector_action`; omit it
+    for webhook-only dispatch. A declaration is a FULL replacement:
+    re-declaring without ``binding`` clears a stored one. Returns the stored
+    definition ``{connector, name, description, params_schema, risk,
+    binding, ...}``.
+
+    Optional fields travel ONLY when set, so a bare declaration puts the
+    exact same body on the wire as before they existed.
+    """
+    if not connector:
+        raise ValueError("connector is required")
+    if not name:
+        raise ValueError("name is required")
+    body: Dict[str, Any] = {"name": name}
+    if description is not None:
+        body["description"] = description
+    if params_schema is not None:
+        if not isinstance(params_schema, dict):
+            raise ValueError("params_schema must be a dict (a JSON Schema object)")
+        body["params_schema"] = params_schema
+    if risk is not None:
+        body["risk"] = risk
+    if binding is not None:
+        if not isinstance(binding, dict):
+            raise ValueError("binding must be a dict (an ActionBinding object)")
+        body["binding"] = binding
+    return client._request("POST", f"/connectors/{connector}/actions", json=body)
+
+
+def list_connector_actions(client: AndoPlatform, connector: str) -> dict:
+    """``GET /connectors/{slug}/actions`` — a connector's declared actions.
+
+    Requires ``actions:read``. Returns ``{actions: [...], count}``.
+    """
+    if not connector:
+        raise ValueError("connector is required")
+    return client._request("GET", f"/connectors/{connector}/actions")
+
+
+def delete_connector_action(
+    client: AndoPlatform, connector: str, name: str
+) -> dict:
+    """``DELETE /connectors/{slug}/actions/{name}`` — remove a declaration.
+
+    Requires ``sources:manage``. Returns ``{deleted, connector, name}``.
+    """
+    if not connector:
+        raise ValueError("connector is required")
+    if not name:
+        raise ValueError("name is required")
+    return client._request(
+        "DELETE", f"/connectors/{connector}/actions/{name}"
+    )
+
+
+def invoke_connector_action(
+    client: AndoPlatform,
+    connector: str,
+    name: str,
+    params: Optional[dict] = None,
+    *,
+    confirm_risk: bool = False,
+) -> dict:
+    """``POST /connectors/{slug}/actions/{name}/invoke`` — invoke an
+    HTTP-bound capability synchronously (actions:write).
+
+    The synchronous sibling of the propose/execute loop: Ando calls the
+    endpoint the capability's declared ``binding`` points at and returns
+    the outcome in one round trip — ``{ok, status_code, response}``.
+    ``params`` are validated against the declared ``params_schema`` (the
+    same seam propose uses).
+
+    RISK GATE — the same one execute enforces, one vocabulary, one policy:
+    a ``high``/``critical``-risk capability is REFUSED (``invalid_request``,
+    400) unless ``confirm_risk=True`` is passed explicitly. With a TEST key
+    validation and gating run for real but the bound endpoint is NEVER
+    called — the response carries ``test: true`` (the same Twilio semantics
+    as execute).
+
+    Errors: ``invalid_request`` (400 — params fail the schema, missing
+    ``confirm_risk``, or the capability declares no binding), ``not_found``
+    (404 — unknown connector or action), ``insufficient_scope`` (403).
+    """
+    if not connector:
+        raise ValueError("connector is required")
+    if not name:
+        raise ValueError("name is required")
+    body: Dict[str, Any] = {"confirm_risk": bool(confirm_risk)}
+    if params is not None:
+        if not isinstance(params, dict):
+            raise ValueError("params must be a dict")
+        body["params"] = params
+    return client._request(
+        "POST", f"/connectors/{connector}/actions/{name}/invoke", json=body
+    )
+
+
+# ---------------------------------------------------------------------------
+# Request lifecycle — actions:write (+ resource_policy) / actions:read
+# ---------------------------------------------------------------------------
+
+
+def propose_action(
+    client: AndoPlatform,
+    connector: str,
+    action: str,
+    params: Optional[dict] = None,
+    idempotency_key: Optional[str] = None,
+) -> dict:
+    """``POST /actions`` — propose an action (validate + preview, no run).
+
+    Requires ``actions:write`` AND a resource policy that allows
+    ``connector``. ``params`` are validated against the action's declared
+    schema and the request is persisted ``proposed`` with a ``preview`` —
+    nothing runs on your systems until :func:`execute_action`. Returns the
+    ``201`` request ``{id, connector, action, params, status, risk,
+    preview, ...}``.
+
+    Pass ``idempotency_key`` (opaque, <=255 chars) so a retried propose
+    (same connector + action + params) REPLAYS the first ``201`` instead of
+    creating a duplicate; reusing a key for a DIFFERENT request is a ``409``
+    (:class:`~ando_ai.client.ApiError` code ``invalid_request``).
+    Omit it and the request is sent exactly as before idempotency existed.
+    """
+    if not connector:
+        raise ValueError("connector is required")
+    if not action:
+        raise ValueError("action is required")
+    body: Dict[str, Any] = {"connector": connector, "action": action}
+    if params is not None:
+        if not isinstance(params, dict):
+            raise ValueError("params must be a dict")
+        body["params"] = params
+    if idempotency_key is not None:
+        if not isinstance(idempotency_key, str) or not idempotency_key:
+            raise ValueError("idempotency_key must be a non-empty string")
+        return client._request(
+            "POST",
+            "/actions",
+            json=body,
+            headers={_IDEMPOTENCY_KEY_HEADER: idempotency_key},
+        )
+    return client._request("POST", "/actions", json=body)
+
+
+def execute_action(
+    client: AndoPlatform, action_id: str, confirm_risk: bool = False
+) -> dict:
+    """``POST /actions/{id}/execute`` — dispatch a proposed action.
+
+    Requires ``actions:write`` AND a policy that allows the request's
+    connector. Dispatches a signed ``action.requested`` webhook to your app
+    and returns the request, now ``dispatched``. ``high``/``critical``-risk
+    actions require ``confirm_risk=True``.
+
+    If no webhook is subscribed to ``action.requested`` the call raises
+    :class:`~ando_ai.client.ApiError` (``invalid_request``) and the
+    request STAYS ``proposed`` (retryable) — register one via
+    ``POST /v1/webhooks``, then execute again.
+    """
+    if not action_id:
+        raise ValueError("action_id is required")
+    return client._request(
+        "POST",
+        f"/actions/{action_id}/execute",
+        json={"confirm_risk": bool(confirm_risk)},
+    )
+
+
+def complete_action(
+    client: AndoPlatform,
+    action_id: str,
+    status: str,
+    result: Optional[dict] = None,
+    error: Optional[str] = None,
+) -> dict:
+    """``POST /actions/{id}/complete`` — report a dispatched action's outcome.
+
+    Requires ``actions:write`` AND a policy that allows the request's
+    connector. ``status`` is ``completed`` or ``failed``; pass ``result``
+    (a free-form outcome payload) on success or ``error`` (a human-readable
+    reason) on failure. Only a ``dispatched`` request can be completed (no
+    double-completes). Returns the terminal request.
+    """
+    if not action_id:
+        raise ValueError("action_id is required")
+    if not status:
+        raise ValueError("status is required")
+    body: Dict[str, Any] = {"status": status}
+    if result is not None:
+        if not isinstance(result, dict):
+            raise ValueError("result must be a dict")
+        body["result"] = result
+    if error is not None:
+        body["error"] = error
+    return client._request(
+        "POST", f"/actions/{action_id}/complete", json=body
+    )
+
+
+def get_action(client: AndoPlatform, action_id: str) -> dict:
+    """``GET /actions/{id}`` — poll one action request (actions:read).
+
+    Returns the request with its current ``status`` (``proposed`` ->
+    ``dispatched`` -> ``completed`` | ``failed``) and detail.
+    """
+    if not action_id:
+        raise ValueError("action_id is required")
+    return client._request("GET", f"/actions/{action_id}")
+
+
+def list_actions(
+    client: AndoPlatform,
+    connector: Optional[str] = None,
+    limit: Optional[int] = None,
+    cursor: Optional[str] = None,
+) -> dict:
+    """``GET /actions`` — the project's action requests, newest first.
+
+    Requires ``actions:read``. Returns ``{actions, count, has_more,
+    next_cursor}``. Cursor-paginated: pass ``next_cursor`` back as
+    ``cursor`` until ``has_more`` is false. ``connector`` filters to one
+    slug. Params travel ONLY when set.
+    """
+    params: Dict[str, Any] = {}
+    if connector is not None:
+        params["connector"] = connector
+    if limit is not None:
+        params["limit"] = limit
+    if cursor is not None:
+        params["cursor"] = cursor
+    return client._request("GET", "/actions", params=params)
+
+
+class AndoActions:
+    """Ergonomic wrapper over the Actions write-loop, bound to one client.
+
+    Constructed by :meth:`AndoPlatform.actions` (``ando.actions()``), the
+    mirror of ``ando.connector(slug)`` for the write half: it binds the
+    client so you drop the first argument on every call, and adds
+    :meth:`run` — propose + execute in one shot.
+
+    Args:
+        client: A configured :class:`~ando_ai.client.AndoPlatform`.
+    """
+
+    def __init__(self, client: AndoPlatform) -> None:
+        self._client = client
+
+    # -- definitions (sources:manage / actions:read) ------------------------
+
+    def declare(
+        self,
+        connector: str,
+        name: str,
+        description: Optional[str] = None,
+        params_schema: Optional[dict] = None,
+        risk: Optional[str] = None,
+        binding: Optional[ActionBinding] = None,
+    ) -> dict:
+        """Declare an action on ``connector`` (:func:`declare_connector_action`)."""
+        return declare_connector_action(
+            self._client,
+            connector,
+            name,
+            description=description,
+            params_schema=params_schema,
+            risk=risk,
+            binding=binding,
+        )
+
+    def definitions(self, connector: str) -> dict:
+        """A connector's declared actions (:func:`list_connector_actions`)."""
+        return list_connector_actions(self._client, connector)
+
+    def undeclare(self, connector: str, name: str) -> dict:
+        """Remove a declaration (:func:`delete_connector_action`)."""
+        return delete_connector_action(self._client, connector, name)
+
+    def invoke(
+        self,
+        connector: str,
+        name: str,
+        params: Optional[dict] = None,
+        *,
+        confirm_risk: bool = False,
+    ) -> dict:
+        """Invoke an HTTP-bound capability (:func:`invoke_connector_action`)."""
+        return invoke_connector_action(
+            self._client,
+            connector,
+            name,
+            params=params,
+            confirm_risk=confirm_risk,
+        )
+
+    # -- request lifecycle (actions:write / actions:read) -------------------
+
+    def propose(
+        self,
+        connector: str,
+        action: str,
+        params: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> dict:
+        """Propose an action (:func:`propose_action`)."""
+        return propose_action(
+            self._client,
+            connector,
+            action,
+            params=params,
+            idempotency_key=idempotency_key,
+        )
+
+    def execute(self, action_id: str, confirm_risk: bool = False) -> dict:
+        """Dispatch a proposed action (:func:`execute_action`)."""
+        return execute_action(self._client, action_id, confirm_risk=confirm_risk)
+
+    def complete(
+        self,
+        action_id: str,
+        status: str,
+        result: Optional[dict] = None,
+        error: Optional[str] = None,
+    ) -> dict:
+        """Report a dispatched action's outcome (:func:`complete_action`)."""
+        return complete_action(
+            self._client, action_id, status, result=result, error=error
+        )
+
+    def get(self, action_id: str) -> dict:
+        """Poll one request (:func:`get_action`)."""
+        return get_action(self._client, action_id)
+
+    def list(
+        self,
+        connector: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> dict:
+        """List the project's requests (:func:`list_actions`)."""
+        return list_actions(
+            self._client, connector=connector, limit=limit, cursor=cursor
+        )
+
+    # -- happy path ---------------------------------------------------------
+
+    def run(
+        self,
+        connector: str,
+        action: str,
+        params: Optional[dict] = None,
+        confirm_risk: bool = False,
+        idempotency_key: Optional[str] = None,
+    ) -> dict:
+        """Propose then execute in one call — the write-loop's happy path.
+
+        Returns the ``dispatched`` request. The ``action.requested`` webhook
+        is now on its way to your app; the app still reports the outcome via
+        :meth:`complete` (or its own webhook handler). ``confirm_risk`` is
+        required for ``high``/``critical`` actions, exactly as on
+        :meth:`execute`. Pass ``idempotency_key`` to make the PROPOSE half
+        idempotent (a retried ``run`` with the same key replays the proposal
+        rather than duplicating it before the execute).
+        """
+        proposed = self.propose(
+            connector, action, params=params, idempotency_key=idempotency_key
+        )
+        return self.execute(proposed["id"], confirm_risk=confirm_risk)