dmn-sdk 0.1.0__tar.gz

dmn_sdk-0.1.0/LICENSE

@@ -0,0 +1,158 @@
+# DMN Mesh — Restricted-Use Evaluation Licence
+
+**Issuer:** Tata Communications Limited ("**TCL**")
+**Software:** dmn-ucpe and the DMN Mesh agent, dashboard, SDK and associated artefacts (collectively, the "**Software**")
+**Classification:** Internal — Restricted Evaluation Release
+**Status:** This is a **pre-release / testing build**. It is not a production-grade product.
+
+> **NOTICE — DRAFT FOR LEGAL REVIEW.** This text is a working draft authored for an internal evaluation programme. It must be reviewed and signed off by TCL Legal before being presented to any tenant for acceptance.
+
+---
+
+## 1. Acceptance
+
+1.1. By logging in to the DMN Mesh dashboard or invoking the DMN Mesh APIs as a tenant operator, the legal entity on whose behalf the tenant was provisioned (the "**Tenant**") is presented with this Licence and must indicate acceptance before any tenant-scoped feature becomes available.
+
+1.2. Acceptance is recorded as an immutable, hash-chained audit entry signed by the issuing DMN agent, including the OpenID Connect (OIDC) identity of the human operator who acted, the software version, and the cryptographic digest of the Licence text shown at the time of acceptance.
+
+1.3. **Acceptance is required again whenever a new release of the Software is installed on the mesh, or whenever the text of this Licence changes.** Previously recorded acceptances do not carry forward across release boundaries.
+
+1.4. The person clicking "Accept" warrants that they are duly authorised to bind the Tenant to this Licence.
+
+## 2. Limited Evaluation Grant
+
+2.1. Subject to the Tenant's continued compliance with this Licence, TCL grants the Tenant a **non-exclusive, non-transferable, non-sublicensable, revocable** licence to access and use the Software **solely within the DMN mesh instance operated by TCL** for the Tenant's **internal evaluation and operational testing** purposes.
+
+2.2. The grant is limited to use through the named tenant identity provisioned by TCL. The Tenant has no right to use the Software outside that tenant scope, on behalf of any third party, or for any commercial purpose other than the Tenant's own internal evaluation.
+
+2.3. No title, ownership or intellectual property right in the Software is transferred to the Tenant. All rights not expressly granted are reserved by TCL.
+
+## 3. Restrictions — Anti-Copying and Anti-Redistribution
+
+The Tenant **shall not, and shall not permit any person under its control or instruction to**:
+
+3.1. **Copy, mirror, archive, snapshot, image or export** the Software (in binary, source, container, image, package, configuration, key-material or any other form) outside the TCL-operated DMN mesh.
+
+3.2. **Install, deploy, run, register, attach, join or attempt to onboard** the Software onto any node, device, hardware, virtual machine, container, cloud account, partner network or third-party environment that has not been explicitly authorised in writing by TCL.
+
+3.3. **Redistribute, sublicense, lease, lend, sell, rent, host as a service, or otherwise make the Software available** to any third party.
+
+3.4. **Reverse engineer, decompile, disassemble, decrypt, extract, or attempt to derive the source code, structure, internal logic, keying material, or trade secrets** of the Software, except to the minimum extent expressly required by applicable law and only after notifying TCL in writing.
+
+3.5. **Remove, obscure, alter, or interfere with** any proprietary notice, copyright marker, licence banner, watermark, audit hook, attestation envelope, signature envelope, or telemetry channel embedded in the Software.
+
+3.6. **Publish or disclose** any benchmark, performance number, comparison, screenshot, defect report, security finding, training output, derived dataset, or analytical result obtained through the Software, in any external venue, without TCL's prior written consent.
+
+3.7. **Share, delegate, federate or transfer** the tenant identity, the OIDC credentials, the cryptographic keys, the signed manifests, or any session token issued by the Software, to any person other than employees of the Tenant who are individually bound by confidentiality obligations no less protective than those in this Licence.
+
+3.8. **Use the Software to circumvent or attempt to circumvent** any access control, policy gate, capability gate, attestation check, signature check, audit log, tenant scoping, or rate limit imposed by the Software or by TCL.
+
+## 4. Pre-Release Software Notice and Risk Acknowledgement
+
+4.1. **The Software is a pre-release, experimental, testing build.** It is provided for the Tenant's evaluation only and is **not warranted, certified, or intended for production, mission-critical, regulated, safety-of-life, or revenue-generating workloads**.
+
+4.2. **The operational impact of the Software on the Tenant's existing systems, networks, applications, security posture, regulatory compliance, data integrity, or service availability has not been measured, validated, or certified** by TCL. The Tenant acknowledges that the Software may interact with the Tenant's environment in ways that are not fully characterised.
+
+4.3. **The Software is expected to contain defects, regressions, breaking changes, behavioural surprises, performance variability, and undocumented behaviour.** Frequent releases — including releases that alter, remove, or replace capabilities the Tenant currently relies on — are anticipated.
+
+4.4. **The Tenant agrees to use the Software with the utmost caution and responsibility**, including but not limited to: deploying it first in non-critical environments, maintaining independent backups and rollback paths, isolating it from systems whose continued operation is materially important, and treating every release as a fresh evaluation event.
+
+4.5. The Tenant acknowledges that this Licence and the Software may be modified, suspended, withdrawn or terminated by TCL at any time, with or without notice, including in response to operational risk.
+
+## 5. Tenant Responsibilities — Monitoring, Review, and Reporting
+
+The Tenant shall, on a continuing basis and at the Tenant's sole cost:
+
+5.1. **Continuously monitor** the behaviour, output, resource consumption, network activity, and security posture of the Software within the Tenant's environment.
+
+5.2. **Periodically review** the Software's effects on the Tenant's connected systems, including any unexpected change in performance, latency, traffic patterns, data flows, model outputs, or third-party integrations.
+
+5.3. **Promptly report** to TCL, through the channel TCL designates, any of the following: suspected defect; suspected security vulnerability; suspected data leakage; suspected policy violation; suspected unauthorised access; unexpected behaviour of any kind; any third-party complaint, dispute, regulatory enquiry, or incident response engagement that relates in any way to the Software.
+
+5.4. **Cooperate in good faith** with any TCL investigation, including by providing relevant logs, audit chain entries, configuration, and signed manifests on TCL's reasonable request.
+
+5.5. **Not delay** reporting under section 5.3 for commercial, reputational, or convenience reasons. The Tenant acknowledges that silence on a known defect or vulnerability is itself a material breach of this Licence.
+
+## 6. Disclaimer of Warranties
+
+6.1. **THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITH ALL FAULTS AND WITHOUT WARRANTY OF ANY KIND.** To the maximum extent permitted by applicable law, TCL expressly disclaims all warranties, conditions, representations and terms — whether express, implied, statutory, contractual, customary, or otherwise — including without limitation any warranty of **merchantability, fitness for a particular purpose, accuracy, completeness, reliability, availability, timeliness, security, non-infringement, quiet enjoyment, title, or course of dealing**.
+
+6.2. **TCL does not warrant** that the Software will meet the Tenant's requirements, operate without interruption, be free of defects, be free of vulnerabilities, produce correct results, preserve any data, prevent unauthorised access, comply with any standard, integrate with any third-party product, or be compatible with any future version of itself.
+
+6.3. **No advice or information**, whether oral or written, obtained from TCL or through the Software, shall create any warranty not expressly stated in this Licence.
+
+## 7. Limitation of Liability and Indemnity
+
+7.1. **TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, TCL SHALL NOT BE LIABLE TO THE TENANT, ITS AFFILIATES, ITS PERSONNEL, ITS CUSTOMERS, OR ANY THIRD PARTY** for any direct, indirect, incidental, special, consequential, exemplary, punitive, or any other damages whatsoever arising out of, related to, or in connection with the Software, this Licence, or the Tenant's use of, inability to use, or reliance on the Software — including without limitation damages for loss of profits, loss of revenue, loss of business, loss of goodwill, loss of data, loss of use, loss of customers, cost of substitute products, regulatory fines, third-party claims, downtime, breach of security, breach of confidentiality, or any other commercial or operational loss — even if TCL has been advised of, or could have foreseen, the possibility of such damages.
+
+7.2. The Tenant acknowledges that **the aggregate liability of TCL** under or in connection with this Licence and the Software, on any theory of liability whatsoever (including contract, tort, strict liability, statute, or otherwise), shall **not exceed zero (₹0)**, the parties having expressly priced the Software as a no-fee evaluation release.
+
+7.3. **The Tenant shall defend, indemnify, and hold harmless** TCL, its affiliates, and their respective officers, directors, employees, and agents from and against any and all third-party claims, demands, actions, proceedings, damages, liabilities, losses, costs and expenses (including reasonable legal fees) arising out of or in connection with: (a) the Tenant's breach of this Licence; (b) the Tenant's use of the Software in violation of section 3; (c) the Tenant's failure to monitor, review, or report as required by section 5; or (d) any data, content or input the Tenant introduces into the Software.
+
+7.4. The exclusions and limitations in this section 7 apply regardless of whether the remedies in this Licence are found to have failed of their essential purpose. They form an essential basis of the bargain between the parties; absent them, TCL would not provide the Software on a no-fee evaluation basis.
+
+## 8. Audit, Logging and Telemetry
+
+8.1. The Tenant acknowledges and consents that the Software records, and that TCL may collect and retain, **a hash-chained audit log of all Tenant-initiated state changes**, including without limitation: acceptance of this Licence, app and API onboarding, pipeline operations, model promotion, round abort, tenant withdrawal, and any operator action through the dashboard.
+
+8.2. Audit entries are append-only, signed, and chained by cryptographic hash. The Tenant shall not delete, alter, redact, exfiltrate, or interfere with the audit log.
+
+8.3. TCL may use audit data to investigate suspected breach of this Licence, to respond to incidents, to improve the Software, and to satisfy regulatory or contractual obligations.
+
+## 9. Suspension and Termination
+
+9.1. TCL may **suspend or terminate** this Licence, the Tenant's access to the Software, or any specific capability, at any time, with or without notice, for any reason or no reason, including suspected breach of section 3 (Restrictions), section 5 (Reporting), or section 8 (Audit).
+
+9.2. The Tenant may terminate this Licence by ceasing all use of the Software and requesting tenant withdrawal through the dashboard.
+
+9.3. **Effect of tenant deletion.** Upon withdrawal or deletion of the Tenant from the mesh — whether by the Tenant, by TCL, or automatically as a consequence of suspension — this Licence is automatically terminated, the Tenant's acceptance record is tombstoned, and the agreement becomes **null and void** as between the parties on a go-forward basis. Sections 3, 5.3, 6, 7, 8 and 11 survive termination.
+
+9.4. Termination does not entitle the Tenant to a refund or any other remedy; the Software is provided at no charge.
+
+## 10. No Support, No Service Level
+
+10.1. TCL is under **no obligation** to provide support, bug fixes, updates, upgrades, patches, security advisories, migrations, or professional services in connection with the Software.
+
+10.2. No service-level agreement, availability commitment, or response-time commitment of any kind applies to the Software.
+
+## 11. Confidentiality
+
+11.1. The Software, its design, its internal interfaces, the contents of any audit or telemetry data shared with the Tenant, and any defect or security finding the Tenant becomes aware of through use of the Software, are **TCL Confidential Information**.
+
+11.2. The Tenant shall protect TCL Confidential Information with at least the same degree of care it uses for its own most sensitive confidential information, and in no event less than a reasonable degree of care.
+
+## 12. Compliance with Law
+
+12.1. The Tenant shall use the Software in compliance with all applicable laws and regulations, including without limitation laws governing data protection, privacy, cryptography, export control, sanctions, and information security.
+
+12.2. The Software contains cryptographic components. The Tenant is solely responsible for ensuring that its use, possession, import or transmission of such components is lawful in every jurisdiction in which the Tenant operates.
+
+## 13. Governing Law and Jurisdiction
+
+13.1. This Licence is governed by and construed in accordance with the laws of the Republic of India, without regard to its conflict-of-laws principles.
+
+13.2. The courts at **Mumbai, Maharashtra, India** shall have exclusive jurisdiction over any dispute arising out of or in connection with this Licence.
+
+## 14. Entire Agreement; Severability; No Waiver
+
+14.1. This Licence is the entire agreement between the parties with respect to the Software and supersedes any prior or contemporaneous agreement, representation, or understanding.
+
+14.2. If any provision of this Licence is held to be unenforceable, the remaining provisions shall continue in full force and effect, and the unenforceable provision shall be replaced by an enforceable provision that most closely reflects the parties' intent.
+
+14.3. No failure or delay by TCL in exercising any right under this Licence shall operate as a waiver of that right.
+
+## 15. Acceptance Mechanism
+
+15.1. Acceptance is captured electronically by the DMN Mesh dashboard, signed by the issuing agent, and stored as an immutable, hash-chained audit entry. Each acceptance entry binds together:
+
+- the canonical name of the Tenant on the mesh;
+- the software version and the SHA-256 digest of this Licence text;
+- the OIDC issuer, subject, and bearer-token digest of the human operator who acted;
+- the hybrid logical clock and wall-clock timestamps of the action; and
+- the identity of the agent that witnessed the acceptance.
+
+15.2. The Tenant agrees that this electronic record constitutes valid, enforceable evidence of acceptance, equivalent to a handwritten signature.
+
+---
+
+*End of Licence.* © Tata Communications Limited. All rights reserved.

