marchward 0.1.0__py3-none-any.whl

marchward/__init__.py

@@ -0,0 +1,51 @@
+"""
+Marchward Python SDK — runtime authority for AI agents.
+
+The wedge persona builds on LangGraph/LangChain (both Python), so this is
+the primary, first-class SDK. Mirrors the `/v1/execute` contract and the
+TypeScript SDK's `execute()` surface.
+
+Quickstart
+----------
+    from marchward import MarchwardClient
+
+    tenet = MarchwardClient(api_key="tnt_...")  # or TENET_API_KEY env
+
+    decision = tenet.execute(
+        service="github",
+        tool_name="github.repos.delete",
+        arguments={"owner": "acme", "repo": "old"},
+        context={"env": "production"},
+    )
+
+    if decision.allowed:
+        ...  # safe to proceed
+    elif decision.escalated:
+        ...  # paused for human approval (decision.review_id)
+    elif decision.blocked:
+        ...  # refused by policy
+"""
+
+from .client import MarchwardClient
+from .models import Decision, Outcome
+from .errors import MarchwardError, MarchwardAuthError, MarchwardAPIError
+
+__all__ = [
+    "MarchwardClient",
+    "Decision",
+    "Outcome",
+    "MarchwardError",
+    "MarchwardAuthError",
+    "MarchwardAPIError",
+]
+
+# ── Back-compat aliases (pre-Marchward names; deprecated, kept one major cycle) ──
+# Existing `from marchward import TenetClient` (or legacy `tenet`) consumers keep working.
+TenetClient = MarchwardClient
+TenetError = MarchwardError
+TenetAuthError = MarchwardAuthError
+TenetAPIError = MarchwardAPIError
+
+__all__ += ["TenetClient", "TenetError", "TenetAuthError", "TenetAPIError"]
+
+__version__ = "0.1.0"

marchward/client.py

