kollguard 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.
- kollguard-0.1.0/.gitignore +7 -0
- kollguard-0.1.0/LICENSE +21 -0
- kollguard-0.1.0/PKG-INFO +192 -0
- kollguard-0.1.0/README.md +167 -0
- kollguard-0.1.0/pyproject.toml +42 -0
- kollguard-0.1.0/src/kollguard/__init__.py +14 -0
- kollguard-0.1.0/src/kollguard/_version.py +1 -0
- kollguard-0.1.0/src/kollguard/client.py +334 -0
- kollguard-0.1.0/src/kollguard/describe.py +112 -0
- kollguard-0.1.0/src/kollguard/langgraph.py +153 -0
- kollguard-0.1.0/src/kollguard/openai_agents.py +131 -0
- kollguard-0.1.0/src/kollguard/policy.py +97 -0
- kollguard-0.1.0/src/kollguard/py.typed +0 -0
- kollguard-0.1.0/tests/conftest.py +204 -0
- kollguard-0.1.0/tests/test_client.py +348 -0
- kollguard-0.1.0/tests/test_langgraph.py +128 -0
- kollguard-0.1.0/tests/test_langgraph_real.py +166 -0
- kollguard-0.1.0/tests/test_openai_agents.py +143 -0
- kollguard-0.1.0/tests/test_openai_agents_real.py +112 -0
kollguard-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kollitech Corp
|
|
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.
|
kollguard-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: kollguard
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: KollGuard Agent Watch gate for Python agents: authorize tool calls before they run (LangGraph, OpenAI Agents SDK).
|
|
5
|
+
Project-URL: Homepage, https://kollguard.com
|
|
6
|
+
Author: Kollitech Corp
|
|
7
|
+
License: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: ai-agents,governance,human-in-the-loop,kollguard,langgraph,openai-agents
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Typing :: Typed
|
|
14
|
+
Requires-Python: >=3.9
|
|
15
|
+
Provides-Extra: langgraph
|
|
16
|
+
Requires-Dist: langchain-core<2,>=1.0; extra == 'langgraph'
|
|
17
|
+
Requires-Dist: langgraph-prebuilt<2,>=1.1; extra == 'langgraph'
|
|
18
|
+
Requires-Dist: langgraph<2,>=1.2; extra == 'langgraph'
|
|
19
|
+
Provides-Extra: openai-agents
|
|
20
|
+
Requires-Dist: openai-agents<1,>=0.25; extra == 'openai-agents'
|
|
21
|
+
Provides-Extra: test
|
|
22
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
|
|
23
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# kollguard (Python)
|
|
27
|
+
|
|
28
|
+
Authorize every tool call your Python agent makes **before it runs**. Each call is checked against your KollGuard
|
|
29
|
+
Agent Watch policy and answers `allow`, `deny`, or `pending` (a named human approves it in KollGuard).
|
|
30
|
+
|
|
31
|
+
- Adapters for **LangGraph** and the **OpenAI Agents SDK**, both optional extras.
|
|
32
|
+
- Zero runtime dependencies (stdlib only). Sync and async. Python 3.9+.
|
|
33
|
+
- **Argument values never leave your host.** KollGuard sees the tool name, the argument *names*, and the optional
|
|
34
|
+
`resource` string you choose to pass. The `kgw_` token goes only in the `x-agent-token` header and is never logged
|
|
35
|
+
or included in an exception message.
|
|
36
|
+
- **Fail modes per tool.** If KollGuard cannot answer (network, timeout, 5xx, 429, bad token), a tool marked
|
|
37
|
+
`fail: "closed"` is blocked and a tool marked `fail: "open"` runs. The default is closed.
|
|
38
|
+
|
|
39
|
+
> Enforcement is **cooperative**: this SDK gates the calls that go through it. It is not a sandbox, and code that
|
|
40
|
+
> bypasses the wrapper is not gated. Agent Watch labels it that way on the agent's passport.
|
|
41
|
+
|
|
42
|
+
Get an agent token in KollGuard under Agent Control, then:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
export KOLLGUARD_AGENT_TOKEN=kgw_...
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## LangGraph in 3 steps
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
pip install "kollguard[langgraph]"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
1. Swap `ToolNode` for the gated one.
|
|
55
|
+
2. Compile with a checkpointer (needed for approvals that pause the graph).
|
|
56
|
+
3. Resume with `Command(resume=...)` after the human decides in KollGuard.
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
from kollguard import KollGuard
|
|
60
|
+
from kollguard.langgraph import kollguard_tool_node
|
|
61
|
+
from langgraph.checkpoint.memory import InMemorySaver
|
|
62
|
+
from langgraph.types import Command
|
|
63
|
+
|
|
64
|
+
kg = KollGuard(policy={"tools": {"send_email": {"class": "external_comm"},
|
|
65
|
+
"lookup": {"class": "read", "fail": "open"}}})
|
|
66
|
+
|
|
67
|
+
graph.add_node("tools", kollguard_tool_node([send_email, lookup], kg)) # step 1
|
|
68
|
+
app = graph.compile(checkpointer=InMemorySaver()) # step 2
|
|
69
|
+
|
|
70
|
+
out = app.invoke({"messages": [("user", "email the customer")]}, {"configurable": {"thread_id": "t1"}})
|
|
71
|
+
if "__interrupt__" in out: # pending approval
|
|
72
|
+
print(out["__interrupt__"][0].value) # {"kind": "kollguard_approval", "kollguard_request_id": ..., ...}
|
|
73
|
+
# ...the approver clicks Approve in KollGuard...
|
|
74
|
+
out = app.invoke(Command(resume=True), {"configurable": {"thread_id": "t1"}}) # step 3
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
What happens: allow runs the tool; deny returns a `ToolMessage(status="error")` to the model and the tool never
|
|
78
|
+
runs; pending calls `interrupt()`. LangGraph re-executes the node on resume, and the idempotency key
|
|
79
|
+
(`thread_id` + `tool_call_id`) makes the second check a replay of the *same* request, never a duplicate. The resume
|
|
80
|
+
value is never treated as approval: KollGuard is asked again, and if it is still pending the graph interrupts again.
|
|
81
|
+
|
|
82
|
+
`ToolNode(..., **kollguard_wrappers(kg))` and `kollguard.langgraph.check(kg, name, args, ...)` (for your own nodes)
|
|
83
|
+
are also available. The wrapper has the `(request, handler)` shape of `AgentMiddleware.wrap_tool_call`.
|
|
84
|
+
|
|
85
|
+
## OpenAI Agents SDK in 3 steps
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
pip install "kollguard[openai-agents]"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
1. Wrap your tools with `guard_tool`.
|
|
92
|
+
2. Run the agent; a call that needs a human stops the run with an interruption.
|
|
93
|
+
3. After the human decides in KollGuard, call `resolve_interruptions` and run again from the state.
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
from agents import Agent, Runner, function_tool
|
|
97
|
+
from kollguard import KollGuard
|
|
98
|
+
from kollguard.openai_agents import guard_tool, aresolve_interruptions
|
|
99
|
+
|
|
100
|
+
kg = KollGuard(policy={"tools": {"refund": {"class": "money_auth"}}})
|
|
101
|
+
|
|
102
|
+
@function_tool
|
|
103
|
+
def refund(order_id: str) -> str: ...
|
|
104
|
+
|
|
105
|
+
agent = Agent(name="support", tools=[guard_tool(refund, kg)]) # step 1
|
|
106
|
+
result = await Runner.run(agent, "refund order 42") # step 2
|
|
107
|
+
while result.interruptions:
|
|
108
|
+
# ...wait for the approver in KollGuard...
|
|
109
|
+
state = result.to_state()
|
|
110
|
+
await aresolve_interruptions(state, kg) # approves/rejects each call from KollGuard's answer (step 3)
|
|
111
|
+
result = await Runner.run(agent, state)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
`guard_tool` attaches two things: a `ToolInputGuardrail` that is the real gate (runs just before the tool, after any
|
|
115
|
+
approval, so a local `state.approve()` can never bypass KollGuard) and a `needs_approval` that returns True only
|
|
116
|
+
while KollGuard has the call pending. Both use the model's `call_id` as the idempotency key. Use
|
|
117
|
+
`kollguard_tool_guardrail(kg)` / `kollguard_needs_approval(kg, "tool_name")` separately if you prefer.
|
|
118
|
+
|
|
119
|
+
## Any other agent
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
d = kg.gate("send_email", {"to": to, "body": body}, framework="my-agent", resource="mail:outbound")
|
|
123
|
+
if not d.allowed: # d.decision is "deny" or "pending"; d.reason says why
|
|
124
|
+
raise PermissionError(d.reason)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`kg.decide()` asks once; `kg.gate()` also waits inline (default 120 s) for a human; `kg.wait_for_decision(request_id)`
|
|
128
|
+
polls. Async twins: `adecide`, `agate`, `await_decision`, `apoll`. None of them raise.
|
|
129
|
+
|
|
130
|
+
## Policy file
|
|
131
|
+
|
|
132
|
+
A compatible subset (`tools`, `default`) of the JSON `kollguard-claude-hook` reads (`mcp` and `mcpServers` are ignored):
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"tools": {
|
|
137
|
+
"send_email": {"class": "external_comm", "fail": "closed"},
|
|
138
|
+
"lookup_order": {"class": "read", "fail": "open"},
|
|
139
|
+
"get_time": {"gate": false},
|
|
140
|
+
"stripe_*": {"class": "money_auth"}
|
|
141
|
+
},
|
|
142
|
+
"default": {"class": "unclassified", "fail": "closed"}
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`KollGuard(policy="kollguard.policy.json")`. Classes: read, propose, write, external_comm, money_auth, phi_access,
|
|
147
|
+
patient_facing, unclassified. `"gate": false` makes no network call (zero added latency).
|
|
148
|
+
|
|
149
|
+
## What is sent
|
|
150
|
+
|
|
151
|
+
| Sent | Never sent |
|
|
152
|
+
|---|---|
|
|
153
|
+
| tool name, framework label, argument **names**, action class, your optional `resource` and `summary` text, an HMAC idempotency key | argument values, prompts, completions, tool results, the token in any body or log |
|
|
154
|
+
|
|
155
|
+
`resource` is sent exactly as you give it (the server redacts it before storage): pass a template such as
|
|
156
|
+
`stripe:refund`, not a value.
|
|
157
|
+
|
|
158
|
+
## Limits in this release
|
|
159
|
+
|
|
160
|
+
- Python: the core client runs on 3.9+. The LangGraph and OpenAI Agents extras need 3.10+ (their own floor). Using
|
|
161
|
+
LangGraph with **async** graphs and approvals (`interrupt()`) needs Python 3.11+ (LangGraph relies on contextvars
|
|
162
|
+
there; verified failing on 3.10). Sync graphs work on 3.10.
|
|
163
|
+
- OpenAI Agents: do not enable `RunConfig.tool_execution.pre_approval_tool_input_guardrails` together with
|
|
164
|
+
`guard_tool`. The guardrail would then run before the pause and turn a pending call into a refusal instead of an
|
|
165
|
+
interruption.
|
|
166
|
+
- If one `tool_call_id` is asked again after its request has expired twice, the deterministic retry key replays the
|
|
167
|
+
expired row and the call is denied (fail-safe) rather than re-filed.
|
|
168
|
+
- v1 wire contract: pending requests expire after 15 minutes and an allow is valid for 15 minutes. Approvals that
|
|
169
|
+
must outlive a process (72 h) need the resumable gate (server PR1b); until then keep the process or checkpointer
|
|
170
|
+
alive, or the call is asked again with a new request after expiry.
|
|
171
|
+
- Not included yet: webhook signature verification and the OpenTelemetry span processor (they depend on server
|
|
172
|
+
pieces that have not shipped).
|
|
173
|
+
|
|
174
|
+
## Develop
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
uv venv && uv pip install -e ".[langgraph,openai-agents,test]"
|
|
178
|
+
pytest
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
The tests run a fake gate that enforces the route's exact validation, and the adapter tests run against the real
|
|
182
|
+
frameworks when installed (mocked otherwise).
|
|
183
|
+
|
|
184
|
+
## Release
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
python -m pip install build twine
|
|
188
|
+
python -m build # dist/kollguard-<version>.tar.gz and .whl
|
|
189
|
+
twine upload dist/* # needs a PyPI account and API token for the `kollguard` project
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
MIT licensed.
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# kollguard (Python)
|
|
2
|
+
|
|
3
|
+
Authorize every tool call your Python agent makes **before it runs**. Each call is checked against your KollGuard
|
|
4
|
+
Agent Watch policy and answers `allow`, `deny`, or `pending` (a named human approves it in KollGuard).
|
|
5
|
+
|
|
6
|
+
- Adapters for **LangGraph** and the **OpenAI Agents SDK**, both optional extras.
|
|
7
|
+
- Zero runtime dependencies (stdlib only). Sync and async. Python 3.9+.
|
|
8
|
+
- **Argument values never leave your host.** KollGuard sees the tool name, the argument *names*, and the optional
|
|
9
|
+
`resource` string you choose to pass. The `kgw_` token goes only in the `x-agent-token` header and is never logged
|
|
10
|
+
or included in an exception message.
|
|
11
|
+
- **Fail modes per tool.** If KollGuard cannot answer (network, timeout, 5xx, 429, bad token), a tool marked
|
|
12
|
+
`fail: "closed"` is blocked and a tool marked `fail: "open"` runs. The default is closed.
|
|
13
|
+
|
|
14
|
+
> Enforcement is **cooperative**: this SDK gates the calls that go through it. It is not a sandbox, and code that
|
|
15
|
+
> bypasses the wrapper is not gated. Agent Watch labels it that way on the agent's passport.
|
|
16
|
+
|
|
17
|
+
Get an agent token in KollGuard under Agent Control, then:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
export KOLLGUARD_AGENT_TOKEN=kgw_...
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## LangGraph in 3 steps
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install "kollguard[langgraph]"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
1. Swap `ToolNode` for the gated one.
|
|
30
|
+
2. Compile with a checkpointer (needed for approvals that pause the graph).
|
|
31
|
+
3. Resume with `Command(resume=...)` after the human decides in KollGuard.
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
from kollguard import KollGuard
|
|
35
|
+
from kollguard.langgraph import kollguard_tool_node
|
|
36
|
+
from langgraph.checkpoint.memory import InMemorySaver
|
|
37
|
+
from langgraph.types import Command
|
|
38
|
+
|
|
39
|
+
kg = KollGuard(policy={"tools": {"send_email": {"class": "external_comm"},
|
|
40
|
+
"lookup": {"class": "read", "fail": "open"}}})
|
|
41
|
+
|
|
42
|
+
graph.add_node("tools", kollguard_tool_node([send_email, lookup], kg)) # step 1
|
|
43
|
+
app = graph.compile(checkpointer=InMemorySaver()) # step 2
|
|
44
|
+
|
|
45
|
+
out = app.invoke({"messages": [("user", "email the customer")]}, {"configurable": {"thread_id": "t1"}})
|
|
46
|
+
if "__interrupt__" in out: # pending approval
|
|
47
|
+
print(out["__interrupt__"][0].value) # {"kind": "kollguard_approval", "kollguard_request_id": ..., ...}
|
|
48
|
+
# ...the approver clicks Approve in KollGuard...
|
|
49
|
+
out = app.invoke(Command(resume=True), {"configurable": {"thread_id": "t1"}}) # step 3
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
What happens: allow runs the tool; deny returns a `ToolMessage(status="error")` to the model and the tool never
|
|
53
|
+
runs; pending calls `interrupt()`. LangGraph re-executes the node on resume, and the idempotency key
|
|
54
|
+
(`thread_id` + `tool_call_id`) makes the second check a replay of the *same* request, never a duplicate. The resume
|
|
55
|
+
value is never treated as approval: KollGuard is asked again, and if it is still pending the graph interrupts again.
|
|
56
|
+
|
|
57
|
+
`ToolNode(..., **kollguard_wrappers(kg))` and `kollguard.langgraph.check(kg, name, args, ...)` (for your own nodes)
|
|
58
|
+
are also available. The wrapper has the `(request, handler)` shape of `AgentMiddleware.wrap_tool_call`.
|
|
59
|
+
|
|
60
|
+
## OpenAI Agents SDK in 3 steps
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install "kollguard[openai-agents]"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
1. Wrap your tools with `guard_tool`.
|
|
67
|
+
2. Run the agent; a call that needs a human stops the run with an interruption.
|
|
68
|
+
3. After the human decides in KollGuard, call `resolve_interruptions` and run again from the state.
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
from agents import Agent, Runner, function_tool
|
|
72
|
+
from kollguard import KollGuard
|
|
73
|
+
from kollguard.openai_agents import guard_tool, aresolve_interruptions
|
|
74
|
+
|
|
75
|
+
kg = KollGuard(policy={"tools": {"refund": {"class": "money_auth"}}})
|
|
76
|
+
|
|
77
|
+
@function_tool
|
|
78
|
+
def refund(order_id: str) -> str: ...
|
|
79
|
+
|
|
80
|
+
agent = Agent(name="support", tools=[guard_tool(refund, kg)]) # step 1
|
|
81
|
+
result = await Runner.run(agent, "refund order 42") # step 2
|
|
82
|
+
while result.interruptions:
|
|
83
|
+
# ...wait for the approver in KollGuard...
|
|
84
|
+
state = result.to_state()
|
|
85
|
+
await aresolve_interruptions(state, kg) # approves/rejects each call from KollGuard's answer (step 3)
|
|
86
|
+
result = await Runner.run(agent, state)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`guard_tool` attaches two things: a `ToolInputGuardrail` that is the real gate (runs just before the tool, after any
|
|
90
|
+
approval, so a local `state.approve()` can never bypass KollGuard) and a `needs_approval` that returns True only
|
|
91
|
+
while KollGuard has the call pending. Both use the model's `call_id` as the idempotency key. Use
|
|
92
|
+
`kollguard_tool_guardrail(kg)` / `kollguard_needs_approval(kg, "tool_name")` separately if you prefer.
|
|
93
|
+
|
|
94
|
+
## Any other agent
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
d = kg.gate("send_email", {"to": to, "body": body}, framework="my-agent", resource="mail:outbound")
|
|
98
|
+
if not d.allowed: # d.decision is "deny" or "pending"; d.reason says why
|
|
99
|
+
raise PermissionError(d.reason)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
`kg.decide()` asks once; `kg.gate()` also waits inline (default 120 s) for a human; `kg.wait_for_decision(request_id)`
|
|
103
|
+
polls. Async twins: `adecide`, `agate`, `await_decision`, `apoll`. None of them raise.
|
|
104
|
+
|
|
105
|
+
## Policy file
|
|
106
|
+
|
|
107
|
+
A compatible subset (`tools`, `default`) of the JSON `kollguard-claude-hook` reads (`mcp` and `mcpServers` are ignored):
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"tools": {
|
|
112
|
+
"send_email": {"class": "external_comm", "fail": "closed"},
|
|
113
|
+
"lookup_order": {"class": "read", "fail": "open"},
|
|
114
|
+
"get_time": {"gate": false},
|
|
115
|
+
"stripe_*": {"class": "money_auth"}
|
|
116
|
+
},
|
|
117
|
+
"default": {"class": "unclassified", "fail": "closed"}
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`KollGuard(policy="kollguard.policy.json")`. Classes: read, propose, write, external_comm, money_auth, phi_access,
|
|
122
|
+
patient_facing, unclassified. `"gate": false` makes no network call (zero added latency).
|
|
123
|
+
|
|
124
|
+
## What is sent
|
|
125
|
+
|
|
126
|
+
| Sent | Never sent |
|
|
127
|
+
|---|---|
|
|
128
|
+
| tool name, framework label, argument **names**, action class, your optional `resource` and `summary` text, an HMAC idempotency key | argument values, prompts, completions, tool results, the token in any body or log |
|
|
129
|
+
|
|
130
|
+
`resource` is sent exactly as you give it (the server redacts it before storage): pass a template such as
|
|
131
|
+
`stripe:refund`, not a value.
|
|
132
|
+
|
|
133
|
+
## Limits in this release
|
|
134
|
+
|
|
135
|
+
- Python: the core client runs on 3.9+. The LangGraph and OpenAI Agents extras need 3.10+ (their own floor). Using
|
|
136
|
+
LangGraph with **async** graphs and approvals (`interrupt()`) needs Python 3.11+ (LangGraph relies on contextvars
|
|
137
|
+
there; verified failing on 3.10). Sync graphs work on 3.10.
|
|
138
|
+
- OpenAI Agents: do not enable `RunConfig.tool_execution.pre_approval_tool_input_guardrails` together with
|
|
139
|
+
`guard_tool`. The guardrail would then run before the pause and turn a pending call into a refusal instead of an
|
|
140
|
+
interruption.
|
|
141
|
+
- If one `tool_call_id` is asked again after its request has expired twice, the deterministic retry key replays the
|
|
142
|
+
expired row and the call is denied (fail-safe) rather than re-filed.
|
|
143
|
+
- v1 wire contract: pending requests expire after 15 minutes and an allow is valid for 15 minutes. Approvals that
|
|
144
|
+
must outlive a process (72 h) need the resumable gate (server PR1b); until then keep the process or checkpointer
|
|
145
|
+
alive, or the call is asked again with a new request after expiry.
|
|
146
|
+
- Not included yet: webhook signature verification and the OpenTelemetry span processor (they depend on server
|
|
147
|
+
pieces that have not shipped).
|
|
148
|
+
|
|
149
|
+
## Develop
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
uv venv && uv pip install -e ".[langgraph,openai-agents,test]"
|
|
153
|
+
pytest
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
The tests run a fake gate that enforces the route's exact validation, and the adapter tests run against the real
|
|
157
|
+
frameworks when installed (mocked otherwise).
|
|
158
|
+
|
|
159
|
+
## Release
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
python -m pip install build twine
|
|
163
|
+
python -m build # dist/kollguard-<version>.tar.gz and .whl
|
|
164
|
+
twine upload dist/* # needs a PyPI account and API token for the `kollguard` project
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
MIT licensed.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.21"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "kollguard"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "KollGuard Agent Watch gate for Python agents: authorize tool calls before they run (LangGraph, OpenAI Agents SDK)."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
requires-python = ">=3.9"
|
|
12
|
+
authors = [{ name = "Kollitech Corp" }]
|
|
13
|
+
keywords = ["ai-agents", "governance", "langgraph", "openai-agents", "kollguard", "human-in-the-loop"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"License :: OSI Approved :: MIT License",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Typing :: Typed",
|
|
19
|
+
]
|
|
20
|
+
dependencies = []
|
|
21
|
+
|
|
22
|
+
[project.optional-dependencies]
|
|
23
|
+
langgraph = ["langgraph>=1.2,<2", "langgraph-prebuilt>=1.1,<2", "langchain-core>=1.0,<2"]
|
|
24
|
+
openai-agents = ["openai-agents>=0.25,<1"]
|
|
25
|
+
test = ["pytest>=8", "pytest-asyncio>=0.23"]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
Homepage = "https://kollguard.com"
|
|
29
|
+
|
|
30
|
+
[tool.hatch.version]
|
|
31
|
+
path = "src/kollguard/_version.py"
|
|
32
|
+
|
|
33
|
+
[tool.hatch.build.targets.wheel]
|
|
34
|
+
packages = ["src/kollguard"]
|
|
35
|
+
|
|
36
|
+
[tool.hatch.build.targets.sdist]
|
|
37
|
+
include = ["src/kollguard", "tests", "README.md", "LICENSE", "pyproject.toml"]
|
|
38
|
+
|
|
39
|
+
[tool.pytest.ini_options]
|
|
40
|
+
testpaths = ["tests"]
|
|
41
|
+
asyncio_mode = "auto"
|
|
42
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""KollGuard Agent Watch gate for Python agents.
|
|
2
|
+
|
|
3
|
+
from kollguard import KollGuard
|
|
4
|
+
kg = KollGuard() # KOLLGUARD_AGENT_TOKEN from the environment
|
|
5
|
+
d = kg.gate("send_email", {"to": ..., "body": ...}, framework="my-agent")
|
|
6
|
+
if d.allowed: ...
|
|
7
|
+
|
|
8
|
+
Framework adapters (optional extras): ``kollguard.langgraph`` and ``kollguard.openai_agents``.
|
|
9
|
+
"""
|
|
10
|
+
from ._version import __version__
|
|
11
|
+
from .client import DEFAULT_API_URL, Decision, KollGuard, refusal_text
|
|
12
|
+
from .policy import ACTION_CLASSES, Policy, Rule
|
|
13
|
+
|
|
14
|
+
__all__ = ["KollGuard", "Decision", "Policy", "Rule", "ACTION_CLASSES", "DEFAULT_API_URL", "refusal_text", "__version__"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|