langchain-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,155 @@
1
+ Metadata-Version: 2.4
2
+ Name: langchain-sealgraf
3
+ Version: 0.1.0
4
+ Summary: Sealgraf spend-approval tools for LangChain: 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: langchain,agents,spend-approval,sealgraf
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: langchain-core<2,>=1.8
19
+ Requires-Dist: httpx<0.29,>=0.27
20
+ Requires-Dist: pydantic<3,>=2
21
+ Provides-Extra: test
22
+ Requires-Dist: pytest>=8; extra == "test"
23
+ Dynamic: license-file
24
+
25
+ # langchain-sealgraf
26
+
27
+ Sealgraf spend-approval tools for [LangChain](https://www.langchain.com/)
28
+ agents.
29
+
30
+ [Sealgraf](https://sealgraf.com) is the owner-approval layer for agent
31
+ spending: **the agent checks BEFORE buying → the owner approves above
32
+ their pre-set limits on Sealgraf's own surface → the completed purchase
33
+ is sealed into a receipt neither side can rewrite.** This package wraps
34
+ the full loop — including the token claim and the completion, which go
35
+ over Sealgraf's REST API — as four LangChain tools.
36
+
37
+ > Status: 0.1.0, built and unit-tested locally. Not yet published to
38
+ > PyPI.
39
+
40
+ ## Install
41
+
42
+ ```bash
43
+ pip install langchain-sealgraf
44
+ ```
45
+
46
+ Depends only on `langchain-core`, `httpx`, and `pydantic` — not the
47
+ full `langchain` metapackage.
48
+
49
+ ## Configure
50
+
51
+ The API key is an agent-scope Sealgraf key. It is host configuration,
52
+ never a tool argument (tool arguments are chosen by the model and land
53
+ in prompts and logs).
54
+
55
+ ```bash
56
+ export SEALGRAF_API_KEY=<your agent-scope API key>
57
+ # optional:
58
+ export SEALGRAF_BASE_URL=https://sealgraf.com # default
59
+ export SEALGRAF_TIMEOUT_SECONDS=20 # default
60
+ ```
61
+
62
+ Or pass configuration in code:
63
+
64
+ ```python
65
+ from langchain_sealgraf import get_sealgraf_tools
66
+
67
+ tools = get_sealgraf_tools(api_key="see_...", base_url="https://sealgraf.com")
68
+ # or hand in a pre-built client:
69
+ from langchain_sealgraf import SealgrafClient, get_sealgraf_tools
70
+ tools = get_sealgraf_tools(SealgrafClient("https://sealgraf.com", "see_..."))
71
+ ```
72
+
73
+ ## Use
74
+
75
+ ```python
76
+ from langchain_sealgraf import get_sealgraf_tools
77
+
78
+ tools = get_sealgraf_tools()
79
+ # → [sealgraf_check_permission, sealgraf_claim_decision_token,
80
+ # sealgraf_complete_purchase, sealgraf_get_receipt]
81
+
82
+ # Any LangChain agent that takes tools can run the loop:
83
+ agent = create_agent(model, tools=tools) # LangChain v1 style
84
+ # or bind them to a chat model, a graph, or call them directly:
85
+ check = tools[0]
86
+ print(check.invoke({
87
+ "category": "household",
88
+ "amount_minor": 4250, # $42.50, integer minor units
89
+ "counterparty": "Lowe's",
90
+ "description": "Trash bags",
91
+ }))
92
+ ```
93
+
94
+ `SealgrafToolkit().get_tools()` returns the same four tools as a
95
+ bundle.
96
+
97
+ ## The four tools
98
+
99
+ | Tool | Sealgraf operation | Purpose |
100
+ |---|---|---|
101
+ | `sealgraf_check_permission` | `POST /v1/preauthorize` | Ask permission BEFORE buying. Returns `allow` (with a single-use `decision_token`), `deny`, or `needs_human_approval`. |
102
+ | `sealgraf_claim_decision_token` | `POST /v1/preauthorize/{id}/decision-token` | After the owner approves, claim the single-use decision token. Fails with code `not_approved_yet` while the owner hasn't decided — wait and retry. |
103
+ | `sealgraf_complete_purchase` | `POST /v1/preauthorize/{id}/complete` | Report the finished purchase; Sealgraf seals it into a receipt. Retry-safe with the same `completion_nonce`. |
104
+ | `sealgraf_get_receipt` | `GET /v1/preauthorize/{id}` or `GET /v1/receipts/{id}` | Read a check's state or a sealed receipt. |
105
+
106
+ ## Conventions
107
+
108
+ - **Outputs are JSON strings.** Each tool returns the parsed Sealgraf
109
+ result serialized as JSON (per LangChain's string-return convention)
110
+ with a stable shape: `outcome`, `state`, `preauth_id`,
111
+ `decision_token`, `receipt_id`, `replayed`, ... A chain that needs
112
+ the values can `json.loads` the output.
113
+ - **Failures raise.** Every failure — missing key, timeout, network
114
+ error, non-2xx status, malformed response — raises `SealgrafError`
115
+ (API failures raise `SealgrafApiError` with `.status_code`,
116
+ `.detail`, and the server's stable `.code` when it sends one). The
117
+ tools never return an error string: in a spend loop, a raised error
118
+ fails the tool call outright, while an error-shaped string is one
119
+ misreading away from a purchase. `needs_human_approval` is a normal
120
+ outcome, not an error.
121
+ - **Fail closed.** A fresh `allow` without a decision token is treated
122
+ as malformed and raises. An idempotent replay of a check returns the
123
+ original record flagged `"replayed": true` with
124
+ `"decision_token_redelivered": false` — Sealgraf never re-serves
125
+ tokens, and a replay is never presented as a fresh permission.
126
+ - **Amounts are integer minor units** (cents): $42.50 is `4250`,
127
+ everywhere.
128
+ - **Categories are a closed list** (Sealgraf's canonical 14:
129
+ groceries, household, dining, travel, software, office_supplies,
130
+ shopping, transport, entertainment, health, supplies, materials,
131
+ equipment, fuel).
132
+ - **The key travels only in the `X-API-Key` header.** Decision tokens
133
+ are passed through untouched and are never logged by this package.
134
+
135
+ ## The spend loop
136
+
137
+ ```
138
+ check_permission ── allow ──────────────► complete_purchase ──► receipt
139
+ │
140
+ └─ needs_human_approval ─► owner approves in Sealgraf
141
+ └─► claim_decision_token ─► complete_purchase
142
+ │
143
+ └─ deny ─► do not buy
144
+ ```
145
+
146
+ ## Development
147
+
148
+ ```bash
149
+ python -m venv .venv && .venv/bin/pip install -e ".[test]"
150
+ .venv/bin/python -m pytest # mocked HTTP only; no network
151
+ ```
152
+
153
+ ## License
154
+
155
+ MIT
@@ -0,0 +1,131 @@
1
+ # langchain-sealgraf
2
+
3
+ Sealgraf spend-approval tools for [LangChain](https://www.langchain.com/)
4
+ agents.
5
+
6
+ [Sealgraf](https://sealgraf.com) is the owner-approval layer for agent
7
+ spending: **the agent checks BEFORE buying → the owner approves above
8
+ their pre-set limits on Sealgraf's own surface → the completed purchase
9
+ is sealed into a receipt neither side can rewrite.** This package wraps
10
+ the full loop — including the token claim and the completion, which go
11
+ over Sealgraf's REST API — as four LangChain tools.
12
+
13
+ > Status: 0.1.0, built and unit-tested locally. Not yet published to
14
+ > PyPI.
15
+
16
+ ## Install
17
+
18
+ ```bash
19
+ pip install langchain-sealgraf
20
+ ```
21
+
22
+ Depends only on `langchain-core`, `httpx`, and `pydantic` — not the
23
+ full `langchain` metapackage.
24
+
25
+ ## Configure
26
+
27
+ The API key is an agent-scope Sealgraf key. It is host configuration,
28
+ never a tool argument (tool arguments are chosen by the model and land
29
+ in prompts and logs).
30
+
31
+ ```bash
32
+ export SEALGRAF_API_KEY=<your agent-scope API key>
33
+ # optional:
34
+ export SEALGRAF_BASE_URL=https://sealgraf.com # default
35
+ export SEALGRAF_TIMEOUT_SECONDS=20 # default
36
+ ```
37
+
38
+ Or pass configuration in code:
39
+
40
+ ```python
41
+ from langchain_sealgraf import get_sealgraf_tools
42
+
43
+ tools = get_sealgraf_tools(api_key="see_...", base_url="https://sealgraf.com")
44
+ # or hand in a pre-built client:
45
+ from langchain_sealgraf import SealgrafClient, get_sealgraf_tools
46
+ tools = get_sealgraf_tools(SealgrafClient("https://sealgraf.com", "see_..."))
47
+ ```
48
+
49
+ ## Use
50
+
51
+ ```python
52
+ from langchain_sealgraf import get_sealgraf_tools
53
+
54
+ tools = get_sealgraf_tools()
55
+ # → [sealgraf_check_permission, sealgraf_claim_decision_token,
56
+ # sealgraf_complete_purchase, sealgraf_get_receipt]
57
+
58
+ # Any LangChain agent that takes tools can run the loop:
59
+ agent = create_agent(model, tools=tools) # LangChain v1 style
60
+ # or bind them to a chat model, a graph, or call them directly:
61
+ check = tools[0]
62
+ print(check.invoke({
63
+ "category": "household",
64
+ "amount_minor": 4250, # $42.50, integer minor units
65
+ "counterparty": "Lowe's",
66
+ "description": "Trash bags",
67
+ }))
68
+ ```
69
+
70
+ `SealgrafToolkit().get_tools()` returns the same four tools as a
71
+ bundle.
72
+
73
+ ## The four tools
74
+
75
+ | Tool | Sealgraf operation | Purpose |
76
+ |---|---|---|
77
+ | `sealgraf_check_permission` | `POST /v1/preauthorize` | Ask permission BEFORE buying. Returns `allow` (with a single-use `decision_token`), `deny`, or `needs_human_approval`. |
78
+ | `sealgraf_claim_decision_token` | `POST /v1/preauthorize/{id}/decision-token` | After the owner approves, claim the single-use decision token. Fails with code `not_approved_yet` while the owner hasn't decided — wait and retry. |
79
+ | `sealgraf_complete_purchase` | `POST /v1/preauthorize/{id}/complete` | Report the finished purchase; Sealgraf seals it into a receipt. Retry-safe with the same `completion_nonce`. |
80
+ | `sealgraf_get_receipt` | `GET /v1/preauthorize/{id}` or `GET /v1/receipts/{id}` | Read a check's state or a sealed receipt. |
81
+
82
+ ## Conventions
83
+
84
+ - **Outputs are JSON strings.** Each tool returns the parsed Sealgraf
85
+ result serialized as JSON (per LangChain's string-return convention)
86
+ with a stable shape: `outcome`, `state`, `preauth_id`,
87
+ `decision_token`, `receipt_id`, `replayed`, ... A chain that needs
88
+ the values can `json.loads` the output.
89
+ - **Failures raise.** Every failure — missing key, timeout, network
90
+ error, non-2xx status, malformed response — raises `SealgrafError`
91
+ (API failures raise `SealgrafApiError` with `.status_code`,
92
+ `.detail`, and the server's stable `.code` when it sends one). The
93
+ tools never return an error string: in a spend loop, a raised error
94
+ fails the tool call outright, while an error-shaped string is one
95
+ misreading away from a purchase. `needs_human_approval` is a normal
96
+ outcome, not an error.
97
+ - **Fail closed.** A fresh `allow` without a decision token is treated
98
+ as malformed and raises. An idempotent replay of a check returns the
99
+ original record flagged `"replayed": true` with
100
+ `"decision_token_redelivered": false` — Sealgraf never re-serves
101
+ tokens, and a replay is never presented as a fresh permission.
102
+ - **Amounts are integer minor units** (cents): $42.50 is `4250`,
103
+ everywhere.
104
+ - **Categories are a closed list** (Sealgraf's canonical 14:
105
+ groceries, household, dining, travel, software, office_supplies,
106
+ shopping, transport, entertainment, health, supplies, materials,
107
+ equipment, fuel).
108
+ - **The key travels only in the `X-API-Key` header.** Decision tokens
109
+ are passed through untouched and are never logged by this package.
110
+
111
+ ## The spend loop
112
+
113
+ ```
114
+ check_permission ── allow ──────────────► complete_purchase ──► receipt
115
+ │
116
+ └─ needs_human_approval ─► owner approves in Sealgraf
117
+ └─► claim_decision_token ─► complete_purchase
118
+ │
119
+ └─ deny ─► do not buy
120
+ ```
121
+
122
+ ## Development
123
+
124
+ ```bash
125
+ python -m venv .venv && .venv/bin/pip install -e ".[test]"
126
+ .venv/bin/python -m pytest # mocked HTTP only; no network
127
+ ```
128
+
129
+ ## License
130
+
131
+ MIT
@@ -0,0 +1,77 @@
1
+ """Sealgraf tools for LangChain.
2
+
3
+ Sealgraf is the owner-approval layer for agent spending. These tools
4
+ run the full loop inside a LangChain agent: check a purchase against
5
+ the owner's pre-set limits BEFORE buying, let the owner approve larger
6
+ purchases on Sealgraf's own surface, and seal every completed purchase
7
+ into a receipt neither side can rewrite.
8
+
9
+ from langchain_sealgraf import get_sealgraf_tools
10
+
11
+ tools = get_sealgraf_tools() # reads SEALGRAF_API_KEY from the env
12
+
13
+ Tools return JSON strings and raise :class:`SealgrafError` on any
14
+ failure — a failed tool call is never a permission.
15
+ """
16
+
17
+ from .client import (
18
+ CATEGORIES,
19
+ DECISION_OUTCOMES,
20
+ DEFAULT_BASE_URL,
21
+ PAYMENT_PROVENANCES,
22
+ PAYMENT_RAILS,
23
+ RAIL_REF_KINDS,
24
+ SealgrafApiError,
25
+ SealgrafClient,
26
+ SealgrafConfigError,
27
+ SealgrafError,
28
+ SealgrafSettings,
29
+ client_from_settings,
30
+ )
31
+ from .tools import (
32
+ Category,
33
+ CheckPermissionInput,
34
+ CheckPermissionTool,
35
+ ClaimDecisionTokenInput,
36
+ ClaimDecisionTokenTool,
37
+ CompletePurchaseInput,
38
+ CompletePurchaseTool,
39
+ GetReceiptInput,
40
+ GetReceiptTool,
41
+ PaymentProvenance,
42
+ PaymentRail,
43
+ RailRefKind,
44
+ SealgrafToolkit,
45
+ get_sealgraf_tools,
46
+ )
47
+
48
+ __version__ = "0.1.0"
49
+
50
+ __all__ = [
51
+ "CATEGORIES",
52
+ "DECISION_OUTCOMES",
53
+ "DEFAULT_BASE_URL",
54
+ "PAYMENT_PROVENANCES",
55
+ "PAYMENT_RAILS",
56
+ "RAIL_REF_KINDS",
57
+ "Category",
58
+ "CheckPermissionInput",
59
+ "CheckPermissionTool",
60
+ "ClaimDecisionTokenInput",
61
+ "ClaimDecisionTokenTool",
62
+ "CompletePurchaseInput",
63
+ "CompletePurchaseTool",
64
+ "GetReceiptInput",
65
+ "GetReceiptTool",
66
+ "PaymentProvenance",
67
+ "PaymentRail",
68
+ "RailRefKind",
69
+ "SealgrafApiError",
70
+ "SealgrafClient",
71
+ "SealgrafConfigError",
72
+ "SealgrafError",
73
+ "SealgrafSettings",
74
+ "SealgrafToolkit",
75
+ "client_from_settings",
76
+ "get_sealgraf_tools",
77
+ ]