truststate 0.2.0__tar.gz

truststate-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyreneBot
+
+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.

truststate-0.2.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: truststate
+Version: 0.2.0
+Summary: Python SDK for TrustState compliance validation
+License: MIT
+Project-URL: Homepage, https://trustchainlabs.com
+Project-URL: Repository, https://github.com/MyreneBot/truststate-py
+Project-URL: Bug Tracker, https://github.com/MyreneBot/truststate-py/issues
+Keywords: compliance,AI governance,truststate,audit
+Classifier: Development Status :: 3 - Alpha
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: dataclasses-json>=0.6
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# TrustState Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/truststate.svg)](https://pypi.org/project/truststate/)
+[![Python](https://img.shields.io/pypi/pyversions/truststate.svg)](https://pypi.org/project/truststate/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Python SDK for the [TrustState](https://truststate.apps.trustchainlabs.com) compliance API — validate, audit, and enforce compliance rules on any entity or data record. Built for financial services, AI governance, and regulated industries.
+
+## Install
+
+```bash
+pip install truststate
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import asyncio
+from truststate import TrustStateClient
+
+client = TrustStateClient(api_key="ts_your_api_key")
+
+async def main():
+    result = await client.check(
+        entity_type="SukukBond",
+        data={
+            "id": "BOND-001",
+            "issuerId": "ISS-001",
+            "currency": "MYR",
+            "faceValue": 5_000_000,
+            "maturityDate": "2030-06-01",
+            "status": "DRAFT",
+        },
+    )
+
+    if result.passed:
+        print(f"✅ Passed — record ID: {result.record_id}")
+    else:
+        print(f"❌ Failed — {result.fail_reason} (step {result.failed_step})")
+
+asyncio.run(main())
+```
+
+## Batch Writes
+
+Submit multiple records in a single API call. Useful for feed-based pipelines.
+
+```python
+result = await client.check_batch(
+    items=[
+        {"entity_type": "SukukBond", "data": {"id": "BOND-001", ...}},
+        {"entity_type": "SukukBond", "data": {"id": "BOND-002", ...}},
+        {"entity_type": "SukukBond", "data": {"id": "BOND-003", ...}},
+    ],
+    feed_label="core-banking-feed",   # echoed on every item result
+)
+
+print(f"Accepted: {result.accepted}/{result.total}")
+for item in result.results:
+    print(f"  {item.entity_id}: {'✅' if item.passed else '❌'} {item.feed_label}")
+```
+
+## BYOP Evidence (Oracle Data)
+
+Attach oracle evidence to compliance checks — FX rates, KYC status, credit scores, sanctions screening.
+
+```python
+# Fetch evidence from registered oracle providers
+fx    = await client.fetch_fx_rate("MYR", "USD")
+kyc   = await client.fetch_kyc_status("actor-jasim")
+score = await client.fetch_credit_score("actor-jasim")
+
+# Submit with evidence attached
+result = await client.check_with_evidence(
+    entity_type="SukukBond",
+    data={"id": "BOND-001", "issuerId": "ISS-001", "currency": "MYR", "faceValue": 5_000_000},
+    evidence=[fx, kyc, score],
+)
+```
+
+## Mock Mode
+
+Test without making any API calls. Useful for unit tests and local development.
+
+```python
+client = TrustStateClient(
+    api_key="any",
+    mock=True,
+    mock_pass_rate=0.8,   # 80% of checks will pass
+)
+
+result = await client.check("SukukBond", {"id": "TEST-001", ...})
+print(result.mock)   # True
+```
+
+## Django / FastAPI Middleware
+
+Automatically validate every incoming request body against TrustState policies.
+
+```python
+# FastAPI
+from truststate import TrustStateMiddleware
+
+app.add_middleware(
+    TrustStateMiddleware,
+    api_key="ts_your_api_key",
+    entity_type="AgentResponse",
+)
+
+# Django
+MIDDLEWARE = [
+    "truststate.middleware.TrustStateMiddleware",
+    ...
+]
+TRUSTSTATE_API_KEY = "ts_your_api_key"
+TRUSTSTATE_ENTITY_TYPE = "AgentResponse"
+```
+
+## `@compliant` Decorator
+
+Wrap any async function to automatically submit its return value for compliance checking.
+
+```python
+from truststate import compliant, TrustStateClient
+
+client = TrustStateClient(api_key="ts_your_api_key")
+
+@compliant(client=client, entity_type="AgentResponse")
+async def generate_response(prompt: str) -> dict:
+    return {"text": "Hello!", "score": 0.95}
+
+result = await generate_response("What is TrustState?")
+# result is a ComplianceResult — .passed, .record_id, etc.
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str` | required | Your TrustState API key |
+| `base_url` | `str` | production URL | Override the API base URL |
+| `default_schema_version` | `str \| None` | `None` | Schema version (auto-resolved if omitted) |
+| `default_actor_id` | `str` | `""` | Actor ID for the audit trail |
+| `mock` | `bool` | `False` | Enable mock mode (no HTTP calls) |
+| `mock_pass_rate` | `float` | `1.0` | Pass probability in mock mode (0.0–1.0) |
+| `timeout` | `int` | `30` | HTTP timeout in seconds |
+
+## API Reference
+
+### `check(entity_type, data, *, action, entity_id, schema_version, actor_id)`
+
+Submit a single record for compliance checking.
+
+Returns: `ComplianceResult`
+
+### `check_batch(items, *, default_schema_version, default_actor_id, feed_label)`
+
+Submit up to 500 records in a single call.
+
+Returns: `BatchResult`
+
+### `check_with_evidence(entity_type, data, evidence, *, action, entity_id, schema_version, actor_id)`
+
+Submit a record with oracle evidence attached.
+
+Returns: `ComplianceResult`
+
+### `fetch_fx_rate(from_currency, to_currency, *, provider_id, max_age_seconds)`
+### `fetch_kyc_status(subject_id, *, provider_id, max_age_seconds)`
+### `fetch_credit_score(subject_id, *, provider_id, max_age_seconds)`
+### `fetch_sanctions(subject_id, *, provider_id, max_age_seconds)`
+
+Fetch oracle evidence items from registered providers.
+
+Returns: `EvidenceItem`
+
+### `verify(record_id, bearer_token)`
+
+Retrieve an immutable compliance record from the ledger.
+
+Returns: `dict`
+
+## ComplianceResult
+
+| Field | Type | Description |
+|---|---|---|
+| `passed` | `bool` | True if all checks passed |
+| `record_id` | `str \| None` | Immutable ledger record ID (only when passed) |
+| `request_id` | `str` | Unique API request ID |
+| `entity_id` | `str` | Entity ID that was submitted |
+| `fail_reason` | `str \| None` | Human-readable failure reason |
+| `failed_step` | `int \| None` | Step that failed (8=schema, 9=policy) |
+| `feed_label` | `str \| None` | Feed label from batch request |
+| `mock` | `bool` | True if synthesised in mock mode |
+
+## Requirements
+
+- Python 3.9+
+- `httpx>=0.27`
+
+## License
+
+MIT © Trustchain Labs

truststate-0.2.0/README.md

@@ -0,0 +1,205 @@
+# TrustState Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/truststate.svg)](https://pypi.org/project/truststate/)
+[![Python](https://img.shields.io/pypi/pyversions/truststate.svg)](https://pypi.org/project/truststate/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Python SDK for the [TrustState](https://truststate.apps.trustchainlabs.com) compliance API — validate, audit, and enforce compliance rules on any entity or data record. Built for financial services, AI governance, and regulated industries.
+
+## Install
+
+```bash
+pip install truststate
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+import asyncio
+from truststate import TrustStateClient
+
+client = TrustStateClient(api_key="ts_your_api_key")
+
+async def main():
+    result = await client.check(
+        entity_type="SukukBond",
+        data={
+            "id": "BOND-001",
+            "issuerId": "ISS-001",
+            "currency": "MYR",
+            "faceValue": 5_000_000,
+            "maturityDate": "2030-06-01",
+            "status": "DRAFT",
+        },
+    )
+
+    if result.passed:
+        print(f"✅ Passed — record ID: {result.record_id}")
+    else:
+        print(f"❌ Failed — {result.fail_reason} (step {result.failed_step})")
+
+asyncio.run(main())
+```
+
+## Batch Writes
+
+Submit multiple records in a single API call. Useful for feed-based pipelines.
+
+```python
+result = await client.check_batch(
+    items=[
+        {"entity_type": "SukukBond", "data": {"id": "BOND-001", ...}},
+        {"entity_type": "SukukBond", "data": {"id": "BOND-002", ...}},
+        {"entity_type": "SukukBond", "data": {"id": "BOND-003", ...}},
+    ],
+    feed_label="core-banking-feed",   # echoed on every item result
+)
+
+print(f"Accepted: {result.accepted}/{result.total}")
+for item in result.results:
+    print(f"  {item.entity_id}: {'✅' if item.passed else '❌'} {item.feed_label}")
+```
+
+## BYOP Evidence (Oracle Data)
+
+Attach oracle evidence to compliance checks — FX rates, KYC status, credit scores, sanctions screening.
+
+```python
+# Fetch evidence from registered oracle providers
+fx    = await client.fetch_fx_rate("MYR", "USD")
+kyc   = await client.fetch_kyc_status("actor-jasim")
+score = await client.fetch_credit_score("actor-jasim")
+
+# Submit with evidence attached
+result = await client.check_with_evidence(
+    entity_type="SukukBond",
+    data={"id": "BOND-001", "issuerId": "ISS-001", "currency": "MYR", "faceValue": 5_000_000},
+    evidence=[fx, kyc, score],
+)
+```
+
+## Mock Mode
+
+Test without making any API calls. Useful for unit tests and local development.
+
+```python
+client = TrustStateClient(
+    api_key="any",
+    mock=True,
+    mock_pass_rate=0.8,   # 80% of checks will pass
+)
+
+result = await client.check("SukukBond", {"id": "TEST-001", ...})
+print(result.mock)   # True
+```
+
+## Django / FastAPI Middleware
+
+Automatically validate every incoming request body against TrustState policies.
+
+```python
+# FastAPI
+from truststate import TrustStateMiddleware
+
+app.add_middleware(
+    TrustStateMiddleware,
+    api_key="ts_your_api_key",
+    entity_type="AgentResponse",
+)
+
+# Django
+MIDDLEWARE = [
+    "truststate.middleware.TrustStateMiddleware",
+    ...
+]
+TRUSTSTATE_API_KEY = "ts_your_api_key"
+TRUSTSTATE_ENTITY_TYPE = "AgentResponse"
+```
+
+## `@compliant` Decorator
+
+Wrap any async function to automatically submit its return value for compliance checking.
+
+```python
+from truststate import compliant, TrustStateClient
+
+client = TrustStateClient(api_key="ts_your_api_key")
+
+@compliant(client=client, entity_type="AgentResponse")
+async def generate_response(prompt: str) -> dict:
+    return {"text": "Hello!", "score": 0.95}
+
+result = await generate_response("What is TrustState?")
+# result is a ComplianceResult — .passed, .record_id, etc.
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | `str` | required | Your TrustState API key |
+| `base_url` | `str` | production URL | Override the API base URL |
+| `default_schema_version` | `str \| None` | `None` | Schema version (auto-resolved if omitted) |
+| `default_actor_id` | `str` | `""` | Actor ID for the audit trail |
+| `mock` | `bool` | `False` | Enable mock mode (no HTTP calls) |
+| `mock_pass_rate` | `float` | `1.0` | Pass probability in mock mode (0.0–1.0) |
+| `timeout` | `int` | `30` | HTTP timeout in seconds |
+
+## API Reference
+
+### `check(entity_type, data, *, action, entity_id, schema_version, actor_id)`
+
+Submit a single record for compliance checking.
+
+Returns: `ComplianceResult`
+
+### `check_batch(items, *, default_schema_version, default_actor_id, feed_label)`
+
+Submit up to 500 records in a single call.
+
+Returns: `BatchResult`
+
+### `check_with_evidence(entity_type, data, evidence, *, action, entity_id, schema_version, actor_id)`
+
+Submit a record with oracle evidence attached.
+
+Returns: `ComplianceResult`
+
+### `fetch_fx_rate(from_currency, to_currency, *, provider_id, max_age_seconds)`
+### `fetch_kyc_status(subject_id, *, provider_id, max_age_seconds)`
+### `fetch_credit_score(subject_id, *, provider_id, max_age_seconds)`
+### `fetch_sanctions(subject_id, *, provider_id, max_age_seconds)`
+
+Fetch oracle evidence items from registered providers.
+
+Returns: `EvidenceItem`
+
+### `verify(record_id, bearer_token)`
+
+Retrieve an immutable compliance record from the ledger.
+
+Returns: `dict`
+
+## ComplianceResult
+
+| Field | Type | Description |
+|---|---|---|
+| `passed` | `bool` | True if all checks passed |
+| `record_id` | `str \| None` | Immutable ledger record ID (only when passed) |
+| `request_id` | `str` | Unique API request ID |
+| `entity_id` | `str` | Entity ID that was submitted |
+| `fail_reason` | `str \| None` | Human-readable failure reason |
+| `failed_step` | `int \| None` | Step that failed (8=schema, 9=policy) |
+| `feed_label` | `str \| None` | Feed label from batch request |
+| `mock` | `bool` | True if synthesised in mock mode |
+
+## Requirements
+
+- Python 3.9+
+- `httpx>=0.27`
+
+## License
+
+MIT © Trustchain Labs

truststate-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "truststate"
+version = "0.2.0"
+description = "Python SDK for TrustState compliance validation"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["compliance", "AI governance", "truststate", "audit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+]
+dependencies = [
+    "httpx>=0.27",
+    "dataclasses-json>=0.6",
+]
+
+[project.optional-dependencies]
+fastapi = ["starlette>=0.27"]
+dev = ["pytest>=7", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://trustchainlabs.com"
+Repository = "https://github.com/MyreneBot/truststate-py"
+"Bug Tracker" = "https://github.com/MyreneBot/truststate-py/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["truststate*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

truststate-0.2.0/setup.cfg

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

truststate-0.2.0/tests/test_client.py

@@ -0,0 +1,181 @@
+"""Unit tests for TrustStateClient.
+
+Run with: pytest tests/test_client.py -v
+"""
+
+from __future__ import annotations
+
+import asyncio
+import pytest
+from truststate import TrustStateClient
+from truststate.types import ComplianceResult, BatchResult
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def run(coro):
+    """Run a coroutine in a new event loop (compatibility helper)."""
+    return asyncio.get_event_loop().run_until_complete(coro)
+
+
+def make_mock_client(mock_pass_rate: float = 1.0) -> TrustStateClient:
+    return TrustStateClient(
+        api_key="test-key",
+        mock=True,
+        mock_pass_rate=mock_pass_rate,
+    )
+
+
+SAMPLE_DATA = {"responseText": "Hello", "confidenceScore": 0.9}
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestMockMode:
+    """Tests that run entirely in mock mode — no network calls required."""
+
+    def test_check_passes_in_mock_mode(self):
+        """check() returns a passing ComplianceResult when mock_pass_rate=1.0."""
+        client = make_mock_client(mock_pass_rate=1.0)
+        result = run(client.check("AgentResponse", SAMPLE_DATA))
+
+        assert isinstance(result, ComplianceResult)
+        assert result.passed is True
+        assert result.record_id is not None
+        assert result.record_id.startswith("mock-rec-")
+        assert result.fail_reason is None
+        assert result.failed_step is None
+        assert result.mock is True
+
+    def test_check_batch_in_mock_mode(self):
+        """check_batch() returns a BatchResult with mock=True for all results."""
+        client = make_mock_client(mock_pass_rate=1.0)
+        items = [
+            {"entity_type": "Tx", "data": {"amount": 100}},
+            {"entity_type": "Tx", "data": {"amount": 200}},
+            {"entity_type": "Tx", "data": {"amount": 300}},
+        ]
+        batch = run(client.check_batch(items))
+
+        assert isinstance(batch, BatchResult)
+        assert batch.total == 3
+        assert batch.accepted == 3
+        assert batch.rejected == 0
+        assert len(batch.results) == 3
+        assert batch.mock is True
+        assert all(r.mock for r in batch.results)
+        assert all(r.passed for r in batch.results)
+
+    def test_mock_pass_rate_zero_always_fails(self):
+        """mock_pass_rate=0.0 means every check() call returns passed=False."""
+        client = make_mock_client(mock_pass_rate=0.0)
+
+        # Run multiple times to confirm it is deterministic at 0.0
+        for _ in range(10):
+            result = run(client.check("AgentResponse", SAMPLE_DATA))
+            assert result.passed is False
+            assert result.record_id is None
+            assert result.fail_reason is not None
+            assert result.failed_step == 9
+            assert result.mock is True
+
+    def test_entity_id_auto_generated(self):
+        """check() generates a unique entity_id when none is provided."""
+        client = make_mock_client()
+        result1 = run(client.check("AgentResponse", SAMPLE_DATA))
+        result2 = run(client.check("AgentResponse", SAMPLE_DATA))
+
+        # Both should have non-empty entity IDs
+        assert result1.entity_id
+        assert result2.entity_id
+        # They should be different (uuid4 generated)
+        assert result1.entity_id != result2.entity_id
+
+    def test_entity_id_preserved_when_provided(self):
+        """check() preserves a caller-supplied entity_id."""
+        client = make_mock_client()
+        my_id = "my-stable-entity-id-123"
+        result = run(client.check("AgentResponse", SAMPLE_DATA, entity_id=my_id))
+
+        assert result.entity_id == my_id
+
+    def test_batch_partial_pass(self):
+        """With mixed pass rate, accepted + rejected == total."""
+        import random
+        random.seed(42)  # deterministic for the test
+        client = make_mock_client(mock_pass_rate=0.5)
+        items = [{"entity_type": "X", "data": {"v": i}} for i in range(20)]
+        batch = run(client.check_batch(items))
+
+        assert batch.total == 20
+        assert batch.accepted + batch.rejected == batch.total
+        assert len(batch.results) == 20
+
+    def test_check_batch_auto_generates_entity_ids(self):
+        """check_batch() auto-generates entity_id for items that omit it."""
+        client = make_mock_client()
+        items = [
+            {"entity_type": "T", "data": {"x": 1}},  # no entity_id
+            {"entity_type": "T", "data": {"x": 2}, "entity_id": "explicit-id"},
+        ]
+        batch = run(client.check_batch(items))
+
+        assert batch.results[0].entity_id  # auto-generated, non-empty
+        assert batch.results[1].entity_id == "explicit-id"
+
+
+class TestErrorHandling:
+    """Tests for TrustStateError and validation."""
+
+    def test_trust_state_error_attributes(self):
+        """TrustStateError carries message and status_code."""
+        from truststate.exceptions import TrustStateError
+        err = TrustStateError("something broke", 422)
+        assert err.message == "something broke"
+        assert err.status_code == 422
+        assert "422" in repr(err)
+
+    def test_compliant_decorator_raises_on_fail(self):
+        """@compliant with on_fail='raise' raises TrustStateError when check fails."""
+        from truststate import compliant
+        from truststate.exceptions import TrustStateError
+
+        client = make_mock_client(mock_pass_rate=0.0)
+
+        @compliant(client, entity_type="Test", on_fail="raise")
+        async def my_fn():
+            return {"value": 1}
+
+        with pytest.raises(TrustStateError):
+            run(my_fn())
+
+    def test_compliant_decorator_returns_none_on_fail(self):
+        """@compliant with on_fail='return_none' returns None when check fails."""
+        from truststate import compliant
+
+        client = make_mock_client(mock_pass_rate=0.0)
+
+        @compliant(client, entity_type="Test", on_fail="return_none")
+        async def my_fn():
+            return {"value": 1}
+
+        result = run(my_fn())
+        assert result is None
+
+    def test_compliant_passes_through_value_on_success(self):
+        """@compliant returns the original value when check passes."""
+        from truststate import compliant
+
+        client = make_mock_client(mock_pass_rate=1.0)
+        expected = {"responseText": "hi", "confidenceScore": 0.9}
+
+        @compliant(client, entity_type="Test", on_fail="raise")
+        async def my_fn():
+            return expected
+
+        result = run(my_fn())
+        assert result == expected