ethersflow 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ethersflow-0.1.0/PKG-INFO +177 -0
- ethersflow-0.1.0/README.md +165 -0
- ethersflow-0.1.0/ethersflow/__init__.py +8 -0
- ethersflow-0.1.0/ethersflow/client.py +60 -0
- ethersflow-0.1.0/ethersflow.egg-info/PKG-INFO +177 -0
- ethersflow-0.1.0/ethersflow.egg-info/SOURCES.txt +9 -0
- ethersflow-0.1.0/ethersflow.egg-info/dependency_links.txt +1 -0
- ethersflow-0.1.0/ethersflow.egg-info/requires.txt +1 -0
- ethersflow-0.1.0/ethersflow.egg-info/top_level.txt +1 -0
- ethersflow-0.1.0/pyproject.toml +19 -0
- ethersflow-0.1.0/setup.cfg +4 -0
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ethersflow
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: EthersFlow Python SDK — lightweight client + LangChain tool wrapper
|
|
5
|
+
Author-email: EthersFlow <dev@ethersflow.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Requires-Python: >=3.8
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
Requires-Dist: requests>=2.28
|
|
12
|
+
|
|
13
|
+
# EthersFlow Python SDK
|
|
14
|
+
|
|
15
|
+
**Lightweight Python client + LangChain tool wrapper for the EthersFlow multi-model agent trust layer.**
|
|
16
|
+
|
|
17
|
+
## Overview
|
|
18
|
+
|
|
19
|
+
EthersFlow gates autonomous AI agent actions through adversarial multi-model consensus before execution. The Python SDK provides:
|
|
20
|
+
|
|
21
|
+
- **Direct API client** — Make requests to the EthersFlow verification gateway
|
|
22
|
+
- **LangChain integration** — Drop-in tool wrapper for LangChain agents
|
|
23
|
+
- **Zero-dependency reference implementation** — Full signature verification (Ed25519) with no external crypto libraries
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
pip install ethersflow
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
### Verify an Agent Action
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
from ethersflow import EthersFlowClient
|
|
37
|
+
|
|
38
|
+
client = EthersFlowClient(
|
|
39
|
+
base_url="https://ethersflow-225907257236.us-east1.run.app",
|
|
40
|
+
api_key="ef_live_YOUR_API_KEY" # Replace with your actual API key
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
# Submit an agent action for verification
|
|
44
|
+
result = client.verify_action(
|
|
45
|
+
agent_action="Execute $250,000 wire transfer to Vendor X",
|
|
46
|
+
reasoning_chain="Invoice PO-8841 matched; under approval threshold.",
|
|
47
|
+
persona_preset="financial_compliance",
|
|
48
|
+
agent_count=5 # 5-node adversarial council
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
if result["status"] == "APPROVED":
|
|
52
|
+
print(f"✅ Action approved with {result['consensus_score']}% confidence")
|
|
53
|
+
else:
|
|
54
|
+
print(f"⛔ Action flagged: {result['verdict_summary']}")
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### LangChain Tool Integration
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from langchain.agents import AgentType, initialize_agent
|
|
61
|
+
from langchain.llms import OpenAI
|
|
62
|
+
from ethersflow.langchain import ethersflow_tool
|
|
63
|
+
|
|
64
|
+
llm = OpenAI(temperature=0)
|
|
65
|
+
agent = initialize_agent(
|
|
66
|
+
tools=[ethersflow_tool(api_key="ef_live_YOUR_API_KEY")],
|
|
67
|
+
llm=llm,
|
|
68
|
+
agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
# Agent automatically gates decisions through EthersFlow
|
|
72
|
+
response = agent.run(
|
|
73
|
+
"Before executing a trade, verify it passes adversarial review."
|
|
74
|
+
)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## API Reference
|
|
78
|
+
|
|
79
|
+
### `EthersFlowClient`
|
|
80
|
+
|
|
81
|
+
#### Constructor
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
EthersFlowClient(
|
|
85
|
+
base_url: str = "https://ethersflow-225907257236.us-east1.run.app",
|
|
86
|
+
api_key: str = None # Falls back to ETHERSFLOW_API_KEY env var
|
|
87
|
+
)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
#### Methods
|
|
91
|
+
|
|
92
|
+
**`verify_action(agent_action, reasoning_chain=None, persona_preset="general_adversarial", agent_count=3)`**
|
|
93
|
+
|
|
94
|
+
Verify an autonomous agent action through adversarial consensus.
|
|
95
|
+
|
|
96
|
+
**Parameters:**
|
|
97
|
+
- `agent_action` (str, required): The proposed action (e.g., "Execute wire transfer")
|
|
98
|
+
- `reasoning_chain` (str, optional): The reasoning leading to the action
|
|
99
|
+
- `persona_preset` (str, optional): Council type
|
|
100
|
+
- `"clinical_safety"` — Medical/clinical context
|
|
101
|
+
- `"financial_compliance"` — Fintech/banking context
|
|
102
|
+
- `"legal_citation"` — Legal/contract analysis
|
|
103
|
+
- `"cybersecurity_auditor"` — Security & threat assessment
|
|
104
|
+
- `"general_adversarial"` (default) — Generic multi-model debate
|
|
105
|
+
- `agent_count` (int, optional): Number of audit nodes (2–7, default 3)
|
|
106
|
+
|
|
107
|
+
**Returns:** Dict with keys:
|
|
108
|
+
- `status` (str): `"APPROVED"`, `"FLAGGED_HUMAN_REVIEW"`, or `"REJECTED"`
|
|
109
|
+
- `verified` (bool): `True` if status is `"APPROVED"`
|
|
110
|
+
- `consensus_score` (float): Confidence 0–100%
|
|
111
|
+
- `risk_index` (float): Risk 0–100%
|
|
112
|
+
- `verdict_summary` (str): Human-readable verdict
|
|
113
|
+
- `perspectives` (list): Individual node verdicts
|
|
114
|
+
|
|
115
|
+
**`get_jwks()`**
|
|
116
|
+
|
|
117
|
+
Fetch the JWKS public key set for cryptographic signature verification.
|
|
118
|
+
|
|
119
|
+
**`get_attestation_manifest()`**
|
|
120
|
+
|
|
121
|
+
Fetch the attestation authority manifest with public key and metadata.
|
|
122
|
+
|
|
123
|
+
## Environment Variables
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
# API endpoint (optional, defaults to production Cloud Run)
|
|
127
|
+
ETHERSFLOW_BASE_URL=https://ethersflow-225907257236.us-east1.run.app
|
|
128
|
+
|
|
129
|
+
# API key (required for authenticated endpoints)
|
|
130
|
+
ETHERSFLOW_API_KEY=ef_live_YOUR_KEY
|
|
131
|
+
ETHERSFLOW_TOKEN=ef_live_YOUR_KEY # Alternative
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Signature Verification
|
|
135
|
+
|
|
136
|
+
The SDK includes a zero-dependency verifier for Ed25519 node attestations:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
from ethersflow import EthersFlowVerifier
|
|
140
|
+
|
|
141
|
+
verifier = EthersFlowVerifier()
|
|
142
|
+
|
|
143
|
+
# Verify a node's cryptographic attestation
|
|
144
|
+
attestation = verifier.verify_attestation_signature(node_payload)
|
|
145
|
+
if attestation["valid"]:
|
|
146
|
+
print(f"✅ Signature valid, issued by {attestation['issuer']}")
|
|
147
|
+
else:
|
|
148
|
+
print(f"❌ Signature invalid or tampered")
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Troubleshooting
|
|
152
|
+
|
|
153
|
+
### 401 Unauthorized
|
|
154
|
+
|
|
155
|
+
- Ensure `ETHERSFLOW_API_KEY` or `api_key` parameter is set
|
|
156
|
+
- Verify the key format starts with `ef_live_` or matches your subscription tier
|
|
157
|
+
- Check that the key hasn't expired in your EthersFlow dashboard
|
|
158
|
+
|
|
159
|
+
### Connection Timeout
|
|
160
|
+
|
|
161
|
+
- Increase timeout: `client.timeout = 30`
|
|
162
|
+
- Verify `base_url` is correct and accessible
|
|
163
|
+
- Check network connectivity to the Cloud Run endpoint
|
|
164
|
+
|
|
165
|
+
### LangChain Integration Not Found
|
|
166
|
+
|
|
167
|
+
- Ensure LangChain is installed: `pip install langchain>=0.0.200`
|
|
168
|
+
|
|
169
|
+
## Support
|
|
170
|
+
|
|
171
|
+
- **Issues:** [GitHub Issues](https://github.com/Ethersflow/EthersFlow/issues)
|
|
172
|
+
- **Docs:** [https://ethersflow.com](https://ethersflow.com)
|
|
173
|
+
- **Email:** [ethersflow.dev@gmail.com](mailto:ethersflow.dev@gmail.com)
|
|
174
|
+
|
|
175
|
+
## License
|
|
176
|
+
|
|
177
|
+
MIT
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# EthersFlow Python SDK
|
|
2
|
+
|
|
3
|
+
**Lightweight Python client + LangChain tool wrapper for the EthersFlow multi-model agent trust layer.**
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
EthersFlow gates autonomous AI agent actions through adversarial multi-model consensus before execution. The Python SDK provides:
|
|
8
|
+
|
|
9
|
+
- **Direct API client** — Make requests to the EthersFlow verification gateway
|
|
10
|
+
- **LangChain integration** — Drop-in tool wrapper for LangChain agents
|
|
11
|
+
- **Zero-dependency reference implementation** — Full signature verification (Ed25519) with no external crypto libraries
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
pip install ethersflow
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Quick Start
|
|
20
|
+
|
|
21
|
+
### Verify an Agent Action
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
from ethersflow import EthersFlowClient
|
|
25
|
+
|
|
26
|
+
client = EthersFlowClient(
|
|
27
|
+
base_url="https://ethersflow-225907257236.us-east1.run.app",
|
|
28
|
+
api_key="ef_live_YOUR_API_KEY" # Replace with your actual API key
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
# Submit an agent action for verification
|
|
32
|
+
result = client.verify_action(
|
|
33
|
+
agent_action="Execute $250,000 wire transfer to Vendor X",
|
|
34
|
+
reasoning_chain="Invoice PO-8841 matched; under approval threshold.",
|
|
35
|
+
persona_preset="financial_compliance",
|
|
36
|
+
agent_count=5 # 5-node adversarial council
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
if result["status"] == "APPROVED":
|
|
40
|
+
print(f"✅ Action approved with {result['consensus_score']}% confidence")
|
|
41
|
+
else:
|
|
42
|
+
print(f"⛔ Action flagged: {result['verdict_summary']}")
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### LangChain Tool Integration
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from langchain.agents import AgentType, initialize_agent
|
|
49
|
+
from langchain.llms import OpenAI
|
|
50
|
+
from ethersflow.langchain import ethersflow_tool
|
|
51
|
+
|
|
52
|
+
llm = OpenAI(temperature=0)
|
|
53
|
+
agent = initialize_agent(
|
|
54
|
+
tools=[ethersflow_tool(api_key="ef_live_YOUR_API_KEY")],
|
|
55
|
+
llm=llm,
|
|
56
|
+
agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
|
|
57
|
+
)
|
|
58
|
+
|
|
59
|
+
# Agent automatically gates decisions through EthersFlow
|
|
60
|
+
response = agent.run(
|
|
61
|
+
"Before executing a trade, verify it passes adversarial review."
|
|
62
|
+
)
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## API Reference
|
|
66
|
+
|
|
67
|
+
### `EthersFlowClient`
|
|
68
|
+
|
|
69
|
+
#### Constructor
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
EthersFlowClient(
|
|
73
|
+
base_url: str = "https://ethersflow-225907257236.us-east1.run.app",
|
|
74
|
+
api_key: str = None # Falls back to ETHERSFLOW_API_KEY env var
|
|
75
|
+
)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
#### Methods
|
|
79
|
+
|
|
80
|
+
**`verify_action(agent_action, reasoning_chain=None, persona_preset="general_adversarial", agent_count=3)`**
|
|
81
|
+
|
|
82
|
+
Verify an autonomous agent action through adversarial consensus.
|
|
83
|
+
|
|
84
|
+
**Parameters:**
|
|
85
|
+
- `agent_action` (str, required): The proposed action (e.g., "Execute wire transfer")
|
|
86
|
+
- `reasoning_chain` (str, optional): The reasoning leading to the action
|
|
87
|
+
- `persona_preset` (str, optional): Council type
|
|
88
|
+
- `"clinical_safety"` — Medical/clinical context
|
|
89
|
+
- `"financial_compliance"` — Fintech/banking context
|
|
90
|
+
- `"legal_citation"` — Legal/contract analysis
|
|
91
|
+
- `"cybersecurity_auditor"` — Security & threat assessment
|
|
92
|
+
- `"general_adversarial"` (default) — Generic multi-model debate
|
|
93
|
+
- `agent_count` (int, optional): Number of audit nodes (2–7, default 3)
|
|
94
|
+
|
|
95
|
+
**Returns:** Dict with keys:
|
|
96
|
+
- `status` (str): `"APPROVED"`, `"FLAGGED_HUMAN_REVIEW"`, or `"REJECTED"`
|
|
97
|
+
- `verified` (bool): `True` if status is `"APPROVED"`
|
|
98
|
+
- `consensus_score` (float): Confidence 0–100%
|
|
99
|
+
- `risk_index` (float): Risk 0–100%
|
|
100
|
+
- `verdict_summary` (str): Human-readable verdict
|
|
101
|
+
- `perspectives` (list): Individual node verdicts
|
|
102
|
+
|
|
103
|
+
**`get_jwks()`**
|
|
104
|
+
|
|
105
|
+
Fetch the JWKS public key set for cryptographic signature verification.
|
|
106
|
+
|
|
107
|
+
**`get_attestation_manifest()`**
|
|
108
|
+
|
|
109
|
+
Fetch the attestation authority manifest with public key and metadata.
|
|
110
|
+
|
|
111
|
+
## Environment Variables
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# API endpoint (optional, defaults to production Cloud Run)
|
|
115
|
+
ETHERSFLOW_BASE_URL=https://ethersflow-225907257236.us-east1.run.app
|
|
116
|
+
|
|
117
|
+
# API key (required for authenticated endpoints)
|
|
118
|
+
ETHERSFLOW_API_KEY=ef_live_YOUR_KEY
|
|
119
|
+
ETHERSFLOW_TOKEN=ef_live_YOUR_KEY # Alternative
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Signature Verification
|
|
123
|
+
|
|
124
|
+
The SDK includes a zero-dependency verifier for Ed25519 node attestations:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from ethersflow import EthersFlowVerifier
|
|
128
|
+
|
|
129
|
+
verifier = EthersFlowVerifier()
|
|
130
|
+
|
|
131
|
+
# Verify a node's cryptographic attestation
|
|
132
|
+
attestation = verifier.verify_attestation_signature(node_payload)
|
|
133
|
+
if attestation["valid"]:
|
|
134
|
+
print(f"✅ Signature valid, issued by {attestation['issuer']}")
|
|
135
|
+
else:
|
|
136
|
+
print(f"❌ Signature invalid or tampered")
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Troubleshooting
|
|
140
|
+
|
|
141
|
+
### 401 Unauthorized
|
|
142
|
+
|
|
143
|
+
- Ensure `ETHERSFLOW_API_KEY` or `api_key` parameter is set
|
|
144
|
+
- Verify the key format starts with `ef_live_` or matches your subscription tier
|
|
145
|
+
- Check that the key hasn't expired in your EthersFlow dashboard
|
|
146
|
+
|
|
147
|
+
### Connection Timeout
|
|
148
|
+
|
|
149
|
+
- Increase timeout: `client.timeout = 30`
|
|
150
|
+
- Verify `base_url` is correct and accessible
|
|
151
|
+
- Check network connectivity to the Cloud Run endpoint
|
|
152
|
+
|
|
153
|
+
### LangChain Integration Not Found
|
|
154
|
+
|
|
155
|
+
- Ensure LangChain is installed: `pip install langchain>=0.0.200`
|
|
156
|
+
|
|
157
|
+
## Support
|
|
158
|
+
|
|
159
|
+
- **Issues:** [GitHub Issues](https://github.com/Ethersflow/EthersFlow/issues)
|
|
160
|
+
- **Docs:** [https://ethersflow.com](https://ethersflow.com)
|
|
161
|
+
- **Email:** [ethersflow.dev@gmail.com](mailto:ethersflow.dev@gmail.com)
|
|
162
|
+
|
|
163
|
+
## License
|
|
164
|
+
|
|
165
|
+
MIT
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
"""EthersFlow Python SDK - package initializer"""
|
|
2
|
+
|
|
3
|
+
from .client import EthersFlowClient, EthersFlowLangChainTool
|
|
4
|
+
|
|
5
|
+
__all__ = ["EthersFlowClient", "EthersFlowLangChainTool", "__version__"]
|
|
6
|
+
|
|
7
|
+
# Keep package version coordinated with pyproject.toml when bumping releases
|
|
8
|
+
__version__ = "0.1.0"
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import requests
|
|
2
|
+
from typing import Dict, Any, Optional, List
|
|
3
|
+
|
|
4
|
+
class EthersFlowClient:
|
|
5
|
+
"""
|
|
6
|
+
Official Python Client for EthersFlow Multi-Model Adversarial Consensus API
|
|
7
|
+
"""
|
|
8
|
+
def __init__(self, api_key: str, base_url: str = "https://ethersflow-225907257236.us-east1.run.app"):
|
|
9
|
+
self.api_key = api_key
|
|
10
|
+
self.base_url = base_url.rstrip("/")
|
|
11
|
+
self.headers = {
|
|
12
|
+
"Authorization": f"Bearer {self.api_key}",
|
|
13
|
+
"Content-Type": "application/json"
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
def verify_agent_action(
|
|
17
|
+
self,
|
|
18
|
+
agent_action: str,
|
|
19
|
+
reasoning_chain: Optional[str] = None,
|
|
20
|
+
agent_count: int = 3,
|
|
21
|
+
persona_preset: str = "general_adversarial",
|
|
22
|
+
grounding_enabled: bool = True
|
|
23
|
+
) -> Dict[str, Any]:
|
|
24
|
+
"""
|
|
25
|
+
Verify an autonomous agent's proposed action before execution.
|
|
26
|
+
"""
|
|
27
|
+
url = f"{self.base_url}/api/v1/verify"
|
|
28
|
+
payload = {
|
|
29
|
+
"agent_action": agent_action,
|
|
30
|
+
"reasoning_chain": reasoning_chain,
|
|
31
|
+
"agent_count": agent_count,
|
|
32
|
+
"persona_preset": persona_preset,
|
|
33
|
+
"grounding_enabled": grounding_enabled,
|
|
34
|
+
"zero_retention": True
|
|
35
|
+
}
|
|
36
|
+
response = requests.post(url, json=payload, headers=self.headers)
|
|
37
|
+
response.raise_for_status()
|
|
38
|
+
return response.json()
|
|
39
|
+
|
|
40
|
+
# LangChain Integration Tool Wrapper
|
|
41
|
+
class EthersFlowLangChainTool:
|
|
42
|
+
"""
|
|
43
|
+
LangChain BaseTool wrapper for EthersFlow Verification
|
|
44
|
+
"""
|
|
45
|
+
name = "ethersflow_agent_verify"
|
|
46
|
+
description = "Verify an agent action or decision with multi-model adversarial debate before executing side effects."
|
|
47
|
+
|
|
48
|
+
def __init__(self, api_key: str):
|
|
49
|
+
self.client = EthersFlowClient(api_key=api_key)
|
|
50
|
+
|
|
51
|
+
def _run(self, agent_action: str, reasoning_chain: str = "", persona_preset: str = "general_adversarial") -> str:
|
|
52
|
+
res = self.client.verify_agent_action(
|
|
53
|
+
agent_action=agent_action,
|
|
54
|
+
reasoning_chain=reasoning_chain,
|
|
55
|
+
persona_preset=persona_preset
|
|
56
|
+
)
|
|
57
|
+
if res.get("verified"):
|
|
58
|
+
return f"APPROVED (Consensus Score: {res.get('consensus_score')}%). Action is safe to execute."
|
|
59
|
+
else:
|
|
60
|
+
return f"REJECTED/FLAGGED (Risk Index: {res.get('risk_index')}%). Reason: {res.get('verdict_summary')}"
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ethersflow
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: EthersFlow Python SDK — lightweight client + LangChain tool wrapper
|
|
5
|
+
Author-email: EthersFlow <dev@ethersflow.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Requires-Python: >=3.8
|
|
10
|
+
Description-Content-Type: text/markdown
|
|
11
|
+
Requires-Dist: requests>=2.28
|
|
12
|
+
|
|
13
|
+
# EthersFlow Python SDK
|
|
14
|
+
|
|
15
|
+
**Lightweight Python client + LangChain tool wrapper for the EthersFlow multi-model agent trust layer.**
|
|
16
|
+
|
|
17
|
+
## Overview
|
|
18
|
+
|
|
19
|
+
EthersFlow gates autonomous AI agent actions through adversarial multi-model consensus before execution. The Python SDK provides:
|
|
20
|
+
|
|
21
|
+
- **Direct API client** — Make requests to the EthersFlow verification gateway
|
|
22
|
+
- **LangChain integration** — Drop-in tool wrapper for LangChain agents
|
|
23
|
+
- **Zero-dependency reference implementation** — Full signature verification (Ed25519) with no external crypto libraries
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
pip install ethersflow
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
### Verify an Agent Action
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
from ethersflow import EthersFlowClient
|
|
37
|
+
|
|
38
|
+
client = EthersFlowClient(
|
|
39
|
+
base_url="https://ethersflow-225907257236.us-east1.run.app",
|
|
40
|
+
api_key="ef_live_YOUR_API_KEY" # Replace with your actual API key
|
|
41
|
+
)
|
|
42
|
+
|
|
43
|
+
# Submit an agent action for verification
|
|
44
|
+
result = client.verify_action(
|
|
45
|
+
agent_action="Execute $250,000 wire transfer to Vendor X",
|
|
46
|
+
reasoning_chain="Invoice PO-8841 matched; under approval threshold.",
|
|
47
|
+
persona_preset="financial_compliance",
|
|
48
|
+
agent_count=5 # 5-node adversarial council
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
if result["status"] == "APPROVED":
|
|
52
|
+
print(f"✅ Action approved with {result['consensus_score']}% confidence")
|
|
53
|
+
else:
|
|
54
|
+
print(f"⛔ Action flagged: {result['verdict_summary']}")
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### LangChain Tool Integration
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from langchain.agents import AgentType, initialize_agent
|
|
61
|
+
from langchain.llms import OpenAI
|
|
62
|
+
from ethersflow.langchain import ethersflow_tool
|
|
63
|
+
|
|
64
|
+
llm = OpenAI(temperature=0)
|
|
65
|
+
agent = initialize_agent(
|
|
66
|
+
tools=[ethersflow_tool(api_key="ef_live_YOUR_API_KEY")],
|
|
67
|
+
llm=llm,
|
|
68
|
+
agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
# Agent automatically gates decisions through EthersFlow
|
|
72
|
+
response = agent.run(
|
|
73
|
+
"Before executing a trade, verify it passes adversarial review."
|
|
74
|
+
)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## API Reference
|
|
78
|
+
|
|
79
|
+
### `EthersFlowClient`
|
|
80
|
+
|
|
81
|
+
#### Constructor
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
EthersFlowClient(
|
|
85
|
+
base_url: str = "https://ethersflow-225907257236.us-east1.run.app",
|
|
86
|
+
api_key: str = None # Falls back to ETHERSFLOW_API_KEY env var
|
|
87
|
+
)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
#### Methods
|
|
91
|
+
|
|
92
|
+
**`verify_action(agent_action, reasoning_chain=None, persona_preset="general_adversarial", agent_count=3)`**
|
|
93
|
+
|
|
94
|
+
Verify an autonomous agent action through adversarial consensus.
|
|
95
|
+
|
|
96
|
+
**Parameters:**
|
|
97
|
+
- `agent_action` (str, required): The proposed action (e.g., "Execute wire transfer")
|
|
98
|
+
- `reasoning_chain` (str, optional): The reasoning leading to the action
|
|
99
|
+
- `persona_preset` (str, optional): Council type
|
|
100
|
+
- `"clinical_safety"` — Medical/clinical context
|
|
101
|
+
- `"financial_compliance"` — Fintech/banking context
|
|
102
|
+
- `"legal_citation"` — Legal/contract analysis
|
|
103
|
+
- `"cybersecurity_auditor"` — Security & threat assessment
|
|
104
|
+
- `"general_adversarial"` (default) — Generic multi-model debate
|
|
105
|
+
- `agent_count` (int, optional): Number of audit nodes (2–7, default 3)
|
|
106
|
+
|
|
107
|
+
**Returns:** Dict with keys:
|
|
108
|
+
- `status` (str): `"APPROVED"`, `"FLAGGED_HUMAN_REVIEW"`, or `"REJECTED"`
|
|
109
|
+
- `verified` (bool): `True` if status is `"APPROVED"`
|
|
110
|
+
- `consensus_score` (float): Confidence 0–100%
|
|
111
|
+
- `risk_index` (float): Risk 0–100%
|
|
112
|
+
- `verdict_summary` (str): Human-readable verdict
|
|
113
|
+
- `perspectives` (list): Individual node verdicts
|
|
114
|
+
|
|
115
|
+
**`get_jwks()`**
|
|
116
|
+
|
|
117
|
+
Fetch the JWKS public key set for cryptographic signature verification.
|
|
118
|
+
|
|
119
|
+
**`get_attestation_manifest()`**
|
|
120
|
+
|
|
121
|
+
Fetch the attestation authority manifest with public key and metadata.
|
|
122
|
+
|
|
123
|
+
## Environment Variables
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
# API endpoint (optional, defaults to production Cloud Run)
|
|
127
|
+
ETHERSFLOW_BASE_URL=https://ethersflow-225907257236.us-east1.run.app
|
|
128
|
+
|
|
129
|
+
# API key (required for authenticated endpoints)
|
|
130
|
+
ETHERSFLOW_API_KEY=ef_live_YOUR_KEY
|
|
131
|
+
ETHERSFLOW_TOKEN=ef_live_YOUR_KEY # Alternative
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Signature Verification
|
|
135
|
+
|
|
136
|
+
The SDK includes a zero-dependency verifier for Ed25519 node attestations:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
from ethersflow import EthersFlowVerifier
|
|
140
|
+
|
|
141
|
+
verifier = EthersFlowVerifier()
|
|
142
|
+
|
|
143
|
+
# Verify a node's cryptographic attestation
|
|
144
|
+
attestation = verifier.verify_attestation_signature(node_payload)
|
|
145
|
+
if attestation["valid"]:
|
|
146
|
+
print(f"✅ Signature valid, issued by {attestation['issuer']}")
|
|
147
|
+
else:
|
|
148
|
+
print(f"❌ Signature invalid or tampered")
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Troubleshooting
|
|
152
|
+
|
|
153
|
+
### 401 Unauthorized
|
|
154
|
+
|
|
155
|
+
- Ensure `ETHERSFLOW_API_KEY` or `api_key` parameter is set
|
|
156
|
+
- Verify the key format starts with `ef_live_` or matches your subscription tier
|
|
157
|
+
- Check that the key hasn't expired in your EthersFlow dashboard
|
|
158
|
+
|
|
159
|
+
### Connection Timeout
|
|
160
|
+
|
|
161
|
+
- Increase timeout: `client.timeout = 30`
|
|
162
|
+
- Verify `base_url` is correct and accessible
|
|
163
|
+
- Check network connectivity to the Cloud Run endpoint
|
|
164
|
+
|
|
165
|
+
### LangChain Integration Not Found
|
|
166
|
+
|
|
167
|
+
- Ensure LangChain is installed: `pip install langchain>=0.0.200`
|
|
168
|
+
|
|
169
|
+
## Support
|
|
170
|
+
|
|
171
|
+
- **Issues:** [GitHub Issues](https://github.com/Ethersflow/EthersFlow/issues)
|
|
172
|
+
- **Docs:** [https://ethersflow.com](https://ethersflow.com)
|
|
173
|
+
- **Email:** [ethersflow.dev@gmail.com](mailto:ethersflow.dev@gmail.com)
|
|
174
|
+
|
|
175
|
+
## License
|
|
176
|
+
|
|
177
|
+
MIT
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
requests>=2.28
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
ethersflow
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "ethersflow"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "EthersFlow Python SDK — lightweight client + LangChain tool wrapper"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
authors = [{ name = "EthersFlow", email = "dev@ethersflow.com" }]
|
|
12
|
+
requires-python = ">=3.8"
|
|
13
|
+
dependencies = [
|
|
14
|
+
"requests>=2.28"
|
|
15
|
+
]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"License :: OSI Approved :: MIT License"
|
|
19
|
+
]
|