trace2rules 0.1.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.
- trace2rules/__init__.py +1 -0
- trace2rules/cli.py +543 -0
- trace2rules/cluster.py +348 -0
- trace2rules/db.py +84 -0
- trace2rules/detectors.py +183 -0
- trace2rules/ingest.py +717 -0
- trace2rules/labels.py +431 -0
- trace2rules/models.py +33 -0
- trace2rules/patterns.py +159 -0
- trace2rules/sources/__init__.py +1 -0
- trace2rules/sources/agent_trajectory.py +456 -0
- trace2rules/sources/common.py +99 -0
- trace2rules/sources/opencode.py +154 -0
- trace2rules/sources/swe_chat.py +117 -0
- trace2rules/synthesize.py +538 -0
- trace2rules-0.1.0.dist-info/METADATA +323 -0
- trace2rules-0.1.0.dist-info/RECORD +20 -0
- trace2rules-0.1.0.dist-info/WHEEL +4 -0
- trace2rules-0.1.0.dist-info/entry_points.txt +3 -0
- trace2rules-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,538 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import os
|
|
5
|
+
import re
|
|
6
|
+
import sys
|
|
7
|
+
from collections import defaultdict
|
|
8
|
+
from dataclasses import replace
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import Literal
|
|
11
|
+
|
|
12
|
+
from pydantic import BaseModel, Field
|
|
13
|
+
from rich.console import Console
|
|
14
|
+
from rich.markup import escape
|
|
15
|
+
from rich.table import Table
|
|
16
|
+
|
|
17
|
+
from .detectors import Finding
|
|
18
|
+
|
|
19
|
+
MAX_RULES = 5
|
|
20
|
+
MAX_LINES = 60
|
|
21
|
+
MAX_CHARS = 2500
|
|
22
|
+
OUT_PATH = Path("AGENTS.proposed.md")
|
|
23
|
+
EXACT_LENGTHS = (3, 4, 5)
|
|
24
|
+
|
|
25
|
+
GENERATED_VERIFIER_RE = re.compile(
|
|
26
|
+
r"final_|validation_test|test_fix_verification|test_reproduce_issue|comprehensive_test"
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class Rule(BaseModel):
|
|
31
|
+
category: Literal["test_command", "architecture_map", "context_hygiene", "convention"]
|
|
32
|
+
rule_markdown: str
|
|
33
|
+
evidence_summary: str
|
|
34
|
+
estimated_tokens_saved_per_session: int = Field(ge=0)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class Synthesis(BaseModel):
|
|
38
|
+
repo: str
|
|
39
|
+
rules: list[Rule]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _generated_verifier(sequence: str) -> bool:
|
|
43
|
+
if GENERATED_VERIFIER_RE.search(sequence):
|
|
44
|
+
return True
|
|
45
|
+
for part in sequence.split(" | "):
|
|
46
|
+
for field in part.split(":"):
|
|
47
|
+
if field.endswith(".py") and "/" not in field and field.startswith("test_"):
|
|
48
|
+
return True
|
|
49
|
+
return False
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _usable_exact(finding: Finding) -> bool:
|
|
53
|
+
if finding.kind != "exact":
|
|
54
|
+
return True
|
|
55
|
+
if _generated_verifier(finding.sequence):
|
|
56
|
+
return False
|
|
57
|
+
high_coverage_setup = finding.sessions >= 10 and finding.setup_tax > 0
|
|
58
|
+
paired_rework = finding.paired_instances >= 2 and finding.delta_rework >= 1
|
|
59
|
+
return high_coverage_setup or paired_rework
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _sequence_tokens(finding: Finding) -> tuple[str, ...]:
|
|
63
|
+
return tuple(
|
|
64
|
+
part.split(":", 1)[1]
|
|
65
|
+
for part in re.split(r" \| (?=s\d+:)", finding.sequence)
|
|
66
|
+
if ":" in part
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _is_subsequence(inner: tuple[str, ...], outer: tuple[str, ...]) -> bool:
|
|
71
|
+
if not inner or len(inner) > len(outer):
|
|
72
|
+
return False
|
|
73
|
+
return any(outer[index : index + len(inner)] == inner for index in range(len(outer) - len(inner) + 1))
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def select_findings(
|
|
77
|
+
exact: list[Finding],
|
|
78
|
+
mined: dict[str, list[Finding]],
|
|
79
|
+
repo: str,
|
|
80
|
+
limit: int = 20,
|
|
81
|
+
) -> list[Finding]:
|
|
82
|
+
findings: list[Finding] = []
|
|
83
|
+
exact_repo = [finding for finding in exact if finding.repo == repo]
|
|
84
|
+
selected_tokens: list[tuple[str, ...]] = []
|
|
85
|
+
for finding in sorted(
|
|
86
|
+
(finding for finding in exact_repo if _usable_exact(finding)),
|
|
87
|
+
key=lambda finding: (len(_sequence_tokens(finding)), finding.cost),
|
|
88
|
+
reverse=True,
|
|
89
|
+
):
|
|
90
|
+
tokens = _sequence_tokens(finding)
|
|
91
|
+
if any(
|
|
92
|
+
_is_subsequence(tokens, seen) or _is_subsequence(seen, tokens)
|
|
93
|
+
for seen in selected_tokens
|
|
94
|
+
):
|
|
95
|
+
continue
|
|
96
|
+
selected_tokens.append(tokens)
|
|
97
|
+
findings.append(finding)
|
|
98
|
+
if len(findings) >= 10:
|
|
99
|
+
break
|
|
100
|
+
for key in ("recovery", "hotspots", "context", "clusters"):
|
|
101
|
+
findings.extend(
|
|
102
|
+
[finding for finding in mined[key] if finding.repo == repo][:2]
|
|
103
|
+
)
|
|
104
|
+
return findings[:limit]
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def annotate_findings(con, findings: list[Finding]) -> list[Finding]:
|
|
108
|
+
"""Attach labels by full event key, falling back to the finding title."""
|
|
109
|
+
targets = sorted(
|
|
110
|
+
{finding.title for finding in findings if finding.title}
|
|
111
|
+
| {
|
|
112
|
+
target
|
|
113
|
+
for finding in findings
|
|
114
|
+
for _tool, _action, target in finding.event_keys
|
|
115
|
+
}
|
|
116
|
+
)
|
|
117
|
+
if not targets:
|
|
118
|
+
return findings
|
|
119
|
+
placeholders = ",".join("?" for _ in targets)
|
|
120
|
+
rows = con.execute(
|
|
121
|
+
f"""
|
|
122
|
+
SELECT tool_name, action_type, target,
|
|
123
|
+
intent, object_type, intent_confidence, object_confidence
|
|
124
|
+
FROM target_labels
|
|
125
|
+
WHERE target IN ({placeholders})
|
|
126
|
+
""",
|
|
127
|
+
targets,
|
|
128
|
+
).fetchall()
|
|
129
|
+
|
|
130
|
+
grouped: dict[tuple[str, str, str], list[tuple[str, str, float, float]]] = defaultdict(list)
|
|
131
|
+
for tool_name, action_type, target, intent, object_type, intent_confidence, object_confidence in rows:
|
|
132
|
+
grouped[(tool_name, action_type, target)].append(
|
|
133
|
+
(intent, object_type, float(intent_confidence), float(object_confidence))
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
labels: dict[tuple[str, str, str], tuple[str, str, float, float]] = {}
|
|
137
|
+
for key, entries in grouped.items():
|
|
138
|
+
intents = {entry[0] for entry in entries}
|
|
139
|
+
objects = {entry[1] for entry in entries}
|
|
140
|
+
if len(intents) != 1 or len(objects) != 1:
|
|
141
|
+
continue
|
|
142
|
+
intent, object_type, intent_confidence, object_confidence = max(
|
|
143
|
+
entries, key=lambda entry: (entry[2] + entry[3], entry[3], entry[2])
|
|
144
|
+
)
|
|
145
|
+
if intent_confidence < 0.4 or object_confidence < 0.6:
|
|
146
|
+
continue
|
|
147
|
+
labels[key] = (intent, object_type, intent_confidence, object_confidence)
|
|
148
|
+
|
|
149
|
+
title_labels = {
|
|
150
|
+
key[2]: value for key, value in labels.items() if key[0] and key[1]
|
|
151
|
+
}
|
|
152
|
+
annotated = []
|
|
153
|
+
for finding in findings:
|
|
154
|
+
candidates = [
|
|
155
|
+
labels[key] for key in finding.event_keys if key in labels
|
|
156
|
+
]
|
|
157
|
+
label = (
|
|
158
|
+
max(candidates, key=lambda item: (item[2] + item[3], item[3], item[2]))
|
|
159
|
+
if candidates
|
|
160
|
+
else title_labels.get(finding.title)
|
|
161
|
+
)
|
|
162
|
+
if label is None:
|
|
163
|
+
annotated.append(finding)
|
|
164
|
+
continue
|
|
165
|
+
intent, object_type, intent_confidence, object_confidence = label
|
|
166
|
+
annotated.append(
|
|
167
|
+
replace(
|
|
168
|
+
finding,
|
|
169
|
+
intent=intent,
|
|
170
|
+
object_type=object_type,
|
|
171
|
+
intent_confidence=float(intent_confidence),
|
|
172
|
+
object_confidence=float(object_confidence),
|
|
173
|
+
)
|
|
174
|
+
)
|
|
175
|
+
return annotated
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def label_summary(con, repo: str, limit: int = 12) -> list[dict]:
|
|
179
|
+
rows = con.execute(
|
|
180
|
+
"""
|
|
181
|
+
SELECT l.intent, l.object_type,
|
|
182
|
+
count(*) AS calls,
|
|
183
|
+
count(DISTINCT e.session_id) AS sessions,
|
|
184
|
+
avg(l.intent_confidence) AS intent_confidence,
|
|
185
|
+
avg(l.object_confidence) AS object_confidence
|
|
186
|
+
FROM tool_events e
|
|
187
|
+
JOIN target_labels l
|
|
188
|
+
ON e.tool_name = l.tool_name
|
|
189
|
+
AND e.action_type = l.action_type
|
|
190
|
+
AND e.target = l.target
|
|
191
|
+
WHERE e.repo = ?
|
|
192
|
+
GROUP BY 1, 2
|
|
193
|
+
ORDER BY calls DESC
|
|
194
|
+
LIMIT ?
|
|
195
|
+
""",
|
|
196
|
+
[repo, limit],
|
|
197
|
+
).fetchall()
|
|
198
|
+
return [
|
|
199
|
+
{
|
|
200
|
+
"intent": intent,
|
|
201
|
+
"object_type": object_type,
|
|
202
|
+
"calls": calls,
|
|
203
|
+
"sessions": sessions,
|
|
204
|
+
"intent_confidence": round(float(intent_confidence or 0), 2),
|
|
205
|
+
"object_confidence": round(float(object_confidence or 0), 2),
|
|
206
|
+
}
|
|
207
|
+
for intent, object_type, calls, sessions, intent_confidence, object_confidence in rows
|
|
208
|
+
]
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def _truncate(text: str, width: int) -> str:
|
|
212
|
+
text = " ".join(text.split())
|
|
213
|
+
return text if len(text) <= width else text[: width - 1] + "…"
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
def print_findings(findings: list[Finding], console: Console | None = None) -> None:
|
|
217
|
+
console = console or Console()
|
|
218
|
+
table = Table(title="Ranked friction findings", header_style="bold", expand=True)
|
|
219
|
+
table.add_column("#", width=3)
|
|
220
|
+
table.add_column("Kind", width=9)
|
|
221
|
+
table.add_column("Repo", width=22)
|
|
222
|
+
table.add_column("Sessions", justify="right", width=8)
|
|
223
|
+
table.add_column("Cost", justify="right", width=10)
|
|
224
|
+
table.add_column("Finding")
|
|
225
|
+
for rank, finding in enumerate(findings, start=1):
|
|
226
|
+
table.add_row(
|
|
227
|
+
str(rank),
|
|
228
|
+
escape(finding.kind),
|
|
229
|
+
escape(finding.repo),
|
|
230
|
+
str(finding.sessions),
|
|
231
|
+
f"{finding.cost or finding.tokens:,}",
|
|
232
|
+
escape(_truncate(finding.title, 110)),
|
|
233
|
+
)
|
|
234
|
+
console.print(table)
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
def _client() -> tuple[object, str] | None:
|
|
238
|
+
key = os.getenv("TRACE2RULES_LLM_API_KEY") or os.getenv("TRACE2RULES_API_KEY")
|
|
239
|
+
base = os.getenv("TRACE2RULES_BASE_URL")
|
|
240
|
+
model = os.getenv("TRACE2RULES_MODEL")
|
|
241
|
+
if key:
|
|
242
|
+
return _make_client(key, base, model or "gemini-2.5-pro")
|
|
243
|
+
gemini_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
|
|
244
|
+
if gemini_key:
|
|
245
|
+
return _make_client(
|
|
246
|
+
gemini_key,
|
|
247
|
+
base or "https://generativelanguage.googleapis.com/v1beta/openai/",
|
|
248
|
+
model or "gemini-2.5-pro",
|
|
249
|
+
)
|
|
250
|
+
openai_key = os.getenv("OPENAI_API_KEY")
|
|
251
|
+
if openai_key:
|
|
252
|
+
return _make_client(openai_key, base, model or "gpt-5")
|
|
253
|
+
return None
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def _make_client(key: str, base: str | None, model: str):
|
|
257
|
+
from openai import OpenAI
|
|
258
|
+
|
|
259
|
+
client = OpenAI(api_key=key, base_url=base) if base else OpenAI(api_key=key)
|
|
260
|
+
return client, model
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def _prompt(findings: list[Finding], repo: str, labels: list[dict]) -> str:
|
|
264
|
+
payload = [
|
|
265
|
+
{
|
|
266
|
+
"kind": finding.kind,
|
|
267
|
+
"sessions": finding.sessions,
|
|
268
|
+
"cost": finding.cost or finding.tokens,
|
|
269
|
+
"setup_tax": finding.setup_tax,
|
|
270
|
+
"rework": finding.rework,
|
|
271
|
+
"paired_instances": finding.paired_instances,
|
|
272
|
+
"delta_rework": round(finding.delta_rework, 2),
|
|
273
|
+
"detail": finding.detail,
|
|
274
|
+
"sequence": finding.sequence,
|
|
275
|
+
"variants": list(finding.variants),
|
|
276
|
+
"intent": finding.intent,
|
|
277
|
+
"object_type": finding.object_type,
|
|
278
|
+
}
|
|
279
|
+
for finding in findings
|
|
280
|
+
]
|
|
281
|
+
return f"""Repo: {repo}
|
|
282
|
+
|
|
283
|
+
Findings from mined agent trajectories for this repo only (JSON):
|
|
284
|
+
{json.dumps(payload, indent=2)}
|
|
285
|
+
|
|
286
|
+
Semantic target labels observed for this repo (clef/decision-model annotations, JSON):
|
|
287
|
+
{json.dumps(labels, indent=2)}
|
|
288
|
+
|
|
289
|
+
Write AGENTS.md rules for this repository. Requirements:
|
|
290
|
+
- Emit 1-5 declarative rules, not task-specific issue descriptions.
|
|
291
|
+
- Categories: test_command, architecture_map, context_hygiene, convention.
|
|
292
|
+
- rule_markdown: 1-2 imperative sentences, concrete command or file names.
|
|
293
|
+
- evidence_summary: sessions affected and approximate setup/rework token cost.
|
|
294
|
+
- No generic platitudes ("be careful", "read the docs").
|
|
295
|
+
- Ignore task-specific verifier scripts, one-off filenames, and normal edit -> test-fail loops.
|
|
296
|
+
- For `recovery` findings, turn the failed -> successful transition into a convention rule.
|
|
297
|
+
- If any finding has `paired_instances >= 2` and `delta_rework >= 1`, include one `convention` rule: read the exception signature; if the same signature repeats after an edit, fix the product code or test scope instead of editing the harness.
|
|
298
|
+
- Total output must stay under 5 rules, 60 lines, and 2,500 characters.
|
|
299
|
+
|
|
300
|
+
Return JSON only, shaped exactly as:
|
|
301
|
+
{{"repo": "{repo}", "rules": [{{"category": "...", "rule_markdown": "...", "evidence_summary": "...", "estimated_tokens_saved_per_session": 0}}]}}"""
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
def _llm_synthesis(
|
|
305
|
+
findings: list[Finding], repo: str, labels: list[dict]
|
|
306
|
+
) -> Synthesis | None:
|
|
307
|
+
resolved = _client()
|
|
308
|
+
if resolved is None:
|
|
309
|
+
return None
|
|
310
|
+
client, model = resolved
|
|
311
|
+
response = client.chat.completions.create(
|
|
312
|
+
model=model,
|
|
313
|
+
temperature=0,
|
|
314
|
+
response_format={"type": "json_object"},
|
|
315
|
+
messages=[
|
|
316
|
+
{
|
|
317
|
+
"role": "system",
|
|
318
|
+
"content": "You convert observed coding-agent friction into terse, repo-level AGENTS.md rules.",
|
|
319
|
+
},
|
|
320
|
+
{"role": "user", "content": _prompt(findings, repo, labels)},
|
|
321
|
+
],
|
|
322
|
+
)
|
|
323
|
+
content = (response.choices[0].message.content or "").strip()
|
|
324
|
+
content = re.sub(r"^```(?:json)?\s*|\s*```$", "", content)
|
|
325
|
+
return Synthesis.model_validate(json.loads(content))
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
def _is_path_target(title: str) -> bool:
|
|
329
|
+
return bool(title) and " " not in title and ("/" in title or "." in title)
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
def _offline_synthesis(findings: list[Finding], repo: str) -> Synthesis:
|
|
333
|
+
rules: list[Rule] = []
|
|
334
|
+
seen: set[tuple[str, str]] = set()
|
|
335
|
+
|
|
336
|
+
def add(category: str, markdown: str, evidence: str, tokens: int) -> None:
|
|
337
|
+
key = (category, markdown)
|
|
338
|
+
if key in seen or len(rules) >= MAX_RULES:
|
|
339
|
+
return
|
|
340
|
+
seen.add(key)
|
|
341
|
+
rules.append(
|
|
342
|
+
Rule(
|
|
343
|
+
category=category,
|
|
344
|
+
rule_markdown=markdown,
|
|
345
|
+
evidence_summary=evidence,
|
|
346
|
+
estimated_tokens_saved_per_session=max(tokens, 0),
|
|
347
|
+
)
|
|
348
|
+
)
|
|
349
|
+
|
|
350
|
+
for finding in findings:
|
|
351
|
+
if finding.intent and finding.intent_confidence < 0.4:
|
|
352
|
+
continue
|
|
353
|
+
if finding.kind == "exact" and "pip:editable" in finding.sequence:
|
|
354
|
+
if finding.sessions < 10:
|
|
355
|
+
continue
|
|
356
|
+
add(
|
|
357
|
+
"test_command",
|
|
358
|
+
"Run `pip install -e .` before import, CLI, or pytest probes; treat pre-install failures as setup failures, not code failures.",
|
|
359
|
+
f"{finding.sessions} sessions; {finding.setup_tax:,} setup tokens.",
|
|
360
|
+
finding.setup_tax // max(finding.sessions, 1),
|
|
361
|
+
)
|
|
362
|
+
elif (
|
|
363
|
+
finding.kind == "exact"
|
|
364
|
+
and finding.paired_instances >= 2
|
|
365
|
+
and finding.delta_rework >= 1
|
|
366
|
+
):
|
|
367
|
+
add(
|
|
368
|
+
"convention",
|
|
369
|
+
"After a command fails, read the exception signature. If the same signature repeats after an edit, change the product code or test scope instead of editing the harness.",
|
|
370
|
+
f"Paired delta +{finding.delta_rework:.1f} rework in {finding.paired_instances} instances.",
|
|
371
|
+
int(finding.delta_rework * 1000),
|
|
372
|
+
)
|
|
373
|
+
elif finding.kind == "exact":
|
|
374
|
+
add(
|
|
375
|
+
"convention",
|
|
376
|
+
f"Treat `{_truncate(finding.sequence, 120)}` as a recurring friction sequence; inspect the failing step before repeating it.",
|
|
377
|
+
f"{finding.sessions} sessions; lift {finding.lift:.1f}; cost {finding.cost:,}.",
|
|
378
|
+
finding.cost // max(finding.sessions, 1),
|
|
379
|
+
)
|
|
380
|
+
elif finding.kind == "hotspot":
|
|
381
|
+
if finding.object_type == "unknown":
|
|
382
|
+
continue
|
|
383
|
+
if not _is_path_target(finding.title):
|
|
384
|
+
continue
|
|
385
|
+
basename = finding.title.rstrip("/").rsplit("/", 1)[-1]
|
|
386
|
+
if "." in basename:
|
|
387
|
+
markdown = f"Open `{_truncate(finding.title, 70)}` early; it is a read-only reference file."
|
|
388
|
+
else:
|
|
389
|
+
markdown = f"Map `{_truncate(finding.title, 70)}` before editing; it is a read-only reference path."
|
|
390
|
+
add(
|
|
391
|
+
"architecture_map",
|
|
392
|
+
markdown,
|
|
393
|
+
f"Read-only in {finding.sessions} sessions; {finding.tokens:,} tokens spent.",
|
|
394
|
+
finding.tokens // max(finding.sessions, 1),
|
|
395
|
+
)
|
|
396
|
+
elif finding.kind == "context":
|
|
397
|
+
if finding.intent == "other":
|
|
398
|
+
continue
|
|
399
|
+
if " " not in finding.title:
|
|
400
|
+
continue
|
|
401
|
+
avg = re.search(r"avg (\d+) tokens", finding.detail)
|
|
402
|
+
size = f"{int(avg.group(1)):,}" if avg else "large"
|
|
403
|
+
add(
|
|
404
|
+
"context_hygiene",
|
|
405
|
+
f"Bound `{_truncate(finding.title, 70)}`; scope it to one file or test and avoid unbounded output.",
|
|
406
|
+
f"Average {size} output tokens in {finding.sessions} sessions.",
|
|
407
|
+
finding.tokens // max(finding.sessions, 1),
|
|
408
|
+
)
|
|
409
|
+
elif finding.kind == "recovery":
|
|
410
|
+
# Recovery titles are task-specific command fragments; leave them to
|
|
411
|
+
# the LLM, which can generalize them into a convention rule.
|
|
412
|
+
continue
|
|
413
|
+
|
|
414
|
+
return Synthesis(repo=repo, rules=rules[:MAX_RULES])
|
|
415
|
+
|
|
416
|
+
|
|
417
|
+
def render(synthesis: Synthesis, repo: str, sessions: int) -> str:
|
|
418
|
+
lines = [
|
|
419
|
+
"# AGENTS.md",
|
|
420
|
+
"",
|
|
421
|
+
f"Generated by trace2rules from {sessions} sessions in {repo}.",
|
|
422
|
+
"",
|
|
423
|
+
]
|
|
424
|
+
for rule in synthesis.rules:
|
|
425
|
+
lines.append(f"## {rule.category}")
|
|
426
|
+
lines.append(f"- **Rule:** {rule.rule_markdown}")
|
|
427
|
+
lines.append(f" **Evidence:** {rule.evidence_summary}")
|
|
428
|
+
lines.append("")
|
|
429
|
+
return "\n".join(lines).rstrip() + "\n"
|
|
430
|
+
|
|
431
|
+
|
|
432
|
+
def enforce_caps(synthesis: Synthesis, repo: str, sessions: int) -> tuple[Synthesis, str]:
|
|
433
|
+
synthesis = Synthesis(repo=synthesis.repo, rules=synthesis.rules[:MAX_RULES])
|
|
434
|
+
while True:
|
|
435
|
+
text = render(synthesis, repo, sessions)
|
|
436
|
+
if len(text) <= MAX_CHARS and len(text.splitlines()) <= MAX_LINES:
|
|
437
|
+
return synthesis, text
|
|
438
|
+
if not synthesis.rules:
|
|
439
|
+
return synthesis, text[:MAX_CHARS]
|
|
440
|
+
synthesis = Synthesis(repo=synthesis.repo, rules=synthesis.rules[:-1])
|
|
441
|
+
|
|
442
|
+
|
|
443
|
+
def _slug(repo: str) -> str:
|
|
444
|
+
return repo.replace("/", "__")
|
|
445
|
+
|
|
446
|
+
|
|
447
|
+
def synthesize(
|
|
448
|
+
con,
|
|
449
|
+
out_path: str | Path | None = None,
|
|
450
|
+
out_dir: str | Path = ".",
|
|
451
|
+
repo: str | None = None,
|
|
452
|
+
top: int = 25,
|
|
453
|
+
offline: bool = False,
|
|
454
|
+
console: Console | None = None,
|
|
455
|
+
) -> list[tuple[Path, Synthesis]]:
|
|
456
|
+
from .cluster import exact_sequences, mine
|
|
457
|
+
|
|
458
|
+
console = console or Console()
|
|
459
|
+
repo_rows = _repos_with_sessions(con)
|
|
460
|
+
if repo:
|
|
461
|
+
repo_rows = [row for row in repo_rows if row["repo"] == repo]
|
|
462
|
+
if not repo_rows:
|
|
463
|
+
raise ValueError(f"repo not found in database: {repo}")
|
|
464
|
+
|
|
465
|
+
exact: list[Finding] = []
|
|
466
|
+
for length in EXACT_LENGTHS:
|
|
467
|
+
exact.extend(
|
|
468
|
+
exact_sequences(
|
|
469
|
+
con,
|
|
470
|
+
length=length,
|
|
471
|
+
min_sessions=3,
|
|
472
|
+
top=500,
|
|
473
|
+
min_instances=2,
|
|
474
|
+
min_lift=1.5,
|
|
475
|
+
)
|
|
476
|
+
)
|
|
477
|
+
mined = mine(con, top=None)
|
|
478
|
+
out_dir = Path(out_dir)
|
|
479
|
+
out_dir.mkdir(parents=True, exist_ok=True)
|
|
480
|
+
results: list[tuple[Path, Synthesis]] = []
|
|
481
|
+
|
|
482
|
+
for row in repo_rows:
|
|
483
|
+
repo_name = row["repo"]
|
|
484
|
+
findings = annotate_findings(
|
|
485
|
+
con, select_findings(exact, mined, repo_name)
|
|
486
|
+
)
|
|
487
|
+
labels = label_summary(con, repo_name)
|
|
488
|
+
print_findings(findings, console)
|
|
489
|
+
if not findings:
|
|
490
|
+
if repo and out_path is not None and str(out_path) != "-":
|
|
491
|
+
Path(out_path).unlink(missing_ok=True)
|
|
492
|
+
console.print(f"[yellow]No rules for {escape(repo_name)}; skipped.[/yellow]")
|
|
493
|
+
continue
|
|
494
|
+
|
|
495
|
+
synthesis: Synthesis | None = None
|
|
496
|
+
llm_failed = False
|
|
497
|
+
if not offline:
|
|
498
|
+
try:
|
|
499
|
+
synthesis = _llm_synthesis(findings, repo_name, labels)
|
|
500
|
+
except Exception as error: # noqa: BLE001 - degrade to deterministic output
|
|
501
|
+
llm_failed = True
|
|
502
|
+
console.print(f"[yellow]LLM synthesis unavailable: {escape(str(error))}[/yellow]")
|
|
503
|
+
if synthesis is None:
|
|
504
|
+
synthesis = _offline_synthesis(findings, repo_name)
|
|
505
|
+
if offline:
|
|
506
|
+
reason = "--offline"
|
|
507
|
+
elif llm_failed:
|
|
508
|
+
reason = "LLM call failed; using deterministic rules"
|
|
509
|
+
else:
|
|
510
|
+
reason = "no LLM credentials"
|
|
511
|
+
console.print(f"[yellow]Deterministic rules for {escape(repo_name)} ({reason}).[/yellow]")
|
|
512
|
+
|
|
513
|
+
synthesis, text = enforce_caps(synthesis, repo_name, row["sessions"])
|
|
514
|
+
if not synthesis.rules:
|
|
515
|
+
if repo and out_path is not None and str(out_path) != "-":
|
|
516
|
+
Path(out_path).unlink(missing_ok=True)
|
|
517
|
+
console.print(f"[yellow]No rules for {escape(repo_name)}; skipped.[/yellow]")
|
|
518
|
+
continue
|
|
519
|
+
if repo and out_path is not None:
|
|
520
|
+
if str(out_path) == "-":
|
|
521
|
+
sys.stdout.write(text)
|
|
522
|
+
if not text.endswith("\n"):
|
|
523
|
+
sys.stdout.write("\n")
|
|
524
|
+
results.append((Path("-"), synthesis))
|
|
525
|
+
continue
|
|
526
|
+
path = Path(out_path)
|
|
527
|
+
else:
|
|
528
|
+
path = out_dir / f"AGENTS.{_slug(repo_name)}.proposed.md"
|
|
529
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
530
|
+
path.write_text(text)
|
|
531
|
+
results.append((path, synthesis))
|
|
532
|
+
|
|
533
|
+
return results
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
def _repos_with_sessions(con) -> list[dict]:
|
|
537
|
+
rows = con.execute("SELECT repo, count(*) FROM sessions GROUP BY repo ORDER BY repo").fetchall()
|
|
538
|
+
return [{"repo": repo, "sessions": count} for repo, count in rows]
|