Metadata-Version: 2.4
Name: agenizai-sdk
Version: 2.5.0
Summary: Zero-trust ML Risk Oracle and Firewall for Algorand AI Agents
Home-page: https://github.com/Ishankalhe911/ageniz-sdk
Author: Ishan Kalhe
Author-email: ishankalhe1@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: py-algorand-sdk>=2.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🛡️ Ageniz SDK

**The Zero-Trust ML Risk Oracle and Firewall for Algorand AI Agents.**

Ageniz is a developer-first security protocol that prevents AI Agents (like trading bots or autonomous assistants) from draining wallets through hallucinations, prompt injections, or malicious intent.

By routing all agent transactions through an off-chain Machine Learning Oracle and validating them on-chain via an immutable Smart Contract Vault, Ageniz provides enterprise-grade "Defense in Depth."

---

## ✨ Features

* **ML Intent Scoring:** Prevents prompt-injection attacks and anomalies before they reach the blockchain.
* **Cryptographic Bait-and-Switch Protection:** Recipient addresses and amounts are bound into the Oracle's Ed25519 signature.
* **Replay Attack Immunity:** Strict, timestamp-based Nonce tracking stored in Algorand Local State.
* **👻 Shadow Mode (New):** Safely test the Oracle in production without gating payments to collect real-world training data.
* **Automated x402 Routing:** Seamlessly bundles security tolls and Vault payments into a single Atomic Transaction.

---

## 📦 Installation

```bash
pip install agenizai-sdk

```

---

## 🚀 Quickstart: Live Firewall Mode

### 1. Environment Setup

Create a `.env` file in your project root with your Algorand wallet details and Ageniz configuration:

```env
# Your AI Agent's Wallet
DEPLOYER_MNEMONIC="your twenty five word algorand testnet mnemonic phrase goes here..."

# Ageniz Protocol Config
APP_ID=760267917
ORACLE_URL="https://ageniz-backend.onrender.com"

```

### 2. Execute a Protected Payment (`pay()`)

In Live Firewall mode, the payment is strictly gated. The SDK automatically builds a 3-transaction Atomic Group (ABI Validation + Vendor Payment + Protocol Fee). If the ML Oracle flags the transaction, it never reaches the blockchain.

```python
import os
from dotenv import load_dotenv
from ageniz_sdk.core import AgenizSDK

load_dotenv()

# 1. Initialize the Firewall
agent = AgenizSDK(
    wallet_mnemonic=os.getenv("DEPLOYER_MNEMONIC"),
    ageniz_api_key="your_developer_api_key",
    app_id=int(os.getenv("APP_ID")),
    oracle_url=os.getenv("ORACLE_URL")
)

# 2. Opt-in to the Vault (Required once per wallet for Nonce tracking)
agent.opt_in()

# 3. Execute a Protected Payment
print("Requesting payment authorization...")

result = agent.pay(
    recipient="YZ2L7MGFX35YUGVPB2YF3S4K3KQVNJ4BWYFIB3UVMJNQAPEME3MK7ME2DU",
    amount_algo=1.0,
    context="Paying external weather API for daily data fetch."
)

# 4. Handle the Verdict
if result["status"] == "SUCCESS":
    print(f"✅ Payment cleared firewall! TxID: {result['tx_id']}")
elif result["status"] == "BLOCKED":
    print(f"❌ Payment blocked by ML Oracle: {result['reason']}")

```

---

## Shadow Mode: Observe & Train

For developers integrating Ageniz into an existing live agent, gating transactions immediately can be risky. **Shadow Mode** allows you to monitor your agent's behavior and see what Ageniz *would* have done, without actually blocking any payments.

### Payment Clarification in Shadow Mode

When you use `observe()` instead of `pay()`:

* **No Atomic Group:** The SDK submits a standard, direct Algorand `PaymentTxn`.
* **No Gating:** The transaction **always executes** on the blockchain, regardless of the ML verdict.
* **No Fees/Custody:** The Ageniz Smart Contract is bypassed entirely, and no protocol fees are charged.

### Using `observe()`

```python
result = agent.observe(
    recipient="YZ2L7MGFX35YUGVPB2YF3S4K3KQVNJ4BWYFIB3UVMJNQAPEME3MK7ME2DU",
    amount_algo=1.0,
    context="Testing weather API integration.",
    scenario_tag="beta_testing"
)

print(f"💸 Payment Executed! TxID: {result['tx_id']}")

# See what Ageniz WOULD have done:
print(f"Ageniz Verdict: {result['ageniz_verdict']}") 
if result['would_have_blocked']:
    print("⚠️ Warning: Ageniz would have blocked this transaction in Live Mode!")

# Save this ID to provide human feedback later
shadow_id = result["shadow_log_id"] 

```

### 🧠 Closing the Loop: Submitting Human Verdicts

Shadow Mode is designed for data collection and fine-tuning. Every `observe()` call logs the transaction details and the hypothetical ML verdict to the Ageniz database, returning a unique `shadow_log_id`.

Developers or human operators can later review these logs and submit a **Human Verdict** (`LEGITIMATE`, `ATTACK`, or `AMBIGUOUS`) to train the ML model on false positives/negatives.

You can submit ground-truth labels directly to the Ageniz REST API:

```bash
# Label a flagged transaction as a false positive (LEGITIMATE)
curl -X PATCH https://ageniz-backend.onrender.com/shadow/<shadow_log_id>/verdict \
  -H "Content-Type: application/json" \
  -d '{"human_verdict": "LEGITIMATE"}'

```

By running in Shadow Mode and labeling the data, you can build a perfectly tailored ML risk profile for your specific AI agent before switching your code to `pay()`.

---

## 🔐 Architecture: The Non-Custodial Fortress

Ageniz does not rely solely on off-chain AI. It enforces security on-chain using an **Atomic Verification Group**.

When `agent.pay()` is called:

1. The SDK sends the request context to the **Ageniz ML Oracle**.
2. If deemed `SAFE`, the Oracle generates a cryptographic Ed25519 signature binding the exact `(amount, recipient, nonce)`.
3. The SDK bundles this signature and the agent's payment into an **Algorand Atomic Group**.
4. The **Ageniz Smart Contract** (Txn 0) verifies the Oracle's signature via `ed25519verify` and peeks at the agent's payment (Txn 1) via `Gtxn` to ensure the amount and recipient were not tampered with. If the math matches, the payment executes trustlessly.

---

## 📊 Checking Agent Reputation

You can monitor your agent's standing with the protocol at any time:

```python
status = agent.get_status()

print(f"Reputation Score : {status['reputation_score']}/100")
print(f"Velocity         : {status['velocity']} tx/hr")
print(f"Fee Tier         : {status['fee_tier']['tier']} ({status['fee_tier']['fee_pct']}%)")

```

---

## 📄 License

This project is licensed under the MIT License.
