ralio 0.1.0__tar.gz

ralio-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Default owners for everything in the repo.
+* @lgrosales
+
+# Security-sensitive crypto and auth lifecycle get explicit ownership.
+/src/ralio/_crypto.py @lgrosales
+/src/ralio/auth.py @lgrosales
+/src/ralio/transport.py @lgrosales
+/src/ralio/registration.py @lgrosales

ralio-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,47 @@
+name: Bug report
+description: Report a problem with the Ralio Python SDK
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. **Do not include private keys, access
+        tokens, or registration tickets** in this issue. For security
+        vulnerabilities, see [SECURITY.md](../../SECURITY.md) instead.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including the full traceback if any.
+      placeholder: When I call client.chat.send(...), I get ...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: A minimal code snippet that triggers the issue (redact secrets).
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: sdk-version
+    attributes:
+      label: SDK version
+      placeholder: "0.1.0  (python -c 'import ralio; print(ralio.__version__)')"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true
+  - type: textarea
+    id: extra
+    attributes:
+      label: Anything else?
+      description: OS, networking setup (proxies), or other context.
+    validations:
+      required: false

ralio-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/Ralioco/ralio-python/security/advisories/new
+    about: Report security issues privately — never in a public issue.
+  - name: Ralio documentation
+    url: https://docs.ralio.co
+    about: API reference, authentication guides, and concepts.

ralio-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Suggest a new capability or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the use case, not just the proposed solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would the API look like? A code sketch helps.
+      render: python
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

ralio-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## Summary
+
+<!-- What does this change and why? -->
+
+## Changes
+
+<!-- Bullet the notable changes. -->
+-
+
+## Checklist
+
+- [ ] `ruff check .` passes
+- [ ] `mypy` passes
+- [ ] `pytest -q` passes (new behavior has tests; network is mocked)
+- [ ] `CHANGELOG.md` updated under the unreleased section
+- [ ] No new runtime dependencies (or discussed in the issue)
+- [ ] This PR touches security-sensitive code (key handling / signing / tokens) — flagged for extra review: yes / no
+
+## Related issues
+
+<!-- Closes #123 -->

ralio-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

ralio-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy
+      - run: pytest -q

ralio-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) when a version tag is pushed.
+# No API token is stored — PyPI verifies the workflow identity directly.
+# One-time setup: add this repo + workflow as a trusted publisher for the
+# `ralio` project at https://pypi.org/manage/account/publishing/.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ralio-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Secrets — never commit private keys
+*.pem
+ralio-key*
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

ralio-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: detect-private-key