@@ -0,0 +1,264 @@
+"""
+MarchwardClient — the primary Python entry point.
+
+Zero runtime dependencies (stdlib urllib) so it drops into any agent
+environment without dependency conflicts. Speaks the Model-B contract:
+
+    client.execute(service="github", tool_name="github.repos.delete",
+                   arguments={"owner": "acme", "repo": "old"})
+
+You send a logical tool call (service + tool_name + arguments); Marchward
+resolves the real downstream HTTP request, governs it, injects the
+credential server-side, executes it, and returns the result. The agent
+never holds downstream credentials.
+
+Response model (matches /v1/execute):
+    403 BLOCK                 -> Decision(blocked)            [immediate]
+    202 ESCALATE + reviewId   -> Decision(escalated)          [immediate]
+    202 ALLOW  + jobId        -> poll GET /v1/jobs/:id until terminal,
+                                 then Decision(allowed) with .execution set
+    401                       -> MarchwardAuthError
+    5xx / unknown_tool etc.   -> MarchwardAPIError / surfaced on the Decision
+
+ALLOW is asynchronous server-side (Marchward fires the downstream in the
+background and hands back a jobId). By default execute() polls that job to
+completion so callers get the result synchronously; pass wait=False to get
+the pending Decision back immediately and poll yourself.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+import urllib.request
+import urllib.error
+from typing import Any
+
+from .models import Decision, Outcome
+from .errors import MarchwardAuthError, MarchwardAPIError
+
+# Identify as the Marchward SDK, not the stdlib default. urllib's default
+# `Python-urllib/3.x` User-Agent is fingerprinted and BANNED by Cloudflare's
+# browser-integrity check (returns "error code: 1010" — the request never
+# reaches the API). A normal product UA passes. This matters for real
+# customers too: agent SDKs on stdlib HTTP must not look like a bot.
+_USER_AGENT = "tenet-python-sdk/0.1"
+_DEFAULT_API_URL = "https://api.trytenet.com"
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_POLL_TIMEOUT = 120.0
+_DEFAULT_POLL_INTERVAL = 0.75
+
+
+class MarchwardClient:
+    """Client for the Marchward runtime-authority API.
+
+    Args:
+        api_key: Your tenant API key (``tnt_...``). Falls back to the
+            ``TENET_API_KEY`` env var.
+        api_url: API base URL. Falls back to ``TENET_API_URL`` env var,
+            then the production default.
+        default_agent_id: Agent identity attached to every call. Defaults
+            to ``"default"`` — the agent every tenant auto-provisions and
+            that the dashboard binds connected services to. Override only
+            if you created a differently-named agent and bound your
+            credentials to it (otherwise credential resolution won't find
+            a binding and calls return 403 credential_not_found).
+        timeout: Per-request timeout in seconds.
+        poll_timeout: Max seconds to wait for an async ALLOW job to finish.
+        poll_interval: Seconds between job polls.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        api_url: str | None = None,
+        default_agent_id: str = "default",
+        timeout: float = _DEFAULT_TIMEOUT,
+        poll_timeout: float = _DEFAULT_POLL_TIMEOUT,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+    ) -> None:
+        self.api_key = api_key or (os.environ.get("MARCHWARD_API_KEY") or os.environ.get("TENET_API_KEY"))
+        if not self.api_key:
+            raise MarchwardAuthError(
+                "No API key. Pass api_key=... or set the MARCHWARD_API_KEY (or legacy TENET_API_KEY) env var."
+            )
+        self.api_url = (api_url or (os.environ.get("MARCHWARD_API_URL") or os.environ.get("TENET_API_URL")) or _DEFAULT_API_URL).rstrip("/")
+        self.default_agent_id = default_agent_id
+        self.timeout = timeout
+        self.poll_timeout = poll_timeout
+        self.poll_interval = poll_interval
+
+    # ──────────────────────────────────────────────────────────────────
+    def execute(
+        self,
+        *,
+        service: str,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        agent_id: str | None = None,
+        request_id: str | None = None,
+        wait: bool = True,
+    ) -> Decision:
+        """Authorize + execute a tool call through Marchward (Model B).
+
+        Sends `service` + `tool_name` + `arguments`; Marchward resolves the
+        downstream call from its tool catalog. Returns a :class:`Decision`.
+        Never raises on a normal governance outcome (ALLOW/ESCALATE/BLOCK)
+        — only on auth/transport errors.
+
+        When the outcome is ALLOW, the downstream runs asynchronously
+        server-side. With ``wait=True`` (default) this polls the job to
+        completion and attaches the result to ``decision.execution``. With
+        ``wait=False`` you get the pending Decision immediately (poll the
+        job yourself via ``get_job(decision.job_id)``).
+        """
+        rid = request_id or str(uuid.uuid4())
+        body = json.dumps(
+            {
+                "requestId": rid,
+                "service": service,
+                "toolCall": {"toolName": tool_name, "arguments": arguments or {}},
+                "agent": {"agentId": agent_id or self.default_agent_id},
+                "context": context or {},
+            }
+        ).encode()
+
+        payload, status = self._post("/v1/execute", body, idempotency_key=rid)
+        decision = self._to_decision(payload, status)
+
+        # ALLOW arrives as 202 + jobId (async downstream). Poll unless the
+        # caller opted out. ESCALATE/BLOCK are terminal and have no job.
+        job_id = payload.get("jobId") if isinstance(payload, dict) else None
+        decision.job_id = job_id if isinstance(job_id, str) else None
+        if wait and decision.job_id and status == 202 and decision.allowed:
+            return self._await_job(decision)
+
+        return decision
+
+    # ──────────────────────────────────────────────────────────────────
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        """Poll a single async job once. Returns the raw job payload
+        (`status` is one of pending / running / completed / failed)."""
+        payload, _ = self._get(f"/v1/jobs/{job_id}")
+        return payload if isinstance(payload, dict) else {}
+
+    # ── Internals ──────────────────────────────────────────────────────
+    def _await_job(self, decision: Decision) -> Decision:
+        """Poll GET /v1/jobs/:id until the downstream call terminates,
+        then fold the result into the Decision."""
+        assert decision.job_id is not None
+        deadline = time.monotonic() + self.poll_timeout
+        while True:
+            payload, status = self._get(f"/v1/jobs/{decision.job_id}")
+            job_status = payload.get("status") if isinstance(payload, dict) else None
+
+            if job_status in ("completed", "failed"):
+                decision.http_status = status
+                decision.raw = payload
+                if job_status == "completed":
+                    decision.execution = payload.get("execution")
+                else:
+                    decision.execution_error = payload.get("executionError") or "downstream_failed"
+                return decision
+
+            if time.monotonic() >= deadline:
+                decision.execution_error = "poll_timeout"
+                return decision
+
+            time.sleep(self.poll_interval)
+
+    def _post(self, path: str, body: bytes, *, idempotency_key: str | None = None):
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": _USER_AGENT,
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        req = urllib.request.Request(f"{self.api_url}{path}", data=body, headers=headers, method="POST")
+        return self._send(req)
+
+    def _get(self, path: str):
+        req = urllib.request.Request(
+            f"{self.api_url}{path}",
+            headers={"Authorization": f"Bearer {self.api_key}", "User-Agent": _USER_AGENT},
+            method="GET",
+        )
+        return self._send(req)
+
+    def _send(self, req: urllib.request.Request):
+        _debug = (os.environ.get("MARCHWARD_DEBUG") or os.environ.get("TENET_DEBUG"))
+        if _debug:
+            body_preview = (req.data or b"").decode("utf-8", "replace")[:300]
+            print(f"[tenet] → {req.method} {req.full_url}")
+            print(f"[tenet]   headers: { {k: ('***' if k.lower()=='authorization' else v) for k,v in req.headers.items()} }")
+            print(f"[tenet]   body: {body_preview}")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                payload = json.loads(resp.read() or b"{}")
+                if _debug:
+                    print(f"[tenet] ← {resp.status} {json.dumps(payload)[:400]}")
+                return payload, resp.status
+        except urllib.error.HTTPError as e:
+            raw = e.read() or b"{}"
+            try:
+                payload = json.loads(raw)
+            except json.JSONDecodeError:
+                payload = {}
+            status = e.code
+            if _debug:
+                print(f"[tenet] ← {status} (raw: {raw.decode('utf-8','replace')[:400]})")
+            if status == 401:
+                raise MarchwardAuthError("Marchward rejected the API key (401).") from e
+            if status >= 500:
+                raise MarchwardAPIError(
+                    f"Marchward API error ({status}).", status=status, body=raw.decode("utf-8", "replace")
+                ) from e
+            # 4xx governance outcomes (403 BLOCK) + resolver 4xx (400
+            # unknown_tool etc.) arrive here as HTTPError; fall through so
+            # the caller sees them on the Decision rather than as an
+            # exception.
+            return payload, status
+        except urllib.error.URLError as e:
+            raise MarchwardAPIError(f"Could not reach Marchward at {self.api_url}: {e}") from e
+
+    # ──────────────────────────────────────────────────────────────────
+    @staticmethod
+    def _to_decision(payload: dict[str, Any], status: int) -> Decision:
+        # The API returns the outcome either at the top level (`decision`
+        # string + `decisionId`) or nested under `decision`; handle both.
+        decision_obj = payload.get("decision")
+        if isinstance(decision_obj, dict):
+            outcome_str = decision_obj.get("outcome") or decision_obj.get("decision")
+            decision_id = decision_obj.get("decisionId") or decision_obj.get("id")
+            review_id = decision_obj.get("reviewId")
+            reasons = decision_obj.get("reasonCodes") or decision_obj.get("reason_codes") or []
+        else:
+            outcome_str = decision_obj if isinstance(decision_obj, str) else payload.get("outcome")
+            decision_id = payload.get("decisionId")
+            review_id = payload.get("reviewId")
+            reasons = payload.get("reasonCodes") or payload.get("reason_codes") or []
+
+        try:
+            outcome = Outcome(outcome_str)
+        except (ValueError, TypeError):
+            # No recognizable outcome — infer from HTTP status as a fallback.
+            outcome = {200: Outcome.ALLOW, 202: Outcome.ESCALATE, 403: Outcome.BLOCK}.get(
+                status, Outcome.BLOCK
+            )
+
+        return Decision(
+            outcome=outcome,
+            decision_id=decision_id,
+            review_id=review_id,
+            reason_codes=list(reasons),
+            http_status=status,
+            raw=payload,
+            execution_error=(
+                payload.get("executionError") if isinstance(payload, dict) else None
+            ),
+        )

