crewai-sealgraf 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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sai Arun Gunuganti
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,124 @@
1
+ Metadata-Version: 2.4
2
+ Name: crewai-sealgraf
3
+ Version: 0.1.0
4
+ Summary: Sealgraf spend-approval tools for CrewAI: check a purchase against the owner's limits before buying, owner approval on Sealgraf's own surface, sealed receipts.
5
+ Author: Sai Arun Gunuganti
6
+ License: MIT
7
+ Project-URL: Homepage, https://sealgraf.com
8
+ Project-URL: Documentation, https://sealgraf.com/developers/setup
9
+ Keywords: crewai,agents,spend-approval,sealgraf,receipts
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
15
+ Requires-Python: >=3.10
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Requires-Dist: crewai<2,>=1.15
19
+ Requires-Dist: httpx<0.29,>=0.27
20
+ Requires-Dist: pydantic<3,>=2
21
+ Dynamic: license-file
22
+
23
+ # crewai-sealgraf
24
+
25
+ Sealgraf spend-approval tools for [CrewAI](https://crewai.com): before an
26
+ agent buys anything, it checks the purchase against limits the owner set
27
+ in advance; purchases above the owner's ask-line wait for the owner's own
28
+ approval on Sealgraf's surface; every completed purchase is sealed into a
29
+ receipt neither side can rewrite.
30
+
31
+ > Status: built and tested locally; not yet published to PyPI.
32
+
33
+ ## The spend loop
34
+
35
+ ```
36
+ check_permission ── allow ──────────────► buy ──► complete_purchase ──► receipt
37
+ │
38
+ ├── deny ────────────────────────► do not buy
39
+ │
40
+ └── needs_human_approval ──► owner approves in Sealgraf
41
+ claim_decision_token ──► buy
42
+ complete_purchase ──► receipt
43
+ ```
44
+
45
+ `get_receipt` reads back either a check (by `preauth_id`, via
46
+ `GET /v1/preauthorize/{id}`) or a sealed receipt (by `receipt_id`,
47
+ via `GET /v1/receipts/{id}`) at any point.
48
+
49
+ ## Install
50
+
51
+ ```bash
52
+ pip install crewai-sealgraf
53
+ ```
54
+
55
+ ## Configure
56
+
57
+ The tools need an **agent-scope Sealgraf API key**. The key is host
58
+ configuration, never a tool argument (tool arguments are chosen by the
59
+ model and visible in prompts and logs). Pass it in code or set the
60
+ environment:
61
+
62
+ ```bash
63
+ export SEALGRAF_API_KEY=<redacted>
64
+ # optional; defaults to https://sealgraf.com
65
+ export SEALGRAF_BASE_URL=https://sealgraf.com
66
+ ```
67
+
68
+ ## Use
69
+
70
+ ```python
71
+ from crewai import Agent
72
+ from crewai_sealgraf import sealgraf_tools
73
+
74
+ buyer = Agent(
75
+ role="Purchasing agent",
76
+ goal="Buy approved supplies within the owner's limits",
77
+ backstory="...",
78
+ tools=sealgraf_tools(), # reads SEALGRAF_API_KEY
79
+ )
80
+
81
+ # or explicitly:
82
+ tools = sealgraf_tools(api_key="see_...", base_url="https://sealgraf.com")
83
+ ```
84
+
85
+ The four tools:
86
+
87
+ | Tool | Name for the model | What it does |
88
+ |---|---|---|
89
+ | `SealgrafCheckPermissionTool` | `sealgraf_check_permission` | Ask before buying. Returns `allow` (with a single-use `decision_token`), `deny`, or `needs_human_approval`. |
90
+ | `SealgrafClaimDecisionTokenTool` | `sealgraf_claim_decision_token` | After the owner approves, claim the single-use decision token. Fails with a stable code (e.g. `not_approved_yet`) while the owner has not decided. |
91
+ | `SealgrafCompletePurchaseTool` | `sealgraf_complete_purchase` | After the purchase is made, report it; Sealgraf seals it into a receipt. Amounts are integer minor units (cents). |
92
+ | `SealgrafGetReceiptTool` | `sealgraf_get_receipt` | Read a check's state (by `preauth_id`) or a sealed receipt (by `receipt_id`). |
93
+
94
+ Every tool returns the parsed Sealgraf result as JSON — the same shapes
95
+ as the Sealgraf Dify plugin and MCP surfaces.
96
+
97
+ ## Safety behaviour
98
+
99
+ - **Fail closed.** Any failure — timeout, network error, non-2xx,
100
+ malformed response, a token the server did not actually issue — raises
101
+ and fails the tool call. A tool never renders an ambiguous answer as
102
+ permission.
103
+ - **Replay honesty.** Repeating a check with the same idempotency key
104
+ returns the original check flagged `"replayed": true`; a replayed
105
+ `allow` does **not** re-serve the decision token
106
+ (`"decision_token_redelivered": false`). Use the token from the first
107
+ response; if it is lost, run a fresh check without the idempotency key.
108
+ - **Tokens are single-use** and are passed through untouched; they are
109
+ never logged by this package.
110
+ - **Waiting for approval.** After a `needs_human_approval` check, the
111
+ owner's decision takes human time. Poll `sealgraf_get_receipt` for
112
+ the preauth's state until it reads `authorized`, *then* claim — do
113
+ not call `sealgraf_claim_decision_token` repeatedly while waiting:
114
+ every early claim fails with `not_approved_yet`, and an agent
115
+ executor will happily retry it in a tight loop (observed live: 6
116
+ retries in one run). The refusal is harmless — no token exists
117
+ before approval — but the polling pattern is cheaper and clearer.
118
+
119
+ ## Development
120
+
121
+ ```bash
122
+ python -m venv .venv && .venv/bin/pip install -e . pytest
123
+ .venv/bin/python -m pytest tests/ # mocked HTTP only; no network
124
+ ```
@@ -0,0 +1,102 @@
1
+ # crewai-sealgraf
2
+
3
+ Sealgraf spend-approval tools for [CrewAI](https://crewai.com): before an
4
+ agent buys anything, it checks the purchase against limits the owner set
5
+ in advance; purchases above the owner's ask-line wait for the owner's own
6
+ approval on Sealgraf's surface; every completed purchase is sealed into a
7
+ receipt neither side can rewrite.
8
+
9
+ > Status: built and tested locally; not yet published to PyPI.
10
+
11
+ ## The spend loop
12
+
13
+ ```
14
+ check_permission ── allow ──────────────► buy ──► complete_purchase ──► receipt
15
+ │
16
+ ├── deny ────────────────────────► do not buy
17
+ │
18
+ └── needs_human_approval ──► owner approves in Sealgraf
19
+ claim_decision_token ──► buy
20
+ complete_purchase ──► receipt
21
+ ```
22
+
23
+ `get_receipt` reads back either a check (by `preauth_id`, via
24
+ `GET /v1/preauthorize/{id}`) or a sealed receipt (by `receipt_id`,
25
+ via `GET /v1/receipts/{id}`) at any point.
26
+
27
+ ## Install
28
+
29
+ ```bash
30
+ pip install crewai-sealgraf
31
+ ```
32
+
33
+ ## Configure
34
+
35
+ The tools need an **agent-scope Sealgraf API key**. The key is host
36
+ configuration, never a tool argument (tool arguments are chosen by the
37
+ model and visible in prompts and logs). Pass it in code or set the
38
+ environment:
39
+
40
+ ```bash
41
+ export SEALGRAF_API_KEY=<redacted>
42
+ # optional; defaults to https://sealgraf.com
43
+ export SEALGRAF_BASE_URL=https://sealgraf.com
44
+ ```
45
+
46
+ ## Use
47
+
48
+ ```python
49
+ from crewai import Agent
50
+ from crewai_sealgraf import sealgraf_tools
51
+
52
+ buyer = Agent(
53
+ role="Purchasing agent",
54
+ goal="Buy approved supplies within the owner's limits",
55
+ backstory="...",
56
+ tools=sealgraf_tools(), # reads SEALGRAF_API_KEY
57
+ )
58
+
59
+ # or explicitly:
60
+ tools = sealgraf_tools(api_key="see_...", base_url="https://sealgraf.com")
61
+ ```
62
+
63
+ The four tools:
64
+
65
+ | Tool | Name for the model | What it does |
66
+ |---|---|---|
67
+ | `SealgrafCheckPermissionTool` | `sealgraf_check_permission` | Ask before buying. Returns `allow` (with a single-use `decision_token`), `deny`, or `needs_human_approval`. |
68
+ | `SealgrafClaimDecisionTokenTool` | `sealgraf_claim_decision_token` | After the owner approves, claim the single-use decision token. Fails with a stable code (e.g. `not_approved_yet`) while the owner has not decided. |
69
+ | `SealgrafCompletePurchaseTool` | `sealgraf_complete_purchase` | After the purchase is made, report it; Sealgraf seals it into a receipt. Amounts are integer minor units (cents). |
70
+ | `SealgrafGetReceiptTool` | `sealgraf_get_receipt` | Read a check's state (by `preauth_id`) or a sealed receipt (by `receipt_id`). |
71
+
72
+ Every tool returns the parsed Sealgraf result as JSON — the same shapes
73
+ as the Sealgraf Dify plugin and MCP surfaces.
74
+
75
+ ## Safety behaviour
76
+
77
+ - **Fail closed.** Any failure — timeout, network error, non-2xx,
78
+ malformed response, a token the server did not actually issue — raises
79
+ and fails the tool call. A tool never renders an ambiguous answer as
80
+ permission.
81
+ - **Replay honesty.** Repeating a check with the same idempotency key
82
+ returns the original check flagged `"replayed": true`; a replayed
83
+ `allow` does **not** re-serve the decision token
84
+ (`"decision_token_redelivered": false`). Use the token from the first
85
+ response; if it is lost, run a fresh check without the idempotency key.
86
+ - **Tokens are single-use** and are passed through untouched; they are
87
+ never logged by this package.
88
+ - **Waiting for approval.** After a `needs_human_approval` check, the
89
+ owner's decision takes human time. Poll `sealgraf_get_receipt` for
90
+ the preauth's state until it reads `authorized`, *then* claim — do
91
+ not call `sealgraf_claim_decision_token` repeatedly while waiting:
92
+ every early claim fails with `not_approved_yet`, and an agent
93
+ executor will happily retry it in a tight loop (observed live: 6
94
+ retries in one run). The refusal is harmless — no token exists
95
+ before approval — but the polling pattern is cheaper and clearer.
96
+
97
+ ## Development
98
+
99
+ ```bash
100
+ python -m venv .venv && .venv/bin/pip install -e . pytest
101
+ .venv/bin/python -m pytest tests/ # mocked HTTP only; no network
102
+ ```
@@ -0,0 +1,68 @@
1
+ """Sealgraf spend-approval tools for CrewAI.
2
+
3
+ Four tools that run the Sealgraf spend loop inside a crew:
4
+ check_permission, claim_decision_token, complete_purchase, get_receipt.
5
+ The agent checks BEFORE buying, the owner approves larger purchases on
6
+ Sealgraf's own surface, and every completed purchase is sealed into a
7
+ receipt neither side can rewrite.
8
+ """
9
+
10
+ from .client import (
11
+ CATEGORIES,
12
+ DEFAULT_BASE_URL,
13
+ SealgrafApiError,
14
+ SealgrafClient,
15
+ SealgrafError,
16
+ )
17
+ from .schemas import (
18
+ Category,
19
+ CheckPermissionInput,
20
+ CheckPermissionResult,
21
+ ClaimDecisionTokenInput,
22
+ ClaimDecisionTokenResult,
23
+ CompletePurchaseInput,
24
+ CompletePurchaseResult,
25
+ GetReceiptInput,
26
+ GetReceiptResult,
27
+ PaymentProvenance,
28
+ PaymentRail,
29
+ RailRefKind,
30
+ )
31
+ from .tools import (
32
+ SealgrafBaseTool,
33
+ SealgrafCheckPermissionTool,
34
+ SealgrafClaimDecisionTokenTool,
35
+ SealgrafCompletePurchaseTool,
36
+ SealgrafGetReceiptTool,
37
+ build_evidence,
38
+ sealgraf_tools,
39
+ )
40
+
41
+ __version__ = "0.1.0"
42
+
43
+ __all__ = [
44
+ "CATEGORIES",
45
+ "DEFAULT_BASE_URL",
46
+ "Category",
47
+ "CheckPermissionInput",
48
+ "CheckPermissionResult",
49
+ "ClaimDecisionTokenInput",
50
+ "ClaimDecisionTokenResult",
51
+ "CompletePurchaseInput",
52
+ "CompletePurchaseResult",
53
+ "GetReceiptInput",
54
+ "GetReceiptResult",
55
+ "PaymentProvenance",
56
+ "PaymentRail",
57
+ "RailRefKind",
58
+ "SealgrafApiError",
59
+ "SealgrafBaseTool",
60
+ "SealgrafCheckPermissionTool",
61
+ "SealgrafClaimDecisionTokenTool",
62
+ "SealgrafClient",
63
+ "SealgrafCompletePurchaseTool",
64
+ "SealgrafError",
65
+ "SealgrafGetReceiptTool",
66
+ "build_evidence",
67
+ "sealgraf_tools",
68
+ ]