traceforge-pcb 1.0.0__py3-none-any.whl

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 (219) hide show
  1. traceforge/__init__.py +3 -0
  2. traceforge/__main__.py +3 -0
  3. traceforge/acp_server.py +570 -0
  4. traceforge/agent.py +680 -0
  5. traceforge/altium/__init__.py +6 -0
  6. traceforge/altium/cfb.py +70 -0
  7. traceforge/altium/cli.py +60 -0
  8. traceforge/altium/model.py +163 -0
  9. traceforge/altium/outputs.py +24 -0
  10. traceforge/altium/pcb.py +301 -0
  11. traceforge/altium/project.py +328 -0
  12. traceforge/altium/schematic.py +400 -0
  13. traceforge/altium/tools.py +166 -0
  14. traceforge/approval.py +219 -0
  15. traceforge/attachments.py +346 -0
  16. traceforge/background.py +253 -0
  17. traceforge/bench/__init__.py +5 -0
  18. traceforge/bench/adapters.py +337 -0
  19. traceforge/bench/checks.py +410 -0
  20. traceforge/bench/cli.py +121 -0
  21. traceforge/bench/design.py +439 -0
  22. traceforge/bench/kicad.py +99 -0
  23. traceforge/bench/partscheck.py +159 -0
  24. traceforge/bench/review.py +100 -0
  25. traceforge/bench/runner.py +226 -0
  26. traceforge/bench/score.py +204 -0
  27. traceforge/bench/tasks.py +102 -0
  28. traceforge/chat.py +1185 -0
  29. traceforge/checks.py +328 -0
  30. traceforge/checks_sides.py +118 -0
  31. traceforge/cli.py +2224 -0
  32. traceforge/clipboard.py +107 -0
  33. traceforge/config.py +299 -0
  34. traceforge/context.py +276 -0
  35. traceforge/design/__init__.py +1 -0
  36. traceforge/design/constraints.py +397 -0
  37. traceforge/design/generate.py +1789 -0
  38. traceforge/design/outline.py +905 -0
  39. traceforge/design/schematic_layout.py +932 -0
  40. traceforge/design/schematic_lint.py +329 -0
  41. traceforge/design/schematic_route.py +207 -0
  42. traceforge/design/sheets.py +854 -0
  43. traceforge/design/sides.py +328 -0
  44. traceforge/design/spec.py +462 -0
  45. traceforge/design/specsheet.py +2351 -0
  46. traceforge/design/specsheet_render.py +183 -0
  47. traceforge/desktop/__init__.py +109 -0
  48. traceforge/desktop/keys.py +90 -0
  49. traceforge/desktop/project.py +443 -0
  50. traceforge/desktop/review.py +20 -0
  51. traceforge/desktop/server.py +1277 -0
  52. traceforge/desktop/static/app.css +223 -0
  53. traceforge/desktop/static/app.js +683 -0
  54. traceforge/desktop/static/highlight.js +77 -0
  55. traceforge/desktop/static/index.html +89 -0
  56. traceforge/desktop/static/md.js +90 -0
  57. traceforge/desktop/static/viewer.js +213 -0
  58. traceforge/desktop/symbols.py +212 -0
  59. traceforge/desktop/update.py +65 -0
  60. traceforge/diagnostics.py +67 -0
  61. traceforge/errata.py +219 -0
  62. traceforge/fab.py +108 -0
  63. traceforge/fab_layers.py +44 -0
  64. traceforge/features/__init__.py +6 -0
  65. traceforge/features/candidates.py +117 -0
  66. traceforge/features/cli.py +200 -0
  67. traceforge/features/package.py +433 -0
  68. traceforge/features/revdiff.py +224 -0
  69. traceforge/features/sarif.py +145 -0
  70. traceforge/features/viewer.py +265 -0
  71. traceforge/firmware/__init__.py +3 -0
  72. traceforge/firmware/cli.py +174 -0
  73. traceforge/firmware/drivers.py +372 -0
  74. traceforge/firmware/drivers_data.py +256 -0
  75. traceforge/firmware/mcus.py +177 -0
  76. traceforge/firmware/netlist.py +55 -0
  77. traceforge/firmware/pinmap.py +296 -0
  78. traceforge/firmware/scaffold.py +466 -0
  79. traceforge/firmware/toolchain.py +262 -0
  80. traceforge/hooks.py +237 -0
  81. traceforge/kicad/__init__.py +0 -0
  82. traceforge/kicad/cli.py +519 -0
  83. traceforge/kicad/diffpair.py +174 -0
  84. traceforge/kicad/edgegeom.py +191 -0
  85. traceforge/kicad/edit.py +405 -0
  86. traceforge/kicad/escape.py +1410 -0
  87. traceforge/kicad/formats.py +1073 -0
  88. traceforge/kicad/impedance.py +320 -0
  89. traceforge/kicad/install.py +75 -0
  90. traceforge/kicad/libraries.py +490 -0
  91. traceforge/kicad/models3d.py +942 -0
  92. traceforge/kicad/outputs.py +81 -0
  93. traceforge/kicad/pcb.py +787 -0
  94. traceforge/kicad/planes.py +1242 -0
  95. traceforge/kicad/project.py +136 -0
  96. traceforge/kicad/route.py +2698 -0
  97. traceforge/kicad/routegeom.py +164 -0
  98. traceforge/kicad/schematic.py +268 -0
  99. traceforge/kicad/sides.py +34 -0
  100. traceforge/kicad/stackup.py +424 -0
  101. traceforge/kicad_plugin/__init__.py +12 -0
  102. traceforge/kicad_plugin/actions.py +92 -0
  103. traceforge/kicad_plugin/cli.py +66 -0
  104. traceforge/kicad_plugin/client.py +86 -0
  105. traceforge/kicad_plugin/context.py +257 -0
  106. traceforge/kicad_plugin/discovery.py +81 -0
  107. traceforge/kicad_plugin/install.py +203 -0
  108. traceforge/kicad_plugin/overlay.py +60 -0
  109. traceforge/kicad_plugin/payload/action_plugin.py +65 -0
  110. traceforge/kicad_plugin/payload/ipc_main.py +42 -0
  111. traceforge/kicad_plugin/payload/plugin.json +90 -0
  112. traceforge/kicad_plugin/payload/requirements.txt +1 -0
  113. traceforge/kicad_plugin/views.py +202 -0
  114. traceforge/langchain.py +57 -0
  115. traceforge/local.py +580 -0
  116. traceforge/mcp_server.py +304 -0
  117. traceforge/models.py +310 -0
  118. traceforge/next_steps.py +110 -0
  119. traceforge/parts/__init__.py +52 -0
  120. traceforge/parts/alternates.py +488 -0
  121. traceforge/parts/bom.py +423 -0
  122. traceforge/parts/brief.py +705 -0
  123. traceforge/parts/catalog.py +297 -0
  124. traceforge/parts/cli_sourcing.py +156 -0
  125. traceforge/parts/data/duty_rates.yaml +37 -0
  126. traceforge/parts/data/hs_codes.yaml +103 -0
  127. traceforge/parts/datasheet.py +278 -0
  128. traceforge/parts/fx.py +100 -0
  129. traceforge/parts/model.py +185 -0
  130. traceforge/parts/net.py +187 -0
  131. traceforge/parts/offers.py +46 -0
  132. traceforge/parts/packages.py +397 -0
  133. traceforge/parts/pinout.py +714 -0
  134. traceforge/parts/providers/__init__.py +17 -0
  135. traceforge/parts/providers/base.py +100 -0
  136. traceforge/parts/providers/jlc.py +364 -0
  137. traceforge/parts/providers/keyed.py +661 -0
  138. traceforge/parts/report.py +508 -0
  139. traceforge/parts/supply.py +330 -0
  140. traceforge/parts/verify.py +455 -0
  141. traceforge/parts/web.py +575 -0
  142. traceforge/plans.py +70 -0
  143. traceforge/preferences.py +127 -0
  144. traceforge/prices.py +130 -0
  145. traceforge/prices.yaml +28 -0
  146. traceforge/prompts/__init__.py +54 -0
  147. traceforge/prompts/system.md +103 -0
  148. traceforge/providers.py +764 -0
  149. traceforge/remote/__init__.py +33 -0
  150. traceforge/remote/client.py +422 -0
  151. traceforge/remote/oidc.py +240 -0
  152. traceforge/remote/orgs.py +510 -0
  153. traceforge/remote/server.py +690 -0
  154. traceforge/remote/store.py +100 -0
  155. traceforge/review_changes.py +187 -0
  156. traceforge/routing.py +99 -0
  157. traceforge/runtime.py +435 -0
  158. traceforge/sessions.py +324 -0
  159. traceforge/sexpr.py +279 -0
  160. traceforge/sim/__init__.py +17 -0
  161. traceforge/sim/acmath.py +234 -0
  162. traceforge/sim/circuit.py +499 -0
  163. traceforge/sim/cli.py +162 -0
  164. traceforge/sim/engine.py +172 -0
  165. traceforge/sim/ltspice.py +175 -0
  166. traceforge/sim/measure.py +123 -0
  167. traceforge/sim/models.py +76 -0
  168. traceforge/sim/project.py +218 -0
  169. traceforge/sim/rawfile.py +123 -0
  170. traceforge/sim/results.py +298 -0
  171. traceforge/sim/tune.py +172 -0
  172. traceforge/skill_commands.py +165 -0
  173. traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
  174. traceforge/skill_library/compliance-review/SKILL.md +51 -0
  175. traceforge/skill_library/design-review/SKILL.md +47 -0
  176. traceforge/skill_library/errata-hunt/SKILL.md +30 -0
  177. traceforge/skill_library/firmware/SKILL.md +26 -0
  178. traceforge/skill_library/power-budget/SKILL.md +27 -0
  179. traceforge/skill_library/release-package/SKILL.md +29 -0
  180. traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
  181. traceforge/skill_library/thermal-review/SKILL.md +15 -0
  182. traceforge/skills.py +131 -0
  183. traceforge/thermal.py +557 -0
  184. traceforge/tools/__init__.py +48 -0
  185. traceforge/tools/agent_tools.py +213 -0
  186. traceforge/tools/base.py +303 -0
  187. traceforge/tools/batch.py +155 -0
  188. traceforge/tools/connections.py +245 -0
  189. traceforge/tools/files.py +777 -0
  190. traceforge/tools/firmware_tools.py +218 -0
  191. traceforge/tools/kicad_tools.py +1072 -0
  192. traceforge/tools/models3d_tools.py +141 -0
  193. traceforge/tools/parts_tools.py +473 -0
  194. traceforge/tools/processes.py +246 -0
  195. traceforge/tools/review_tools.py +178 -0
  196. traceforge/tools/sim_tools.py +230 -0
  197. traceforge/tui.py +620 -0
  198. traceforge/updates.py +124 -0
  199. traceforge/validate/__init__.py +77 -0
  200. traceforge/validate/builtins.py +1091 -0
  201. traceforge/validate/circuits.py +1240 -0
  202. traceforge/validate/config.py +410 -0
  203. traceforge/validate/default.yaml +113 -0
  204. traceforge/validate/design.py +191 -0
  205. traceforge/validate/explain.py +112 -0
  206. traceforge/validate/grounding.py +169 -0
  207. traceforge/validate/ipc2221.py +350 -0
  208. traceforge/validate/multilayer.py +805 -0
  209. traceforge/validate/netmodel.py +261 -0
  210. traceforge/validate/partcheck.py +472 -0
  211. traceforge/validate/report.py +280 -0
  212. traceforge/validate/review.py +322 -0
  213. traceforge/validate/runner.py +662 -0
  214. traceforge/workspace.py +171 -0
  215. traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
  216. traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
  217. traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
  218. traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
  219. traceforge_pcb-1.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,575 @@
