capsule-strands 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,290 @@
1
+ # Local Docker data
2
+ .docker/
3
+
4
+ # Local-only dead-reference checker, not a maintained repo config
5
+ /knip.config.ts
6
+
7
+ # playwright-cli local session data (auth state, screenshots, logs)
8
+ .playwright-cli/
9
+
10
+ # Byte-compiled / optimized / DLL files
11
+ __pycache__/
12
+ *.py[cod]
13
+ *$py.class
14
+
15
+ # C extensions
16
+ *.so
17
+
18
+ # Distribution / packaging
19
+ .Python
20
+ build/
21
+ develop-eggs/
22
+ dist/
23
+ downloads/
24
+ eggs/
25
+ .eggs/
26
+ lib/
27
+ !apps/portal/src/lib/
28
+ !apps/backoffice-ui/src/lib/
29
+ !libs/ui/src/lib/
30
+ # Paraglide-js output — auto-generated; never track (compiler rewrites .gitignore comment URL per version)
31
+ apps/portal/src/lib/i18n/
32
+ lib64/
33
+ parts/
34
+ sdist/
35
+ var/
36
+ wheels/
37
+ share/python-wheels/
38
+ *.egg-info/
39
+ .installed.cfg
40
+ *.egg
41
+ MANIFEST
42
+
43
+ # PyInstaller
44
+ # Usually these files are written by a python script from a template
45
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
46
+ *.manifest
47
+ *.spec
48
+
49
+ # Installer logs
50
+ pip-log.txt
51
+ pip-delete-this-directory.txt
52
+
53
+ # Unit test / coverage reports
54
+ htmlcov/
55
+ .tox/
56
+ .nox/
57
+ .coverage
58
+ .coverage.*
59
+ .cache
60
+ nosetests.xml
61
+ coverage.xml
62
+ *.cover
63
+ *.py,cover
64
+ .hypothesis/
65
+ .pytest_cache/
66
+ cover/
67
+
68
+ # Translations
69
+ *.mo
70
+ *.pot
71
+
72
+ # Django stuff:
73
+ *.log
74
+ local_settings.py
75
+ db.sqlite3
76
+ db.sqlite3-journal
77
+
78
+ # Flask stuff:
79
+ instance/
80
+ .webassets-cache
81
+
82
+ # Scrapy stuff:
83
+ .scrapy
84
+
85
+ # Sphinx documentation
86
+ docs/_build/
87
+
88
+ # PyBuilder
89
+ .pybuilder/
90
+ target/
91
+
92
+ # Jupyter Notebook
93
+ .ipynb_checkpoints
94
+
95
+ # IPython
96
+ profile_default/
97
+ ipython_config.py
98
+
99
+ # pyenv
100
+ # For a library or package, you might want to ignore these files since the code is
101
+ # intended to run in multiple environments; otherwise, check them in:
102
+ # .python-version
103
+
104
+ # pipenv
105
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
106
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
107
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
108
+ # install all needed dependencies.
109
+ #Pipfile.lock
110
+
111
+ # poetry
112
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
113
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
114
+ # commonly ignored for libraries.
115
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
116
+ #poetry.lock
117
+
118
+ # pdm
119
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
120
+ #pdm.lock
121
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
122
+ # in version control.
123
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
124
+ .pdm.toml
125
+ .pdm-python
126
+ .pdm-build/
127
+
128
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
129
+ __pypackages__/
130
+
131
+ # Celery stuff
132
+ celerybeat-schedule
133
+ celerybeat.pid
134
+
135
+ # SageMath parsed files
136
+ *.sage.py
137
+
138
+ # Environments
139
+ .env
140
+ .venv
141
+ env/
142
+ venv/
143
+ ENV/
144
+ env.bak/
145
+ venv.bak/
146
+
147
+ # Spyder project settings
148
+ .spyderproject
149
+ .spyproject
150
+
151
+ # Rope project settings
152
+ .ropeproject
153
+
154
+ # mkdocs documentation
155
+ /site
156
+
157
+ # mypy
158
+ .mypy_cache/
159
+ .dmypy.json
160
+ dmypy.json
161
+
162
+ # Pyre type checker
163
+ .pyre/
164
+
165
+ # pytype static type analyzer
166
+ .pytype/
167
+
168
+ # Cython debug symbols
169
+ cython_debug/
170
+
171
+ # PyCharm
172
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
173
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
174
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
175
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
176
+ .idea/
177
+
178
+
179
+
180
+ # dependencies
181
+ /node_modules
182
+ /.pnpm-store
183
+
184
+ # testing
185
+ /coverage
186
+
187
+ # production
188
+ /build
189
+
190
+ # misc
191
+ .DS_Store
192
+ .env.local
193
+ .env.development.local
194
+ .env.test.local
195
+ .env.production.local
196
+
197
+ npm-debug.log*
198
+ yarn-debug.log*
199
+ yarn-error.log*
200
+
201
+ .nx/cache
202
+ .nx/workspace-data
203
+ vite.config.*.timestamp*
204
+ vitest.config.*.timestamp*
205
+ test-output
206
+
207
+ # Ignore cursor IDE files, except shared agent rules
208
+ .cursor/*
209
+ !.cursor/rules/
210
+
211
+ # Codex temporary files
212
+ .codex_tmp/
213
+
214
+ # TypeScript cache
215
+ *.tsbuildinfo
216
+ out-tsc/
217
+
218
+ .vscode/settings.json
219
+ .vscode/mcp.json
220
+
221
+ .github/instructions/*.instructions.md
222
+ instructions.txt
223
+ node_modules
224
+
225
+ # Figma temporary assets
226
+ figma-assets/
227
+ tmp-figma-assets/
228
+ apps/portal/logs
229
+ logs
230
+
231
+ # CDN assets (synced from GCS for local development)
232
+ cdn/
233
+
234
+ # Private assets / files for local development, not meant to be shared
235
+ .local/
236
+
237
+ # Claude Code (machine-specific)
238
+ .claude/teams/*/inboxes/
239
+ .claude/settings.local.json
240
+ CLAUDE.local.md
241
+ .worktrees/
242
+
243
+ # Pinned protoc binary cache
244
+ .protoc/
245
+
246
+
247
+ .claude/scheduled_tasks.lock
248
+ .claude/tmp/
249
+ .claude/worktrees/
250
+ .claude/plans/
251
+ # Test artifacts
252
+ screenshots/
253
+ libs/graph/src/**/__screenshots__/
254
+ !libs/graph/src/components/__tests__/__screenshots__/
255
+ libs/ui/src/**/__screenshots__/
256
+ .playwright-mcp/
257
+
258
+ # Designer prototypes / scratch docs (kept local, not tracked)
259
+ /notification-empty-state.html
260
+ /notification-channels-empty-state.html
261
+ /notification-popover-prototype.html
262
+ /capsule-qr.html
263
+ /policy-violations-empty-states.html
264
+ /figma-prompt-notification-states.md
265
+ /discovery-node-edge-audit.md
266
+
267
+ # UI lib test CSS — built fresh by libs/ui `npm run build:test-css` before each vitest run
268
+ libs/ui/playwright/output.css
269
+ libs/graph/storybook-static
270
+
271
+ # Codex
272
+ .agents/
273
+ .codex/
274
+ AGENTS.md
275
+ .claude/worktrees
276
+ .nx/polygraph
277
+ .nx/self-healing
278
+ auth.json
279
+ .playwright-cli/
280
+ .claude/workflows/
281
+ apps/portal/tests/integration/auth.json
282
+ apps/portal/tests/integration/auth.json.auth0.bak
283
+
284
+ # direnv
285
+ .envrc
286
+
287
+ .eslintcache
288
+
289
+ # Vendor API specs and other local-only reference material, linked from integration READMEs
290
+ working-docs/
@@ -0,0 +1,32 @@
1
+ Capsule Security Commercial License
2
+
3
+ Copyright (c) Capsule Security, Inc. All rights reserved.
4
+
5
+ This software is licensed, not sold, and is made available solely to customers
6
+ of Capsule Security, Inc. ("Capsule") under the terms of an active commercial
7
+ agreement (the "Subscription Agreement") between the customer and Capsule.
8
+
9
+ Subject to the Subscription Agreement, Capsule grants the customer a
10
+ non-exclusive, non-transferable, non-sublicensable, revocable license to install
11
+ and run this software in connection with the customer's authorized use of the
12
+ Capsule platform, solely for the customer's internal business operations.
13
+
14
+ Except as expressly permitted by the Subscription Agreement, you may not:
15
+ (a) copy, modify, or create derivative works of the software;
16
+ (b) reverse engineer, decompile, or disassemble the software;
17
+ (c) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
18
+ software to any third party;
19
+ (d) remove or alter any proprietary notices contained in the software; or
20
+ (e) use the software except in connection with an active Subscription
21
+ Agreement.
22
+
23
+ Without a valid Subscription Agreement with Capsule, no rights are granted to
24
+ use this software. Unauthorized use is prohibited.
25
+
26
+ THE SOFTWARE IS PROVIDED "AS IS" AND CAPSULE DISCLAIMS ALL WARRANTIES, EXPRESS
27
+ OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY,
28
+ FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. CAPSULE SHALL NOT BE
29
+ LIABLE FOR ANY DAMAGES ARISING FROM OR RELATING TO USE OF THE SOFTWARE EXCEPT
30
+ AS EXPRESSLY SET FORTH IN THE SUBSCRIPTION AGREEMENT.
31
+
32
+ For licensing inquiries, contact: sales@capsulesecurity.io
@@ -0,0 +1,124 @@
1
+ Metadata-Version: 2.5
2
+ Name: capsule-strands
3
+ Version: 0.1.0
4
+ Summary: Capsule plugin for Strands Agents - gates prompts and tool calls against Capsule policies and reports every session for audit.
5
+ Project-URL: Homepage, https://github.com/capsulesecurity
6
+ Project-URL: Documentation, https://docs.capsulesecurity.io/guides/strands
7
+ Author: Capsule Security
8
+ License: Capsule Security Commercial License
9
+
10
+ Copyright (c) Capsule Security, Inc. All rights reserved.
11
+
12
+ This software is licensed, not sold, and is made available solely to customers
13
+ of Capsule Security, Inc. ("Capsule") under the terms of an active commercial
14
+ agreement (the "Subscription Agreement") between the customer and Capsule.
15
+
16
+ Subject to the Subscription Agreement, Capsule grants the customer a
17
+ non-exclusive, non-transferable, non-sublicensable, revocable license to install
18
+ and run this software in connection with the customer's authorized use of the
19
+ Capsule platform, solely for the customer's internal business operations.
20
+
21
+ Except as expressly permitted by the Subscription Agreement, you may not:
22
+ (a) copy, modify, or create derivative works of the software;
23
+ (b) reverse engineer, decompile, or disassemble the software;
24
+ (c) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
25
+ software to any third party;
26
+ (d) remove or alter any proprietary notices contained in the software; or
27
+ (e) use the software except in connection with an active Subscription
28
+ Agreement.
29
+
30
+ Without a valid Subscription Agreement with Capsule, no rights are granted to
31
+ use this software. Unauthorized use is prohibited.
32
+
33
+ THE SOFTWARE IS PROVIDED "AS IS" AND CAPSULE DISCLAIMS ALL WARRANTIES, EXPRESS
34
+ OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY WARRANTIES OF MERCHANTABILITY,
35
+ FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. CAPSULE SHALL NOT BE
36
+ LIABLE FOR ANY DAMAGES ARISING FROM OR RELATING TO USE OF THE SOFTWARE EXCEPT
37
+ AS EXPRESSLY SET FORTH IN THE SUBSCRIPTION AGREEMENT.
38
+
39
+ For licensing inquiries, contact: sales@capsulesecurity.io
40
+ License-File: LICENSE
41
+ Keywords: agent-security,capsule,policy,security,strands,strands-agents
42
+ Classifier: License :: Other/Proprietary License
43
+ Classifier: Programming Language :: Python :: 3
44
+ Classifier: Programming Language :: Python :: 3 :: Only
45
+ Requires-Python: >=3.10
46
+ Requires-Dist: httpx>=0.27
47
+ Requires-Dist: strands-agents>=1.43
48
+ Description-Content-Type: text/markdown
49
+
50
+ # capsule-strands
51
+
52
+ Capsule plugin for [Strands Agents](https://strandsagents.com). It sends every prompt and tool call of a Strands agent to Capsule for an allow/block verdict before it runs, and reports the rest of the session for audit.
53
+
54
+ ## Install
55
+
56
+ ```bash
57
+ pip install capsule-strands
58
+ ```
59
+
60
+ It requires `strands-agents` 1.43 or later.
61
+
62
+ ## Configure
63
+
64
+ Attach the plugin to each agent:
65
+
66
+ ```python
67
+ from strands import Agent
68
+ from capsule_strands import CapsulePlugin
69
+
70
+ agent = Agent(
71
+ agent_id="support-agent",
72
+ name="Acme Support Agent",
73
+ system_prompt="You answer Acme billing questions.",
74
+ tools=[...],
75
+ plugins=[CapsulePlugin()],
76
+ )
77
+ ```
78
+
79
+ Set the endpoint and token where the agent runs:
80
+
81
+ ```bash
82
+ export CAPSULE_STRANDS_ENDPOINT="https://agents.capsule.security/v1/strands/hooks/events"
83
+ export CAPSULE_STRANDS_TOKEN="<token from the Capsule portal>"
84
+ ```
85
+
86
+ The `endpoint` and `token` values are issued by Capsule when you install the Strands Agents integration in the portal (**Integrations → Strands Agents**). The token is a JWT scoped to your tenant and environment, so treat it as a secret.
87
+
88
+ Every setting can also be passed to `CapsulePlugin(...)`. A constructor argument wins over its environment variable.
89
+
90
+ | Argument | Environment variable | Default | Description |
91
+ | --------------- | ------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
92
+ | `endpoint` | `CAPSULE_STRANDS_ENDPOINT` | | Required. |
93
+ | `token` | `CAPSULE_STRANDS_TOKEN` | | Required. |
94
+ | `block_on_risk` | `CAPSULE_STRANDS_BLOCK_ON_RISK` | `true` | Apply Capsule's `block` verdicts. Set to `false` to run the plugin in observe-only mode. |
95
+ | `fail_open` | `CAPSULE_STRANDS_FAIL_OPEN` | `true` | Let a prompt or tool call through when Capsule is unreachable or answers with an error. Set to `false` to block. |
96
+ | `timeout_ms` | `CAPSULE_STRANDS_TIMEOUT_MS` | `35000` | How long to wait for Capsule's verdict. When it passes first, the prompt or tool call follows `fail_open`. |
97
+
98
+ ## How it works
99
+
100
+ | Strands hook | Type | Event | What happens on a block |
101
+ | ----------------------- | ----------- | ----------------- | ------------------------------------------------------------------------------------- |
102
+ | `BeforeInvocationEvent` | Blocking | `user_message` | The invocation is cancelled before the model is called; the agent returns the reason. |
103
+ | `BeforeToolCallEvent` | Blocking | `tool_invocation` | The tool never runs; the model gets an error tool result carrying the reason. |
104
+ | `AfterToolCallEvent` | Observation | `tool_result` | |
105
+ | `AfterInvocationEvent` | Observation | `agent_message` | |
106
+
107
+ The first invocation of each agent also reports a `session_start` with the agent's system prompt, model id and registered tools, before its prompt is judged. Tool results and replies are posted from a background thread, in the order they happened, so they never slow the agent down.
108
+
109
+ The deprecated `Agent.structured_output()` method is gated too. Strands gives hooks neither its prompt nor a way to cancel it, so the plugin judges the prompt before the call and raises `capsule_strands.CapsuleBlockedError` with the reason when Capsule blocks it.
110
+
111
+ Every event carries the agent's identity: its `agent_id`, or its `name` when `agent_id` is left at the Strands default. Set `agent_id` on each agent so Capsule keeps them apart. The session id is `trace_attributes["session.id"]` when the agent sets one, then the session manager's session id, and otherwise a random id per `Agent` instance.
112
+
113
+ ## Tests
114
+
115
+ ```bash
116
+ pip install "strands-agents==<version>" -e . -r tests/requirements.txt
117
+ pytest tests
118
+ ```
119
+
120
+ The tests run real Strands agents against a scripted model and a fake Capsule. The end-to-end suite against the real Capsule backend lives in `apps/agentsecurity` (`nx run agentsecurity:test:strands-evals`).
121
+
122
+ ## License
123
+
124
+ Capsule Security Commercial License. See [LICENSE](./LICENSE).
@@ -0,0 +1,75 @@
1
+ # capsule-strands
2
+
3
+ Capsule plugin for [Strands Agents](https://strandsagents.com). It sends every prompt and tool call of a Strands agent to Capsule for an allow/block verdict before it runs, and reports the rest of the session for audit.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pip install capsule-strands
9
+ ```
10
+
11
+ It requires `strands-agents` 1.43 or later.
12
+
13
+ ## Configure
14
+
15
+ Attach the plugin to each agent:
16
+
17
+ ```python
18
+ from strands import Agent
19
+ from capsule_strands import CapsulePlugin
20
+
21
+ agent = Agent(
22
+ agent_id="support-agent",
23
+ name="Acme Support Agent",
24
+ system_prompt="You answer Acme billing questions.",
25
+ tools=[...],
26
+ plugins=[CapsulePlugin()],
27
+ )
28
+ ```
29
+
30
+ Set the endpoint and token where the agent runs:
31
+
32
+ ```bash
33
+ export CAPSULE_STRANDS_ENDPOINT="https://agents.capsule.security/v1/strands/hooks/events"
34
+ export CAPSULE_STRANDS_TOKEN="<token from the Capsule portal>"
35
+ ```
36
+
37
+ The `endpoint` and `token` values are issued by Capsule when you install the Strands Agents integration in the portal (**Integrations → Strands Agents**). The token is a JWT scoped to your tenant and environment, so treat it as a secret.
38
+
39
+ Every setting can also be passed to `CapsulePlugin(...)`. A constructor argument wins over its environment variable.
40
+
41
+ | Argument | Environment variable | Default | Description |
42
+ | --------------- | ------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
43
+ | `endpoint` | `CAPSULE_STRANDS_ENDPOINT` | | Required. |
44
+ | `token` | `CAPSULE_STRANDS_TOKEN` | | Required. |
45
+ | `block_on_risk` | `CAPSULE_STRANDS_BLOCK_ON_RISK` | `true` | Apply Capsule's `block` verdicts. Set to `false` to run the plugin in observe-only mode. |
46
+ | `fail_open` | `CAPSULE_STRANDS_FAIL_OPEN` | `true` | Let a prompt or tool call through when Capsule is unreachable or answers with an error. Set to `false` to block. |
47
+ | `timeout_ms` | `CAPSULE_STRANDS_TIMEOUT_MS` | `35000` | How long to wait for Capsule's verdict. When it passes first, the prompt or tool call follows `fail_open`. |
48
+
49
+ ## How it works
50
+
51
+ | Strands hook | Type | Event | What happens on a block |
52
+ | ----------------------- | ----------- | ----------------- | ------------------------------------------------------------------------------------- |
53
+ | `BeforeInvocationEvent` | Blocking | `user_message` | The invocation is cancelled before the model is called; the agent returns the reason. |
54
+ | `BeforeToolCallEvent` | Blocking | `tool_invocation` | The tool never runs; the model gets an error tool result carrying the reason. |
55
+ | `AfterToolCallEvent` | Observation | `tool_result` | |
56
+ | `AfterInvocationEvent` | Observation | `agent_message` | |
57
+
58
+ The first invocation of each agent also reports a `session_start` with the agent's system prompt, model id and registered tools, before its prompt is judged. Tool results and replies are posted from a background thread, in the order they happened, so they never slow the agent down.
59
+
60
+ The deprecated `Agent.structured_output()` method is gated too. Strands gives hooks neither its prompt nor a way to cancel it, so the plugin judges the prompt before the call and raises `capsule_strands.CapsuleBlockedError` with the reason when Capsule blocks it.
61
+
62
+ Every event carries the agent's identity: its `agent_id`, or its `name` when `agent_id` is left at the Strands default. Set `agent_id` on each agent so Capsule keeps them apart. The session id is `trace_attributes["session.id"]` when the agent sets one, then the session manager's session id, and otherwise a random id per `Agent` instance.
63
+
64
+ ## Tests
65
+
66
+ ```bash
67
+ pip install "strands-agents==<version>" -e . -r tests/requirements.txt
68
+ pytest tests
69
+ ```
70
+
71
+ The tests run real Strands agents against a scripted model and a fake Capsule. The end-to-end suite against the real Capsule backend lives in `apps/agentsecurity` (`nx run agentsecurity:test:strands-evals`).
72
+
73
+ ## License
74
+
75
+ Capsule Security Commercial License. See [LICENSE](./LICENSE).
@@ -0,0 +1,36 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.21"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "capsule-strands"
7
+ version = "0.1.0"
8
+ description = "Capsule plugin for Strands Agents - gates prompts and tool calls against Capsule policies and reports every session for audit."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { file = "LICENSE" }
12
+ authors = [{ name = "Capsule Security" }]
13
+ keywords = [
14
+ "strands",
15
+ "strands-agents",
16
+ "capsule",
17
+ "security",
18
+ "policy",
19
+ "agent-security",
20
+ ]
21
+ classifiers = [
22
+ "License :: Other/Proprietary License",
23
+ "Programming Language :: Python :: 3",
24
+ "Programming Language :: Python :: 3 :: Only",
25
+ ]
26
+ dependencies = [
27
+ "httpx>=0.27",
28
+ "strands-agents>=1.43",
29
+ ]
30
+
31
+ [project.urls]
32
+ Homepage = "https://github.com/capsulesecurity"
33
+ Documentation = "https://docs.capsulesecurity.io/guides/strands"
34
+
35
+ [tool.hatch.build.targets.wheel]
36
+ packages = ["src/capsule_strands"]
@@ -0,0 +1,9 @@
1
+ """Capsule plugin for Strands Agents.
2
+
3
+ Puts a Strands agent's prompts and tool calls behind Capsule policies and reports every session for audit.
4
+ """
5
+
6
+ from .config import CapsuleConfig
7
+ from .plugin import PLUGIN_VERSION, CapsuleBlockedError, CapsulePlugin
8
+
9
+ __all__ = ["CapsuleBlockedError", "CapsuleConfig", "CapsulePlugin", "PLUGIN_VERSION"]
@@ -0,0 +1,65 @@
1
+ """Configuration for the Capsule Strands plugin."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from dataclasses import dataclass
7
+
8
+ _ENV_PREFIX = "CAPSULE_STRANDS_"
9
+ _TRUE_VALUES = {"1", "true", "yes", "on"}
10
+ DEFAULT_TIMEOUT_MS = 35_000
11
+
12
+
13
+ def _env(key: str) -> str | None:
14
+ value = os.environ.get(f"{_ENV_PREFIX}{key}")
15
+ return value if value else None
16
+
17
+
18
+ def _env_bool(key: str, default: bool) -> bool:
19
+ value = _env(key)
20
+ return default if value is None else value.strip().lower() in _TRUE_VALUES
21
+
22
+
23
+ def _env_int(key: str, default: int) -> int:
24
+ value = _env(key)
25
+ if value is None:
26
+ return default
27
+ try:
28
+ return int(value)
29
+ except ValueError as error:
30
+ raise ValueError(f"capsule_strands: {_ENV_PREFIX}{key} must be an integer, got {value!r}") from error
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class CapsuleConfig:
35
+ """Plugin settings. Constructor arguments win; `CAPSULE_STRANDS_*` environment variables fill in the rest."""
36
+
37
+ endpoint: str
38
+ token: str
39
+ block_on_risk: bool
40
+ fail_open: bool
41
+ timeout_ms: int
42
+
43
+ @classmethod
44
+ def load(
45
+ cls,
46
+ *,
47
+ endpoint: str | None = None,
48
+ token: str | None = None,
49
+ block_on_risk: bool | None = None,
50
+ fail_open: bool | None = None,
51
+ timeout_ms: int | None = None,
52
+ ) -> CapsuleConfig:
53
+ resolved_endpoint = endpoint or _env("ENDPOINT")
54
+ resolved_token = token or _env("TOKEN")
55
+ if not resolved_endpoint:
56
+ raise ValueError(f"capsule_strands: endpoint missing (pass endpoint= or set {_ENV_PREFIX}ENDPOINT)")
57
+ if not resolved_token:
58
+ raise ValueError(f"capsule_strands: token missing (pass token= or set {_ENV_PREFIX}TOKEN)")
59
+ return cls(
60
+ endpoint=resolved_endpoint,
61
+ token=resolved_token,
62
+ block_on_risk=block_on_risk if block_on_risk is not None else _env_bool("BLOCK_ON_RISK", True),
63
+ fail_open=fail_open if fail_open is not None else _env_bool("FAIL_OPEN", True),
64
+ timeout_ms=timeout_ms if timeout_ms is not None else _env_int("TIMEOUT_MS", DEFAULT_TIMEOUT_MS),
65
+ )