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.
@@ -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]