dmn_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: dmn-sdk
+Version: 0.1.0
+Summary: Python SDK for the DMN mesh — call tenant APIs from your code.
+Author-email: inno8cube <dmn-dev@inno8cube.com>
+License-Expression: LicenseRef-RestrictedUseEvaluation
+Project-URL: Homepage, https://github.com/dmn-ucpe/dmn-ucpe
+Project-URL: Documentation, https://github.com/dmn-ucpe/dmn-ucpe/blob/main/docs/SDK.md
+Project-URL: Source, https://github.com/dmn-ucpe/dmn-ucpe/tree/main/sdk/python
+Keywords: dmn,mesh,ndn,sdk,iot,telemetry
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Requires-Dist: websocket-client<2,>=1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# dmn-sdk
+
+Python client for the DMN mesh. Call tenant APIs from your own code with one import.
+
+## Install
+
+From a checkout:
+
+```bash
+pip install ./sdk/python/
+```
+
+From PyPI (v0.282.3+):
+
+```bash
+pip install dmn-sdk
+```
+
+Requires Python 3.9+. Pulls in `requests` and `websocket-client`.
+
+## Quickstart
+
+```python
+import dmn_sdk as dmn
+
+client = dmn.connect()                                 # reads DMN_API_TOKEN env
+ingestor = client.tenant("/tata/dmn/acme").app("ingestor")
+
+# Unary POST
+resp = ingestor.post("/telemetry", json={"sensor": "s1", "value": 23.4})
+print(resp.status_code, resp.json())
+
+# Subscribe to a topic
+for msg in ingestor.subscribe("telemetry"):
+    print(msg.seq, msg.payload)
+```
+
+## Authentication
+
+Three sources, in priority order:
+
+1. **Explicit kwargs** to `dmn.connect(token=..., base_url=...)`
+2. **Environment**: `DMN_API_TOKEN` + `DMN_API_BASE_URL` + (optional) `DMN_PROFILE`
+3. **Config file** `~/.dmn/credentials` (INI-style)
+
+### Env var setup
+
+```bash
+# Mint a token at /ui/dev/tokens/ on the dashboard,
+# then export:
+export DMN_API_TOKEN="eyJhbGc...the wire JWT..."
+export DMN_API_BASE_URL="https://console.dmn.inno8cube.com"
+```
+
+### Config file setup
+
+`~/.dmn/credentials`:
+
+```ini
+[default]
+token = eyJhbGc...
+base_url = https://console.dmn.inno8cube.com
+
+[acme-prod]
+token = eyJhbGc...
+base_url = https://console.dmn.acme.io
+```
+
+Pick a profile:
+
+```python
+client = dmn.connect(profile="acme-prod")
+```
+
+Or via env: `export DMN_PROFILE=acme-prod`.
+
+## API reference
+
+### `dmn.connect(...)`
+
+```python
+def connect(
+    token: str | None = None,
+    base_url: str | None = None,
+    *,
+    profile: str | None = None,
+    config_path: str | None = None,
+    timeout: float = 30,
+    ws_timeout: float = 30,
+    verify_tls: bool = True,
+    user_agent: str | None = None,
+) -> Client
+```
+
+Returns a `Client`. Raises `dmn.ConfigError` if no source can supply `token` + `base_url`.
+
+### `Client.tenant(name)`
+
+```python
+def tenant(self, name: str) -> Tenant
+```
+
+`name` must be a full NDN name starting with `/`, e.g. `"/tata/dmn/acme"`. Returns a `Tenant`.
+
+### `Tenant.app(name)`
+
+```python
+def app(self, name: str) -> App
+```
+
+Returns an `App` handle.
+
+### Unary methods on `App`
+
+```python
+app.get(path, **kwargs)     -> Response
+app.post(path, **kwargs)    -> Response
+app.put(path, **kwargs)     -> Response
+app.patch(path, **kwargs)   -> Response
+app.delete(path, **kwargs)  -> Response
+```
+
+`**kwargs` are passed through to `requests.Session.request` — most useful ones: `json=`, `data=`, `params=`, `headers=`, `timeout=`.
+
+### `App.subscribe(topic)`
+
+```python
+def subscribe(self, topic: str) -> Iterator[Message]
+```
+
+Opens a WebSocket to the gateway's subscribe bridge. Yields `Message(seq, topic, payload, ts)` objects as they arrive. The iterator runs until the server closes the connection or you `break`. Re-iterating opens a fresh connection.
+
+### `Response`
+
+```python
+resp.status_code  -> int
+resp.ok           -> bool          # True for 2xx
+resp.headers      -> dict[str,str]
+resp.text         -> str
+resp.content      -> bytes
+resp.json()       -> Any
+resp.raw          -> requests.Response  # power-user escape hatch
+```
+
+### `Message`
+
+```python
+@dataclass(frozen=True)
+class Message:
+    seq: int          # per-topic monotonic sequence number
+    topic: str        # which topic this message was on
+    payload: Any      # decoded JSON body
+    ts: int           # unix timestamp (seconds) at the publisher
+```
+
+### Errors
+
+All raised by the SDK descend from `dmn.DMNError`:
+
+| Exception | When |
+|---|---|
+| `dmn.ConfigError` | Missing token/base_url, malformed config file, unknown profile |
+| `dmn.AuthError` | Gateway returned 401 or 403 |
+| `dmn.NotFoundError` | Gateway returned 404 (tenant/app not in routing table) |
+| `dmn.BackendError` | 5xx from the backend, transport failures, gateway-streamed error frame |
+| `dmn.APIError` | Other non-2xx responses |
+
+Most application code wants:
+
+```python
+try:
+    resp = ingestor.post("/telemetry", json={...})
+except dmn.AuthError:
+    # Token issue — re-mint or re-auth
+    raise
+except dmn.NotFoundError:
+    # Misconfigured route
+    raise
+except dmn.BackendError as e:
+    # Retryable
+    print(f"retrying: {e}")
+```
+
+## Examples
+
+See `examples/`:
+
+- `post_telemetry.py` — single-shot POST to the reference ingestor
+- `subscribe_topic.py` — WebSocket-backed iterator consuming a topic
+
+## Dev notes
+
+```bash
+# Run tests
+cd sdk/python
+pip install -e ".[dev]"
+pytest -v
+
+# Lint (if installed)
+ruff check dmn_sdk tests
+```
+
+## Versioning
+
+The SDK version tracks the DMN agent's compatible wire format. v0.282.x is the first stable line; breaking changes to the gateway's REST/WS surface will bump the major. Backwards-compatible additions bump the minor.
+
+## License
+
+Restricted-Use Evaluation Licence — see `../../docs/RESTRICTED-USE-LICENSE.md`.

