Metadata-Version: 2.4
Name: ranbval-sdk
Version: 0.2.13
Summary: Ranbval Runtime Blind Decryption Python SDK
Author: Ahsan Tariq
Requires-Python: >=3.10,<4.0
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: Programming Language :: Python :: 3.14
Requires-Dist: certifi (>=2024.0.0)
Requires-Dist: cryptography (>=42.0.0,<43.0.0)
Requires-Dist: openai (>=1.12.0,<2.0.0)
Description-Content-Type: text/markdown

# Ranbval Python SDK

A secure, fully Zero-Memory execution wrapper for AI and generic API clients. 
Instead of storing plaintext credentials in `os.environ`, this SDK keeps them completely invisible. It intercepts the client construction, performs a blind PBKDF2 decryption in-memory at runtime, securely passes the decrypted credential only to the relevant library, and immediately purges it.

## Quick Start (Pre-Built Clients)

For the most popular SDKs, we offer drop-in replacements. Simply swap your import and let Ranbval handle the encryption boundary without changing your codebase format.

### OpenAI
```python
import os
from ranbval_sdk import SecureOpenAI

os.environ["OPENAI_API_KEY"] = "ranbval.xxxxxxxxxx.[BLOB].ahsan"
os.environ["RANBVAL_VAULT_SECRET"] = "your_master_password"

client = SecureOpenAI()
# Uses native standard client methods safely behind the scenes
client.chat.completions.create(model="gpt-4", ...) 
```

### Anthropic / Mistral / Supabase
We offer similarly secure blind wrappers for other leading SDKs:
```python
from ranbval_sdk import SecureAnthropic, SecureMistral, SecureSupabase

anthropic_client = SecureAnthropic()
mistral_client = SecureMistral()
```

## Universal Custom Platform Wrapper

If you need to strictly encrypt secrets for an SDK that we don't natively ship (e.g. `Stripe`, `Twilio`, or internal APIs), you can use the Universal Integration Engine to wrap ANY Python class dynamically:

```python
from ranbval_sdk import build_secure_client
import stripe

# Generates a Drop-in Secure Proxy for the Stripe SDK dynamically
SecureStripe = build_secure_client(
    SDKClass=stripe.StripeClient,
    env_var_name="STRIPE_SECRET_KEY",
    key_kwarg="api_key"
)

# Completely encrypted in ENV. Handled securely in-memory.
stripe_client = SecureStripe()
```

## Telemetry

Pre-built clients enqueue **usage and security metadata** to your Ranbval API (`POST {RANBVAL_HOST}/api/telemetry`) on a **background worker thread** so model calls are not blocked.

### Hosted production (dashboard online)

Use the **password-manager** origin (default in recent SDK versions: `https://ranbval-password-manager.onrender.com`). The **auth** URL is only for login in the browser; telemetry never goes there. Your Ranbval token must come from the **same** Supabase project as the dashboard, or the server will not attach events to your project.

| Variable | Meaning |
|----------|---------|
| `RANBVAL_HOST` | Password-manager origin (no `/api` suffix). Defaults to the hosted service; set to `http://localhost:8006` for local backends. |
| `RANBVAL_TELEMETRY` | `0`, `false`, `off` — disable telemetry entirely |
| `RANBVAL_TELEMETRY_DEBUG` | `1` / `true` — print failures from `POST …/api/telemetry` to stderr (wrong `RANBVAL_HOST`, network, etc.) |

**Important:** `RANBVAL_HOST` must be the **password-manager** origin (telemetry + repo policy). Do not point it at the auth service; that URL does not ingest telemetry.

**SSL errors on macOS** (`CERTIFICATE_VERIFY_FAILED`): the SDK depends on `certifi` for HTTPS to telemetry and repo-policy. Run `pip install -U certifi ranbval-sdk` or use the Python.org installer’s “Install Certificates” command if issues persist.

For the full ingest schema, pagination, and dashboard behavior, see the **[ranbval-password-manager README](../ranbval-password-manager/README.md)** (Telemetry section).

## Git remote allowlist

If the project owner adds allowed repo URLs in the dashboard (or via `POST /api/projects/{id}/whitelist`), the SDK calls **`GET /api/public/repo-policy?client_salt=…`** and compares the result to the local **`git remote get-url origin`**. When **`enforce_allowlist`** is true (non-empty list), decrypt fails with a clear **`PermissionError`** before any provider API call.

| Variable | Meaning |
|----------|---------|
| `RANBVAL_HOST` | Same origin as telemetry (paths like `/api/public/repo-policy` are appended internally). |
| `RANBVAL_SKIP_REPO_CHECK` | Set to `1` / `true` to skip the check (development only; not for production). |

Empty allowlist on the server means **no** client-side enforcement.

