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.
- traceforge/__init__.py +3 -0
- traceforge/__main__.py +3 -0
- traceforge/acp_server.py +570 -0
- traceforge/agent.py +680 -0
- traceforge/altium/__init__.py +6 -0
- traceforge/altium/cfb.py +70 -0
- traceforge/altium/cli.py +60 -0
- traceforge/altium/model.py +163 -0
- traceforge/altium/outputs.py +24 -0
- traceforge/altium/pcb.py +301 -0
- traceforge/altium/project.py +328 -0
- traceforge/altium/schematic.py +400 -0
- traceforge/altium/tools.py +166 -0
- traceforge/approval.py +219 -0
- traceforge/attachments.py +346 -0
- traceforge/background.py +253 -0
- traceforge/bench/__init__.py +5 -0
- traceforge/bench/adapters.py +337 -0
- traceforge/bench/checks.py +410 -0
- traceforge/bench/cli.py +121 -0
- traceforge/bench/design.py +439 -0
- traceforge/bench/kicad.py +99 -0
- traceforge/bench/partscheck.py +159 -0
- traceforge/bench/review.py +100 -0
- traceforge/bench/runner.py +226 -0
- traceforge/bench/score.py +204 -0
- traceforge/bench/tasks.py +102 -0
- traceforge/chat.py +1185 -0
- traceforge/checks.py +328 -0
- traceforge/checks_sides.py +118 -0
- traceforge/cli.py +2224 -0
- traceforge/clipboard.py +107 -0
- traceforge/config.py +299 -0
- traceforge/context.py +276 -0
- traceforge/design/__init__.py +1 -0
- traceforge/design/constraints.py +397 -0
- traceforge/design/generate.py +1789 -0
- traceforge/design/outline.py +905 -0
- traceforge/design/schematic_layout.py +932 -0
- traceforge/design/schematic_lint.py +329 -0
- traceforge/design/schematic_route.py +207 -0
- traceforge/design/sheets.py +854 -0
- traceforge/design/sides.py +328 -0
- traceforge/design/spec.py +462 -0
- traceforge/design/specsheet.py +2351 -0
- traceforge/design/specsheet_render.py +183 -0
- traceforge/desktop/__init__.py +109 -0
- traceforge/desktop/keys.py +90 -0
- traceforge/desktop/project.py +443 -0
- traceforge/desktop/review.py +20 -0
- traceforge/desktop/server.py +1277 -0
- traceforge/desktop/static/app.css +223 -0
- traceforge/desktop/static/app.js +683 -0
- traceforge/desktop/static/highlight.js +77 -0
- traceforge/desktop/static/index.html +89 -0
- traceforge/desktop/static/md.js +90 -0
- traceforge/desktop/static/viewer.js +213 -0
- traceforge/desktop/symbols.py +212 -0
- traceforge/desktop/update.py +65 -0
- traceforge/diagnostics.py +67 -0
- traceforge/errata.py +219 -0
- traceforge/fab.py +108 -0
- traceforge/fab_layers.py +44 -0
- traceforge/features/__init__.py +6 -0
- traceforge/features/candidates.py +117 -0
- traceforge/features/cli.py +200 -0
- traceforge/features/package.py +433 -0
- traceforge/features/revdiff.py +224 -0
- traceforge/features/sarif.py +145 -0
- traceforge/features/viewer.py +265 -0
- traceforge/firmware/__init__.py +3 -0
- traceforge/firmware/cli.py +174 -0
- traceforge/firmware/drivers.py +372 -0
- traceforge/firmware/drivers_data.py +256 -0
- traceforge/firmware/mcus.py +177 -0
- traceforge/firmware/netlist.py +55 -0
- traceforge/firmware/pinmap.py +296 -0
- traceforge/firmware/scaffold.py +466 -0
- traceforge/firmware/toolchain.py +262 -0
- traceforge/hooks.py +237 -0
- traceforge/kicad/__init__.py +0 -0
- traceforge/kicad/cli.py +519 -0
- traceforge/kicad/diffpair.py +174 -0
- traceforge/kicad/edgegeom.py +191 -0
- traceforge/kicad/edit.py +405 -0
- traceforge/kicad/escape.py +1410 -0
- traceforge/kicad/formats.py +1073 -0
- traceforge/kicad/impedance.py +320 -0
- traceforge/kicad/install.py +75 -0
- traceforge/kicad/libraries.py +490 -0
- traceforge/kicad/models3d.py +942 -0
- traceforge/kicad/outputs.py +81 -0
- traceforge/kicad/pcb.py +787 -0
- traceforge/kicad/planes.py +1242 -0
- traceforge/kicad/project.py +136 -0
- traceforge/kicad/route.py +2698 -0
- traceforge/kicad/routegeom.py +164 -0
- traceforge/kicad/schematic.py +268 -0
- traceforge/kicad/sides.py +34 -0
- traceforge/kicad/stackup.py +424 -0
- traceforge/kicad_plugin/__init__.py +12 -0
- traceforge/kicad_plugin/actions.py +92 -0
- traceforge/kicad_plugin/cli.py +66 -0
- traceforge/kicad_plugin/client.py +86 -0
- traceforge/kicad_plugin/context.py +257 -0
- traceforge/kicad_plugin/discovery.py +81 -0
- traceforge/kicad_plugin/install.py +203 -0
- traceforge/kicad_plugin/overlay.py +60 -0
- traceforge/kicad_plugin/payload/action_plugin.py +65 -0
- traceforge/kicad_plugin/payload/ipc_main.py +42 -0
- traceforge/kicad_plugin/payload/plugin.json +90 -0
- traceforge/kicad_plugin/payload/requirements.txt +1 -0
- traceforge/kicad_plugin/views.py +202 -0
- traceforge/langchain.py +57 -0
- traceforge/local.py +580 -0
- traceforge/mcp_server.py +304 -0
- traceforge/models.py +310 -0
- traceforge/next_steps.py +110 -0
- traceforge/parts/__init__.py +52 -0
- traceforge/parts/alternates.py +488 -0
- traceforge/parts/bom.py +423 -0
- traceforge/parts/brief.py +705 -0
- traceforge/parts/catalog.py +297 -0
- traceforge/parts/cli_sourcing.py +156 -0
- traceforge/parts/data/duty_rates.yaml +37 -0
- traceforge/parts/data/hs_codes.yaml +103 -0
- traceforge/parts/datasheet.py +278 -0
- traceforge/parts/fx.py +100 -0
- traceforge/parts/model.py +185 -0
- traceforge/parts/net.py +187 -0
- traceforge/parts/offers.py +46 -0
- traceforge/parts/packages.py +397 -0
- traceforge/parts/pinout.py +714 -0
- traceforge/parts/providers/__init__.py +17 -0
- traceforge/parts/providers/base.py +100 -0
- traceforge/parts/providers/jlc.py +364 -0
- traceforge/parts/providers/keyed.py +661 -0
- traceforge/parts/report.py +508 -0
- traceforge/parts/supply.py +330 -0
- traceforge/parts/verify.py +455 -0
- traceforge/parts/web.py +575 -0
- traceforge/plans.py +70 -0
- traceforge/preferences.py +127 -0
- traceforge/prices.py +130 -0
- traceforge/prices.yaml +28 -0
- traceforge/prompts/__init__.py +54 -0
- traceforge/prompts/system.md +103 -0
- traceforge/providers.py +764 -0
- traceforge/remote/__init__.py +33 -0
- traceforge/remote/client.py +422 -0
- traceforge/remote/oidc.py +240 -0
- traceforge/remote/orgs.py +510 -0
- traceforge/remote/server.py +690 -0
- traceforge/remote/store.py +100 -0
- traceforge/review_changes.py +187 -0
- traceforge/routing.py +99 -0
- traceforge/runtime.py +435 -0
- traceforge/sessions.py +324 -0
- traceforge/sexpr.py +279 -0
- traceforge/sim/__init__.py +17 -0
- traceforge/sim/acmath.py +234 -0
- traceforge/sim/circuit.py +499 -0
- traceforge/sim/cli.py +162 -0
- traceforge/sim/engine.py +172 -0
- traceforge/sim/ltspice.py +175 -0
- traceforge/sim/measure.py +123 -0
- traceforge/sim/models.py +76 -0
- traceforge/sim/project.py +218 -0
- traceforge/sim/rawfile.py +123 -0
- traceforge/sim/results.py +298 -0
- traceforge/sim/tune.py +172 -0
- traceforge/skill_commands.py +165 -0
- traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
- traceforge/skill_library/compliance-review/SKILL.md +51 -0
- traceforge/skill_library/design-review/SKILL.md +47 -0
- traceforge/skill_library/errata-hunt/SKILL.md +30 -0
- traceforge/skill_library/firmware/SKILL.md +26 -0
- traceforge/skill_library/power-budget/SKILL.md +27 -0
- traceforge/skill_library/release-package/SKILL.md +29 -0
- traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
- traceforge/skill_library/thermal-review/SKILL.md +15 -0
- traceforge/skills.py +131 -0
- traceforge/thermal.py +557 -0
- traceforge/tools/__init__.py +48 -0
- traceforge/tools/agent_tools.py +213 -0
- traceforge/tools/base.py +303 -0
- traceforge/tools/batch.py +155 -0
- traceforge/tools/connections.py +245 -0
- traceforge/tools/files.py +777 -0
- traceforge/tools/firmware_tools.py +218 -0
- traceforge/tools/kicad_tools.py +1072 -0
- traceforge/tools/models3d_tools.py +141 -0
- traceforge/tools/parts_tools.py +473 -0
- traceforge/tools/processes.py +246 -0
- traceforge/tools/review_tools.py +178 -0
- traceforge/tools/sim_tools.py +230 -0
- traceforge/tui.py +620 -0
- traceforge/updates.py +124 -0
- traceforge/validate/__init__.py +77 -0
- traceforge/validate/builtins.py +1091 -0
- traceforge/validate/circuits.py +1240 -0
- traceforge/validate/config.py +410 -0
- traceforge/validate/default.yaml +113 -0
- traceforge/validate/design.py +191 -0
- traceforge/validate/explain.py +112 -0
- traceforge/validate/grounding.py +169 -0
- traceforge/validate/ipc2221.py +350 -0
- traceforge/validate/multilayer.py +805 -0
- traceforge/validate/netmodel.py +261 -0
- traceforge/validate/partcheck.py +472 -0
- traceforge/validate/report.py +280 -0
- traceforge/validate/review.py +322 -0
- traceforge/validate/runner.py +662 -0
- traceforge/workspace.py +171 -0
- traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
- traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
- traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
- traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
- traceforge_pcb-1.0.0.dist-info/licenses/LICENSE +21 -0
traceforge/parts/web.py
ADDED
|
@@ -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))
|