dmn_sdk-0.1.0/README.md

@@ -0,0 +1,209 @@
+# dmn-sdk
+
+Python client for the DMN mesh. Call tenant APIs from your own code with one import.
+
+## Install
+
+From a checkout:
+
+```bash
+pip install ./sdk/python/
+```
+
+From PyPI (v0.282.3+):
+
+```bash
+pip install dmn-sdk
+```
+
+Requires Python 3.9+. Pulls in `requests` and `websocket-client`.
+
+## Quickstart
+
+```python
+import dmn_sdk as dmn
+
+client = dmn.connect()                                 # reads DMN_API_TOKEN env
+ingestor = client.tenant("/tata/dmn/acme").app("ingestor")
+
+# Unary POST
+resp = ingestor.post("/telemetry", json={"sensor": "s1", "value": 23.4})
+print(resp.status_code, resp.json())
+
+# Subscribe to a topic
+for msg in ingestor.subscribe("telemetry"):
+    print(msg.seq, msg.payload)
+```
+
+## Authentication
+
+Three sources, in priority order:
+
+1. **Explicit kwargs** to `dmn.connect(token=..., base_url=...)`
+2. **Environment**: `DMN_API_TOKEN` + `DMN_API_BASE_URL` + (optional) `DMN_PROFILE`
+3. **Config file** `~/.dmn/credentials` (INI-style)
+
+### Env var setup
+
+```bash
+# Mint a token at /ui/dev/tokens/ on the dashboard,
+# then export:
+export DMN_API_TOKEN="eyJhbGc...the wire JWT..."
+export DMN_API_BASE_URL="https://console.dmn.inno8cube.com"
+```
+
+### Config file setup
+
+`~/.dmn/credentials`:
+
+```ini
+[default]
+token = eyJhbGc...
+base_url = https://console.dmn.inno8cube.com
+
+[acme-prod]
+token = eyJhbGc...
+base_url = https://console.dmn.acme.io
+```
+
+Pick a profile:
+
+```python
+client = dmn.connect(profile="acme-prod")
+```
+
+Or via env: `export DMN_PROFILE=acme-prod`.
+
+## API reference
+
+### `dmn.connect(...)`
+
+```python
+def connect(
+    token: str | None = None,
+    base_url: str | None = None,
+    *,
+    profile: str | None = None,
+    config_path: str | None = None,
+    timeout: float = 30,
+    ws_timeout: float = 30,
+    verify_tls: bool = True,
+    user_agent: str | None = None,
+) -> Client
+```
+
+Returns a `Client`. Raises `dmn.ConfigError` if no source can supply `token` + `base_url`.
+
+### `Client.tenant(name)`
+
+```python
+def tenant(self, name: str) -> Tenant
+```
+
+`name` must be a full NDN name starting with `/`, e.g. `"/tata/dmn/acme"`. Returns a `Tenant`.
+
+### `Tenant.app(name)`
+
+```python
+def app(self, name: str) -> App
+```
+
+Returns an `App` handle.
+
+### Unary methods on `App`
+
+```python
+app.get(path, **kwargs)     -> Response
+app.post(path, **kwargs)    -> Response
+app.put(path, **kwargs)     -> Response
+app.patch(path, **kwargs)   -> Response
+app.delete(path, **kwargs)  -> Response
+```
+
+`**kwargs` are passed through to `requests.Session.request` — most useful ones: `json=`, `data=`, `params=`, `headers=`, `timeout=`.
+
+### `App.subscribe(topic)`
+
+```python
+def subscribe(self, topic: str) -> Iterator[Message]
+```
+
+Opens a WebSocket to the gateway's subscribe bridge. Yields `Message(seq, topic, payload, ts)` objects as they arrive. The iterator runs until the server closes the connection or you `break`. Re-iterating opens a fresh connection.
+
+### `Response`
+
+```python
+resp.status_code  -> int
+resp.ok           -> bool          # True for 2xx
+resp.headers      -> dict[str,str]
+resp.text         -> str
+resp.content      -> bytes
+resp.json()       -> Any
+resp.raw          -> requests.Response  # power-user escape hatch
+```
+
+### `Message`
+
+```python
+@dataclass(frozen=True)
+class Message:
+    seq: int          # per-topic monotonic sequence number
+    topic: str        # which topic this message was on
+    payload: Any      # decoded JSON body
+    ts: int           # unix timestamp (seconds) at the publisher
+```
+
+### Errors
+
+All raised by the SDK descend from `dmn.DMNError`:
+
+| Exception | When |
+|---|---|
+| `dmn.ConfigError` | Missing token/base_url, malformed config file, unknown profile |
+| `dmn.AuthError` | Gateway returned 401 or 403 |
+| `dmn.NotFoundError` | Gateway returned 404 (tenant/app not in routing table) |
+| `dmn.BackendError` | 5xx from the backend, transport failures, gateway-streamed error frame |
+| `dmn.APIError` | Other non-2xx responses |
+
+Most application code wants:
+
+```python
+try:
+    resp = ingestor.post("/telemetry", json={...})
+except dmn.AuthError:
+    # Token issue — re-mint or re-auth
+    raise
+except dmn.NotFoundError:
+    # Misconfigured route
+    raise
+except dmn.BackendError as e:
+    # Retryable
+    print(f"retrying: {e}")
+```
+
+## Examples
+
+See `examples/`:
+
+- `post_telemetry.py` — single-shot POST to the reference ingestor
+- `subscribe_topic.py` — WebSocket-backed iterator consuming a topic
+
+## Dev notes
+
+```bash
+# Run tests
+cd sdk/python
+pip install -e ".[dev]"
+pytest -v
+
+# Lint (if installed)
+ruff check dmn_sdk tests
+```
+
+## Versioning
+
+The SDK version tracks the DMN agent's compatible wire format. v0.282.x is the first stable line; breaking changes to the gateway's REST/WS surface will bump the major. Backwards-compatible additions bump the minor.
+
+## License
+
+Restricted-Use Evaluation Licence — see `../../docs/RESTRICTED-USE-LICENSE.md`.