marchward/errors.py

@@ -0,0 +1,20 @@
+"""Marchward SDK exceptions."""
+
+from __future__ import annotations
+
+
+class MarchwardError(Exception):
+    """Base class for all Marchward SDK errors."""
+
+
+class MarchwardAuthError(MarchwardError):
+    """Raised on a 401 — the API key is missing, invalid, or revoked."""
+
+
+class MarchwardAPIError(MarchwardError):
+    """Raised on an unexpected API response (5xx, malformed body, etc.)."""
+
+    def __init__(self, message: str, *, status: int | None = None, body: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body

marchward/models.py

@@ -0,0 +1,69 @@
+"""Typed result objects for Marchward decisions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Outcome(str, Enum):
+    """The governance outcome for a tool call."""
+
+    ALLOW = "ALLOW"
+    ALLOW_WITH_CONDITIONS = "ALLOW_WITH_CONDITIONS"
+    ESCALATE = "ESCALATE"
+    BLOCK = "BLOCK"
+
+
+@dataclass
+class Decision:
+    """The result of a `tenet.execute()` call.
+
+    The boolean helpers (`allowed` / `escalated` / `blocked`) are the
+    ergonomic surface most agent code branches on; the raw fields are
+    there when you need them.
+    """
+
+    outcome: Outcome
+    decision_id: str | None = None
+    review_id: str | None = None
+    reason_codes: list[str] = field(default_factory=list)
+    http_status: int = 0
+    raw: dict[str, Any] = field(default_factory=dict)
+    # ── Model-B async-execute fields ────────────────────────────────────
+    # For ALLOW, the downstream runs asynchronously: `job_id` identifies the
+    # async job; after the SDK polls it to completion, `execution` holds the
+    # downstream result ({status, headers, body, durationMs}). On a failed
+    # downstream (or unmet binding / poll timeout), `execution_error` is set.
+    job_id: str | None = None
+    execution: dict[str, Any] | None = None
+    execution_error: str | None = None
+
+    # ── Ergonomic branch helpers ───────────────────────────────────────
+    @property
+    def allowed(self) -> bool:
+        return self.outcome in (Outcome.ALLOW, Outcome.ALLOW_WITH_CONDITIONS)
+
+    @property
+    def escalated(self) -> bool:
+        return self.outcome == Outcome.ESCALATE
+
+    @property
+    def blocked(self) -> bool:
+        return self.outcome == Outcome.BLOCK
+
+    @property
+    def executed(self) -> bool:
+        """True only if the downstream actually ran (ALLOW + a completed
+        execution with no error). An ALLOW with no connected credential, a
+        failed downstream, or a still-pending job is NOT executed."""
+        return self.allowed and self.execution is not None and self.execution_error is None
+
+    def __str__(self) -> str:
+        bits = [self.outcome.value]
+        if self.review_id:
+            bits.append(f"review={self.review_id}")
+        if self.reason_codes:
+            bits.append(f"reasons={','.join(self.reason_codes)}")
+        return f"Decision({' '.join(bits)})"

marchward-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: marchward
+Version: 0.1.0
+Summary: Tenet — runtime authority for AI agents. Gate every tool call through cost caps, approval gates, and a tamper-evident audit log.
+Project-URL: Homepage, https://trytenet.com
+Project-URL: Documentation, https://trytenet.com/docs
+Project-URL: Source, https://github.com/trytenet/tenet-python
+Project-URL: Changelog, https://github.com/trytenet/tenet-python/releases
+Author-email: Tenet <team@trytenet.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,cost-cap,governance,guardrails,human-in-the-loop,langchain,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Marchward — Python SDK
+
+Runtime authority for AI agents. Gate every tool call through a cost cap,
+approval gates on irreversible actions, and a tamper-evident audit log.
+
+**Python is the primary Marchward SDK** — the wedge persona builds on
+LangGraph / LangChain (both Python). Zero runtime dependencies (stdlib only).
+
+## Install
+```bash
+pip install tenet-python
+```
+
+## Quickstart
+```python
+from tenet import TenetClient
+
+tenet = TenetClient(api_key="tnt_...")   # or set TENET_API_KEY
+
+decision = tenet.execute(
+    service="github",
+    tool_name="github.repos.delete",
+    arguments={"owner": "acme", "repo": "old-experiment"},
+    context={"env": "production"},
+)
+
+if decision.allowed:
+    do_the_delete()
+elif decision.escalated:
+    print(f"Paused for approval — review {decision.review_id}")
+elif decision.blocked:
+    print(f"Blocked: {decision.reason_codes}")
+```
+
+## With LangGraph (the persona's stack)
+```python
+from langchain_core.tools import tool
+from tenet import TenetClient
+
+tenet = TenetClient()
+
+@tool
+def delete_repo(owner: str, repo: str) -> str:
+    """Delete a GitHub repository."""
+    d = tenet.execute(service="github", tool_name="github.repos.delete",
+                      arguments={"owner": owner, "repo": repo})
+    if not d.allowed:
+        return f"Refused by Marchward ({d.outcome.value})."
+    # ... real delete here ...
+    return "deleted"
+```
+
+## How it works (Model B)
+You send a logical tool call — `service` + `tool_name` + `arguments`. Marchward
+resolves the real downstream HTTP request from its tool catalog, governs it,
+injects your stored credential server-side, and executes it. Your agent holds
+only `TENET_API_KEY`; it never touches downstream credentials. Connect those
+once in the dashboard (Settings → Connected services).
+
+## API
+- `TenetClient(api_key=None, *, api_url=None, default_agent_id="python-sdk", timeout=30.0, poll_timeout=120.0, poll_interval=0.75)`
+- `.execute(*, service, tool_name, arguments=None, context=None, agent_id=None, request_id=None, wait=True) -> Decision`
+- `.get_job(job_id) -> dict` — poll one async job manually (for `wait=False`).
+- `Decision`: `.allowed` / `.escalated` / `.blocked` / `.executed`, plus `.outcome`,
+  `.decision_id`, `.review_id`, `.reason_codes`, `.http_status`, `.raw`,
+  `.job_id`, `.execution`, `.execution_error`.
+
+## Contract
+| HTTP | Outcome | Meaning |
+|---|---|---|
+| 200/202 + jobId | ALLOW | authorized; downstream runs async — the SDK polls the job and fills `.execution` (set `wait=False` to poll yourself) |
+| 202 + reviewId | ESCALATE | held for human approval; auto-executes on approve |
+| 403 | BLOCK | refused by policy |
+| 401 | — | `TenetAuthError` (bad/missing/revoked key) |
+
+`.executed` is `True` only when an ALLOW actually ran its downstream — an
+ALLOW with no connected credential, a failed downstream, or a still-pending
+job is allowed-but-not-executed.
+
+## Risk classification
+Risk is classified by the **resolved HTTP method**, not the tool name — any
+`DELETE` (or a flagged destructive `POST` like `stripe.charges.create`) is
+treated as irreversible and gated, regardless of what the tool is named. So a
+custom-named destructive tool can't slip past the approval gate.
+
+## Tests
+```bash
+cd packages/sdk-python && python -m unittest discover -s tests
+```

marchward-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+marchward/__init__.py,sha256=lfvtK8lBOx13KRNjcM2ZEhHpsWwsPgDEWTMmxRPryaE,1495
+marchward/client.py,sha256=CDn9gWhYwc3i7j4Kh8Kw8GvS0OI6rwYH3AQ60HoE31I,12330
+marchward/errors.py,sha256=lJS2Y9PqskP4uhL82hDj712Y2CSaIXe94Ce1aIAxRuY,582
+marchward/models.py,sha256=CGye295YbHDm_4e61BtAee03GLkfvxEqVzz7WXRykMI,2536
+marchward-0.1.0.dist-info/METADATA,sha256=4nbFe3bWgToCUlPyjDSZChFAJi4VecQUj4GtXXSwn7U,4463
+marchward-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+marchward-0.1.0.dist-info/licenses/LICENSE,sha256=UbfFi7BOqNW_2AixHhoot6oQ0ohuoMiA2aw0S92M8HI,1062
+marchward-0.1.0.dist-info/RECORD,,

marchward-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

marchward-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tenet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.