merkl-sdk 0.1.0__tar.gz

merkl_sdk-0.1.0/.gitignore

@@ -0,0 +1 @@
+dist/

merkl_sdk-0.1.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# merkl-sdk
+
+Thin Python HTTP client for Merkl. This is what agent developers `pip install` to instrument their agents.
+
+Developed in the merkl monorepo (`packages/merkl-sdk`); the standalone `merkl-sdk` repo is a read-only export — change things there via the monorepo, then re-run the subtree split.
+
+## What This Package Does
+
+- `MerklClient` — main entry point (endpoint URL, agent_id, API key)
+- `SessionContext` — async context manager for session lifecycle
+- `@trace` and `@guardrail` decorators for auto-recording actions (concurrency-safe via `contextvars`)
+- `merkl` CLI — `merkl install --claude-code [--global]` writes hooks into `settings.json`
+- `HookState` (`merkl/hooks/claude_code.py`) — one tempfile-backed object per Claude Code session, owns session_id, turn rotation, dataflow snippets, sub-agent parent linkage
+- Framework integrations: LangChain, OpenAI, Google ADK, CrewAI — all route through `merkl.integrations._common.record_tool_call` so new action fields plumb through one call site
+- Shared value objects (`SHA256Hash`, `canonical_hash`, `SessionId`, `ActionId`, `Timestamp`, enums, errors) imported by both SDK and merkl-api
+
+## What This Package Does NOT Do
+
+No domain logic, no Merkle trees, no batching, no Solana, no persistence. Pure HTTP client.
+
+## Key Files
+
+- `merkl/sdk/client.py` — `MerklClient`: creates sessions, holds transport
+- `merkl/sdk/session_context.py` — `SessionContext`: async with, `record_action()`, auto-close; binds itself to the `_current_session` contextvar on enter
+- `merkl/sdk/transport.py` — `AsyncTransport`: httpx with retry + buffering
+- `merkl/sdk/decorators.py` — `@trace`, `@guardrail` + `set_current_session` / `reset_current_session` backed by `contextvars`
+- `merkl/integrations/_common.py` — `record_tool_call()` shared by every framework adapter
+- `merkl/integrations/` — langchain.py, openai.py, google_adk.py, crewai.py
+- `merkl/hooks/claude_code.py` — Claude Code PostToolUse + SessionEnd hook; `HookState` class owns all per-session scratch state
+- `merkl/cli/main.py` — `merkl install --claude-code` CLI
+- `merkl/shared/hashing.py` — `SHA256Hash`, `canonical_hash()`, `canonical_bytes()` (deterministic JSON-sorted-keys hashing shared by SDK, hook, and server-side leaf verification)
+- `merkl/shared/` — ids.py, timestamps.py, enums.py, errors.py, events.py
+
+## Usage
+
+```python
+from merkl.sdk import MerklClient
+
+client = MerklClient(endpoint="http://localhost:8000", agent_id="my-agent", api_key="mk_...")
+async with client.session(goal="Process refunds", allowed_tools=["query_db"]) as session:
+    result = await session.record_action(tool_name="query_db", input_data="SELECT ...", output_data={...})
+    # result includes leaf_index
+```
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest  # 137 tests
+```
+
+## Guidelines
+
+- Keep it thin. Server logic belongs in the merkl-api package.
+- `merkl/shared/` is imported by both the SDK and the merkl-api server (in the monorepo) — changes affect both, and `canonical_hash` / leaf encodings are proof-format-critical.
+- Framework integrations should end at `record_tool_call()` in `_common.py`, not call `session.record_action()` directly. New action fields flow through one site.
+- Input/output hashing must go through `canonical_hash()`. Raw `str()` is non-deterministic for dicts; the SDK and the Claude Code hook must produce identical leaf hashes for the same logical payload.
+- The SDK must never import from `merkl_api.*`.
+- Dependencies must stay minimal (uuid6, httpx, cryptography). This ships to customers.
+
+## Known Issues
+
+- `@trace` and `@guardrail` decorators only wrap async functions; sync is passthrough
+- `@guardrail` runs client-side policy (allowlist or callable); no server-side evaluation yet

merkl_sdk-0.1.0/INSTALL.md

@@ -0,0 +1,93 @@
+---
+name: merkl-install
+description: Install Merkl into the user's Claude Code and verify it records a real session, with minimal prompting. Use for first-time setup, reconnect, or "why isn't Merkl recording?".
+---
+
+# merkl install
+
+You are driving this install. Do as much as you can yourself; ask the user only for the one thing you cannot get — their API key — and only when you actually need it. After every step, verify before moving on.
+
+Merkl records what an AI agent does, hashes each action into a Merkle tree, and lets anyone verify what happened later. Installing it into Claude Code means registering a hook that fires on every tool call. Full reference: `README.md`.
+
+## Install prompt contract
+
+- Prefer running commands over telling the user to run them.
+- The user must do exactly two things you cannot: (1) get an API key from their dashboard, (2) reload hooks (`/hooks` or restart) — Claude Code loads hooks at session start, so a freshly written hook is not live in the current session. Everything else is yours.
+- Do not print the API key back to the user or paste it into any file they can commit. It goes into the hook command and shell profile only.
+- Verify with a real recorded action, not by assuming the config is correct.
+
+## 1. Install the package
+
+```bash
+pip install merkl-sdk
+merkl --help
+```
+
+If `merkl: command not found` after a successful `pip install`, the package installed into an environment whose scripts are not on `PATH`. Escalate from the actual cause:
+
+- **A pyenv/conda/system Python mismatch** → install with the interpreter Claude Code's hooks will use. `pipx install merkl-sdk` (or `uvx merkl`) puts a stable global `merkl` on `PATH` and is the most robust choice. Prefer it.
+- **A project venv** → the install is fine, just not global; either activate that venv or use `pipx`.
+
+Confirm `command -v merkl` prints a path before continuing.
+
+## 2. Get the API key (the one thing you must ask for)
+
+The key authenticates the hook. Only the user can mint it.
+
+- If `MERKL_API_KEY` is already set in the environment, use it — do not ask.
+- Otherwise ask the user to: open their Merkl dashboard → create an org if they have not → API Keys → create one → copy the `mk_...` value (shown once). While they do this, wait and re-check; do not move on without it.
+- Self-hosted only: also note their API URL for `--endpoint`. The default is `api.merkl.ai`, hardcoded — do not pass `--endpoint` for the hosted service.
+
+## 3. Install the hook
+
+```bash
+merkl install --claude-code --global
+```
+
+The installer prompts for the API key if `MERKL_API_KEY` is unset and bakes it into the hook command, so no shell-profile editing is needed. If you already have the key, pass it non-interactively:
+
+```bash
+merkl install --claude-code --global --api-key mk_...
+```
+
+This registers five events (PostToolUse, SessionEnd, UserPromptSubmit, PermissionRequest, PermissionDenied) in the global settings and uses the current interpreter, not a bare `python`. Read back the written settings file and confirm the hook command contains `merkl.hooks.claude_code` and the key.
+
+## 4. Load the hook
+
+Hooks load at session start, so the hook you just wrote is not active in this session. Tell the user to either run `/hooks` once (reloads config) or start a new Claude Code session. You cannot do this for them — `/hooks` is a user UI action.
+
+## 5. Verify it records — do this, do not assume
+
+Fire a synthetic PostToolUse payload through the hook exactly as Claude Code would, then check the session landed. Use the same interpreter the hook uses.
+
+```bash
+echo '{"session_id":"merkl-install-check","hook_event_name":"PostToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"},"tool_response":"hi","transcript_path":"/nonexistent"}' \
+  | MERKL_API_KEY=<key> python -m merkl.hooks.claude_code
+echo "hook exit: $?"
+```
+
+Then confirm the server received it:
+
+```bash
+curl -s -H "Authorization: Bearer <key>" https://api.merkl.ai/v1/sessions | head -c 400
+```
+
+A session with `agent_id` `claude-code` (or the `MERKL_AGENT_ID` you set) and `action_count >= 1` means it works. If you see it, you are done — tell the user their next real Claude Code session records automatically, and point them at their dashboard.
+
+## Troubleshooting — read the error, escalate from there
+
+Do not restart from step 1. Match the symptom:
+
+- **Hook exits 0 but no session appears** → the hook swallows errors (`2>/dev/null || true`), so a silent failure looks like success. Re-run the hook payload *without* the `2>/dev/null || true` suppression to see the real error, then match below.
+- **HTTP 401 / "Invalid API key"** → the key is wrong, revoked, or from a different Merkl instance than the endpoint. Re-copy it from the dashboard; confirm the endpoint matches where the key was minted.
+- **Connection refused / DNS failure on the endpoint** → for self-hosted, the API URL is wrong or the server is down. For the hosted service, confirm `api.merkl.ai` resolves. Never silently fall back to a different endpoint.
+- **`/hooks` shows "0 hooks configured"** → the settings file you wrote is not the one this session reads. Claude Code loads hooks from the config dir for the session's project root; confirm you wrote to the right scope (`--global` writes `~/.claude/settings.json`; a project install writes `<project>/.claude/settings.json`). If the user runs a non-default `CLAUDE_CONFIG_DIR`, write there.
+- **Session is created but `action_count` stays 0** → the session opened (create succeeded) but PostToolUse never fired for a real tool. Have the user run any tool (read a file, run a command) in a hook-loaded session, then re-check.
+- **Hook command runs `python` and that Python lacks merkl** → an older install wrote a bare `python`. Re-run `merkl install` (it now uses the full interpreter path), or edit the hook command to the absolute path from `command -v python` in the install env.
+- **Dev/self-hosted: sessions vanished after a server restart** → the server is running in-memory (no `DATABASE_URL`). That is expected for dev; use Postgres for anything you want to keep.
+- **Everything looks right but still nothing** → clear stale hook state and retry: `rm -f "$TMPDIR"/merkl_hookstate_*.json`. Stale state points at session ids the server may not have.
+
+## What "installed" means
+
+- `merkl` on `PATH`, hook registered in the correct settings file with the key baked in, hooks reloaded, and a verification action visible in the dashboard or via the sessions API.
+- Nothing about the user's real payloads left their machine: only hashes and tool names go to Merkl; raw data stays in `~/.merkl/evidence/`. If the user wants zero plaintext at all, that is already the default; previews are opt-in via `MERKL_INCLUDE_PREVIEWS=1`.

merkl_sdk-0.1.0/LICENSE

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

merkl_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: merkl-sdk
+Version: 0.1.0
+Summary: Record AI agent actions as independently verifiable cryptographic proofs
+Project-URL: Homepage, https://merkl.ai
+Project-URL: Documentation, https://merkl.ai
+Project-URL: Repository, https://github.com/ramcav/merkl-sdk
+Project-URL: Bug Tracker, https://github.com/ramcav/merkl-sdk/issues
+Author-email: Merkl <hello@merkl.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,compliance,merkle,verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: uuid6>=2025.0.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# merkl-sdk
+
+The accountability layer for AI agents. Every action is hashed on your machine and committed to a signed, append-only log — independently verifiable proof of what happened. Raw payloads stay on disk; the notary only ever sees hashes, tool names, and metadata.
+
+Homepage: [merkl.ai](https://merkl.ai) · Dashboard: [app.merkl.ai](https://app.merkl.ai)
+
+## Install (Claude Code)
+
+```bash
+pip install merkl-sdk
+merkl install --claude-code --global
+```
+
+The installer asks for an API key (`mk_...` from [app.merkl.ai](https://app.merkl.ai)) and wires Claude Code. Restart Claude Code or run `/hooks`. After that, every session records automatically.
+
+To have the agent do the install for you, point it at `INSTALL.md`.
+
+## Python
+
+```python
+from merkl.sdk import MerklClient
+
+client = MerklClient(
+    endpoint="https://api.merkl.ai",
+    agent_id="my-agent",
+    api_key="mk_...",
+)
+async with client.session(goal="Process refunds") as session:
+    await session.record_action(
+        tool_name="query_db",
+        input_data="SELECT ...",
+        output_data={"rows": 42},
+    )
+```
+
+The session seals on exit. Plaintext previews are off by default (`include_previews=True` to send them). The Claude Code hook is the same: opt in with `MERKL_INCLUDE_PREVIEWS=1`.
+
+LangChain, OpenAI, CrewAI, and Google ADK adapters live in `merkl.integrations.*`. They work; Claude Code is the supported launch path.
+
+## Disclose
+
+```bash
+merkl disclose <action_id>
+```
+
+Writes a folder with `verify.html` and one-line `evidence.jsonl`. An auditor opens the page offline — no account, nothing to install.
+
+## Environment
+
+| Variable | What |
+|---|---|
+| `MERKL_API_KEY` | API key (`mk_...`) |
+| `MERKL_ENDPOINT` | API URL (default `https://api.merkl.ai`) |
+| `MERKL_AGENT_ID` | Label in the dashboard (default `claude-code` for the hook) |
+| `MERKL_INCLUDE_PREVIEWS` | `1` to send short plaintext previews |
+| `MERKL_EVIDENCE_DIR` | Local evidence log (default `~/.merkl/evidence/`; `off` to disable) |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

