Metadata-Version: 2.4
Name: citrate-labs-sdk
Version: 0.6.2
Summary: Python SDK for the Citrate distributed AI network (chain 40204). The canonical TypeScript SDK is @citratelabs/sdk on npm; this Python client is opt-in and may lag it.
Author-email: Citrate Team <developers@citrate.ai>
Maintainer-email: Citrate Team <developers@citrate.ai>
License: Apache-2.0
Project-URL: Homepage, https://citrate.ai
Project-URL: Documentation, https://docs.citrate.ai
Project-URL: Repository, https://github.com/CitrateNetwork/citrate-sdk-python
Project-URL: Bug Tracker, https://github.com/CitrateNetwork/citrate-sdk-python/issues
Project-URL: Changelog, https://github.com/CitrateNetwork/citrate-sdk-python/blob/main/CHANGELOG.md
Keywords: citrate,distributed-ai,ai,dag,web3,machine-learning
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests~=2.33
Requires-Dist: urllib3<3,>=2.0
Requires-Dist: cryptography<51,>=48.0.1
Requires-Dist: eth-account~=0.9
Requires-Dist: web3~=7.15
Requires-Dist: numpy~=2.0
Requires-Dist: typing-extensions~=4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: isort<7,>=5.13; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: tomli>=2.0; extra == "dev"
Requires-Dist: setuptools>=83; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=8.1.3; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.20; extra == "docs"
Dynamic: license-file

# citrate-sdk-python

