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,100 @@
1
+ """API keys and token metering for the hosted server."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import secrets
7
+ import sqlite3
8
+ import time
9
+ import uuid
10
+ from pathlib import Path
11
+
12
+ from traceforge.config import data_home
13
+
14
+
15
+ def _hash(key: str) -> str:
16
+ return hashlib.sha256(key.encode()).hexdigest()
17
+
18
+
19
+ def _month() -> str:
20
+ return time.strftime("%Y-%m", time.gmtime())
21
+
22
+
23
+ class KeyStore:
24
+ def __init__(self, path: Path | None = None):
25
+ self.path = path or data_home() / "server.db"
26
+ self.path.parent.mkdir(parents=True, exist_ok=True)
27
+ with self._db() as db:
28
+ db.execute(
29
+ "CREATE TABLE IF NOT EXISTS keys (id TEXT PRIMARY KEY, name TEXT, hash TEXT UNIQUE,"
30
+ " created REAL, revoked INTEGER DEFAULT 0, monthly_limit INTEGER)"
31
+ )
32
+ db.execute(
33
+ "CREATE TABLE IF NOT EXISTS usage (key_id TEXT, month TEXT, input INTEGER, output INTEGER,"
34
+ " requests INTEGER, PRIMARY KEY (key_id, month))"
35
+ )
36
+
37
+ def _db(self) -> sqlite3.Connection:
38
+ return sqlite3.connect(self.path, timeout=10)
39
+
40
+ def create(self, name: str, monthly_token_limit: int | None = None) -> tuple[str, dict]:
41
+ key = "tf_" + secrets.token_urlsafe(32)
42
+ key_id = uuid.uuid4().hex[:10]
43
+ with self._db() as db:
44
+ db.execute(
45
+ "INSERT INTO keys (id, name, hash, created, revoked, monthly_limit)"
46
+ " VALUES (?,?,?,?,0,?)",
47
+ (key_id, name, _hash(key), time.time(), monthly_token_limit),
48
+ )
49
+ return key, {"id": key_id, "name": name}
50
+
51
+ def authenticate(self, key: str) -> dict | None:
52
+ if not key:
53
+ return None
54
+ with self._db() as db:
55
+ row = db.execute(
56
+ "SELECT id, name, revoked, monthly_limit FROM keys WHERE hash = ?", (_hash(key),)
57
+ ).fetchone()
58
+ if row is None or row[2]:
59
+ return None
60
+ return {"id": row[0], "name": row[1], "limit": row[3]}
61
+
62
+ def used(self, key_id: str) -> int:
63
+ with self._db() as db:
64
+ row = db.execute(
65
+ "SELECT input, output FROM usage WHERE key_id = ? AND month = ?", (key_id, _month())
66
+ ).fetchone()
67
+ return (row[0] + row[1]) if row else 0
68
+
69
+ def over_limit(self, key: dict) -> bool:
70
+ return bool(key.get("limit")) and self.used(key["id"]) >= int(key["limit"])
71
+
72
+ def record(self, key_id: str, input_tokens: int, output_tokens: int) -> None:
73
+ with self._db() as db:
74
+ db.execute(
75
+ "INSERT INTO usage VALUES (?,?,?,?,1) ON CONFLICT(key_id, month) DO UPDATE SET "
76
+ "input = input + excluded.input, output = output + excluded.output, requests = requests + 1",
77
+ (key_id, _month(), input_tokens, output_tokens),
78
+ )
79
+
80
+ def list(self) -> list[dict]:
81
+ with self._db() as db:
82
+ rows = db.execute(
83
+ "SELECT id, name, created, revoked, monthly_limit FROM keys ORDER BY created"
84
+ ).fetchall()
85
+ return [
86
+ {
87
+ "id": r[0],
88
+ "name": r[1],
89
+ "created": time.strftime("%Y-%m-%d", time.localtime(r[2])),
90
+ "revoked": bool(r[3]),
91
+ "limit": r[4],
92
+ "used": self.used(r[0]),
93
+ }
94
+ for r in rows
95
+ ]
96
+
97
+ def revoke(self, key_id: str) -> bool:
98
+ with self._db() as db:
99
+ cursor = db.execute("UPDATE keys SET revoked = 1 WHERE id = ?", (key_id,))
100
+ return cursor.rowcount > 0
@@ -0,0 +1,187 @@
1
+ """Snapshots of the project folder around an agent turn, for Accept / Reject review and /undo.
2
+
3
+ Shared by the desktop app and the terminal front ends.
4
+
5
+ Before a turn that may change files, :func:`take` copies the project into
6
+ ``.traceforge/snapshots/<id>``. After the turn, :meth:`Snapshot.changes` lists what differs.
7
+ :meth:`Snapshot.restore` puts files back byte for byte, and refuses to overwrite a file that
8
+ was edited by someone else after the turn ended (the user, in the editor), so a Reject can
9
+ never destroy work the agent did not make.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import difflib
15
+ import hashlib
16
+ import os
17
+ import shutil
18
+ import uuid
19
+ from dataclasses import dataclass, field
20
+ from pathlib import Path
21
+
22
+ SKIP_DIRS = {".git", ".traceforge", "node_modules", "__pycache__", ".venv", "venv", ".mypy_cache"}
23
+ MAX_FILE = 64 * 1024 * 1024
24
+ MAX_TOTAL = 1024 * 1024 * 1024
25
+ SNAP_ROOT = Path(".traceforge") / "snapshots"
26
+
27
+
28
+ class SnapshotTooLarge(RuntimeError):
29
+ pass
30
+
31
+
32
+ def _walk(root: Path):
33
+ for folder, dirs, files in os.walk(root):
34
+ dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
35
+ for name in files:
36
+ path = Path(folder) / name
37
+ if path.is_symlink() or not path.is_file():
38
+ continue
39
+ yield path
40
+
41
+
42
+ def _digest(path: Path) -> str:
43
+ h = hashlib.sha256()
44
+ with path.open("rb") as handle:
45
+ for chunk in iter(lambda: handle.read(1 << 20), b""):
46
+ h.update(chunk)
47
+ return h.hexdigest()
48
+
49
+
50
+ def hash_tree(root: Path) -> dict[str, str]:
51
+ return {p.relative_to(root).as_posix(): _digest(p) for p in _walk(root)}
52
+
53
+
54
+ @dataclass
55
+ class Snapshot:
56
+ root: Path
57
+ id: str
58
+ hashes: dict[str, str]
59
+ after: dict[str, str] = field(default_factory=dict)
60
+ rows: list[dict] = field(default_factory=list)
61
+ label: str = ""
62
+
63
+ @property
64
+ def dir(self) -> Path:
65
+ return self.root / SNAP_ROOT / self.id
66
+
67
+ def saved(self, rel: str) -> Path:
68
+ return self.dir / "files" / rel
69
+
70
+ def finish(self) -> list[dict]:
71
+ """Files that differ from the snapshot; records the end-of-turn state for conflict checks."""
72
+ now = hash_tree(self.root)
73
+ self.after = now
74
+ rows = []
75
+ for rel in sorted(set(now) | set(self.hashes)):
76
+ before, current = self.hashes.get(rel), now.get(rel)
77
+ if before == current:
78
+ continue
79
+ status = "added" if before is None else "deleted" if current is None else "modified"
80
+ rows.append({"path": rel, "status": status, "kind": file_kind(rel)})
81
+ self.rows = rows
82
+ return rows
83
+
84
+ def before_text(self, rel: str) -> str | None:
85
+ return _read_text(self.saved(rel)) if rel in self.hashes else None
86
+
87
+ def conflicts(self, paths: list[str] | None = None) -> list[str]:
88
+ """Changed files that someone edited after the turn ended."""
89
+ wanted = {row["path"] for row in self.rows}
90
+ if paths is not None:
91
+ wanted &= set(paths)
92
+ out = []
93
+ for rel in sorted(wanted):
94
+ target = self.root / rel
95
+ if (_digest(target) if target.is_file() else None) != self.after.get(rel):
96
+ out.append(rel)
97
+ return out
98
+
99
+ def restore(self, paths: list[str] | None = None, *, force: bool = False) -> dict:
100
+ """Put changed files back. Returns {restored, conflicts}; conflicting files are left
101
+ unless ``force`` says to overwrite them."""
102
+ wanted = {row["path"] for row in self.rows}
103
+ if paths is not None:
104
+ wanted &= set(paths)
105
+ restored, conflicts = [], []
106
+ for rel in sorted(wanted):
107
+ target = self.root / rel
108
+ current = _digest(target) if target.is_file() else None
109
+ if current != self.after.get(rel) and not force:
110
+ conflicts.append(rel) # edited after the turn: not the agent's work to undo
111
+ continue
112
+ if rel in self.hashes:
113
+ target.parent.mkdir(parents=True, exist_ok=True)
114
+ shutil.copy2(self.saved(rel), target)
115
+ else:
116
+ target.unlink(missing_ok=True)
117
+ _prune_empty(target.parent, self.root)
118
+ restored.append(rel)
119
+ return {"restored": restored, "conflicts": conflicts}
120
+
121
+ def discard(self) -> None:
122
+ shutil.rmtree(self.dir, ignore_errors=True)
123
+
124
+
125
+ def _prune_empty(folder: Path, root: Path) -> None:
126
+ while folder != root and folder.is_dir() and not any(folder.iterdir()):
127
+ folder.rmdir()
128
+ folder = folder.parent
129
+
130
+
131
+ def take(root: Path) -> Snapshot:
132
+ root = Path(root).resolve()
133
+ snap = Snapshot(root, uuid.uuid4().hex[:10], {})
134
+ total = 0
135
+ for path in _walk(root):
136
+ size = path.stat().st_size
137
+ total += size
138
+ if size > MAX_FILE or total > MAX_TOTAL:
139
+ snap.discard()
140
+ raise SnapshotTooLarge("the project is too large to snapshot for review")
141
+ rel = path.relative_to(root).as_posix()
142
+ dest = snap.saved(rel)
143
+ dest.parent.mkdir(parents=True, exist_ok=True)
144
+ shutil.copy2(path, dest)
145
+ snap.hashes[rel] = _digest(dest)
146
+ snap.dir.mkdir(parents=True, exist_ok=True)
147
+ return snap
148
+
149
+
150
+ def file_kind(rel: str) -> str:
151
+ suffix = Path(rel).suffix.lower()
152
+ if suffix == ".kicad_pcb":
153
+ return "pcb"
154
+ if suffix == ".kicad_sch":
155
+ return "sch"
156
+ return (
157
+ "text"
158
+ if suffix not in {".png", ".jpg", ".jpeg", ".gif", ".pdf", ".zip", ".bin"}
159
+ else "binary"
160
+ )
161
+
162
+
163
+ def _read_text(path: Path) -> str | None:
164
+ try:
165
+ data = path.read_bytes()
166
+ except OSError:
167
+ return None
168
+ if b"\0" in data[:8192]:
169
+ return None
170
+ return data.decode("utf-8", errors="replace")
171
+
172
+
173
+ def text_diff(before: str | None, after: str | None, name: str) -> str:
174
+ lines = difflib.unified_diff(
175
+ (before or "").splitlines(keepends=True),
176
+ (after or "").splitlines(keepends=True),
177
+ f"a/{name}" if before is not None else "/dev/null",
178
+ f"b/{name}" if after is not None else "/dev/null",
179
+ n=3,
180
+ )
181
+ out = "".join(lines)
182
+ return out if len(out) < 400_000 else out[:400_000] + "\n... diff truncated ...\n"
183
+
184
+
185
+ def read_current_text(root: Path, rel: str) -> str | None:
186
+ path = root / rel
187
+ return _read_text(path) if path.is_file() else None
traceforge/routing.py ADDED
@@ -0,0 +1,99 @@
1
+ """Model routing: pick a model and effort per kind of work instead of one for everything.
2
+
3
+ Each model call has a *role*. A role maps to a tier (``fast`` / ``balanced`` /
4
+ ``best``, see :mod:`traceforge.models`) and an effort level:
5
+
6
+ ========= ========== ====== =============================================
7
+ role tier effort used for
8
+ ========= ========== ====== =============================================
9
+ main balanced medium the agent working on a task (``run``, chat)
10
+ ask balanced low read-only questions
11
+ plan best high writing a plan
12
+ review balanced medium validation reviewers
13
+ explore fast low read-only subagents (searching, reading files)
14
+ general balanced medium subagents that change files
15
+ compact fast low summarising old history to save context
16
+ escalate best high a step that keeps failing (see below)
17
+ ========= ========== ====== =============================================
18
+
19
+ Escalation: when the main agent's tool calls fail several times in a row, the rest
20
+ of that turn runs on the ``escalate`` role; the next turn starts on ``main`` again.
21
+
22
+ A model set explicitly (``--model``, ``model:`` in config, ``TRACEFORGE_MODEL``)
23
+ pins the main, ask, plan, review and general roles to that model; helper roles
24
+ (explore, compact) still use the fast tier of the same provider. An explicit effort
25
+ pins the effort the same way. ``routing: false`` in config (or
26
+ ``TRACEFORGE_ROUTING=0``) turns routing off: every call uses the configured model
27
+ and effort. ``routes:`` overrides single roles, e.g. ``routes: {main: best}`` or
28
+ ``routes: {explore: gpt-5.4-mini}``.
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ from dataclasses import dataclass
34
+ from typing import TYPE_CHECKING
35
+
36
+ from traceforge import models
37
+
38
+ if TYPE_CHECKING:
39
+ from traceforge.config import Settings
40
+
41
+ ROLES: dict[str, tuple[str, str]] = {
42
+ "main": ("balanced", "medium"),
43
+ "ask": ("balanced", "low"),
44
+ "plan": ("best", "high"),
45
+ "review": ("balanced", "medium"),
46
+ "explore": ("fast", "low"),
47
+ "general": ("balanced", "medium"),
48
+ "compact": ("fast", "low"),
49
+ "escalate": ("best", "high"),
50
+ }
51
+ # Roles that do the user's actual task; an explicit model or effort pins these.
52
+ PINNABLE = {"main", "ask", "plan", "review", "general"}
53
+ # Consecutive failed tool calls in one turn before switching to the escalate role.
54
+ ESCALATE_AFTER = 3
55
+
56
+ _MODE_ROLES = {
57
+ "agent": "main",
58
+ "ask": "ask",
59
+ "plan": "plan",
60
+ "review": "review",
61
+ "subagent-explore": "explore",
62
+ "subagent-general": "general",
63
+ }
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class Route:
68
+ role: str
69
+ model: str
70
+ effort: str
71
+
72
+
73
+ def role_for_mode(mode: str) -> str:
74
+ return _MODE_ROLES.get(mode, "main")
75
+
76
+
77
+ def route(settings: Settings, role: str) -> Route:
78
+ """The model and effort for one kind of call."""
79
+ if not settings.routing or role not in ROLES:
80
+ return Route(role, settings.model, settings.effort)
81
+ tier, effort = ROLES[role]
82
+ from traceforge.providers import provider_for
83
+
84
+ provider = provider_for(settings.model, settings.provider)
85
+ if provider == "local": # one local model serves every role
86
+ return Route(role, settings.model, settings.effort)
87
+ override = (settings.routes or {}).get(role)
88
+ if override:
89
+ model = models.resolve(str(override), provider) or settings.model
90
+ elif settings.model_explicit and role in PINNABLE:
91
+ model = settings.model
92
+ else:
93
+ model = models.resolve(tier, provider) or settings.model
94
+ # Never route a pinned model *up* a tier for a helper role.
95
+ if settings.model_explicit and models.tier_of(settings.model) == "fast":
96
+ model = settings.model
97
+ if settings.effort_explicit and role in PINNABLE:
98
+ effort = settings.effort
99
+ return Route(role, model, effort)