sonic-sdk 0.1.0__tar.gz

sonic_sdk-0.1.0/INSTALL.md

@@ -0,0 +1,195 @@
+# Sonic SDK Installation Guide
+
+| Package | Description | Version |
+|---------|-------------|---------|
+| **sonic-sdk** | Multi-currency settlement engine with cryptographic receipt attestation | 0.1.0 |
+
+---
+
+## Prerequisites
+
+- Python 3.10+
+- GitHub access to `ToweraiDev/sonic-pay` (private repo)
+- One of: SSH key linked to GitHub, or a GitHub Personal Access Token (PAT)
+
+---
+
+## Install via SSH (recommended)
+
+If you have SSH keys configured with GitHub:
+
+```bash
+pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
+```
+
+With optional extras:
+
+```bash
+# Database support (SQLAlchemy, asyncpg, Alembic)
+pip install "sonic-sdk[db] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
+
+# Redis support
+pip install "sonic-sdk[redis] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
+
+# Everything
+pip install "sonic-sdk[all] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
+```
+
+## Install via Personal Access Token
+
+For CI/CD pipelines or machines without SSH:
+
+```bash
+# Create a PAT at https://github.com/settings/tokens
+# Classic: needs `repo` scope
+# Fine-grained: needs "Contents" read access to ToweraiDev/sonic-pay
+
+export GH_TOKEN=ghp_xxxxxxxxxxxx
+
+pip install "sonic-sdk @ git+https://${GH_TOKEN}@github.com/ToweraiDev/sonic-pay.git"
+```
+
+## Install via GitHub CLI
+
+If you have `gh` authenticated:
+
+```bash
+pip install "sonic-sdk @ git+https://$(gh auth token)@github.com/ToweraiDev/sonic-pay.git"
+```
+
+---
+
+## Adding to your project
+
+### requirements.txt
+
+```
+sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git
+```
+
+Or with extras:
+
+```
+sonic-sdk[all] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git
+```
+
+### pyproject.toml (pip/setuptools)
+
+```toml
+[project]
+dependencies = [
+    "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git",
+]
+```
+
+### pyproject.toml (Poetry)
+
+```toml
+[tool.poetry.dependencies]
+sonic-sdk = {git = "ssh://git@github.com/ToweraiDev/sonic-pay.git"}
+```
+
+---
+
+## Pin to a specific commit or tag
+
+Append `@<ref>` to pin a version:
+
+```bash
+# Pin to a commit
+pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git@abc1234"
+
+# Pin to a tag
+pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git@v0.1.0"
+```
+
+---
+
+## Local development
+
+Clone and install in editable mode:
+
+```bash
+git clone git@github.com:ToweraiDev/sonic-pay.git
+cd sonic-pay
+python -m venv .venv
+source .venv/bin/activate        # Linux/macOS
+# .venv\Scripts\activate         # Windows
+
+pip install -r requirements.txt  # installs -e .[all,dev]
+```
+
+---
+
+## Quick Start
+
+```python
+from sonic import Transaction, TxState, SonicReceipt, SbnClient
+
+# Build a transaction through the state machine
+tx = Transaction(tx_id="tx-001", merchant_id="m-acme")
+event = tx.advance(TxState.RECEIVABLE_DETECTED, amount=100.00, currency="USD")
+
+# Seal receipt to SBN for tamper-evident attestation
+sbn = SbnClient(api_key="sbn_live_...")
+sbn_hash = sbn.seal({"receipt_hash": event.receipt_hash})
+```
+
+### Core modules
+
+```python
+from sonic.core.engine import Transaction, TxState, TxEvent, InvalidTransition
+from sonic.core.receipt_builder import SonicReceipt, ReceiptChain, canonical_hash
+from sonic.core.finality_gate import FinalityGate, FinalityPolicy, FinalityStatus
+from sonic.core.treasury import Treasury, ConversionQuote
+from sonic.core.payout_executor import PayoutExecutor, PayoutInstruction, PayoutResult
+from sonic.events.types import EventType
+from sonic.events.emitter import EventEmitter
+from sonic.sbn import SbnClient, SbnAttester, ReceiptCoupler
+from sonic.sbn.frontier import SONIC_FRONTIER
+from sonic.config import SonicSettings, settings
+```
+
+### Vendored SDKs
+
+`sonic-sdk` vendors `sbn-sdk`, `snapchore-core`, and `dominion-sdk` — no separate
+install needed.
+
+```python
+# Dominion payroll client (re-exported at top level)
+from sonic import DominionSbnClient, DominionSonicClient
+
+# Direct access to vendored packages
+from sonic._vendor.sbn import SbnClient as RawSbnClient, SlotSummary
+from sonic._vendor.snapchore import SmartBlock, SnapChoreChain, snapchore_capture
+from sonic._vendor.dominion import DominionSbnClient, DominionSonicClient
+```
+
+---
+
+## Optional Extras
+
+| Extra | Packages | Use case |
+|-------|----------|----------|
+| `db` | sqlalchemy, asyncpg, alembic | Postgres persistence |
+| `redis` | redis | Event bus / attestation queue |
+| `server` | fastapi, uvicorn, psycopg2, python-jose | Running the Sonic HTTP API server |
+| `all` | db + redis | Everything (without server) |
+| `dev` | pytest, pytest-asyncio, ruff, mypy, python-dotenv | Development & testing |
+
+---
+
+## Dependencies
+
+### Core (always installed)
+
+- `httpx` >= 0.27.0
+- `cryptography` >= 42.0
+- `pydantic` >= 2.5
+- `pydantic-settings` >= 2.1
+
+### Vendored (included in package — no separate install)
+
+- `sbn-sdk` 0.2.0 — SmartBlocks Network client
+- `snapchore-core` 0.1.0 — Cryptographic integrity for stateful events
+- `dominion-sdk` 0.1.0 — Sovereign Compression Payroll Router