dmn_sdk-0.1.0/dmn_sdk/__init__.py

@@ -0,0 +1,48 @@
+"""dmn-sdk — Python client for the DMN mesh.
+
+Quickstart:
+
+    import dmn
+
+    client = dmn.connect()                       # reads DMN_API_TOKEN env
+    ingestor = client.tenant("/tata/dmn/acme").app("ingestor")
+
+    resp = ingestor.post("/telemetry", json={"sensor": "s1", "value": 23.4})
+    print(resp.json())
+
+    for msg in ingestor.subscribe("telemetry"):
+        print(msg.seq, msg.payload)
+
+See https://github.com/dmn-ucpe/dmn-ucpe/blob/main/docs/SDK.md
+for the full reference.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .client import Client, Response, Tenant, App, connect
+from .errors import (
+    DMNError,
+    ConfigError,
+    AuthError,
+    NotFoundError,
+    BackendError,
+    APIError,
+)
+from .types import Message
+
+__all__ = [
+    "__version__",
+    "connect",
+    "Client",
+    "Tenant",
+    "App",
+    "Response",
+    "Message",
+    "DMNError",
+    "ConfigError",
+    "AuthError",
+    "NotFoundError",
+    "BackendError",
+    "APIError",
+]

dmn_sdk-0.1.0/dmn_sdk/_version.py

@@ -0,0 +1,9 @@
+"""Single source of truth for the SDK version.
+
+Kept in its own module so it can be imported during
+package build (setuptools' dynamic version lookup) +
+imported at runtime by tests / log statements without
+pulling in the rest of the SDK.
+"""
+
+__version__ = "0.1.0"