trustos 0.1.0__tar.gz

trustos-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,227 @@
+# 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/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=70", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trustos"
+version = "0.1.0"
+description = "Python SDK for the Trust OS Decision Verification API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Trustfolio Inc.", email = "admin@trust-os.io" }]
+requires-python = ">=3.9"
+dependencies = ["requests>=2.31.0"]
+keywords = ["trust-os", "decision-verification", "ai-agents", "fintech", "api-client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+[project.urls]
+Homepage = "https://trust-os.io"
+Documentation = "https://trust-os.io/docs"
+Source = "https://github.com/trustos-trustfolio/trustos-python-sdk"
+Issues = "https://github.com/trustos-trustfolio/trustos-python-sdk/issues"
+OpenAPI = "https://trust-os.io/openapi.json"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "responses>=0.25.0"]
+
+[tool.setuptools.packages.find]
+include = ["trustos*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

trustos-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trustos-0.1.0/tests/test_client.py

@@ -0,0 +1,165 @@
+"""Tests for TrustOSClient."""
+
+import os
+import json
+
+import pytest
+import responses as resp_mock
+
+from trustos import TrustOSClient, TrustOSError
+
+_API_KEY = "test_api_key_abc123"
+_BASE_URL = "https://trustos-core-gateway-v2-7jm9owrs.an.gateway.dev"
+_VERIFY_URL = f"{_BASE_URL}/v1/decision/verify"
+
+_MOCK_RESPONSE = {
+    "decision_id": "dec_example_001",
+    "recommendation": "APPROVE",
+    "risk_score": 0.18,
+    "risk_level": "LOW",
+    "policy": "Stablecoin Settlement Policy v1.0",
+    "proof_hash": "SHA-256: 0x4a3f...9c2b",
+    "verified": True,
+    "latency_ms": 142,
+}
+
+_PAYLOAD = {"action": "stablecoin_transfer", "amount": 50000, "currency": "USDC"}
+
+
+# ── constructor ───────────────────────────────────────────────────────────────
+
+
+def test_raises_without_api_key(monkeypatch):
+    """Client must raise ValueError when no key is available."""
+    monkeypatch.delenv("TRUSTOS_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="No API key provided"):
+        TrustOSClient()
+
+
+def test_reads_api_key_from_env(monkeypatch):
+    """Client reads API key from TRUSTOS_API_KEY env var."""
+    monkeypatch.setenv("TRUSTOS_API_KEY", _API_KEY)
+    client = TrustOSClient()
+    assert client._api_key == _API_KEY
+
+
+def test_explicit_api_key_takes_precedence(monkeypatch):
+    """Explicit api_key= overrides the environment variable."""
+    monkeypatch.setenv("TRUSTOS_API_KEY", "env_key")
+    client = TrustOSClient(api_key="explicit_key")
+    assert client._api_key == "explicit_key"
+
+
+def test_trailing_slash_removed():
+    """Trailing slashes are stripped from base_url."""
+    client = TrustOSClient(api_key=_API_KEY, base_url="https://example.com///")
+    assert client._base_url == "https://example.com"
+
+
+def test_default_base_url():
+    """Default base URL points to the production gateway."""
+    client = TrustOSClient(api_key=_API_KEY)
+    assert "trustos-core-gateway" in client._base_url
+
+
+# ── verify_decision ───────────────────────────────────────────────────────────
+
+
+@resp_mock.activate
+def test_verify_decision_posts_to_correct_url():
+    """verify_decision sends a POST to /v1/decision/verify."""
+    resp_mock.add(
+        resp_mock.POST,
+        _VERIFY_URL,
+        json=_MOCK_RESPONSE,
+        status=200,
+    )
+    client = TrustOSClient(api_key=_API_KEY)
+    result = client.verify_decision(_PAYLOAD)
+    assert result["decision_id"] == "dec_example_001"
+    assert len(resp_mock.calls) == 1
+    assert resp_mock.calls[0].request.method == "POST"
+    assert "/v1/decision/verify" in resp_mock.calls[0].request.url
+
+
+@resp_mock.activate
+def test_x_api_key_header_is_set():
+    """The x-api-key header is present on every request."""
+    resp_mock.add(resp_mock.POST, _VERIFY_URL, json=_MOCK_RESPONSE, status=200)
+    client = TrustOSClient(api_key=_API_KEY)
+    client.verify_decision(_PAYLOAD)
+    assert resp_mock.calls[0].request.headers.get("x-api-key") == _API_KEY
+
+
+@resp_mock.activate
+def test_verify_alias_calls_verify_decision():
+    """verify() is a transparent alias for verify_decision()."""
+    resp_mock.add(resp_mock.POST, _VERIFY_URL, json=_MOCK_RESPONSE, status=200)
+    client = TrustOSClient(api_key=_API_KEY)
+    result = client.verify(_PAYLOAD)
+    assert result["recommendation"] == "APPROVE"
+    assert len(resp_mock.calls) == 1
+
+
+@resp_mock.activate
+def test_non_2xx_raises_trustos_error():
+    """Non-2xx responses raise TrustOSError with the status code."""
+    resp_mock.add(
+        resp_mock.POST,
+        _VERIFY_URL,
+        json={"error": "unauthorized", "message": "Invalid API key"},
+        status=401,
+    )
+    client = TrustOSClient(api_key="bad_key")
+    with pytest.raises(TrustOSError) as exc_info:
+        client.verify_decision(_PAYLOAD)
+    assert exc_info.value.status_code == 401
+    assert "401" in str(exc_info.value)
+
+
+@resp_mock.activate
+def test_rate_limit_raises_trustos_error():
+    """429 responses raise TrustOSError."""
+    resp_mock.add(
+        resp_mock.POST,
+        _VERIFY_URL,
+        json={"error": "rate_limit_exceeded", "message": "Too many requests"},
+        status=429,
+    )
+    client = TrustOSClient(api_key=_API_KEY)
+    with pytest.raises(TrustOSError) as exc_info:
+        client.verify_decision(_PAYLOAD)
+    assert exc_info.value.status_code == 429
+
+
+@resp_mock.activate
+def test_invalid_json_raises_trustos_error():
+    """A non-JSON response body raises TrustOSError."""
+    resp_mock.add(
+        resp_mock.POST,
+        _VERIFY_URL,
+        body="not json at all",
+        status=200,
+        content_type="text/plain",
+    )
+    client = TrustOSClient(api_key=_API_KEY)
+    with pytest.raises(TrustOSError, match="Invalid JSON"):
+        client.verify_decision(_PAYLOAD)
+
+
+@resp_mock.activate
+def test_response_body_attached_on_error():
+    """TrustOSError.response_body contains the raw error text."""
+    error_body = json.dumps({"error": "internal_error", "message": "Internal server error"})
+    resp_mock.add(
+        resp_mock.POST,
+        _VERIFY_URL,
+        body=error_body,
+        status=500,
+        content_type="application/json",
+    )
+    client = TrustOSClient(api_key=_API_KEY)
+    with pytest.raises(TrustOSError) as exc_info:
+        client.verify_decision(_PAYLOAD)
+    assert exc_info.value.response_body is not None
+    assert "internal_error" in exc_info.value.response_body

trustos-0.1.0/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-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/trustos.egg-info/PKG-INFO

@@ -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/trustos.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_client.py
+trustos/__init__.py
+trustos/client.py
+trustos.egg-info/PKG-INFO
+trustos.egg-info/SOURCES.txt
+trustos.egg-info/dependency_links.txt
+trustos.egg-info/requires.txt
+trustos.egg-info/top_level.txt

trustos-0.1.0/trustos.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

trustos-0.1.0/trustos.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.31.0
+
+[dev]
+pytest>=8.0.0
+responses>=0.25.0

trustos-0.1.0/trustos.egg-info/top_level.txt

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