qaldron 2.0.0
Quantum-Assisted Ledger for Distributed Autonomous Networks
Requires Python: >=3.8

# QALDRON v2.0 - Infrastructure SDK for Multi-Agent AI

**The only SDK that combines quantum-resistant security + cost tracking + compliance audit trails**

[![PyPI version](https://badge.fury.io/py/qaldron.svg)](https://pypi.org/project/qaldron/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 🚀 Quick Start

### Installation
```bash
pip install qaldron
```

### Free Tier (Offline, No API Key)
```python
from qaldron.client import AgentClient

# Works completely offline - no API key needed!
client = AgentClient(agent_id="financial_agent")

# Every message is cryptographically signed
envelope = client.send_message(
    to_agent="compliance_agent",
    content="Transfer $1M to account XYZ"
)

# Tamper detection built-in
if not client.verify_message(envelope):
    raise SecurityError("Message was modified!")
```

**Output:**
```
🔒 Free mode: Local-only (1000 msgs/day)
✅ Message signed with quantum-resistant hash
✅ Stored locally at ~/.qaldron/
```

### Premium Tier (Cloud Monitoring + Analytics)
```python
# Add API key to unlock premium features
client = AgentClient(
    agent_id="sales_agent",
    api_key="sk-premium-your-key-here"  # Get free at qaldron.io
)

# Now with real-time telemetry
client.send_message("analyst", "Analyze Q4 sales data")

# View live dashboard:
# https://qaldron.io/portal
```

**Premium Features:**
- 📊 Real-time agent activity dashboard
- 💰 Per-agent cost tracking (LLM costs)
- 📈 100,000 messages/month
- 📄 Compliance audit trail export (CSV)

---

## ✨ Why QALDRON?

### Enterprise Pain Points Solved:

#### 1. **Security** - "How do I know agents aren't lying?"
```python
# ✅ SOLVED: Cryptographic message signing
envelope = client.send_message("agent", "Approve $10M transaction")

# If anyone modifies the message:
if not client.verify_message(envelope):
    print("🚨 FRAUD DETECTED")  # ← Catches tampering instantly
```

#### 2. **Compliance** - "Regulators want proof"
```python
# ✅ SOLVED: Every message has an audit trail
client.export_audit_trail()  # Downloads CSV with signatures

# Legally admissible evidence:
# - Timestamp: 2026-02-03T10:30:45Z
# - Agent: financial_agent
# - Signature: a8f3d9e2c4b7...
# - Verified: ✅
```

#### 3. **Cost Control** - "LLM costs are out of control"
```python
# ✅ SOLVED: Automatic cost tracking
client.chat("Summarize 500-page document", model="gpt-4")

# Dashboard shows:
# - Agent: analyst → $2.45
# - Agent: writer → $1.32
# - Total: $3.77
```

---

## 🎯 Features

| Feature | Free Tier | Premium Tier |
|---------|-----------|--------------|
| **Quantum-Resistant Signing** | ✅ | ✅ |
| **Tamper Detection** | ✅ | ✅ |
| **Local Message Storage** | ✅ | ✅ |
| **Messages/Month** | 1,000/day | 100,000/month |
| **Real-Time Dashboard** | ❌ | ✅ |
| **Cost Tracking** | ❌ | ✅ |
| **Audit Trail Export** | ❌ | ✅ |
| **Team Collaboration** | ❌ | ✅ |

---

## 📖 Full Documentation

### Basic Usage

```python
from qaldron.client import AgentClient

# Initialize
client = AgentClient(agent_id="my_agent")

# Send message
envelope = client.send_message(
    to_agent="other_agent",
    content="Process invoice #12345",
    metadata={"priority": "high"}
)

# Retrieve messages
messages = client.get_messages(sender="other_agent")

# Check usage (free tier)
stats = client.get_usage_stats()
print(f"Used {stats['messages_today']}/{stats['daily_limit']}")
```

### Advanced: Custom LLM Integration

```python
from openai import OpenAI

# Bring your own LLM
llm = OpenAI().chat.completions.create

client = AgentClient(
    agent_id="analyst",
    api_key="sk-premium-xxx",
    llm=llm  # ← QALDRON tracks costs automatically
)

# Automatically tracked
response = client.chat("Analyze Q4 revenue", model="gpt-4")

# Dashboard shows:
# - Model: gpt-4
# - Cost: $0.12
# - Tokens: 1,240
```

### Tamper Detection Example

```python
from qaldron.layer2 import MessageEnvelope
from qaldron.layer1 import MarkBluHasher

# Create envelope
hasher = MarkBluHasher()
envelope = MessageEnvelope(
    sender="agent_a",
    receiver="agent_b",
    content="Transfer $1,000,000"
)

# Sign
signature = envelope.sign(hasher)

# ⚠️ Attacker modifies content
envelope.content = "Transfer $5,000,000"  # Fraud!

# Verification catches it
if not envelope.verify(hasher):
    print("🚨 MESSAGE TAMPERED - FRAUD DETECTED")
    # Block transaction, alert security
```

---

## 🏢 Enterprise Use Cases

### Financial Services
```python
# SEC compliance: Every trade must have audit trail
trade_client = AgentClient(agent_id="trading_bot", api_key=api_key)
trade_client.send_message("compliance", "Execute trade: 1000 shares AAPL")

# Later: Export for SEC audit
trade_client.export_audit_trail()  # Legally admissible CSV
```

### Healthcare (HIPAA)
```python
# Patient data access must be logged
health_client = AgentClient(agent_id="nurse_assistant", api_key=api_key)
health_client.send_message("doctor_agent", "Patient chart for John Doe")

# HIPAA audit: Who accessed what, when?
# All tracked automatically with cryptographic proof
```

### Customer Support
```python
# Track LLM costs per support agent
support_client = AgentClient(agent_id="support_bot_1", api_key=api_key)

# Dashboard shows:
# - Agent 1: $45.23/month (efficient! ✅)
# - Agent 2: $312.14/month (needs optimization ⚠️)
```

---

## 🛠️ Installation & Setup

### 1. Install Package
```bash
pip install qaldron
```

### 2. Get API Key (Optional)
Visit [qaldron.io](https://qaldron.io) and sign up for free premium tier.

### 3. Start Using
```python
from qaldron.client import AgentClient

# Free tier - works immediately
client = AgentClient(agent_id="my_first_agent")
client.send_message("other_agent", "Hello world!")
```

---

## 🔐 Security Architecture

### MarkBluHasher Algorithm
QALDRON uses a custom **quantum-resistant hashing** algorithm combining:
1. Quantum circuit simulation (Walsh-Hadamard transform)
2. Classical diffusion layers
3. Deterministic S-Box generation

**Result:** Messages are tamper-proof even against future quantum computers.

### Data Isolation
- Each API key is linked to a unique user account
- Telemetry data is isolated by `user_email`
- No cross-contamination between customers

---

## 📊 Monitoring Dashboard

Premium users get access to:

- **Real-Time Activity Feed** - See agent messages as they happen
- **Cost Analytics** - Per-agent LLM cost breakdown with charts
- **Usage Quotas** - Track monthly message usage (100k limit)
- **Audit Export** - Download CSV for compliance audits

Visit: [qaldron.io/Portal](https://qaldron.io/portal)

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file

---

## 🌐 Links

- **Website:** [qaldron.io](https://qaldron.io)
- **Documentation:** [docs.qaldron.io](https://docs.qaldron.io)
- **Dashboard:** [qaldron.io/portal](https://qaldron.io/portal)
- **GitHub:** [github.com/qaldron/qaldron](https://github.com/qaldron/qaldron)
- **PyPI:** [pypi.org/project/qaldron/](https://pypi.org/project/qaldron/)

---

## 💬 Support

- **Email:** support@qaldron.io
- **Issues:** [GitHub Issues](https://github.com/qaldron/qaldron/issues)
- **Discord:** [Join Community](https://discord.gg/qaldron)

---

**Made with ❤️ by the QALDRON Team**

*Securing the future of multi-agent AI*