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.
@@ -0,0 +1,7 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .pytest_cache/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .venv/
@@ -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.
@@ -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"