Metadata-Version: 2.4
Name: merkleon-sdk
Version: 0.3.1
Summary: Cryptographic proof of every AI agent action — tamper-evident, externally verifiable
Author-email: Merkleon <hi@merkleon.in>
Maintainer-email: Merkleon <hi@merkleon.in>
License: MIT
Project-URL: Homepage, https://merkleon.in
Project-URL: Documentation, https://merkleon.in/docs
Project-URL: Repository, https://github.com/Het-Kalariya/VeritasAgent
Project-URL: Issues, https://github.com/Het-Kalariya/VeritasAgent/issues
Project-URL: Changelog, https://github.com/Het-Kalariya/VeritasAgent/releases
Keywords: ai,agents,ai-agents,ai-safety,ai-audit,ai-compliance,audit,audit-trail,audit-log,compliance,observability,cryptographic,cryptography,merkle,merkle-tree,merkle-chain,ed25519,sha-256,tamper-evident,tamper-proof,llm,llm-security,llm-monitoring,openai,anthropic,langchain,mcp,model-context-protocol,soc2,iso-27001,gdpr,hipaa,eu-ai-act
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: langchain>=0.1.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Dynamic: license-file

# Merkleon Python SDK

[![PyPI](https://img.shields.io/pypi/v/merkleon-sdk.svg?color=ff6b00)](https://pypi.org/project/merkleon-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/merkleon-sdk.svg)](https://pypi.org/project/merkleon-sdk/)
[![License](https://img.shields.io/pypi/l/merkleon-sdk.svg)](https://github.com/Het-Kalariya/VeritasAgent/blob/main/sdk/LICENSE)

**Cryptographic proof of every AI agent action — tamper-evident, externally verifiable.**

Drop this SDK into your agent and every LLM call, tool invocation, file operation, or network request is hashed (SHA-256), chained (Merkle), and signed (Ed25519). The result is a server-side audit trail that any third party can mathematically verify — no trust in Merkleon required.

## Why

Logs aren't proof. A startup with `s3://my-bucket/logs/` has nothing a regulator, lawyer, or post-incident investigator can rely on — they can be edited after the fact. Merkleon turns each event into a link in a hash chain anchored by per-tenant Ed25519 keys. Tampering is detectable down to the byte.

- ✅ Tamper-evident — break the chain, break the proof
- ✅ Externally verifiable — public verifier, no Merkleon trust needed
- ✅ Stable across redeploys — your signing identity survives
- ✅ 4 lines of code to instrument any agent

## Install

```bash
pip install merkleon-sdk
```

Optional auto-instrumentation extras:

```bash
pip install "merkleon-sdk[langchain]"   # LangChain callback
pip install "merkleon-sdk[openai]"      # OpenAI client wrapper
pip install "merkleon-sdk[all]"
```

## Quickstart

```python
from merkleon import Merkleon

m = Merkleon(
    endpoint="https://api.merkleon.in",
    api_key="va_…",                  # Settings → API Keys → Generate
    agent_id="research-bot",
)

# Sign one action
result = m.prove(
    "gpt-4o called: summarize Q4 earnings",
    agent="research-bot",
)
print(result["event_id"], result["event_hash"])
```

The response includes the server-assigned `event_id`, the SHA-256 `event_hash`, the `prev_hash` that anchors this event to the chain tip, an Ed25519 `signature`, and any anomaly `alerts` the detection layer raised:

```json
{
  "status": "ingested",
  "event_id": "evt_c2db625a1166429c",
  "event_hash": "c0664aba383cf8a8…",
  "prev_hash": "0000000000000000…",
  "signature": "5e2b9d7c…",
  "alerts": []
}
```

## Get an API key

1. Sign up at [merkleon.in](https://merkleon.in)
2. Settings → **API Keys** → **Generate**
3. Set in your environment:

```bash
export MERKLEON_API_KEY="va_…"
```

The SDK reads `MERKLEON_API_KEY` and `MERKLEON_ENDPOINT` from the environment, so most code only needs:

```python
from merkleon import Merkleon
m = Merkleon(agent_id="research-bot")
```

## Higher-level helpers

```python
m.track_llm(model="gpt-4o", prompt="...", token_count=412, cost_usd=0.0021)
m.track_tool(tool="bash", args={"cmd": "ls /tmp"})
m.track_file_read(path="/etc/secrets.json")
m.track_network(host="api.openai.com", port=443)
```

Each one wraps `prove()` with the right event-type shape so you don't have to think about it.

## Verifying a proof

Anyone — including you, your customer's auditor, or a regulator — can verify an event without trusting Merkleon's server:

```bash
curl "https://api.merkleon.in/api/v1/chain/integrity?agent_id=research-bot"
# → {"clean": true, "events_verified": 1247, "broken_at": null}
```

Or use [merkleon.in/verify](https://merkleon.in/verify) and paste an `event_id`.

## What gets sent

Hashes, never raw content (unless you opt in). Default behaviour:

| Field | Sent? |
|---|---|
| Prompt text | ❌ Only its SHA-256 hash |
| Response text | ❌ Only its SHA-256 hash |
| Tool arguments | Hashed when the tool is sensitive |
| File path | ✅ As-is (PII scrubbed) |
| Token count, cost, model name | ✅ |
| Process name, cmdline | ✅ (PII scrubbed) |
| Network destination host + port | ✅ |

PII scrubbing is on by default. Disable with `Merkleon(scrub_pii=False)`.

## Async / batched mode

For high-throughput agents, batch events client-side and flush periodically:

```python
m = Merkleon(async_mode=True, batch_size=20, flush_interval=2.0)
# prove() now returns immediately and pushes to an in-memory queue
# Background thread flushes every 2s or every 20 events
m.flush()  # explicit flush before shutdown
```

## Pricing

Free tier covers small projects: 100K events / month, 7-day retention, 1 agent. Paid tiers add longer retention, witness cosigners, SIEM export, and SOC 2 evidence packs. See [pricing](https://merkleon.in/pricing).

## Links

- 🌐 [merkleon.in](https://merkleon.in)
- 📚 [Documentation](https://merkleon.in/docs)
- 📝 [Blog](https://merkleon.in/blog)
- 🐙 [GitHub](https://github.com/Het-Kalariya/VeritasAgent)
- 🐍 [PyPI: merkleon-sdk](https://pypi.org/project/merkleon-sdk/)
- 📦 [npm: merkleon-sdk](https://www.npmjs.com/package/merkleon-sdk) (TypeScript SDK)

## License

MIT — see [LICENSE](LICENSE).