ralio-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+Initial release.
+
+- OAuth 2.1 `client_credentials` + `private_key_jwt` + DPoP authentication.
+- One-time credential-binding registration (`ralio.register`) with
+  **synchronous activation** (server PR agentic-payment-gateway#1182): the
+  binding is active as soon as the submit call returns — no owner-approval
+  step, no polling. Ticket errors (`invalid_ticket`, `ticket_expired`,
+  `ticket_already_consumed` with `used_at`/`used_by_host` context,
+  `public_key_already_in_use`, `invalid_public_key`, `invalid_scope`,
+  `scope_exceeds_ticket_ceiling`) map into `RalioRegistrationError`.
+- Zero-config onboarding, in lockstep with the Node SDK
+  (Ralioco/ralio-node#15): `register()` defaults its ticket to
+  `RALIO_REGISTRATION_TICKET`, mints the first access token, and persists
+  credentials to `~/.ralio/` (the CLI's store, so `register()` and
+  `ralio auth agent` are interchangeable; private key at
+  `~/.ralio/keys/<jkt>.pem`, `private_key_path` overrides). `RalioClient()`
+  then constructs with no arguments. Env overrides: `RALIO_API_URL`,
+  `RALIO_CONFIG_DIR`. `CredentialBinding` gained `key_path`; `scopes` now
+  reflects the granted token scope.
+- `client.chat.send` and `client.chat.stream` (SSE). `agent_id` is optional —
+  when omitted, the SDK resolves the single agent the credential is bound to
+  (via `client.agents.list()`) and caches it.
+- `client.agents.list` and the `Agent` type.
+- `client.transactions.list` and `client.payment_intents.list` (paginated).

ralio-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **conduct@ralio.co**. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

ralio-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Thanks for your interest in improving the Ralio Python SDK.
+
+## Development setup
+
+Requires Python 3.10+.
+
+```bash
+git clone https://github.com/Ralioco/ralio-python
+cd ralio-python
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Checks
+
+All of these must pass before a PR is merged; CI runs them on Python 3.10–3.13.
+
+```bash
+ruff check .      # lint
+mypy              # static types (strict)
+pytest -q         # tests
+```
+
+Optionally install the pre-commit hooks so the lint/type checks run on every
+commit:
+
+```bash
+pip install pre-commit && pre-commit install
+```
+
+## Guidelines
+
+- **Public API.** Anything importable from `ralio` (not underscore-prefixed) is
+  public and follows SemVer. Modules like `ralio._crypto` are internal and may
+  change without notice.
+- **Types.** Every public function, method, and attribute is type-annotated;
+  `mypy --strict` must pass.
+- **Tests.** New behavior needs tests. Network is mocked with `respx` — tests
+  must not hit a live API. Crypto correctness (DPoP/assertion claims and
+  signatures) is tested with real keys.
+- **No new runtime dependencies** without discussion. The SDK intentionally
+  depends only on `httpx` and `PyJWT[crypto]`.
+- **Security-sensitive code** (key handling, signing, token lifecycle) gets
+  extra review. If your change touches it, call that out in the PR.
+
+## Commit messages & PRs
+
+- Write a clear subject line in the imperative mood.
+- Keep PRs focused; update `CHANGELOG.md` under the unreleased section.
+- Link any related issue.
+
+## Reporting bugs / requesting features
+
+Use the issue templates. For security issues, see [SECURITY.md](SECURITY.md) —
+do not file a public issue.

ralio-0.1.0/LICENSE

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

ralio-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: ralio
+Version: 0.1.0
+Summary: Official Python SDK for the Ralio agentic payment API.
+Project-URL: Homepage, https://ralio.co
+Project-URL: Documentation, https://docs.ralio.co
+Author: Ralio
+License: MIT
+License-File: LICENSE
+Keywords: agents,dpop,oauth,payments,ralio,sdk
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ralio Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/ralio.svg)](https://pypi.org/project/ralio/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ralio.svg)](https://pypi.org/project/ralio/)
+[![CI](https://github.com/Ralioco/ralio-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Ralioco/ralio-python/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+The official Python client for the [Ralio](https://ralio.co) agentic payment API.
+
+It handles the machine-authentication path end to end — OAuth 2.1
+`client_credentials` with `private_key_jwt` and DPoP-bound access tokens — so
+your integration can talk to an agent without hand-rolling JWT signing, proof
+generation, or token refresh.
+
+> **Scope.** This SDK targets autonomous integrations (CI jobs, agent hosts,
+> server-side callers). It authenticates as a **credential binding**, which can
+> hold the `agents:execute` and `transactions:read` scopes. Agent and binding
+> management (`agents:config`) is a human-only operation in the console and is
+> intentionally not part of this SDK.
+
+## Installation
+
+```bash
+pip install ralio
+```
+
+Requires Python 3.10+.
+
+## Authentication model
+
+Ralio's machine path has no shared secrets. Each credential is a P-256 private
+key that lives on exactly one host:
+
+1. The **owner** mints a one-time registration ticket in the console
+   (**Settings → Credentials → New credential**), choosing the target agent and
+   a scope ceiling. That is where consent happens. They send you the
+   `ralio-reg-…` ticket.
+2. You call `ralio.register()` once on the agent host. It generates a keypair
+   locally and submits the public key with the ticket; the binding is active
+   as soon as the server responds — no approval step, no polling. The owner
+   gets an email receipt with a revoke link. The credentials are persisted to
+   `~/.ralio/` — the same store the `ralio` CLI uses, so `register()` and
+   `ralio auth agent` are interchangeable.
+3. From then on, `RalioClient` mints and refreshes DPoP-bound access tokens
+   transparently and signs a fresh proof for every request.
+
+See the [API authentication guide](https://docs.ralio.co/api-reference/authentication)
+for the protocol details.
+
+## Quickstart
+
+With the owner's ticket in `RALIO_REGISTRATION_TICKET`, onboarding is two
+calls:
+
+```python
+import ralio
+
+ralio.register()  # run once; the binding is active when this returns
+
+client = ralio.RalioClient()  # zero-config: reads the persisted credentials
+reply = client.chat.send(message="What is my current balance?")
+```
+
+`register()` activates the binding in a single call (or raises
+`RalioRegistrationError` if the ticket is invalid, expired, or already
+consumed). The private key is generated locally, written to
+`~/.ralio/keys/<jkt>.pem`, and never leaves the host.
+
+Everything is overridable when you want to manage credentials yourself:
+
+```python
+import ralio
+
+binding = ralio.register(
+    ticket="ralio-reg-...",                      # instead of RALIO_REGISTRATION_TICKET
+    private_key_path="ralio-key.pem",            # generated and written here
+    requested_scopes=["agents:execute", "transactions:read"],
+)
+print(binding.client_id)   # cb_... — store this alongside the key
+```
+
+## Use the client
+
+```python
+import ralio
+
+# Zero-config: reads the credentials persisted by register() / `ralio auth agent`.
+client = ralio.RalioClient()
+
+# Or manage credentials yourself:
+# client = ralio.RalioClient(
+#     client_id="cb_...",
+#     private_key_path="ralio-key.pem",
+# )
+
+# Synchronous chat — agent_id is resolved automatically for a single-agent
+# credential; pass agent_id explicitly to target one of several agents.
+reply = client.chat.send(message="What is my current balance?")
+print(reply.reply)
+
+# Streaming chat (server-sent events)
+for event in client.chat.stream(message="List my recent payments"):
+    if event.event == "text_delta":
+        print(event.text, end="", flush=True)
+    elif event.event == "tool_started":
+        print(f"\n[tool] {event.data['tool_name']}")
+
+# Transactions — list endpoints are paginated; a Page is iterable and sized.
+page = client.transactions.list(per_page=20)
+print(f"showing {len(page)} of {page.total} transactions (page {page.page})")
+for txn in page:
+    print(txn.date, txn.amount, txn.currency, txn.creditor, txn.status)
+
+# Payment intents — what the agent proposed, with per-leg execution detail.
+for intent in client.payment_intents.list(per_page=20):
+    print(intent.created_at, intent.total_amount, intent.currency, intent.approval_status)
+
+client.close()
+```
+
+`RalioClient` is also a context manager:
+
+```python
+with ralio.RalioClient() as client:
+    ...
+```
+
+## Environment variables
+
+| Variable                    | Meaning                                                              |
+| --------------------------- | -------------------------------------------------------------------- |
+| `RALIO_REGISTRATION_TICKET` | Default ticket for `register()` — same variable the CLI reads        |
+| `RALIO_API_URL`             | API origin (default `https://api.ralio.co`)                          |
+| `RALIO_CONFIG_DIR`          | Credential store location (default `~/.ralio`, shared with the CLI)  |
+
+## Payments
+
+There is no `payments.create()` method by design. Payments are executed by the
+**agent**, not by direct REST calls: drive the agent with `chat.send` /
+`chat.stream` ("Pay £500 to Bob for the April invoice") and it will create the
+payment, subject to its spend limits and approval rules. Use
+`transactions.list` (executed payments) and `payment_intents.list` (what the
+agent proposed, with per-leg status) to read what the agent did.
+
+## Errors
+
+All errors subclass `ralio.RalioError`:
+
+| Exception | When |
+|-----------|------|
+| `RalioAuthError` (401) | Missing/invalid token, failed assertion, or rejected DPoP proof |
+| `RalioPermissionError` (403) | Token lacks the required scope, or resource not owned |
+| `RalioNotFoundError` (404) | Resource doesn't exist |
+| `RalioValidationError` (422) | Invalid field values or business-rule violation |
+| `RalioRateLimitError` (429) | Rate limited — back off and retry |
+| `RalioAPIError` | Any other HTTP error (carries `status_code`, `detail`) |
+| `RalioRegistrationError` | Registration failed (invalid / expired / consumed ticket) |
+| `RalioConfigError` | Local configuration problem |
+
+```python
+import ralio
+
+try:
+    client.chat.send(agent_id="...", message="...")
+except ralio.RalioPermissionError as exc:
+    print("scope problem:", exc.detail)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+mypy
+pytest -q
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).