*Part of the **[Citrate Network](https://citrate.ai)** — own the means of computation. · [Docs](https://docs.citrate.ai) · [Run a node](https://citrate.ai/download) · [Contribute → free membership](https://github.com/CitrateNetwork/.github/blob/main/CONTRIBUTING.md)*
> The Python SDK and `citrate` CLI for the Citrate Network (chain **40204**) — connect to the chain, deploy/run models, encrypt inference inputs, and call the inference gateway.

## What it is
`citrate-labs-sdk` is the Python client for the Citrate distributed-AI network: a JSON-RPC
`CitrateClient`, managers for compute/learning/staking/treasury/farming, an AES-GCM/HKDF
crypto envelope for encrypted inference, an OpenAI-compatible `GatewayClient`, and a
`citrate` command-line tool. Chain id 40204 is bound from a vendored federation-contract
artifact and enforced at signing time (a hostile RPC cannot make you sign for another
chain). It mirrors the canonical TypeScript SDK (`@citratelabs/sdk`) and may lag it.

See the concepts in the docs: <https://docs.citrate.ai>.
Depends on a running chain node ([citrate-chain](https://github.com/CitrateNetwork/citrate-chain))
and, for inference, the gateway ([citrate-inference-gateway](https://github.com/CitrateNetwork/citrate-inference-gateway)).

## Prerequisites
```bash
python3 --version   # >= 3.10 (3.10/3.11/3.12 supported)
python3 -m pip --version
# Optional: uv (a uv.lock is committed for reproducible installs)
#   pipx install uv   # or: curl -LsSf https://astral.sh/uv/install.sh | sh
# Optional, only for "Connect it locally": a local Citrate devnet node on :8545
```

## Build from source
```bash
git clone https://github.com/CitrateNetwork/citrate-sdk-python.git
cd citrate-sdk-python

# pip (editable install with dev extras)
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'

# --- or with uv (uses the committed uv.lock) ---
# uv sync

pytest                 # run the test suite
citrate contract       # smoke-test the CLI: prints the federation contract table
```
`pyproject.toml` is the single source of truth for dependencies (`requests`, `cryptography`,
`eth-account`, `web3`, `numpy`). The install exposes the `citrate` console script.

## Run locally
This is a library plus a CLI. Install it into your environment, then either import it or use
the CLI:

```bash
pip install citrate-labs-sdk        # from PyPI (published as citrate-labs-sdk)
citrate --help                      # subcommands: contract, wallet, entitlement, gateway
```

30-second Quickstart (against the public testnet, chain 40204):
```python
import os
from citrate_sdk import CitrateClient

client = CitrateClient(
    rpc_url="https://rpc.citrate.ai",             # testnet default (chain 40204)
    private_key=os.getenv("CITRATE_PRIVATE_KEY"), # optional; required to sign
)
print("chain id:", client.get_chain_id())          # 40204
```

Call the inference gateway (OpenAI-compatible; needs a `cgk_` key):
```python
from citrate_sdk.gateway import GatewayClient

gw = GatewayClient(api_key=os.environ["CITRATE_GATEWAY_API_KEY"])
print(gw.chat_completions(
    model="gemma-4-E4B-it-Q4_K_M",
    messages=[{"role": "user", "content": "Say hi from Citrate"}],
))
```
Runnable examples live in `examples/` (`basic_usage.py`, `encrypted_inference.py`,
`marketplace_demo.py`). Verify it's up: `get_chain_id()` returning `40204` confirms the RPC.

> Security: the client warns/fails on a remote plaintext `http://` RPC (keys and signed
> transactions would go out in cleartext). Loopback `http://` is always allowed; pass
> `allow_insecure_http=True` for a trusted TLS-less internal host.

## Connect it locally  ← the differentiator
Point the SDK at a local Citrate stack on one machine instead of the public testnet.

1. **Local chain** — run a Citrate devnet node (chain 40204) from
   [citrate-chain](https://github.com/CitrateNetwork/citrate-chain) and deploy its contract
   book. It exposes JSON-RPC on `http://localhost:8545`.
2. **Point the SDK at it** (loopback needs no opt-in):
   ```python
   from citrate_sdk import CitrateClient
   client = CitrateClient(
       rpc_url="http://localhost:8545",
       private_key="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",  # anvil acct #0
   )
   assert client.get_chain_id() == 40204
   ```
   The client refuses to sign if the RPC's `eth_chainId` does not match the expected 40204;
   pass `chain_id=` to override for a custom local chain.
3. **Local inference gateway** (optional) — run
   [citrate-inference-gateway](https://github.com/CitrateNetwork/citrate-inference-gateway)
   and point the gateway client at it:
   ```python
   gw = GatewayClient(api_key="cgk_...", base_url="http://localhost:8080")
   ```
4. **End-to-end check** — run the basic example against your local node:
   ```bash
   CITRATE_RPC_URL=http://localhost:8545 python examples/basic_usage.py
   ```

For the full multi-repo bring-up (chain → identity → bundler → gateway → SDKs), see the
LOCAL_STACK guide at <https://docs.citrate.ai>.

## Configuration
| Env var | Default | Purpose |
|---------|---------|---------|
| `CITRATE_RPC_URL` | `http://localhost:8545` | chain JSON-RPC endpoint |
| `CITRATE_PRIVATE_KEY` | — | signer key (examples generate an ephemeral one if unset) |
| `CITRATE_GATEWAY_API_KEY` | — | `cgk_` bearer key for the inference gateway |

`CitrateClient(rpc_url, private_key=None, timeout=..., allow_insecure_http=False, chain_id=None)`.
The expected chain id (40204) and gateway base URL come from the vendored federation
artifact; `citrate contract` prints the full table.

## Links
- Docs: <https://docs.citrate.ai>
- Depends on: [citrate-chain](https://github.com/CitrateNetwork/citrate-chain) · [citrate-inference-gateway](https://github.com/CitrateNetwork/citrate-inference-gateway) · [citrate-identity](https://github.com/CitrateNetwork/citrate-identity)
- Parity with: [citrate-sdk-js](https://github.com/CitrateNetwork/citrate-sdk-js) (canonical SDK)
- Contributing (DCO): `CONTRIBUTING.md` · Security: `SECURITY.md` · License: [`LICENSE`](LICENSE)

## License

Licensed under the Apache License, Version 2.0 (see [`LICENSE`](LICENSE)). This is the open-source infrastructure tier of Citrate's open-core model. The commercial application layer is source-available under BUSL-1.1. Licensor: Citrate Inc.
