Metadata-Version: 2.4
Name: kaldrix-sdk
Version: 0.1.0
Summary: A small Python client for the Kaldrix and Zentrix HTTP API, with helpers for an AI agent to read a database through a signed, purpose bound, time bound permission. Zentrix is sandbox only: no real money moves.
Author: Oguh Chidiebube Kenneth
License: # Notice
        
        Copyright (c) 2026 Kaldrix. **All rights reserved.**
        
        This package is a small client for the Kaldrix and Zentrix test service. It is published so you can read it and use it with that service, under the
        testing agreement you accept when you sign up for a test account.
        
        You may read this code, and run it to use the Kaldrix service. You may **not** copy, modify, redistribute or sell it, or use it to build a competing
        product or service, without written permission. This notice is not an open-source licence, and nothing here grants one.
        
        The permission engine, the payment engine and the service itself are not in this package. Zentrix is a sandbox: no real money moves.
        
        *(A lawyer should review this notice and the testing agreement before this package is promoted widely.)*
        
Project-URL: Homepage, https://kennzyoguh-lang.github.io/kaldrix-zentrix/
Project-URL: Evidence, https://kennzyoguh-lang.github.io/kaldrix-zentrix/evidence.html
Project-URL: Challenge, https://kennzyoguh-lang.github.io/kaldrix-zentrix/challenge.html
Keywords: ai-agents,authorization,database-access,mcp,payments,kaldrix,zentrix
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: NOTICE.md
Requires-Dist: cryptography>=42
Dynamic: license-file

# Kaldrix + Zentrix Python SDK

A small client for the platform's HTTP API, with helpers for an AI agent to read a database through a signed, purpose bound, time bound
permission. One dependency (`cryptography`, for the agent's key). Python 3.10 or later.

**Zentrix is sandbox only. No real money moves.**

```python
from kaldrix_sdk import Client, generate_agent_key

dev = Client("https://your-service", "your-own-test-account-key")

# 1. The agent makes its own key. Only the public half is shared.
key, _seed = generate_agent_key()

# 2. You give it a permission: these tables, these columns, for this purpose, for one minute.
perm = dev.data.issue_permission(
    "support-bot", key.public_key_hex, "customer_support",
    [
        {"table": "support_tickets", "operations": ["read"]},
        {"table": "customers", "operations": ["read"], "columns": ["id", "name", "plan"]},
    ],
    ttl_ms=60_000,
)

# 3. The agent asks. `ask` plans the statement, signs a proof for exactly it, and presents both with the permission.
out = dev.data.ask("demo", "SELECT id, subject FROM support_tickets", perm["token"], key, "support-bot", "customer_support")
if out.allowed:
    print(out.rows_as_objects())
else:
    print("refused:", out.reason)  # nothing ran
```

* A refusal is a normal answer (`out.allowed` is false, `out["stage"]`, `out.reason`), not an exception. Nothing ran unless the stage is `query_executed`.
* A proof is for one exact statement and works once. Sending the same request again is refused as a replay.
* `dev.data.demo()` runs the scripted demonstration. `dev.data.issue_real_permission(...)` (operator key) is for a real database the operator connected, read only.
* `sign_data_proof` and `sign_payment_proof` are exported if you build requests yourself. The same inputs give the same bytes as the TypeScript SDK
  (the shared test vectors are in the source).
* The key goes only in the `Authorization` header, never in a URL.

## Install

```
pip install kaldrix-sdk
```

This is a first version for a test service. It has had no independent security review. See `NOTICE.md` for the terms.
