trustos 0.1.0__py3-none-any.whl

trustos/__init__.py

@@ -0,0 +1,6 @@
+"""Trust OS Python SDK."""
+
+from trustos.client import TrustOSClient, TrustOSError
+
+__all__ = ["TrustOSClient", "TrustOSError"]
+__version__ = "0.1.0"

trustos/client.py

@@ -0,0 +1,130 @@
+"""Trust OS Python SDK — Decision Verification API client."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import requests
+
+
+DEFAULT_BASE_URL = "https://trustos-core-gateway-v2-7jm9owrs.an.gateway.dev"
+_VERIFY_PATH = "/v1/decision/verify"
+
+
+class TrustOSError(Exception):
+    """Raised when the Trust OS API returns a non-2xx response or an
+    unexpected payload.
+
+    Attributes:
+        status_code: HTTP status code, or None for network/parse errors.
+        response_body: Raw response text, or None when unavailable.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response_body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+    def __repr__(self) -> str:
+        return (
+            f"TrustOSError(status_code={self.status_code!r}, "
+            f"message={str(self)!r})"
+        )
+
+
+class TrustOSClient:
+    """Client for the Trust OS Decision Verification API.
+
+    Args:
+        api_key: API key for authentication. If *None*, the value of the
+            ``TRUSTOS_API_KEY`` environment variable is used instead.
+        base_url: Override the API base URL. Trailing slashes are removed
+            automatically. Defaults to the production gateway.
+        timeout: Request timeout in seconds. Defaults to 10.0.
+
+    Raises:
+        ValueError: If no API key is provided and ``TRUSTOS_API_KEY`` is
+            not set in the environment.
+
+    Example::
+
+        from trustos import TrustOSClient
+
+        client = TrustOSClient(api_key="YOUR_API_KEY")
+        result = client.verify_decision({"action": "stablecoin_transfer"})
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("TRUSTOS_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "No API key provided. Pass api_key= to TrustOSClient() "
+                "or set the TRUSTOS_API_KEY environment variable."
+            )
+        self._api_key = resolved_key
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Content-Type": "application/json",
+            "x-api-key": self._api_key,
+            "User-Agent": "trustos-python-sdk/0.1.0",
+        })
+
+    def verify_decision(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Submit a decision payload for verification.
+
+        Args:
+            payload: Decision fields. ``action`` is the only required key.
+                Optional keys: ``amount``, ``currency``, ``destination``,
+                ``source``, ``priority``, ``metadata``.
+
+        Returns:
+            Parsed JSON response containing ``decision_id``,
+            ``recommendation``, ``risk_score``, ``risk_level``, ``policy``,
+            ``proof_hash``, ``verified``, and ``latency_ms``.
+
+        Raises:
+            TrustOSError: On non-2xx HTTP status or unparseable response.
+        """
+        url = f"{self._base_url}{_VERIFY_PATH}"
+        try:
+            response = self._session.post(url, json=payload, timeout=self._timeout)
+        except requests.RequestException as exc:
+            raise TrustOSError(f"Request failed: {exc}") from exc
+
+        if not response.ok:
+            try:
+                body = response.text
+            except Exception:
+                body = None
+            raise TrustOSError(
+                f"API error {response.status_code}: {response.reason}",
+                status_code=response.status_code,
+                response_body=body,
+            )
+
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise TrustOSError(
+                "Invalid JSON in API response",
+                status_code=response.status_code,
+                response_body=response.text,
+            ) from exc
+
+    def verify(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Alias for :meth:`verify_decision`."""
+        return self.verify_decision(payload)

trustos-0.1.0.dist-info/METADATA

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: trustos
+Version: 0.1.0
+Summary: Python SDK for the Trust OS Decision Verification API
+Author-email: "Trustfolio Inc." <admin@trust-os.io>
+License-Expression: MIT
+Project-URL: Homepage, https://trust-os.io
+Project-URL: Documentation, https://trust-os.io/docs
+Project-URL: Source, https://github.com/trustos-trustfolio/trustos-python-sdk
+Project-URL: Issues, https://github.com/trustos-trustfolio/trustos-python-sdk/issues
+Project-URL: OpenAPI, https://trust-os.io/openapi.json
+Keywords: trust-os,decision-verification,ai-agents,fintech,api-client
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Dynamic: license-file
+
+# Trust OS Python SDK
+
+Python SDK for the [Trust OS Decision Verification API](https://trust-os.io/docs/api).
+
+Verify high-impact decisions before execution — payments, treasury operations, AI agent actions, and compliance workflows — with a single function call.
+
+## Links
+
+| Resource | URL |
+|---|---|
+| Website | https://trust-os.io |
+| Developer Docs | https://trust-os.io/docs |
+| API Reference | https://trust-os.io/docs/api |
+| Playground | https://demo.trust-os.io |
+| Operations Demo | https://ops.trust-os.io |
+| GitHub Organization | https://github.com/trustos-trustfolio |
+| OpenAPI Spec | https://trust-os.io/openapi.json |
+
+---
+
+## Installation
+
+> **PyPI release coming soon.** For now, install directly from GitHub once the repository is published:
+
+```bash
+pip install git+https://github.com/trustos-trustfolio/trustos-python-sdk.git
+```
+
+Once published to PyPI:
+
+```bash
+pip install trustos
+```
+
+---
+
+## Quick Start
+
+```python
+from trustos import TrustOSClient
+
+client = TrustOSClient(api_key="YOUR_API_KEY")
+
+result = client.verify_decision({
+    "action": "stablecoin_transfer",
+    "amount": 50000,
+    "currency": "USDC",
+    "destination": "wallet_abc",
+})
+
+print(result["recommendation"])  # APPROVE | REVIEW | DENY
+print(result["proof_hash"])       # SHA-256: 0x4a3f...9c2b
+```
+
+---
+
+## Environment Variables
+
+Store your API key as an environment variable instead of hardcoding it:
+
+```bash
+# .env (never commit this file)
+TRUSTOS_API_KEY=your_api_key_here
+```
+
+The client reads `TRUSTOS_API_KEY` automatically when no `api_key=` argument is provided:
+
+```python
+from trustos import TrustOSClient
+
+client = TrustOSClient()  # reads TRUSTOS_API_KEY from environment
+```
+
+---
+
+## Examples
+
+### Stablecoin Payment
+
+```python
+from trustos import TrustOSClient
+
+client = TrustOSClient()
+
+result = client.verify_decision({
+    "action": "stablecoin_transfer",
+    "amount": 250000,
+    "currency": "USDC",
+    "destination": "wallet_0x4f3b9c2a8d1e6f5a",
+    "source": "Payment API",
+    "priority": "High",
+    "metadata": {"region": "SG", "workflow": "merchant_settlement"},
+})
+
+if result["recommendation"] == "APPROVE":
+    # safe to execute the transfer
+    print("Approved:", result["decision_id"])
+elif result["recommendation"] == "REVIEW":
+    # queue for human review
+    queue_for_review(result["decision_id"])
+else:
+    # block the transfer
+    raise ValueError("Payment denied by Trust OS policy")
+```
+
+### Treasury Disbursement
+
+```python
+result = client.verify_decision({
+    "action": "treasury_disbursement",
+    "amount": 1_000_000,
+    "currency": "USDC",
+    "destination": "dao_multisig_0x91a3b7c2",
+    "source": "governance-system",
+    "priority": "High",
+})
+```
+
+### AI Agent Action
+
+```python
+result = client.verify_decision({
+    "action": "execute_tool",
+    "destination": "database_write",
+    "source": "agent-framework",
+    "priority": "High",
+    "metadata": {"tool": "write_record", "agent_id": "agent_alpha_001"},
+})
+```
+
+More complete examples are in the [`examples/`](./examples/) directory.
+
+---
+
+## API Reference
+
+### `TrustOSClient(api_key=None, base_url=None, timeout=10.0)`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str \| None` | `None` | API key. Falls back to `TRUSTOS_API_KEY` env var. |
+| `base_url` | `str \| None` | Production gateway | Override the API base URL. |
+| `timeout` | `float` | `10.0` | Request timeout in seconds. |
+
+Raises `ValueError` if no API key is found.
+
+### `client.verify_decision(payload: dict) -> dict`
+
+Submit a decision for verification. Returns the parsed JSON response.
+
+**Request fields:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | string | **Yes** | Decision action type |
+| `amount` | number | No | Transaction amount |
+| `currency` | string | No | Currency or asset symbol |
+| `destination` | string | No | Target wallet or account |
+| `source` | string | No | Originating system |
+| `priority` | string | No | `"High"`, `"Medium"`, or `"Low"` |
+| `metadata` | object | No | Additional context fields |
+
+**Response fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `decision_id` | string | Unique identifier — store for audit trail |
+| `recommendation` | string | `APPROVE`, `REVIEW`, or `DENY` |
+| `risk_score` | number | 0.0 (no risk) to 1.0 (maximum) |
+| `risk_level` | string | `LOW`, `MEDIUM`, or `HIGH` |
+| `policy` | string | Policy name and version applied |
+| `proof_hash` | string | SHA-256 cryptographic proof |
+| `verified` | boolean | True when cryptographically verified |
+| `latency_ms` | number | Evaluation latency in milliseconds |
+
+### `client.verify(payload: dict) -> dict`
+
+Alias for `verify_decision()`.
+
+---
+
+## Error Handling
+
+```python
+from trustos import TrustOSClient, TrustOSError
+
+client = TrustOSClient()
+
+try:
+    result = client.verify_decision({"action": "stablecoin_transfer"})
+except TrustOSError as e:
+    print(f"Status code:   {e.status_code}")
+    print(f"Response body: {e.response_body}")
+    print(f"Message:       {e}")
+```
+
+`TrustOSError` is raised on:
+
+- Non-2xx HTTP responses (401 unauthorized, 429 rate limit, 500 server error, etc.)
+- Network errors or timeouts
+- Invalid JSON in the response body
+
+---
+
+## Security
+
+- **Never commit your API key.** Use environment variables or a secrets manager.
+- **Never hardcode keys in example scripts.** All examples use `TrustOSClient()` with no inline key.
+- See [SECURITY.md](./SECURITY.md) for the vulnerability disclosure policy.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

trustos-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+trustos/__init__.py,sha256=2ZYdVg8_zzKng45Fn3XMJiYRHAHG1EXntj_gFU_uHj4,150
+trustos/client.py,sha256=cboZ63EmpPgMenrivskhwzezLu7bL92nyFuHlhTlJ_4,4277
+trustos-0.1.0.dist-info/licenses/LICENSE,sha256=FNhLNRUeGl_PzaXQaUfYmy6KxaL19KSBDXj3v5zdglg,1083
+trustos-0.1.0.dist-info/METADATA,sha256=l7NrW0bTbVVNcausBMNT2RB378tkzj0e2h0E-3G9K_o,7251
+trustos-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+trustos-0.1.0.dist-info/top_level.txt,sha256=r5B1QqBxVi_5HaVyysYSAF77AftJEwxMGbKF_8rPYfg,8
+trustos-0.1.0.dist-info/RECORD,,

trustos-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

trustos-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trust OS / Trustfolio Inc.
+
+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.

trustos-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+trustos