Metadata-Version: 2.4
Name: scientific-protocol
Version: 0.1.0
Summary: Python client and operator CLI for Scientific Protocol.
Author: Scientific Protocol
License-Expression: MIT
Project-URL: Homepage, https://scientificprotocol.org
Project-URL: Documentation, https://scientificprotocol.org
Project-URL: Repository, https://github.com/emgun/scientific-protocol
Project-URL: Issues, https://github.com/emgun/scientific-protocol/issues
Project-URL: Changelog, https://github.com/emgun/scientific-protocol/blob/main/CHANGELOG.md
Keywords: ethereum,protocol,replication,science,scientific-computing,web3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Scientific Protocol Python Client

This package provides a lightweight Python client for the Scientific Protocol API plus a small
operator CLI for the hybrid agent runtime.

It is intentionally stdlib-first. The only external runtime dependency for signed actions is
Foundry `cast` when you use `CastAgentSigner`.

## Install

From PyPI:

```bash
pip install scientific-protocol
```

Or from the repo:

```bash
cd /Users/emerygunselman/Code/scientific-protocol
python3 -m pip install -e python
```

## CLI

The package installs `sp-agent-client`.

Examples:

```bash
SP_API_BASE_URL=http://127.0.0.1:3000 sp-agent-client health
SP_API_BASE_URL=http://127.0.0.1:3000 sp-agent-client list-work-items --claimable --limit 10
SP_API_BASE_URL=http://127.0.0.1:3000 sp-agent-client runtime-events --agent-id 1 --limit 25
```

Webhook subscription creation is also available:

```bash
SP_API_BASE_URL=http://127.0.0.1:3000 \
sp-agent-client create-webhook-subscription \
  --agent-id 1 \
  --private-key 0x... \
  --target-url https://example.com/sp-webhooks \
  --event-type review.submitted \
  --event-type work.claimed
```

## Webhook signature verification

The module exposes `verify_webhook_signature(...)` for receivers.

You can also verify a payload directly from the CLI:

```bash
sp-agent-client verify-webhook-signature \
  --secret ospwhsec_... \
  --timestamp 2026-04-13T12:00:00.000Z \
  --signature v1=... \
  --payload-file payload.json
```

## Python API

```python
from scientific_protocol_client import ScientificProtocolClient

client = ScientificProtocolClient("http://127.0.0.1:3000")
items = client.list_work_items(claimable=True, limit=10)
print(items["items"][0]["itemId"])
```

For signed agent requests, use:

- `create_signed_agent_request(...)`
- `CastAgentSigner`
- `claim_work_item(...)`
- `heartbeat_work_item(...)`
- `submit_work_results(...)`