merkl_sdk-0.1.0/README.md

@@ -0,0 +1,63 @@
+# merkl-sdk
+
+The accountability layer for AI agents. Every action is hashed on your machine and committed to a signed, append-only log — independently verifiable proof of what happened. Raw payloads stay on disk; the notary only ever sees hashes, tool names, and metadata.
+
+Homepage: [merkl.ai](https://merkl.ai) · Dashboard: [app.merkl.ai](https://app.merkl.ai)
+
+## Install (Claude Code)
+
+```bash
+pip install merkl-sdk
+merkl install --claude-code --global
+```
+
+The installer asks for an API key (`mk_...` from [app.merkl.ai](https://app.merkl.ai)) and wires Claude Code. Restart Claude Code or run `/hooks`. After that, every session records automatically.
+
+To have the agent do the install for you, point it at `INSTALL.md`.
+
+## Python
+
+```python
+from merkl.sdk import MerklClient
+
+client = MerklClient(
+    endpoint="https://api.merkl.ai",
+    agent_id="my-agent",
+    api_key="mk_...",
+)
+async with client.session(goal="Process refunds") as session:
+    await session.record_action(
+        tool_name="query_db",
+        input_data="SELECT ...",
+        output_data={"rows": 42},
+    )
+```
+
+The session seals on exit. Plaintext previews are off by default (`include_previews=True` to send them). The Claude Code hook is the same: opt in with `MERKL_INCLUDE_PREVIEWS=1`.
+
+LangChain, OpenAI, CrewAI, and Google ADK adapters live in `merkl.integrations.*`. They work; Claude Code is the supported launch path.
+
+## Disclose
+
+```bash
+merkl disclose <action_id>
+```
+
+Writes a folder with `verify.html` and one-line `evidence.jsonl`. An auditor opens the page offline — no account, nothing to install.
+
+## Environment
+
+| Variable | What |
+|---|---|
+| `MERKL_API_KEY` | API key (`mk_...`) |
+| `MERKL_ENDPOINT` | API URL (default `https://api.merkl.ai`) |
+| `MERKL_AGENT_ID` | Label in the dashboard (default `claude-code` for the hook) |
+| `MERKL_INCLUDE_PREVIEWS` | `1` to send short plaintext previews |
+| `MERKL_EVIDENCE_DIR` | Local evidence log (default `~/.merkl/evidence/`; `off` to disable) |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

merkl_sdk-0.1.0/merkl/__init__.py

@@ -0,0 +1 @@
+"""Merkl SDK — accountability infrastructure for autonomous AI agents."""

merkl_sdk-0.1.0/merkl/cli/__init__.py

@@ -0,0 +1 @@
+"""Merkl CLI — install and manage integrations."""

merkl_sdk-0.1.0/merkl/cli/disclose.py

@@ -0,0 +1,104 @@
+"""``merkl disclose`` — package one action's evidence for an auditor.
+
+The operator side of the disclosure flow. Produces a folder the operator
+can zip and email; the auditor needs no tooling — they open verify.html
+in any browser and drop evidence.jsonl on it.
+
+    merkl disclose <action_id>
+    → disclosure-<action_id[:8]>/
+        verify.html      standalone verifier with the session's proof bundle
+        evidence.jsonl   ONLY the disclosed action's raw record
+
+Selective by construction: undisclosed actions appear in the bundle as
+hashes and typed metadata only; their raw payloads never leave the
+evidence dir.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import httpx
+
+
+def find_evidence_entry(evidence_dir: Path, action_id: str) -> tuple[dict, str] | None:
+    """Scan the evidence dir for an entry with this action_id.
+
+    Returns (entry, raw_line) so the disclosed line is byte-identical to
+    what the hook wrote — re-serializing could change key order and
+    confuse a diff, even though hashing is order-independent.
+    """
+    for path in sorted(evidence_dir.glob("*.jsonl")):
+        with open(path, encoding="utf-8") as f:
+            for line in f:
+                if action_id not in line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if entry.get("action_id") == action_id:
+                    return entry, line.rstrip("\n")
+    return None
+
+
+def disclose(
+    action_id: str,
+    *,
+    evidence_dir: Path | None = None,
+    endpoint: str | None = None,
+    api_key: str | None = None,
+    out_dir: Path | None = None,
+) -> Path:
+    """Build a disclosure folder for one action. Returns the folder path.
+
+    Raises SystemExit with a readable message on any failure — this is a
+    CLI entry point, not a library API.
+    """
+    evidence_dir = evidence_dir or Path(
+        os.environ.get("MERKL_EVIDENCE_DIR") or Path.home() / ".merkl" / "evidence"
+    )
+    endpoint = (endpoint or os.environ.get("MERKL_ENDPOINT", "https://api.merkl.ai")).rstrip("/")
+    api_key = api_key or os.environ.get("MERKL_API_KEY", "")
+
+    if not evidence_dir.is_dir():
+        sys.exit(f"Evidence dir not found: {evidence_dir} (set MERKL_EVIDENCE_DIR)")
+
+    found = find_evidence_entry(evidence_dir, action_id)
+    if found is None:
+        sys.exit(
+            f"No evidence entry for action {action_id} under {evidence_dir}.\n"
+            "Evidence is written by the Merkl hook on the machine the agent ran on."
+        )
+    entry, raw_line = found
+    session_id = entry["session_id"]
+
+    resp = httpx.get(
+        f"{endpoint}/v1/sessions/{session_id}/verify.html",
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=30.0,
+    )
+    if resp.status_code == 422:
+        sys.exit(
+            f"Session {session_id} is not sealed yet — seal it first:\n"
+            f"  curl -X POST -H 'Authorization: Bearer <key>' "
+            f"{endpoint}/v1/sessions/{session_id}/seal"
+        )
+    if not resp.is_success:
+        sys.exit(f"Failed to fetch verifier ({resp.status_code}): {resp.text[:200]}")
+
+    out = out_dir or Path(f"disclosure-{action_id[:8]}")
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "verify.html").write_text(resp.text, encoding="utf-8")
+    (out / "evidence.jsonl").write_text(raw_line + "\n", encoding="utf-8")
+
+    print(f"Disclosure package: {out}/")
+    print(f"  verify.html     session {session_id[:8]}… proof bundle + verifier")
+    print(f"  evidence.jsonl  1 record: {entry.get('tool_name', '?')} action {action_id[:8]}…")
+    print()
+    print("Send the folder to the auditor. They open verify.html in a browser")
+    print("and drop evidence.jsonl on it — no install, no network, no account.")
+    return out