1
+ """Read-only web access for the agent: search, fetch, reference designs.
2
+
3
+ Web search providers, picked by ``TRACEFORGE_WEB_SEARCH`` or the first whose
4
+ key is set: Tavily (``TAVILY_API_KEY``), Brave (``BRAVE_API_KEY``), Perplexity
5
+ Sonar (``PERPLEXITY_API_KEY``), OpenAI's hosted web search tool
6
+ (``OPENAI_API_KEY``), Anthropic's (``ANTHROPIC_API_KEY``), then DuckDuckGo's
7
+ HTML endpoint as a keyless last resort (it may answer with a bot challenge, in
8
+ which case the search fails with a clear message rather than being worked around).
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import html
14
+ import ipaddress
15
+ import os
16
+ import re
17
+ import socket
18
+ from dataclasses import asdict, dataclass, field
19
+ from html.parser import HTMLParser
20
+ from typing import Any
21
+ from urllib.parse import parse_qs, unquote, urlparse
22
+
23
+ from traceforge.parts.net import Cache, Net, Offline, ProviderError, default_net
24
+
25
+
26
+ @dataclass
27
+ class WebResult:
28
+ title: str
29
+ url: str
30
+ snippet: str = ""
31
+
32
+
33
+ @dataclass
34
+ class WebAnswer:
35
+ provider: str
36
+ query: str
37
+ results: list[WebResult] = field(default_factory=list)
38
+ answer: str = "" # synthesized answer, for providers that write one
39
+
40
+ def to_dict(self) -> dict[str, Any]:
41
+ data = asdict(self)
42
+ if not self.answer:
43
+ data.pop("answer")
44
+ return data
45
+
46
+
47
+ def _env(*names: str) -> str:
48
+ for name in names:
49
+ if os.environ.get(name, "").strip():
50
+ return os.environ[name].strip()
51
+ return ""
52
+
53
+
54
+ def _trim(text: str, limit: int) -> str:
55
+ text = re.sub(r"\s+", " ", text or "").strip()
56
+ return text if len(text) <= limit else text[: limit - 1] + "…"
57
+
58
+
59
+ class WebSearchProvider:
60
+ name = "web"
61
+ keys: tuple[str, ...] = ()
62
+
63
+ def __init__(self, net: Net):
64
+ self.net = net
65
+
66
+ def configured(self) -> bool:
67
+ return not self.keys or bool(_env(*self.keys))
68
+
69
+ def search(self, query: str, limit: int) -> WebAnswer: # pragma: no cover - interface
70
+ raise NotImplementedError
71
+
72
+
73
+ class TavilySearch(WebSearchProvider):
74
+ name = "tavily"
75
+ keys = ("TAVILY_API_KEY",)
76
+
77
+ def search(self, query: str, limit: int) -> WebAnswer:
78
+ data = self.net.json(
79
+ "POST",
80
+ "https://api.tavily.com/search",
81
+ json={"query": query, "max_results": limit, "include_answer": True},
82
+ headers={"Authorization": f"Bearer {_env(*self.keys)}"},
83
+ )
84
+ return WebAnswer(
85
+ self.name,
86
+ query,
87
+ [
88
+ WebResult(r.get("title", ""), r.get("url", ""), _trim(r.get("content", ""), 400))
89
+ for r in (data or {}).get("results") or []
90
+ ],
91
+ _trim((data or {}).get("answer") or "", 2000),
92
+ )
93
+
94
+
95
+ class BraveSearch(WebSearchProvider):
96
+ name = "brave"
97
+ keys = ("BRAVE_API_KEY", "BRAVE_SEARCH_API_KEY")
98
+
99
+ def search(self, query: str, limit: int) -> WebAnswer:
100
+ data = self.net.json(
101
+ "GET",
102
+ "https://api.search.brave.com/res/v1/web/search",
103
+ params={"q": query, "count": min(limit, 20)},
104
+ headers={"X-Subscription-Token": _env(*self.keys), "Accept": "application/json"},
105
+ )
106
+ results = ((data or {}).get("web") or {}).get("results") or []
107
+ return WebAnswer(
108
+ self.name,
109
+ query,
110
+ [
111
+ WebResult(
112
+ r.get("title", ""),
113
+ r.get("url", ""),
114
+ _trim(re.sub(r"<[^>]+>", "", r.get("description", "")), 400),
115
+ )
116
+ for r in results
117
+ ],
118
+ )
119
+
120
+
121
+ class PerplexitySearch(WebSearchProvider):
122
+ """Perplexity Sonar: a researched answer with citations (a hosted research tool)."""
123
+
124
+ name = "perplexity"
125
+ keys = ("PERPLEXITY_API_KEY", "PPLX_API_KEY")
126
+
127
+ def search(self, query: str, limit: int) -> WebAnswer:
128
+ data = self.net.json(
129
+ "POST",
130
+ "https://api.perplexity.ai/chat/completions",
131
+ json={
132
+ "model": os.environ.get("TRACEFORGE_PERPLEXITY_MODEL", "sonar"),
133
+ "messages": [
134
+ {
135
+ "role": "system",
136
+ "content": "Answer electronics engineering questions concisely, with "
137
+ "part numbers, values and the sources you used.",
138
+ },
139
+ {"role": "user", "content": query},
140
+ ],
141
+ },
142
+ headers={"Authorization": f"Bearer {_env(*self.keys)}"},
143
+ )
144
+ choices = (data or {}).get("choices") or [{}]
145
+ answer = ((choices[0] or {}).get("message") or {}).get("content", "")
146
+ results = [
147
+ WebResult(r.get("title", ""), r.get("url", ""), _trim(r.get("snippet", ""), 300))
148
+ for r in (data or {}).get("search_results") or []
149
+ ] or [WebResult("", url) for url in (data or {}).get("citations") or []]
150
+ return WebAnswer(self.name, query, results[:limit], _trim(answer, 3000))
151
+
152
+
153
+ class OpenAISearch(WebSearchProvider):
154
+ """OpenAI Responses API with its hosted ``web_search`` tool."""
155
+
156
+ name = "openai"
157
+ keys = ("OPENAI_API_KEY",)
158
+
159
+ def search(self, query: str, limit: int) -> WebAnswer:
160
+ base = os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1").rstrip("/")
161
+ data = self.net.json(
162
+ "POST",
163
+ f"{base}/responses",
164
+ json={
165
+ "model": os.environ.get("TRACEFORGE_WEB_SEARCH_MODEL", "gpt-5.4-mini"),
166
+ "tools": [{"type": "web_search"}],
167
+ "reasoning": {"effort": "low"},
168
+ "input": "Search the web and answer concisely for an electronics engineer, "
169
+ f"citing sources: {query}",
170
+ },
171
+ headers={"Authorization": f"Bearer {_env(*self.keys)}"},
172
+ timeout=120,
173
+ )
174
+ answer, results = "", []
175
+ for item in (data or {}).get("output") or []:
176
+ if item.get("type") != "message":
177
+ continue
178
+ for content in item.get("content") or []:
179
+ answer += content.get("text", "")
180
+ for note in content.get("annotations") or []:
181
+ if note.get("type") == "url_citation" and note.get("url"):
182
+ url = re.sub(r"[?&]utm_source=openai$", "", note["url"])
183
+ results.append(WebResult(note.get("title", ""), url))
184
+ seen: set[str] = set()
185
+ unique = [r for r in results if not (r.url in seen or seen.add(r.url))]
186
+ return WebAnswer(self.name, query, unique[:limit], _trim(answer, 3000))
187
+
188
+
189
+ class AnthropicSearch(WebSearchProvider):
190
+ """Anthropic Messages API with the server-side ``web_search`` tool."""
191
+
192
+ name = "anthropic"
193
+ keys = ("ANTHROPIC_API_KEY",)
194
+
195
+ def search(self, query: str, limit: int) -> WebAnswer:
196
+ base = os.environ.get("ANTHROPIC_BASE_URL", "https://api.anthropic.com").rstrip("/")
197
+ data = self.net.json(
198
+ "POST",
199
+ f"{base}/v1/messages",
200
+ json={
201
+ "model": os.environ.get("TRACEFORGE_WEB_SEARCH_CLAUDE_MODEL", "claude-haiku-4-5"),
202
+ "max_tokens": 1500,
203
+ "tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}],
204
+ "messages": [
205
+ {"role": "user", "content": f"Search the web and answer concisely: {query}"}
206
+ ],
207
+ },
208
+ headers={"x-api-key": _env(*self.keys), "anthropic-version": "2023-06-01"},
209
+ timeout=120,
210
+ )
211
+ answer, results = "", []
212
+ for block in (data or {}).get("content") or []:
213
+ if block.get("type") == "text":
214
+ answer += block.get("text", "")
215
+ elif block.get("type") == "web_search_tool_result":
216
+ for r in block.get("content") or []:
217
+ if isinstance(r, dict) and r.get("url"):
218
+ results.append(WebResult(r.get("title", ""), r["url"]))
219
+ return WebAnswer(self.name, query, results[:limit], _trim(answer, 3000))
220
+
221
+
222
+ class _DdgParser(HTMLParser):
223
+ def __init__(self):
224
+ super().__init__()
225
+ self.results: list[WebResult] = []
226
+ self._mode = ""
227
+
228
+ def handle_starttag(self, tag, attrs):
229
+ classes = dict(attrs).get("class") or ""
230
+ if tag == "a" and "result__a" in classes:
231
+ href = dict(attrs).get("href") or ""
232
+ if "uddg=" in href:
233
+ href = unquote(parse_qs(urlparse(href).query).get("uddg", [href])[0])
234
+ self.results.append(WebResult("", href))
235
+ self._mode = "title"
236
+ elif "result__snippet" in classes and self.results:
237
+ self._mode = "snippet"
238
+
239
+ def handle_endtag(self, tag):
240
+ if tag in {"a", "td", "div"}:
241
+ self._mode = ""
242
+
243
+ def handle_data(self, data):
244
+ if not self.results or not self._mode:
245
+ return
246
+ current = self.results[-1]
247
+ if self._mode == "title":
248
+ current.title += data
249
+ else:
250
+ current.snippet += data
251
+
252
+
253
+ class DuckDuckGoSearch(WebSearchProvider):
254
+ name = "duckduckgo"
255
+
256
+ def search(self, query: str, limit: int) -> WebAnswer:
257
+ response = self.net.request("GET", "https://html.duckduckgo.com/html/", params={"q": query})
258
+ text = response.text
259
+ if (
260
+ response.status_code != 200
261
+ or "anomaly" in text.lower()
262
+ or "bots use duckduckgo" in text.lower()
263
+ ):
264
+ raise ProviderError(
265
+ "duckduckgo answered with a bot challenge; set TAVILY_API_KEY, BRAVE_API_KEY, "
266
+ "PERPLEXITY_API_KEY or OPENAI_API_KEY for web search"
267
+ )
268
+ parser = _DdgParser()
269
+ parser.feed(text)
270
+ results = [
271
+ WebResult(_trim(r.title, 200), r.url, _trim(r.snippet, 400))
272
+ for r in parser.results
273
+ if r.url.startswith("http")
274
+ ]
275
+ return WebAnswer(self.name, query, results[:limit])
276
+
277
+
278
+ WEB_PROVIDERS: dict[str, type[WebSearchProvider]] = {
279
+ "tavily": TavilySearch,
280
+ "brave": BraveSearch,
281
+ "perplexity": PerplexitySearch,
282
+ "openai": OpenAISearch,
283
+ "anthropic": AnthropicSearch,
284
+ "duckduckgo": DuckDuckGoSearch,
285
+ }
286
+
287
+
288
+ def web_providers(net: Net | None = None) -> list[WebSearchProvider]:
289
+ net = net or default_net()
290
+ chosen = os.environ.get("TRACEFORGE_WEB_SEARCH", "").strip().lower()
291
+ names = [n.strip() for n in chosen.split(",") if n.strip()] if chosen else list(WEB_PROVIDERS)
292
+ providers = []
293
+ for name in names:
294
+ cls = WEB_PROVIDERS.get(name)
295
+ if cls and cls(net).configured():
296
+ providers.append(cls(net))
297
+ return providers
298
+
299
+
300
+ def web_search(
301
+ query: str, *, limit: int = 8, net: Net | None = None, cache: Cache | None = None
302
+ ) -> WebAnswer:
303
+ """Search the web with the first provider that answers. Raises Offline/ProviderError."""
304
+ query = query.strip()
305
+ if not query:
306
+ raise ProviderError("empty query")
307
+ cache = cache or Cache()
308
+ errors = []
309
+ offline = True
310
+ for provider in web_providers(net):
311
+ key = f"{provider.name}:{limit}:{query}"
312
+ hit = cache.get("web", key)
313
+ if hit is not None:
314
+ data = hit[0]
315
+ return WebAnswer(
316
+ data["provider"],
317
+ data["query"],
318
+ [WebResult(**r) for r in data["results"]],
319
+ data.get("answer", ""),
320
+ )
321
+ try:
322
+ answer = provider.search(query, limit)
323
+ except Offline as exc:
324
+ errors.append(f"{provider.name}: {exc}")
325
+ continue
326
+ except (ProviderError, ValueError, KeyError, TypeError) as exc:
327
+ offline = False
328
+ errors.append(f"{provider.name}: {exc}")
329
+ continue
330
+ cache.put("web", key, answer.to_dict() | {"answer": answer.answer})
331
+ return answer
332
+ if not errors:
333
+ raise ProviderError("no web search provider is configured")
334
+ if offline:
335
+ raise Offline("; ".join(errors))
336
+ raise ProviderError("; ".join(errors))
337
+
338
+
339
+ # ------------------------------------------------------------------- fetch
340
+
341
+
342
+ def check_url(url: str) -> str:
343
+ """Allow only public http(s) URLs (no file:, no localhost or private addresses)."""
344
+ parsed = urlparse(url.strip())
345
+ if parsed.scheme not in {"http", "https"} or not parsed.hostname:
346
+ raise ProviderError("only http(s) URLs can be fetched")
347
+ host = parsed.hostname.lower()
348
+ if host in {"localhost", "metadata.google.internal"} or host.endswith((".local", ".internal")):
349
+ raise ProviderError(f"refusing to fetch a local address ({host})")
350
+ addresses: list[str] = []
351
+ try:
352
+ addresses = [str(ipaddress.ip_address(host))]
353
+ except ValueError:
354
+ try:
355
+ addresses = [info[4][0] for info in socket.getaddrinfo(host, None)][:4]
356
+ except OSError:
357
+ addresses = [] # resolved by the proxy, if there is one
358
+ for address in addresses:
359
+ ip = ipaddress.ip_address(address.split("%")[0])
360
+ if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_reserved or ip.is_multicast:
361
+ raise ProviderError(f"refusing to fetch a private address ({host} -> {ip})")
362
+ return url.strip()
363
+
364
+
365
+ class _TextParser(HTMLParser):
366
+ SKIP = {"script", "style", "noscript", "svg", "head", "nav", "footer", "form", "iframe"}
367
+ BLOCK = {
368
+ "p",
369
+ "div",
370
+ "br",
371
+ "li",
372
+ "tr",
373
+ "h1",
374
+ "h2",
375
+ "h3",
376
+ "h4",
377
+ "h5",
378
+ "h6",
379
+ "section",
380
+ "table",
381
+ "pre",
382
+ }
383
+
384
+ def __init__(self):
385
+ super().__init__()
386
+ self.parts: list[str] = []
387
+ self.title = ""
388
+ self._skip = 0
389
+ self._in_title = False
390
+ self.links: list[tuple[str, str]] = []
391
+ self._href = ""
392
+
393
+ def handle_starttag(self, tag, attrs):
394
+ if tag == "title":
395
+ self._in_title = True
396
+ if tag in self.SKIP:
397
+ self._skip += 1
398
+ if tag in self.BLOCK:
399
+ self.parts.append("\n")
400
+ if tag in {"h1", "h2", "h3"}:
401
+ self.parts.append("# ")
402
+ if tag == "a":
403
+ self._href = dict(attrs).get("href") or ""
404
+ if tag in {"td", "th"}:
405
+ self.parts.append(" | ")
406
+
407
+ def handle_endtag(self, tag):
408
+ if tag == "title":
409
+ self._in_title = False
410
+ if tag in self.SKIP and self._skip:
411
+ self._skip -= 1
412
+ if tag in self.BLOCK:
413
+ self.parts.append("\n")
414
+
415
+ def handle_data(self, data):
416
+ if self._in_title:
417
+ self.title += data
418
+ return
419
+ if self._skip:
420
+ return
421
+ self.parts.append(data)
422
+ if self._href and data.strip():
423
+ self.links.append((data.strip(), self._href))
424
+ self._href = ""
425
+
426
+
427
+ def html_to_text(raw: str) -> tuple[str, str, list[tuple[str, str]]]:
428
+ parser = _TextParser()
429
+ parser.feed(raw)
430
+ text = html.unescape("".join(parser.parts))
431
+ text = re.sub(r"[ \t\r\f\v]+", " ", text)
432
+ text = re.sub(r"\n\s*\n+", "\n\n", text).strip()
433
+ return _trim(parser.title, 200), text, parser.links
434
+
435
+
436
+ def web_fetch(
437
+ url: str,
438
+ *,
439
+ max_chars: int = 20_000,
440
+ offset: int = 0,
441
+ find: str | None = None,
442
+ net: Net | None = None,
443
+ ) -> dict[str, Any]:
444
+ """Fetch a page as text (PDFs are handed to the datasheet extractor)."""
445
+ url = check_url(url)
446
+ net = net or default_net()
447
+ response = net.request("GET", url)
448
+ if response.status_code >= 400:
449
+ raise ProviderError(f"HTTP {response.status_code} for {url}")
450
+ kind = response.headers.get("content-type", "").split(";")[0].strip().lower()
451
+ if kind == "application/pdf" or response.content[:5] == b"%PDF-":
452
+ from traceforge.parts.datasheet import pdf_pages
453
+
454
+ pages = pdf_pages(response.content)
455
+ text = "\n\n".join(f"[page {i + 1}]\n{t}" for i, t in enumerate(pages))
456
+ title = url.rsplit("/", 1)[-1]
457
+ elif kind.startswith("text/html") or "<html" in response.text[:500].lower():
458
+ title, text, _ = html_to_text(response.text)
459
+ elif kind.startswith("text/") or kind in {"application/json", "application/xml"}:
460
+ title, text = "", response.text
461
+ else:
462
+ raise ProviderError(
463
+ f"unsupported content type {kind or 'unknown'} ({len(response.content)} bytes)"
464
+ )
465
+ total = len(text)
466
+ if find:
467
+ windows = []
468
+ for match in re.finditer(re.escape(find), text, flags=re.IGNORECASE):
469
+ start = max(0, match.start() - 600)
470
+ windows.append(text[start : match.end() + 600])
471
+ if sum(len(w) for w in windows) > max_chars:
472
+ break
473
+ text = "\n...\n".join(windows) if windows else f"[{find!r} not found on the page]"
474
+ else:
475
+ text = text[offset : offset + max_chars]
476
+ return {
477
+ "url": str(response.url),
478
+ "title": title,
479
+ "content_type": kind,
480
+ "total_chars": total,
481
+ "offset": 0 if find else offset,
482
+ "truncated": (not find) and offset + max_chars < total,
483
+ "text": text,
484
+ }
485
+
486
+
487
+ # ------------------------------------------------------- reference projects
488
+
489
+ _ALTIUM_HINT = "altium SchDoc PcbDoc"
490
+ _KICAD_HINT = "kicad kicad_sch kicad_pcb"
491
+
492
+
493
+ def reference_project_search(
494
+ query: str,
495
+ *,
496
+ tool: str = "kicad",
497
+ limit: int = 8,
498
+ net: Net | None = None,
499
+ cache: Cache | None = None,
500
+ ) -> dict[str, Any]:
501
+ """Open hardware projects that use a part or implement a circuit block.
502
+
503
+ GitHub repository search (``GITHUB_TOKEN`` raises the rate limit and enables
504
+ file search inside repositories), plus a web search restricted to OSHWLab,
505
+ Hackaday.io and GitHub when a web provider is configured.
506
+ """
507
+ net = net or default_net()
508
+ cache = cache or Cache()
509
+ hint = {"kicad": "kicad", "altium": "altium", "any": ""}.get(tool, "kicad")
510
+ out: dict[str, Any] = {"query": query, "tool": tool, "github": [], "files": [], "web": None}
511
+ errors: list[str] = []
512
+ token = _env("GITHUB_TOKEN", "GH_TOKEN")
513
+ headers = {"Accept": "application/vnd.github+json"}
514
+ if token:
515
+ headers["Authorization"] = f"Bearer {token}"
516
+ key = f"gh:{tool}:{limit}:{query}"
517
+ hit = cache.get("refs", key)
518
+ if hit is not None:
519
+ out["github"], out["files"] = hit[0]["github"], hit[0]["files"]
520
+ else:
521
+ try:
522
+ data = net.json(
523
+ "GET",
524
+ "https://api.github.com/search/repositories",
525
+ params={
526
+ "q": f"{query} {hint}".strip(),
527
+ "sort": "stars",
528
+ "per_page": min(limit, 20),
529
+ },
530
+ headers=headers,
531
+ )
532
+ out["github"] = [
533
+ {
534
+ "repo": item.get("full_name"),
535
+ "url": item.get("html_url"),
536
+ "stars": item.get("stargazers_count"),
537
+ "updated": (item.get("pushed_at") or "")[:10],
538
+ "description": _trim(item.get("description") or "", 200),
539
+ }
540
+ for item in (data or {}).get("items") or []
541
+ ]
542
+ if token:
543
+ ext = {"kicad": "extension:kicad_sch", "altium": "extension:SchDoc"}.get(tool, "")
544
+ files = net.json(
545
+ "GET",
546
+ "https://api.github.com/search/code",
547
+ params={"q": f"{query} {ext}".strip(), "per_page": min(limit, 20)},
548
+ headers=headers,
549
+ )
550
+ out["files"] = [
551
+ {
552
+ "repo": (item.get("repository") or {}).get("full_name"),
553
+ "path": item.get("path"),
554
+ "url": item.get("html_url"),
555
+ }
556
+ for item in (files or {}).get("items") or []
557
+ ]
558
+ cache.put("refs", key, {"github": out["github"], "files": out["files"]})
559
+ except (Offline, ProviderError) as exc:
560
+ errors.append(f"github: {exc}")
561
+ if any(p.name != "duckduckgo" for p in web_providers(net)):
562
+ try:
563
+ sites = "site:oshwlab.com OR site:hackaday.io OR site:github.com"
564
+ words = _ALTIUM_HINT if tool == "altium" else (_KICAD_HINT if tool == "kicad" else "")
565
+ out["web"] = web_search(
566
+ f"open source {words.split()[0] if words else ''} reference design {query} ({sites})",
567
+ limit=limit,
568
+ net=net,
569
+ cache=cache,
570
+ ).to_dict()
571
+ except (Offline, ProviderError) as exc:
572
+ errors.append(f"web: {exc}")
573
+ if errors:
574
+ out["errors"] = errors
575
+ return out
traceforge/plans.py ADDED
@@ -0,0 +1,70 @@
1
+ """Saved plans (``.traceforge/plans/*.md``, written by plan mode's ``write_plan`` tool)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from dataclasses import dataclass, field
7
+ from pathlib import Path
8
+
9
+ _TODO = re.compile(r"^\s*[-*]\s+\[( |x|X)\]\s+(.+?)\s*$")
10
+
11
+
12
+ @dataclass
13
+ class Plan:
14
+ path: Path
15
+ name: str
16
+ overview: str = ""
17
+ todos: list[tuple[str, bool]] = field(default_factory=list)
18
+
19
+ @property
20
+ def done(self) -> int:
21
+ return sum(1 for _text, done in self.todos if done)
22
+
23
+
24
+ def plans_dir(workspace: Path) -> Path:
25
+ return Path(workspace) / ".traceforge" / "plans"
26
+
27
+
28
+ def list_plans(workspace: Path) -> list[Path]:
29
+ root = plans_dir(workspace)
30
+ if not root.is_dir():
31
+ return []
32
+ return sorted(root.glob("*.md"), key=lambda p: p.stat().st_mtime, reverse=True)
33
+
34
+
35
+ def parse_plan(path: Path) -> Plan:
36
+ text = Path(path).read_text(encoding="utf-8")
37
+ lines = text.splitlines()
38
+ name = next((line[2:].strip() for line in lines if line.startswith("# ")), Path(path).stem)
39
+ overview_lines: list[str] = []
40
+ started = False
41
+ for line in lines:
42
+ if line.startswith("# "):
43
+ started = True
44
+ continue
45
+ if started and line.startswith("## "):
46
+ break
47
+ if started:
48
+ overview_lines.append(line)
49
+ todos = [(m.group(2), m.group(1).lower() == "x") for m in map(_TODO.match, lines) if m]
50
+ return Plan(Path(path), name, "\n".join(overview_lines).strip(), todos)
51
+
52
+
53
+ def resolve_plan(workspace: Path, value: str | None) -> Path | None:
54
+ """A plan by path, by name, or the most recent one when ``value`` is empty."""
55
+ if not value:
56
+ plans = list_plans(workspace)
57
+ return plans[0] if plans else None
58
+ for candidate in (
59
+ Path(value),
60
+ Path(workspace) / value,
61
+ plans_dir(workspace) / value,
62
+ plans_dir(workspace) / f"{value}.md",
63
+ ):
64
+ if candidate.is_file():
65
+ return candidate.resolve()
66
+ return None
67
+
68
+
69
+ def is_plan_file(path: str) -> bool:
70
+ return bool(re.search(r"(^|[\\/])\.traceforge[\\/]plans[\\/][^\\/]+\.md$", path))