@yahyahammad/venastine 0.3.8 → 0.3.10

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.
Files changed (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,148 +1,148 @@
1
- # Third-Party Notices
2
-
3
- This project is licensed under the **Apache License 2.0** — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE) (Copyright 2026 Yahya Hammad).
4
-
5
- The dependencies listed below are **not** part of the project's own source but are required at install/runtime. All are permissive and **Apache-2.0 compatible**; the assessment was made on 2026-08-27, and re-read from each package's own metadata for batch 234's pins on 2026-11-04, when `anthropic` 2.0 moved from MIT to Apache-2.0. This file records it so a scanner or reviewer does not have to re-derive it.
6
-
7
- > **Scope.** Two things are covered here: the project's **declared direct** dependencies — the pins in `requirements.txt` and the extras in `pyproject.toml` — and, under *Non-code third-party material* below, the third-party **text** the repository reproduces.
8
- >
9
- > The transitive dependency closure is *not* enumerated: `sympy` pulls `mpmath`, `sqlmodel` pulls SQLAlchemy, and `mcp==2.3.0` brings `httpx2` (BSD-3-Clause), as `anthropic` and `openai` do since batch 234 (see the note beside the `mcp` pin in `requirements.txt`). Until batch 212 `matplotlib` was here too, pulling numpy, kiwisolver, fonttools and pillow; the confidence chart is drawn as SVG with the standard library now, and none of them is installed. For the full closure, run `pip-licenses` against a resolved environment — see *How to regenerate* below.
10
-
11
- > Versions shown are the pins from `requirements.txt` / `pyproject.toml` at the time this file was created. Where a range is used (e.g. `rich>=14.2,<16`) the exact resolved version will vary.
12
-
13
- ## Runtime / core dependencies
14
-
15
- | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Source |
16
- |---|---|---|---|---|
17
- | anthropic | `==2.1.0` | Apache-2.0 (MIT through 0.x; 2.0 relicensed) | Yes | https://pypi.org/project/anthropic/ |
18
- | ddgs | `==9.16.0` | MIT | Yes | https://pypi.org/project/ddgs/ |
19
- | httpx | `==0.28.1` | BSD-3-Clause | Yes | https://pypi.org/project/httpx/ |
20
- | openai | `==3.36.0` | Apache-2.0 | Yes | https://pypi.org/project/openai/ |
21
- | google-genai | `==2.32.0` | Apache-2.0 | Yes | https://pypi.org/project/google-genai/ |
22
- | pydantic | `==2.14.1` | MIT | Yes | https://pypi.org/project/pydantic/ |
23
- | sympy | `==1.14.0` | BSD-3-Clause | Yes | https://pypi.org/project/sympy/ |
24
- | sqlmodel | `==0.0.48` | MIT | Yes | https://pypi.org/project/sqlmodel/ |
25
- | python-dotenv | `==1.2.4` | BSD-3-Clause | Yes | https://pypi.org/project/python-dotenv/ |
26
- | pyyaml | `==6.0.3` | MIT | Yes | https://pypi.org/project/PyYAML/ |
27
- | ruamel.yaml | `==0.19.1` | MIT | Yes | https://pypi.org/project/ruamel.yaml/ |
28
- | textual | `==8.2.8` | MIT | Yes | https://pypi.org/project/textual/ |
29
- | rich | `>=14.2,<16` | MIT | Yes | https://pypi.org/project/rich/ |
30
- | mcp | `==2.3.0` | MIT | Yes | https://pypi.org/project/mcp/ |
31
- | google-re2 | `==1.1.20251105` | BSD-3-Clause | Yes | https://pypi.org/project/google-re2/ |
32
- | cryptography | `>=50.0.0,<52` | Apache-2.0 OR BSD-3-Clause | Yes | https://pypi.org/project/cryptography/ |
33
- | PyJWT | `>=2.15.0,<3` | MIT | Yes | https://pypi.org/project/PyJWT/ |
34
-
35
- `google-re2` (added 2026-09-15, ROADMAP_v3 §49) and `cryptography` (added 2026-09-24, ROADMAP_v3 §49 slice 5a) are the dependencies above that ship **compiled native code**. Taking `google-re2` first: its wheels carry the RE2 C++ library (BSD-3-Clause) and, as RE2 depends on it, Abseil (Apache-2.0). The paragraph under *What this means* holds for it unchanged — pip fetches the wheel onto the user's machine and this project redistributes nothing — so no inbound `NOTICE` obligation arises. Where no wheel exists (musl/Alpine, glibc older than 2.28), pip builds the source distribution locally, which is the user's build rather than a distribution by this project.
36
-
37
- `cryptography` was **already in the install closure** before it was declared — `google-genai==1.0.0` → `google-auth>=2.14.1` → `cryptography>=38.0.3`, with no extra marker (re-measured on the 2.29.0 pin in batch 172: `google-auth>=2.56.0` → `cryptography>=38.0.3`, still unmarked) — so declaring it added no package to an install and no licence surface that was not already present; it made an existing transitive dependency into a pinned direct one, because the harness-held secret store (ROADMAP_v3 §49 slice 5a, SS57) rests on it. Its wheels carry a **Rust** extension and a statically linked **OpenSSL** (Apache-2.0); the dual licence above is the project's own, and the paragraph under *What this means* holds for it unchanged — pip fetches the wheel onto the user's machine and this project redistributes nothing, so no inbound `NOTICE` obligation arises. Wheels exist for CPython 3.7+ on Windows (x64, x86), macOS (arm64, x86_64) and manylinux/musllinux (x86_64, aarch64); where none does, pip builds the sdist locally and needs a Rust toolchain, which is the user's build rather than a distribution by this project.
38
-
39
- `pillow` was declared on 2026-10-28 (batch 201), as a floor under what `matplotlib` pulled in, and removed with `matplotlib` in batch 212: nothing the harness installs reaches it now. The hosted demo's Gradio bridge still installs it, in an environment of its own (`deploy/hosted/requirements.txt`).
40
-
41
- ## Test dependencies (not used by end users during runtime, only for CI and developer testing)
42
-
43
- | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible |
44
- |---|---|---|---|
45
- | pytest | `>=8.0` | MIT | Yes |
46
- | pytest-mock | `>=3.14` | MIT | Yes |
47
- | pytest-asyncio | `>=1.0` | Apache-2.0 | Yes |
48
- | pytest-xdist | `>=3.6` | MIT | Yes |
49
- | execnet | transitive (via `pytest-xdist`) | MIT | Yes |
50
-
51
- `execnet` is listed although nothing declares it: it is `pytest-xdist`'s only dependency and the process that actually runs each worker, so a reader auditing what a `pip install -r requirements.txt` puts on the machine would otherwise have to go and find it. Both are permissive, so the no-copyleft claim under *What this means* is unchanged.
52
-
53
- ## Optional dependencies (`pyproject.toml` extras)
54
-
55
- | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Notes |
56
- |---|---|---|---|---|
57
- | markitdown | `==0.1.9` (extra `documents`) | MIT | Yes | Permissive; only reachable behind `read`/`write`/`edit` (globally denied). |
58
- | protobuf | `==7.36.2` (extra `documents`) | BSD-3-Clause / Apache-2.0 | Yes | Permissive; transitive via `markitdown`→`onnxruntime`. |
59
- | markdown | unpinned (extra `pdf`) | BSD-3-Clause | Yes | Permissive |
60
- | weasyprint | unpinned (extra `pdf`) | BSD-3-Clause (package) | Yes (with caveats) | Package itself BSD-3-Clause; transitive deps include LGPL (e.g. `pango`/`cairo` via system libs). See weasyprint docs. |
61
-
62
- `weasyprint` is BSD-3-Clause itself; the caveat is its **system** dependencies (`pango`, `cairo`, `harfbuzz`), which are LGPL and are linked at runtime rather than vendored into this project. If `markdown` or `weasyprint` is later pinned, update the version column above.
63
-
64
- ## Hosted demo (`deploy/`, ROADMAP_v3 §79)
65
-
66
- What the bridge -- the process that serves a Space's or Studio's page and relays each session -- runs beside Gradio. None of it is installed by `pip install` or npm: `deploy/` ships in neither, and a deployment installs these from PyPI when the platform builds it, so nothing here is redistributed. Licences read from each version's PyPI metadata (2026-10-23).
67
-
68
- | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Where |
69
- |---|---|---|---|---|
70
- | textual-serve | `==1.1.3` | MIT | Yes | `deploy/hosted/requirements.txt`; its browser assets only, its server never runs |
71
- | uv | `==0.13.4` | MIT OR Apache-2.0 | Yes | `deploy/hosted/requirements.txt`; builds the session environment |
72
- | websockets | `==17.3` | BSD-3-Clause | Yes | `deploy/hosted/requirements.txt`; the websocket upgrade every session is |
73
- | gradio | `==6.30.0` | Apache-2.0 | Yes | installed by the Space at the README's `sdk_version`; in the Studio's `bridge.lock` |
74
- | spaces | `==0.51.3` | Apache-2.0 | Yes | installed by the Space itself; in the Studio's `bridge.lock` |
75
-
76
- ## Deploy tooling (CI only)
77
-
78
- Installed by `.github/workflows/deploy-demo.yml` to build, audit and upload a bundle (batch 169), and by the owner to deploy the Studio by hand. Never part of any install or bundle.
79
-
80
- | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible |
81
- |---|---|---|---|
82
- | huggingface_hub | `==2.2.0` | Apache-2.0 | Yes |
83
- | pip-audit | `==2.10.1` | Apache-2.0 | Yes |
84
-
85
- ## Non-code third-party material
86
-
87
- **No third-party source code is included in this repository.** Measured, not assumed: all 277 tracked
88
- Python files carry no foreign copyright header and no `SPDX-License-Identifier`; a sweep for
89
- copied or adapted code ("adapted from", "copied from", "taken from", "vendored", "borrowed from")
90
- returns only this project's own design prose; and the 45 tracked files that are neither `.py`
91
- nor `.md` are first-party without exception — the licence texts, configuration and packaging
92
- (`config.yaml`, `pyproject.toml`, the three requirements files, `package.json`, `pytest.ini`, the
93
- `.github/` workflows, issue templates and scanner configuration, the dotfiles), the two prompt
94
- texts, `bin/venastine.mjs` and `scripts/prepublish-check.mjs`, `docs/assets/research-mode-birds-eye.mermaid`,
95
- `tui/app.tcss`, the two `.example` templates, the hosted demo's four page templates in
96
- `deploy/hosted/`, one screenshot of this project's own interface, and its cover image with the
97
- page it is rendered from. **No third-party fonts, images or data files are bundled.** The
98
- cover's text is set in Cascadia Mono, Microsoft's font under the SIL Open Font License: the PNG
99
- holds rendered glyphs, and its page names the font, and neither carries a copy of it.
100
-
101
- *(Counts restated in batch 83. The figure had been 166 against 200, the enumeration named
102
- five of the thirty-four, and the closing sentence said there were no images at all while the
103
- screenshot was tracked. The claim itself held throughout; only its arithmetic had drifted.)*
104
-
105
- *(Restated again in batch 198, when the cover joined: 200 and 34 had become 277 and 43 as the
106
- project grew. Both sweeps were run again and found nothing new, and every file added since
107
- batch 83 is first-party.)*
108
-
109
- What the repository *does* reproduce is third-party **text**:
110
-
111
- | Material | Where it lives | Origin | Licensing |
112
- |---|---|---|---|
113
- | **Contributor Covenant, v2.1** | `CODE_OF_CONDUCT.md` (adapted — contact details and enforcement channel are ours) | Authored 2014 by Coraline Ada Ehmke, with later collaborative contributions. https://www.contributor-covenant.org/version/2/1/code_of_conduct.html | **Not stated by upstream** for the document text — see the note below |
114
- | **Mozilla's CoC enforcement ladder** | Inspiration for the *Enforcement Guidelines* section of `CODE_OF_CONDUCT.md`, credited there per the Covenant's own boilerplate | https://github.com/mozilla/diversity | GitHub reports the repository as **MPL-2.0** |
115
- | **Apache License 2.0 text** | `LICENSE` | https://www.apache.org/licenses/LICENSE-2.0 | Reproduced verbatim, which is what the licence itself directs; the appendix boilerplate is filled in with this project's copyright |
116
-
117
- > **On the Covenant's licence.** Upstream does not publish an explicit licence for the Code of
118
- > Conduct *text*. Three sources were checked on 2026-08-27: the project's `LICENSE.md`
119
- > (`EthicalSource/contributor_covenant`) states the **Hippocratic License 3.0**, which covers the
120
- > site and its code; the contributor-covenant.org footer carries a copyright line and no licence
121
- > statement; and the raw `content/version/2/1/code_of_conduct.md` carries none either.
122
- >
123
- > **No licence identifier is asserted here on the Covenant's behalf.** The attribution block kept
124
- > in `CODE_OF_CONDUCT.md` — naming the work, its version, its source URL, and the fact that it is
125
- > *adapted* — is verbatim the attribution upstream prescribes in its own boilerplate, and is the
126
- > best available evidence of what they ask adopters to provide. If you need certainty for a
127
- > compliance review, ask upstream rather than inferring from this file.
128
-
129
- ## What this means
130
-
131
- * All licenses **listed above** are **permissive** (MIT / BSD-3-Clause / PSF / Apache-2.0). None are copyleft (GPL/AGPL) and none impose source-disclosure on this Apache-2.0 work. This is a statement about the direct dependencies in the tables, not about the full transitive closure — see *Scope* at the top.
132
- * This project does not redistribute any of them. It is distributed as **source** — a `git` checkout or the npm package `@yahyahammad/venastine`, which is the same folder of first-party files — and `pip` fetches each dependency from PyPI, onto the user's machine, under its own license. **No inbound `NOTICE` obligation therefore arises** — nothing here carries an upstream NOTICE that this project must propagate. The trigger is **redistribution**, not source-vs-binary, and not which channel delivered the source; if a build that vendors these packages is ever distributed, ship their `LICENSE` and `NOTICE` files as received (Apache-2.0 §4(d) applies to `openai`, `google-genai` and `pytest-asyncio`). **The npm tarball must therefore never carry wheels** — that is the one change that would turn this paragraph false, and `CONTRIBUTING.md` records it as a rule.
133
- * **The npm channel adds no third-party licence surface at all.** Its launcher (`bin/venastine.mjs`) is Node standard library only, with an empty `dependencies` block, so an install of this package fetches no JavaScript code from anyone. What the tarball contains is the first-party source listed under `files` in `package.json`, plus `LICENSE`, `NOTICE` and this file. Publishing *is* distribution of the Work under Apache-2.0 §4 where running from a checkout was not, which is why those three are in the allowlist rather than left to chance: npm auto-includes `LICENSE` and does **not** auto-include `NOTICE`.
134
- * The [NOTICE](./NOTICE) file this project publishes is therefore **voluntary**, not required. Apache-2.0 §4(d) obliges you to propagate a NOTICE you *received*; it does not oblige a licensor to author one. It exists because scanners and reviewers look for it and because it gives the copyright assertion a canonical home — and it is kept minimal on purpose, since anyone who redistributes this work must carry its contents forward.
135
- * Full license texts: `pip show <package>` or `pip-licenses --format plain --with-urls`, or the PyPI links above.
136
-
137
- ## How to regenerate
138
-
139
- ```bash
140
- pip-licenses --format markdown --with-urls --with-license-file
141
- # or
142
- pip install pip-licenses && pip-licenses --format plain
143
- ```
144
-
145
- When a dependency is added or re-pinned, add a row here with its SPDX identifier and re-check the `Apache 2.0 Compatible` column. CI does not enforce this file today — it is documentation for reviewers.
146
-
147
- ---
148
- *Last updated: 2026-08-27. If any row's upstream re-licenses, this file must be updated.*
1
+ # Third-Party Notices
2
+
3
+ This project is licensed under the **Apache License 2.0** — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE) (Copyright 2026 Yahya Hammad).
4
+
5
+ The dependencies listed below are **not** part of the project's own source but are required at install/runtime. All are permissive and **Apache-2.0 compatible**; the assessment was made on 2026-08-27, and re-read from each package's own metadata for batch 234's pins on 2026-11-04, when `anthropic` 2.0 moved from MIT to Apache-2.0. This file records it so a scanner or reviewer does not have to re-derive it.
6
+
7
+ > **Scope.** Two things are covered here: the project's **declared direct** dependencies — the pins in `requirements.txt` and the extras in `pyproject.toml` — and, under *Non-code third-party material* below, the third-party **text** the repository reproduces.
8
+ >
9
+ > The transitive dependency closure is *not* enumerated: `sympy` pulls `mpmath`, `sqlmodel` pulls SQLAlchemy, and `mcp==2.3.0` brings `httpx2` (BSD-3-Clause), as `anthropic` and `openai` do since batch 234 (see the note beside the `mcp` pin in `requirements.txt`). Until batch 212 `matplotlib` was here too, pulling numpy, kiwisolver, fonttools and pillow; the confidence chart is drawn as SVG with the standard library now, and none of them is installed. For the full closure, run `pip-licenses` against a resolved environment — see *How to regenerate* below.
10
+
11
+ > Versions shown are the pins from `requirements.txt` / `pyproject.toml` at the time this file was created. Where a range is used (e.g. `rich>=14.2,<16`) the exact resolved version will vary.
12
+
13
+ ## Runtime / core dependencies
14
+
15
+ | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Source |
16
+ |---|---|---|---|---|
17
+ | anthropic | `==2.1.0` | Apache-2.0 (MIT through 0.x; 2.0 relicensed) | Yes | https://pypi.org/project/anthropic/ |
18
+ | ddgs | `==9.16.0` | MIT | Yes | https://pypi.org/project/ddgs/ |
19
+ | httpx | `==0.28.1` | BSD-3-Clause | Yes | https://pypi.org/project/httpx/ |
20
+ | openai | `==3.36.0` | Apache-2.0 | Yes | https://pypi.org/project/openai/ |
21
+ | google-genai | `==2.32.0` | Apache-2.0 | Yes | https://pypi.org/project/google-genai/ |
22
+ | pydantic | `==2.14.1` | MIT | Yes | https://pypi.org/project/pydantic/ |
23
+ | sympy | `==1.14.0` | BSD-3-Clause | Yes | https://pypi.org/project/sympy/ |
24
+ | sqlmodel | `==0.0.48` | MIT | Yes | https://pypi.org/project/sqlmodel/ |
25
+ | python-dotenv | `==1.2.4` | BSD-3-Clause | Yes | https://pypi.org/project/python-dotenv/ |
26
+ | pyyaml | `==6.0.3` | MIT | Yes | https://pypi.org/project/PyYAML/ |
27
+ | ruamel.yaml | `==0.19.1` | MIT | Yes | https://pypi.org/project/ruamel.yaml/ |
28
+ | textual | `==8.2.8` | MIT | Yes | https://pypi.org/project/textual/ |
29
+ | rich | `>=14.2,<16` | MIT | Yes | https://pypi.org/project/rich/ |
30
+ | mcp | `==2.3.0` | MIT | Yes | https://pypi.org/project/mcp/ |
31
+ | google-re2 | `==1.1.20251105` | BSD-3-Clause | Yes | https://pypi.org/project/google-re2/ |
32
+ | cryptography | `>=50.0.0,<52` | Apache-2.0 OR BSD-3-Clause | Yes | https://pypi.org/project/cryptography/ |
33
+ | PyJWT | `>=2.15.0,<3` | MIT | Yes | https://pypi.org/project/PyJWT/ |
34
+
35
+ `google-re2` (added 2026-09-15, ROADMAP_v3 §49) and `cryptography` (added 2026-09-24, ROADMAP_v3 §49 slice 5a) are the dependencies above that ship **compiled native code**. Taking `google-re2` first: its wheels carry the RE2 C++ library (BSD-3-Clause) and, as RE2 depends on it, Abseil (Apache-2.0). The paragraph under *What this means* holds for it unchanged — pip fetches the wheel onto the user's machine and this project redistributes nothing — so no inbound `NOTICE` obligation arises. Where no wheel exists (musl/Alpine, glibc older than 2.28), pip builds the source distribution locally, which is the user's build rather than a distribution by this project.
36
+
37
+ `cryptography` was **already in the install closure** before it was declared — `google-genai==1.0.0` → `google-auth>=2.14.1` → `cryptography>=38.0.3`, with no extra marker (re-measured on the 2.29.0 pin in batch 172: `google-auth>=2.56.0` → `cryptography>=38.0.3`, still unmarked) — so declaring it added no package to an install and no licence surface that was not already present; it made an existing transitive dependency into a pinned direct one, because the harness-held secret store (ROADMAP_v3 §49 slice 5a, SS57) rests on it. Its wheels carry a **Rust** extension and a statically linked **OpenSSL** (Apache-2.0); the dual licence above is the project's own, and the paragraph under *What this means* holds for it unchanged — pip fetches the wheel onto the user's machine and this project redistributes nothing, so no inbound `NOTICE` obligation arises. Wheels exist for CPython 3.7+ on Windows (x64, x86), macOS (arm64, x86_64) and manylinux/musllinux (x86_64, aarch64); where none does, pip builds the sdist locally and needs a Rust toolchain, which is the user's build rather than a distribution by this project.
38
+
39
+ `pillow` was declared on 2026-10-28 (batch 201), as a floor under what `matplotlib` pulled in, and removed with `matplotlib` in batch 212: nothing the harness installs reaches it now. The hosted demo's Gradio bridge still installs it, in an environment of its own (`deploy/hosted/requirements.txt`).
40
+
41
+ ## Test dependencies (not used by end users during runtime, only for CI and developer testing)
42
+
43
+ | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible |
44
+ |---|---|---|---|
45
+ | pytest | `>=8.0` | MIT | Yes |
46
+ | pytest-mock | `>=3.14` | MIT | Yes |
47
+ | pytest-asyncio | `>=1.0` | Apache-2.0 | Yes |
48
+ | pytest-xdist | `>=3.6` | MIT | Yes |
49
+ | execnet | transitive (via `pytest-xdist`) | MIT | Yes |
50
+
51
+ `execnet` is listed although nothing declares it: it is `pytest-xdist`'s only dependency and the process that actually runs each worker, so a reader auditing what a `pip install -r requirements.txt` puts on the machine would otherwise have to go and find it. Both are permissive, so the no-copyleft claim under *What this means* is unchanged.
52
+
53
+ ## Optional dependencies (`pyproject.toml` extras)
54
+
55
+ | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Notes |
56
+ |---|---|---|---|---|
57
+ | markitdown | `==0.1.9` (extra `documents`) | MIT | Yes | Permissive; only reachable behind `read`/`write`/`edit` (globally denied). |
58
+ | protobuf | `==7.36.2` (extra `documents`) | BSD-3-Clause / Apache-2.0 | Yes | Permissive; transitive via `markitdown`→`onnxruntime`. |
59
+ | markdown | unpinned (extra `pdf`) | BSD-3-Clause | Yes | Permissive |
60
+ | weasyprint | unpinned (extra `pdf`) | BSD-3-Clause (package) | Yes (with caveats) | Package itself BSD-3-Clause; transitive deps include LGPL (e.g. `pango`/`cairo` via system libs). See weasyprint docs. |
61
+
62
+ `weasyprint` is BSD-3-Clause itself; the caveat is its **system** dependencies (`pango`, `cairo`, `harfbuzz`), which are LGPL and are linked at runtime rather than vendored into this project. If `markdown` or `weasyprint` is later pinned, update the version column above.
63
+
64
+ ## Hosted demo (`deploy/`, ROADMAP_v3 §79)
65
+
66
+ What the bridge -- the process that serves a Space's or Studio's page and relays each session -- runs beside Gradio. None of it is installed by `pip install` or npm: `deploy/` ships in neither, and a deployment installs these from PyPI when the platform builds it, so nothing here is redistributed. Licences read from each version's PyPI metadata (2026-10-23).
67
+
68
+ | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Where |
69
+ |---|---|---|---|---|
70
+ | textual-serve | `==1.1.3` | MIT | Yes | `deploy/hosted/requirements.txt`; its browser assets only, its server never runs |
71
+ | uv | `==0.13.4` | MIT OR Apache-2.0 | Yes | `deploy/hosted/requirements.txt`; builds the session environment |
72
+ | websockets | `==17.3` | BSD-3-Clause | Yes | `deploy/hosted/requirements.txt`; the websocket upgrade every session is |
73
+ | gradio | `==6.30.0` | Apache-2.0 | Yes | installed by the Space at the README's `sdk_version`; in the Studio's `bridge.lock` |
74
+ | spaces | `==0.51.3` | Apache-2.0 | Yes | installed by the Space itself; in the Studio's `bridge.lock` |
75
+
76
+ ## Deploy tooling (CI only)
77
+
78
+ Installed by `.github/workflows/deploy-demo.yml` to build, audit and upload a bundle (batch 169), and by the owner to deploy the Studio by hand. Never part of any install or bundle.
79
+
80
+ | Package | Version (as pinned) | Primary License | Apache 2.0 Compatible |
81
+ |---|---|---|---|
82
+ | huggingface_hub | `==2.2.0` | Apache-2.0 | Yes |
83
+ | pip-audit | `==2.10.1` | Apache-2.0 | Yes |
84
+
85
+ ## Non-code third-party material
86
+
87
+ **No third-party source code is included in this repository.** Measured, not assumed: all 277 tracked
88
+ Python files carry no foreign copyright header and no `SPDX-License-Identifier`; a sweep for
89
+ copied or adapted code ("adapted from", "copied from", "taken from", "vendored", "borrowed from")
90
+ returns only this project's own design prose; and the 45 tracked files that are neither `.py`
91
+ nor `.md` are first-party without exception — the licence texts, configuration and packaging
92
+ (`config.yaml`, `pyproject.toml`, the three requirements files, `package.json`, `pytest.ini`, the
93
+ `.github/` workflows, issue templates and scanner configuration, the dotfiles), the two prompt
94
+ texts, `bin/venastine.mjs` and `scripts/prepublish-check.mjs`, `docs/assets/research-mode-birds-eye.mermaid`,
95
+ `tui/app.tcss`, the two `.example` templates, the hosted demo's four page templates in
96
+ `deploy/hosted/`, one screenshot of this project's own interface, and its cover image with the
97
+ page it is rendered from. **No third-party fonts, images or data files are bundled.** The
98
+ cover's text is set in Cascadia Mono, Microsoft's font under the SIL Open Font License: the PNG
99
+ holds rendered glyphs, and its page names the font, and neither carries a copy of it.
100
+
101
+ *(Counts restated in batch 83. The figure had been 166 against 200, the enumeration named
102
+ five of the thirty-four, and the closing sentence said there were no images at all while the
103
+ screenshot was tracked. The claim itself held throughout; only its arithmetic had drifted.)*
104
+
105
+ *(Restated again in batch 198, when the cover joined: 200 and 34 had become 277 and 43 as the
106
+ project grew. Both sweeps were run again and found nothing new, and every file added since
107
+ batch 83 is first-party.)*
108
+
109
+ What the repository *does* reproduce is third-party **text**:
110
+
111
+ | Material | Where it lives | Origin | Licensing |
112
+ |---|---|---|---|
113
+ | **Contributor Covenant, v2.1** | `CODE_OF_CONDUCT.md` (adapted — contact details and enforcement channel are ours) | Authored 2014 by Coraline Ada Ehmke, with later collaborative contributions. https://www.contributor-covenant.org/version/2/1/code_of_conduct.html | **Not stated by upstream** for the document text — see the note below |
114
+ | **Mozilla's CoC enforcement ladder** | Inspiration for the *Enforcement Guidelines* section of `CODE_OF_CONDUCT.md`, credited there per the Covenant's own boilerplate | https://github.com/mozilla/diversity | GitHub reports the repository as **MPL-2.0** |
115
+ | **Apache License 2.0 text** | `LICENSE` | https://www.apache.org/licenses/LICENSE-2.0 | Reproduced verbatim, which is what the licence itself directs; the appendix boilerplate is filled in with this project's copyright |
116
+
117
+ > **On the Covenant's licence.** Upstream does not publish an explicit licence for the Code of
118
+ > Conduct *text*. Three sources were checked on 2026-08-27: the project's `LICENSE.md`
119
+ > (`EthicalSource/contributor_covenant`) states the **Hippocratic License 3.0**, which covers the
120
+ > site and its code; the contributor-covenant.org footer carries a copyright line and no licence
121
+ > statement; and the raw `content/version/2/1/code_of_conduct.md` carries none either.
122
+ >
123
+ > **No licence identifier is asserted here on the Covenant's behalf.** The attribution block kept
124
+ > in `CODE_OF_CONDUCT.md` — naming the work, its version, its source URL, and the fact that it is
125
+ > *adapted* — is verbatim the attribution upstream prescribes in its own boilerplate, and is the
126
+ > best available evidence of what they ask adopters to provide. If you need certainty for a
127
+ > compliance review, ask upstream rather than inferring from this file.
128
+
129
+ ## What this means
130
+
131
+ * All licenses **listed above** are **permissive** (MIT / BSD-3-Clause / PSF / Apache-2.0). None are copyleft (GPL/AGPL) and none impose source-disclosure on this Apache-2.0 work. This is a statement about the direct dependencies in the tables, not about the full transitive closure — see *Scope* at the top.
132
+ * This project does not redistribute any of them. It is distributed as **source** — a `git` checkout or the npm package `@yahyahammad/venastine`, which is the same folder of first-party files — and `pip` fetches each dependency from PyPI, onto the user's machine, under its own license. **No inbound `NOTICE` obligation therefore arises** — nothing here carries an upstream NOTICE that this project must propagate. The trigger is **redistribution**, not source-vs-binary, and not which channel delivered the source; if a build that vendors these packages is ever distributed, ship their `LICENSE` and `NOTICE` files as received (Apache-2.0 §4(d) applies to `openai`, `google-genai` and `pytest-asyncio`). **The npm tarball must therefore never carry wheels** — that is the one change that would turn this paragraph false, and `CONTRIBUTING.md` records it as a rule.
133
+ * **The npm channel adds no third-party licence surface at all.** Its launcher (`bin/venastine.mjs`) is Node standard library only, with an empty `dependencies` block, so an install of this package fetches no JavaScript code from anyone. What the tarball contains is the first-party source listed under `files` in `package.json`, plus `LICENSE`, `NOTICE` and this file. Publishing *is* distribution of the Work under Apache-2.0 §4 where running from a checkout was not, which is why those three are in the allowlist rather than left to chance: npm auto-includes `LICENSE` and does **not** auto-include `NOTICE`.
134
+ * The [NOTICE](./NOTICE) file this project publishes is therefore **voluntary**, not required. Apache-2.0 §4(d) obliges you to propagate a NOTICE you *received*; it does not oblige a licensor to author one. It exists because scanners and reviewers look for it and because it gives the copyright assertion a canonical home — and it is kept minimal on purpose, since anyone who redistributes this work must carry its contents forward.
135
+ * Full license texts: `pip show <package>` or `pip-licenses --format plain --with-urls`, or the PyPI links above.
136
+
137
+ ## How to regenerate
138
+
139
+ ```bash
140
+ pip-licenses --format markdown --with-urls --with-license-file
141
+ # or
142
+ pip install pip-licenses && pip-licenses --format plain
143
+ ```
144
+
145
+ When a dependency is added or re-pinned, add a row here with its SPDX identifier and re-check the `Apache 2.0 Compatible` column. CI does not enforce this file today — it is documentation for reviewers.
146
+
147
+ ---
148
+ *Last updated: 2026-08-27. If any row's upstream re-licenses, this file must be updated.*
package/env_secrets.py CHANGED
@@ -1,118 +1,118 @@
1
- """
2
- env_secrets.py
3
-
4
- Miscellaneous API keys for individual TOOLS (e.g. a GitHub token, an
5
- NVD/NIST API key) -- NOT LLM provider keys. Loaded from a .env file via
6
- python-dotenv.
7
-
8
- This is deliberately separate from credentials.py. The distinction:
9
-
10
- credentials.py -- LLM PROVIDER keys (OpenAI, Anthropic, ...). Structured
11
- per-provider (URL + key + compatibility flag), stored
12
- in providers.json, read/written through
13
- load_provider_data()/save_credentials().
14
-
15
- env_secrets.py -- Flat, single-value secrets that one specific TOOL
16
- needs to call some third-party API. No structure
17
- beyond name -> value, stored in .env (never committed
18
- -- see .gitignore), read through get_env_secret().
19
-
20
- If you're adding a new tool that needs its own API key (a weather API, a
21
- GitHub token, an NVD key, etc.), it belongs here, not in credentials.py or
22
- providers.json -- those are exclusively for the LLM provider abstraction
23
- in core/client.py.
24
- """
25
-
26
- import os
27
-
28
- from dotenv import dotenv_values, find_dotenv
29
-
30
- # Batch 35. Resolved at IMPORT time like credentials.LLM_PROVIDERS_FILE and
31
- # for the same reason -- a test can monkeypatch the attribute, and a user can
32
- # point it anywhere before launch. Reading the variable is all that happens
33
- # at import; the FILE is read by `_file_values()`, at the point of use.
34
- #
35
- # THE usecwd=True IS LOAD-BEARING, not a style choice. A bare find_dotenv()
36
- # is find_dotenv(usecwd=False), which walks up from THE CALLING FRAME'S
37
- # FILE -- this module -- and not from the working directory. In a checkout
38
- # those are the same directory, which is the only reason this has ever looked
39
- # like cwd resolution. Install the harness anywhere else (npm puts it under
40
- # node_modules/) and the walk starts in the wrong tree: it never reaches the
41
- # user's .env, and it can pick up a stray one sitting above the install
42
- # prefix. Measured before the fix, with a .env in the working directory and
43
- # the harness imported from elsewhere: get_env_secret() saw None.
44
- #
45
- # Do not "simplify" this back to a bare call. The defect is invisible from
46
- # a checkout and presents as a tool reporting a missing key that is sitting
47
- # in the .env right next to you.
48
- #
49
- # AGENT_ENV_FILE is the escape hatch, named to match AGENT_PROVIDERS_FILE.
50
- # There is deliberately NO user-level fallback to ~/.config/venastine/ here,
51
- # though providers.json has one: a provider key is machine-wide by nature,
52
- # while .env holds the per-project tool tokens described above, and the two
53
- # stores are kept apart on purpose. find_dotenv returns "" when it finds
54
- # nothing, and that reads as "no file", so the unconfigured case costs one
55
- # directory walk and returns nothing.
56
- ENV_FILE = os.environ.get("AGENT_ENV_FILE")
57
-
58
- # A .env MAY NOT SUPPLY THE HARNESS'S OWN NAMES (TECHNICAL_DEBT 57, batch
59
- # 160). Until then this module called `load_dotenv()` AT IMPORT, which wrote
60
- # every name in the file into `os.environ` for the whole process -- and a
61
- # .env is an ordinary file in a repository, inside no trust boundary. Five
62
- # security-relevant knobs are read from `os.environ`, two of them at call
63
- # time: `AGENT_SECRETS_FILE` moves the encrypted store, `AGENT_LOG_FILE`
64
- # the log, and `VENASTINE_REDACT_OFF` turns pattern redaction off -- the
65
- # switch kept out of settings.json precisely so a cloned repository cannot
66
- # flip it (G7's reason). Nothing imported this module yet, so none of that
67
- # had happened; the first tool to import it would have done all of it.
68
- #
69
- # So the file is now READ, never loaded: `dotenv_values()` returns a mapping
70
- # and touches nothing, `get_env_secret` is the only reader, and the process
71
- # environment still wins, as `load_dotenv`'s default `override=False` made
72
- # it. The filter is the second half and the belt: no harness module reads a
73
- # knob through `get_env_secret`, but a tool asking for one of these names
74
- # must get the environment's answer or none, never the repository's.
75
- _HARNESS_PREFIXES = ("AGENT_", "VENASTINE_")
76
-
77
-
78
- def _file_values() -> dict:
79
- """The tool keys the .env holds, minus every harness name.
80
-
81
- Read at the call, from the file `AGENT_ENV_FILE` names or the nearest
82
- .env walking up from the working directory. A name with no value (a
83
- bare `KEY` line) is absent rather than None, so the caller's
84
- "missing" message stays the one it gives.
85
- """
86
- path = ENV_FILE or find_dotenv(usecwd=True)
87
- if not path:
88
- return {}
89
- return {
90
- name: value for name, value in dotenv_values(path).items()
91
- if value is not None
92
- and not name.upper().startswith(_HARNESS_PREFIXES)
93
- }
94
-
95
-
96
- def get_env_secret(key: str, required: bool = True) -> str:
97
- """
98
- Fetch a misc API key/secret from the environment or .env.
99
-
100
- The process environment answers first, then the .env file; nothing is
101
- written back to `os.environ` (TECHNICAL_DEBT 57).
102
-
103
- Raises a clear, actionable error if a REQUIRED secret is missing,
104
- rather than letting a tool proceed with an empty string and fail
105
- later with a confusing 401 from some third-party API. Pass
106
- required=False for genuinely optional keys (e.g. a key that only
107
- unlocks a higher rate limit but isn't needed for the tool to work
108
- at all).
109
- """
110
- value = os.environ.get(key)
111
- if value is None:
112
- value = _file_values().get(key)
113
- if required and not value:
114
- raise ValueError(
115
- f"Missing required environment variable '{key}'. "
116
- f"Copy .env.example to .env and fill in {key}."
117
- )
118
- return value or ""
1
+ """
2
+ env_secrets.py
3
+
4
+ Miscellaneous API keys for individual TOOLS (e.g. a GitHub token, an
5
+ NVD/NIST API key) -- NOT LLM provider keys. Loaded from a .env file via
6
+ python-dotenv.
7
+
8
+ This is deliberately separate from credentials.py. The distinction:
9
+
10
+ credentials.py -- LLM PROVIDER keys (OpenAI, Anthropic, ...). Structured
11
+ per-provider (URL + key + compatibility flag), stored
12
+ in providers.json, read/written through
13
+ load_provider_data()/save_credentials().
14
+
15
+ env_secrets.py -- Flat, single-value secrets that one specific TOOL
16
+ needs to call some third-party API. No structure
17
+ beyond name -> value, stored in .env (never committed
18
+ -- see .gitignore), read through get_env_secret().
19
+
20
+ If you're adding a new tool that needs its own API key (a weather API, a
21
+ GitHub token, an NVD key, etc.), it belongs here, not in credentials.py or
22
+ providers.json -- those are exclusively for the LLM provider abstraction
23
+ in core/client.py.
24
+ """
25
+
26
+ import os
27
+
28
+ from dotenv import dotenv_values, find_dotenv
29
+
30
+ # Batch 35. Resolved at IMPORT time like credentials.LLM_PROVIDERS_FILE and
31
+ # for the same reason -- a test can monkeypatch the attribute, and a user can
32
+ # point it anywhere before launch. Reading the variable is all that happens
33
+ # at import; the FILE is read by `_file_values()`, at the point of use.
34
+ #
35
+ # THE usecwd=True IS LOAD-BEARING, not a style choice. A bare find_dotenv()
36
+ # is find_dotenv(usecwd=False), which walks up from THE CALLING FRAME'S
37
+ # FILE -- this module -- and not from the working directory. In a checkout
38
+ # those are the same directory, which is the only reason this has ever looked
39
+ # like cwd resolution. Install the harness anywhere else (npm puts it under
40
+ # node_modules/) and the walk starts in the wrong tree: it never reaches the
41
+ # user's .env, and it can pick up a stray one sitting above the install
42
+ # prefix. Measured before the fix, with a .env in the working directory and
43
+ # the harness imported from elsewhere: get_env_secret() saw None.
44
+ #
45
+ # Do not "simplify" this back to a bare call. The defect is invisible from
46
+ # a checkout and presents as a tool reporting a missing key that is sitting
47
+ # in the .env right next to you.
48
+ #
49
+ # AGENT_ENV_FILE is the escape hatch, named to match AGENT_PROVIDERS_FILE.
50
+ # There is deliberately NO user-level fallback to ~/.config/venastine/ here,
51
+ # though providers.json has one: a provider key is machine-wide by nature,
52
+ # while .env holds the per-project tool tokens described above, and the two
53
+ # stores are kept apart on purpose. find_dotenv returns "" when it finds
54
+ # nothing, and that reads as "no file", so the unconfigured case costs one
55
+ # directory walk and returns nothing.
56
+ ENV_FILE = os.environ.get("AGENT_ENV_FILE")
57
+
58
+ # A .env MAY NOT SUPPLY THE HARNESS'S OWN NAMES (TECHNICAL_DEBT 57, batch
59
+ # 160). Until then this module called `load_dotenv()` AT IMPORT, which wrote
60
+ # every name in the file into `os.environ` for the whole process -- and a
61
+ # .env is an ordinary file in a repository, inside no trust boundary. Five
62
+ # security-relevant knobs are read from `os.environ`, two of them at call
63
+ # time: `AGENT_SECRETS_FILE` moves the encrypted store, `AGENT_LOG_FILE`
64
+ # the log, and `VENASTINE_REDACT_OFF` turns pattern redaction off -- the
65
+ # switch kept out of settings.json precisely so a cloned repository cannot
66
+ # flip it (G7's reason). Nothing imported this module yet, so none of that
67
+ # had happened; the first tool to import it would have done all of it.
68
+ #
69
+ # So the file is now READ, never loaded: `dotenv_values()` returns a mapping
70
+ # and touches nothing, `get_env_secret` is the only reader, and the process
71
+ # environment still wins, as `load_dotenv`'s default `override=False` made
72
+ # it. The filter is the second half and the belt: no harness module reads a
73
+ # knob through `get_env_secret`, but a tool asking for one of these names
74
+ # must get the environment's answer or none, never the repository's.
75
+ _HARNESS_PREFIXES = ("AGENT_", "VENASTINE_")
76
+
77
+
78
+ def _file_values() -> dict:
79
+ """The tool keys the .env holds, minus every harness name.
80
+
81
+ Read at the call, from the file `AGENT_ENV_FILE` names or the nearest
82
+ .env walking up from the working directory. A name with no value (a
83
+ bare `KEY` line) is absent rather than None, so the caller's
84
+ "missing" message stays the one it gives.
85
+ """
86
+ path = ENV_FILE or find_dotenv(usecwd=True)
87
+ if not path:
88
+ return {}
89
+ return {
90
+ name: value for name, value in dotenv_values(path).items()
91
+ if value is not None
92
+ and not name.upper().startswith(_HARNESS_PREFIXES)
93
+ }
94
+
95
+
96
+ def get_env_secret(key: str, required: bool = True) -> str:
97
+ """
98
+ Fetch a misc API key/secret from the environment or .env.
99
+
100
+ The process environment answers first, then the .env file; nothing is
101
+ written back to `os.environ` (TECHNICAL_DEBT 57).
102
+
103
+ Raises a clear, actionable error if a REQUIRED secret is missing,
104
+ rather than letting a tool proceed with an empty string and fail
105
+ later with a confusing 401 from some third-party API. Pass
106
+ required=False for genuinely optional keys (e.g. a key that only
107
+ unlocks a higher rate limit but isn't needed for the tool to work
108
+ at all).
109
+ """
110
+ value = os.environ.get(key)
111
+ if value is None:
112
+ value = _file_values().get(key)
113
+ if required and not value:
114
+ raise ValueError(
115
+ f"Missing required environment variable '{key}'. "
116
+ f"Copy .env.example to .env and fill in {key}."
117
+ )
118
+ return value or ""