sonic_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: sonic-sdk
+Version: 0.1.0
+Summary: Multi-currency settlement engine with cryptographic receipt attestation for the SmartBlocks Network.
+Author-email: Tower Technologies <dev@towerai.dev>
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/ToweraiDev/sonic-pay
+Keywords: sonic,settlement,smartblocks,sbn,snapchore,gec,payments
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: cryptography>=42.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pydantic-settings>=2.1
+Provides-Extra: db
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == "db"
+Requires-Dist: asyncpg>=0.29.0; extra == "db"
+Requires-Dist: alembic>=1.13.0; extra == "db"
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == "redis"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.109; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.27; extra == "server"
+Requires-Dist: psycopg2-binary>=2.9; extra == "server"
+Requires-Dist: python-jose[cryptography]>=3.3; extra == "server"
+Provides-Extra: all
+Requires-Dist: sonic-sdk[db,redis]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.2; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
+
+# Sonic SDK Installation Guide
+
+| Package | Description | Version |
+|---------|-------------|---------|
+| **sonic-sdk** | Multi-currency settlement engine with cryptographic receipt attestation | 0.1.0 |
+
+---
+
+## Prerequisites
+
+- Python 3.10+
+- GitHub access to `ToweraiDev/sonic-pay` (private repo)
+- One of: SSH key linked to GitHub, or a GitHub Personal Access Token (PAT)
+
+---
+
+## Install via SSH (recommended)
+
+If you have SSH keys configured with GitHub:
+
+```bash
+pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
+```
+
+With optional extras:
+
+```bash
+# Database support (SQLAlchemy, asyncpg, Alembic)
+pip install "sonic-sdk[db] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
+
+# Redis support
+pip install "sonic-sdk[redis] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
+
+# Everything
+pip install "sonic-sdk[all] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
+```
+
+## Install via Personal Access Token
+
+For CI/CD pipelines or machines without SSH:
+
+```bash
+# Create a PAT at https://github.com/settings/tokens
+# Classic: needs `repo` scope
+# Fine-grained: needs "Contents" read access to ToweraiDev/sonic-pay
+
+export GH_TOKEN=ghp_xxxxxxxxxxxx
+
+pip install "sonic-sdk @ git+https://${GH_TOKEN}@github.com/ToweraiDev/sonic-pay.git"
+```
+
+## Install via GitHub CLI
+
+If you have `gh` authenticated:
+
+```bash
+pip install "sonic-sdk @ git+https://$(gh auth token)@github.com/ToweraiDev/sonic-pay.git"
+```
+
+---
+
+## Adding to your project
+
+### requirements.txt
+
+```
+sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git
+```
+
+Or with extras:
+
+```
+sonic-sdk[all] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git
+```
+
+### pyproject.toml (pip/setuptools)
+
+```toml
+[project]
+dependencies = [
+    "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git",
+]
+```
+
+### pyproject.toml (Poetry)
+
+```toml
+[tool.poetry.dependencies]
+sonic-sdk = {git = "ssh://git@github.com/ToweraiDev/sonic-pay.git"}
+```
+
+---
+
+## Pin to a specific commit or tag
+
+Append `@<ref>` to pin a version:
+
+```bash
+# Pin to a commit
+pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git@abc1234"
+
+# Pin to a tag
+pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git@v0.1.0"
+```
+
+---
+
+## Local development
+
+Clone and install in editable mode:
+
+```bash
+git clone git@github.com:ToweraiDev/sonic-pay.git
+cd sonic-pay
+python -m venv .venv
+source .venv/bin/activate        # Linux/macOS
+# .venv\Scripts\activate         # Windows
+
+pip install -r requirements.txt  # installs -e .[all,dev]
+```
+
+---
+
+## Quick Start
+
+```python
+from sonic import Transaction, TxState, SonicReceipt, SbnClient
+
+# Build a transaction through the state machine
+tx = Transaction(tx_id="tx-001", merchant_id="m-acme")
+event = tx.advance(TxState.RECEIVABLE_DETECTED, amount=100.00, currency="USD")
+
+# Seal receipt to SBN for tamper-evident attestation
+sbn = SbnClient(api_key="sbn_live_...")
+sbn_hash = sbn.seal({"receipt_hash": event.receipt_hash})
+```
+
+### Core modules
+
+```python
+from sonic.core.engine import Transaction, TxState, TxEvent, InvalidTransition
+from sonic.core.receipt_builder import SonicReceipt, ReceiptChain, canonical_hash
+from sonic.core.finality_gate import FinalityGate, FinalityPolicy, FinalityStatus
+from sonic.core.treasury import Treasury, ConversionQuote
+from sonic.core.payout_executor import PayoutExecutor, PayoutInstruction, PayoutResult
+from sonic.events.types import EventType
+from sonic.events.emitter import EventEmitter
+from sonic.sbn import SbnClient, SbnAttester, ReceiptCoupler
+from sonic.sbn.frontier import SONIC_FRONTIER
+from sonic.config import SonicSettings, settings
+```
+
+### Vendored SDKs
+
+`sonic-sdk` vendors `sbn-sdk`, `snapchore-core`, and `dominion-sdk` — no separate
+install needed.
+
+```python
+# Dominion payroll client (re-exported at top level)
+from sonic import DominionSbnClient, DominionSonicClient
+
+# Direct access to vendored packages
+from sonic._vendor.sbn import SbnClient as RawSbnClient, SlotSummary
+from sonic._vendor.snapchore import SmartBlock, SnapChoreChain, snapchore_capture
+from sonic._vendor.dominion import DominionSbnClient, DominionSonicClient
+```
+
+---
+
+## Optional Extras
+
+| Extra | Packages | Use case |
+|-------|----------|----------|
+| `db` | sqlalchemy, asyncpg, alembic | Postgres persistence |
+| `redis` | redis | Event bus / attestation queue |
+| `server` | fastapi, uvicorn, psycopg2, python-jose | Running the Sonic HTTP API server |
+| `all` | db + redis | Everything (without server) |
+| `dev` | pytest, pytest-asyncio, ruff, mypy, python-dotenv | Development & testing |
+
+---
+
+## Dependencies
+
+### Core (always installed)
+
+- `httpx` >= 0.27.0
+- `cryptography` >= 42.0
+- `pydantic` >= 2.5
+- `pydantic-settings` >= 2.1
+
+### Vendored (included in package — no separate install)
+
+- `sbn-sdk` 0.2.0 — SmartBlocks Network client
+- `snapchore-core` 0.1.0 — Cryptographic integrity for stateful events
+- `dominion-sdk` 0.1.0 — Sovereign Compression Payroll Router

