Metadata-Version: 2.4
Name: blockwatch
Version: 0.1.3
Summary: Lightweight telemetry for multi-agent collaboration and orchestration
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: bedrock
Requires-Dist: boto3>=1.26.0; extra == "bedrock"
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# BlockWatch Python SDK

[![PyPI](https://img.shields.io/pypi/v/blockwatch.svg)](https://pypi.org/project/blockwatch/)
[![Python](https://img.shields.io/pypi/pyversions/blockwatch.svg)](https://pypi.org/project/blockwatch/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Agentic Trust Authority** — instrument multi-agent handoffs, detect runtime failures (loops, leaks, token burn), and stream session telemetry to BlockWatch without blocking your agents.

<!-- Replace with your dashboard asset:
![BlockWatch handoff graph](docs/assets/handoff-graph.gif)
-->

## Install

```bash
pip install blockwatch          # core telemetry (requests)
pip install blockwatch[bedrock] # adds boto3 for framework="bedrock"
```

Install the **agent framework** you use in the same environment (`langgraph`, `crewai`, `boto3`, etc.). BlockWatch does not pull them in automatically except via `[bedrock]`.

## Quick start (Bedrock)

```bash
pip install blockwatch[bedrock]
```

```python
import os
import blockwatch
import boto3

blockwatch.init(
    api_key=os.environ["BLOCKWATCH_API_KEY"],
    framework="bedrock",
)

client = boto3.client("bedrock-agent-runtime", region_name="us-east-1")

response = client.invoke_agent(
    agentId=os.environ["BEDROCK_AGENT_ID"],
    agentAliasId=os.environ["BEDROCK_AGENT_ALIAS_ID"],
    sessionId="your-session-id",
    inputText="Hello",
)

for event in response.get("completion", []):
    if "chunk" in event:
        print(event["chunk"]["bytes"].decode(), end="")
```

Call `init()` **once**, before creating the Bedrock client. `enableTrace=True` is injected automatically for `bedrock-agent-runtime`.

Copy [`.env.example`](.env.example) for local runs. Runnable samples: [`examples/`](examples/) (Bedrock, LangGraph, CrewAI).

## Core pillars

| Pillar | What BlockWatch does |
|--------|----------------------|
| **Privacy** | Captures Bedrock orchestration **trace** events (not raw app logs). Review what your traces contain before production; client-side field masking is on the roadmap. |
| **Efficiency** | Surfaces loops, leaks, and stuck handoffs on the BlockWatch platform. The SDK batches up to **50 events** or **1 second** per upload. |
| **Cost** | Correlates token usage and burn patterns from trace analytics so you can spot runaway agents early. |

## Framework support

| Framework | SDK status |
|-----------|------------|
| **Amazon Bedrock** (`bedrock-agent-runtime`) | **Supported** — install `blockwatch[bedrock]` or `boto3`; patches `invoke_agent` + `trace` stream |
| **LangGraph** | **Supported** — `pip install langgraph` in your app env; patches `invoke` / `stream` (prefer streaming for handoff data) |
| **CrewAI** | **Supported** — `pip install crewai` in your app env; patches `Crew.kickoff` |
| **AutoGen** | Telemetry worker only; entry-point patches coming later |

See [ROADMAP.md](ROADMAP.md) for parity tiers and backend normalization.

### LangGraph

```python
import os
import blockwatch

blockwatch.init(api_key=os.environ["BLOCKWATCH_API_KEY"], framework="langgraph")

# Call init before compile(); prefer stream() for step-level telemetry.
for chunk in compiled.stream(input, stream_mode="updates"):
    ...
```

## How it works

- Background **daemon thread** gzip-batches JSON to `https://api.blockwatch.ai/telemetry`
- Short HTTP timeouts (connect 2s, read 5s) — network issues **never** crash your agent
- API key sent via `X-BlockWatch-Api-Key` header (not query strings)
- `atexit` best-effort flush (2s budget) on process exit

## AWS Lambda

**`requirements.txt`**

```text
blockwatch[bedrock]>=0.1.3
```

```python
import os
import blockwatch

blockwatch.init(
    api_key=os.environ["BLOCKWATCH_API_KEY"],
    framework="bedrock",
)
```

Build the layer on Amazon Linux:

```bash
pip install -r requirements.txt -t python/
```

## API

| Function | Description |
|----------|-------------|
| `blockwatch.init(api_key, framework)` | Start telemetry. `framework`: `bedrock`, `langgraph`, `crewai`, or `autogen`. |

## Requirements

- Python **3.9+**
- Core dependency: **requests** (always installed with `blockwatch`)
- **Bedrock:** `boto3` via `pip install blockwatch[bedrock]` or `pip install boto3`
- **LangGraph / CrewAI:** install those packages in your app environment when using those frameworks

## Contributing

1. Open an [issue](https://github.com/innogine/blockwatch-sdk/issues) or pull request.
2. Do **not** commit API keys, PyPI tokens, or customer IDs — use environment variables only.
3. Integration tests (optional): `pytest tests/ -m integration` with `BLOCKWATCH_API_KEY`, `BEDROCK_AGENT_ID`, and `BEDROCK_AGENT_ALIAS_ID` set.

## Security

Report vulnerabilities via GitHub **Security Advisories** (preferred) or a private channel to your BlockWatch contact. Rotate any key that may have been exposed in logs or commits.

## License

MIT — see [LICENSE](LICENSE). Copyright (c) 2026 INNOGINE.