sonic_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "sonic-sdk"
+version = "0.1.0"
+description = "Multi-currency settlement engine with cryptographic receipt attestation for the SmartBlocks Network."
+readme = "INSTALL.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    { name = "Tower Technologies", email = "dev@towerai.dev" },
+]
+keywords = ["sonic", "settlement", "smartblocks", "sbn", "snapchore", "gec", "payments"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "httpx>=0.27.0",
+    "cryptography>=42.0",
+    "pydantic>=2.5",
+    "pydantic-settings>=2.1",
+]
+
+[project.optional-dependencies]
+db = [
+    "sqlalchemy[asyncio]>=2.0.0",
+    "asyncpg>=0.29.0",
+    "alembic>=1.13.0",
+]
+redis = [
+    "redis>=5.0.0",
+]
+server = [
+    "fastapi>=0.109",
+    "uvicorn[standard]>=0.27",
+    "psycopg2-binary>=2.9",
+    "python-jose[cryptography]>=3.3",
+]
+all = [
+    "sonic-sdk[db,redis]",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1",
+    "ruff>=0.2",
+    "mypy>=1.8",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/ToweraiDev/sonic-pay"
+
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sonic*"]
+exclude = ["stillpoint-nested-dev-context*", "tower-agent-nested-dev-context*", "tests*", "alembic*"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

sonic_sdk-0.1.0/setup.cfg

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

sonic_sdk-0.1.0/sonic/__init__.py

@@ -0,0 +1,112 @@
+"""Sonic — Multi-currency settlement engine with cryptographic receipt attestation.
+
+Sonic is a settlement engine that processes multi-currency payments with
+cryptographic receipt chains and optional SBN (SmartBlocks Network)
+attestation.  Every state transition produces an immutable, hash-chained
+receipt that can be independently verified.
+
+Division: Tower Technologies, Brooks Holdings Inc.
+
+Core workflow::
+
+    from sonic import Transaction, TxState, SonicReceipt, SbnClient
+
+    # Build a transaction through the state machine
+    tx = Transaction(tx_id="tx-001", merchant_id="m-acme")
+    event = tx.advance(TxState.RECEIVABLE_DETECTED, amount=100.00, currency="USD")
+
+    # Seal receipt to SBN for tamper-evident attestation
+    sbn = SbnClient(api_key="sbn_live_...")
+    sbn_hash = sbn.seal({"receipt_hash": event.receipt_hash})
+
+Core modules::
+
+    from sonic.core.engine import Transaction, TxState, TxEvent
+    from sonic.core.receipt_builder import SonicReceipt, ReceiptChain, canonical_hash
+    from sonic.core.finality_gate import FinalityGate, FinalityPolicy, FinalityStatus
+    from sonic.core.treasury import Treasury, ConversionQuote
+    from sonic.core.payout_executor import PayoutExecutor, PayoutInstruction, PayoutResult
+    from sonic.events.types import EventType
+    from sonic.events.emitter import EventEmitter
+    from sonic.sbn import SbnClient, SbnAttester, ReceiptCoupler
+"""
+
+from __future__ import annotations
+
+from sonic._version import __version__
+
+# Core settlement
+from sonic.core.engine import Transaction, TxState, TxEvent, InvalidTransition, TRANSITIONS
+from sonic.core.receipt_builder import SonicReceipt, ReceiptChain, canonical_hash
+from sonic.core.finality_gate import (
+    FinalityGate,
+    FinalityPolicy,
+    FinalityStatus,
+    DEFAULT_POLICIES,
+)
+from sonic.core.treasury import Treasury, ConversionQuote
+from sonic.core.payout_executor import PayoutExecutor, PayoutInstruction, PayoutResult
+
+# Events
+from sonic.events.types import EventType
+from sonic.events.emitter import EventEmitter
+
+# SBN integration
+from sonic.sbn.client import SbnClient, SbnError, SbnQuotaExceeded
+from sonic.sbn.attester import SbnAttester
+from sonic.sbn.receipt_coupler import ReceiptCoupler
+from sonic.sbn.frontier import SONIC_FRONTIER
+
+# Configuration
+from sonic.config import SonicSettings, settings
+
+# Vendored SDKs — re-export top-level clients
+from sonic._vendor.dominion import (
+    DominionSbnClient,
+    DominionSonicClient,
+    DominionTranslationRule,
+    DOMINION_TRANSLATION_RULES,
+)
+
+__all__ = [
+    # Core — state machine
+    "Transaction",
+    "TxState",
+    "TxEvent",
+    "InvalidTransition",
+    "TRANSITIONS",
+    # Core — receipts
+    "SonicReceipt",
+    "ReceiptChain",
+    "canonical_hash",
+    # Core — finality
+    "FinalityGate",
+    "FinalityPolicy",
+    "FinalityStatus",
+    "DEFAULT_POLICIES",
+    # Core — treasury
+    "Treasury",
+    "ConversionQuote",
+    # Core — payouts
+    "PayoutExecutor",
+    "PayoutInstruction",
+    "PayoutResult",
+    # Events
+    "EventType",
+    "EventEmitter",
+    # SBN
+    "SbnClient",
+    "SbnError",
+    "SbnQuotaExceeded",
+    "SbnAttester",
+    "ReceiptCoupler",
+    "SONIC_FRONTIER",
+    # Config
+    "SonicSettings",
+    "settings",
+    # Vendored — Dominion
+    "DominionSbnClient",
+    "DominionSonicClient",
+    "DominionTranslationRule",
+    "DOMINION_TRANSLATION_RULES",
+]

sonic_sdk-0.1.0/sonic/_vendor/__init__.py

@@ -0,0 +1 @@
+"""Vendored dependencies — sbn-sdk, snapchore-core, dominion-sdk."""

sonic_sdk-0.1.0/sonic/_vendor/dominion/__init__.py

@@ -0,0 +1,51 @@
+"""Dominion — Sovereign Compression Payroll Router & Reflex Engine.
+
+Dominion is a reflexive sovereign routing and compression layer that
+orchestrates Smart Block-based payouts across fiat, crypto, and hybrid
+treasury systems.  It is GEC-native: every payout operation emits y/x
+efficiency metrics and optional CSK vectors into the SBN analytics
+pipeline, making it a first-class participant in NUMA governance.
+
+Tier model:
+  Tier 1 — Legacy payroll processing (no SBN integration)
+  Tier 2 — Legacy + SnapChore attestation + GEC scoring + Sonic settlement
+  Tier 3 — Tier 2 + Lightweight Tower Agent + NUMA governance + Translation Rules
+
+Division: Tower Technologies, Brooks Holdings Inc.
+
+Clients:
+  DominionSbnClient  — wraps SBN Python SDK for SnapChore, Lattice, GEC, NUMA
+  DominionSonicClient — HTTP client to Sonic settlement engine
+
+Hard Stops:
+  Tax codes are user-programmable and required. No tax codes = no operations.
+
+Usage::
+
+    from dominion import DominionSbnClient, DominionSonicClient
+
+    sbn = DominionSbnClient(
+        base_url="https://api.smartblocks.network",
+        api_key="sbn_live_...",
+        project_id="proj-dominion",
+        tier=2,
+    )
+    sonic = DominionSonicClient(base_url="https://sonic.example.com")
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+
+from .sbn_client import DominionSbnClient
+from .sonic_client import DominionSonicClient
+from .translation_rules import DominionTranslationRule, DOMINION_TRANSLATION_RULES
+
+__all__ = [
+    # Clients
+    "DominionSbnClient",
+    "DominionSonicClient",
+    # Translation rules
+    "DominionTranslationRule",
+    "DOMINION_TRANSLATION_RULES",
+]

sonic_sdk-0.1.0/sonic/_vendor/dominion/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"