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 @@
1
+ """trace2rules: mine coding-agent trajectories into AGENTS.md rules."""
trace2rules/cli.py ADDED
@@ -0,0 +1,543 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import os
5
+ from dataclasses import asdict
6
+ from datetime import datetime, timezone
7
+ from pathlib import Path
8
+ from typing import Annotated
9
+
10
+ import duckdb
11
+ import typer
12
+ from dotenv import load_dotenv
13
+ from rich.console import Console
14
+ from rich.markup import escape
15
+ from rich.table import Table
16
+
17
+ from .cluster import exact_sequences, mine as mine_friction
18
+ from .db import DB_PATH, connect
19
+ from .ingest import DEFAULT_REPOS, SOURCE, ingest as ingest_traces
20
+ from .labels import label_targets
21
+ from .patterns import mine_sequences
22
+ from .synthesize import EXACT_LENGTHS, synthesize as synthesize_rules
23
+
24
+ load_dotenv(Path.cwd() / ".env")
25
+
26
+ app = typer.Typer(add_completion=False, no_args_is_help=True, help="Mine coding-agent trajectories for AGENTS.md rules.")
27
+ console = Console()
28
+
29
+
30
+ def _ingest_command(
31
+ repos: Annotated[
32
+ list[str] | None,
33
+ typer.Option("--repos", "-r", help="instance_id prefixes for swe-rebench."),
34
+ ] = None,
35
+ format: Annotated[
36
+ str,
37
+ typer.Option(
38
+ "--format",
39
+ "-f",
40
+ help="agent-trajectory (default), swe-rebench, or swe-chat.",
41
+ ),
42
+ ] = "agent-trajectory",
43
+ limit: Annotated[int, typer.Option(help="Max sessions (per source where applicable).")] = 200,
44
+ repo: Annotated[
45
+ str | None,
46
+ typer.Option("--repo", help="Override repo label for local/SWE-chat sessions."),
47
+ ] = None,
48
+ db: Annotated[Path, typer.Option(help="DuckDB database path.")] = DB_PATH,
49
+ label: Annotated[
50
+ bool,
51
+ typer.Option(
52
+ "--label",
53
+ help="After ingest, label targets if a decision backend is available.",
54
+ ),
55
+ ] = False,
56
+ source: Annotated[
57
+ list[str] | None,
58
+ typer.Option(
59
+ "--source",
60
+ "-s",
61
+ help="Parquet path, dataset directory, or local session root; repeat for multiple.",
62
+ ),
63
+ ] = None,
64
+ ) -> None:
65
+ fmt = format.strip().lower()
66
+ sources = source or []
67
+ if repos and fmt != "swe-rebench":
68
+ raise typer.BadParameter("--repos is only valid with --format swe-rebench.")
69
+ if fmt == "swe-rebench":
70
+ prefixes = repos or DEFAULT_REPOS
71
+ selected_sources = sources or [SOURCE]
72
+ stats = []
73
+ try:
74
+ for selected_source in selected_sources:
75
+ if selected_source.startswith(("hf://", "http://", "https://")):
76
+ console.print("[dim]Scanning remote parquet; first run downloads metadata/data...[/dim]")
77
+ stats.extend(
78
+ ingest_traces(
79
+ prefixes, limit=limit, db_path=db, source=selected_source
80
+ )
81
+ )
82
+ except (duckdb.Error, OSError, RuntimeError) as error:
83
+ console.print(f"[red]{escape(str(error))}[/red]")
84
+ raise typer.Exit(1) from None
85
+ elif fmt == "swe-chat":
86
+ from .sources.swe_chat import ingest_swe_chat
87
+
88
+ selected_sources = sources or ["data/swe-chat"]
89
+ try:
90
+ stats = [
91
+ ingest_swe_chat(
92
+ selected_source,
93
+ db,
94
+ limit=limit or None,
95
+ repo=repo,
96
+ )
97
+ for selected_source in selected_sources
98
+ ]
99
+ except (FileNotFoundError, ValueError, RuntimeError) as error:
100
+ console.print(f"[red]{escape(str(error))}[/red]")
101
+ raise typer.Exit(1) from None
102
+ elif fmt in {"agent-trajectory", "agent"}:
103
+ from .sources.agent_trajectory import ingest_agent_sessions
104
+
105
+ selected_sources = sources or [str(Path.home())]
106
+ stats = []
107
+ try:
108
+ for selected_source in selected_sources:
109
+ stats.extend(
110
+ ingest_agent_sessions(
111
+ selected_source,
112
+ db,
113
+ limit=limit or None,
114
+ repo=repo,
115
+ )
116
+ )
117
+ except (FileNotFoundError, ValueError, RuntimeError) as error:
118
+ console.print(f"[red]{escape(str(error))}[/red]")
119
+ raise typer.Exit(1) from None
120
+ else:
121
+ raise typer.BadParameter(
122
+ "Unknown format. Use swe-rebench, swe-chat, or agent-trajectory."
123
+ )
124
+
125
+ if repos and fmt != "swe-rebench":
126
+ raise typer.BadParameter("--repos is only valid with --format swe-rebench.")
127
+
128
+ table = Table(title="Ingest summary", header_style="bold")
129
+ table.add_column("Requested source")
130
+ table.add_column("Matched", justify="right")
131
+ table.add_column("Sessions", justify="right")
132
+ table.add_column("Tool events", justify="right")
133
+ for stat in stats:
134
+ table.add_row(stat.prefix, str(stat.matched), str(stat.sessions), f"{stat.events:,}")
135
+ console.print(table)
136
+ for stat in stats:
137
+ if stat.matched == 0:
138
+ console.print(f"[yellow]No sessions found for {stat.prefix!r}.[/yellow]")
139
+ if label:
140
+ from .labels import detect_model
141
+
142
+ model = detect_model()
143
+ if model is None:
144
+ console.print(
145
+ "[yellow]No decision backend detected; skipping labeling.[/yellow]"
146
+ )
147
+ else:
148
+ try:
149
+ done, failed = label_targets(db, model=model)
150
+ console.print(
151
+ f"Labeled [bold]{done}[/bold] targets with [bold]{escape(model)}[/bold]"
152
+ f" ({failed} failed)."
153
+ )
154
+ except RuntimeError as error:
155
+ console.print(f"[yellow]Labeling skipped: {escape(str(error))}[/yellow]")
156
+ console.print(f"Database: [bold]{db}[/bold]")
157
+
158
+
159
+ app.command("ingest")(_ingest_command)
160
+
161
+
162
+ def _print_summary(summary: list[dict]) -> None:
163
+ table = Table(title="Corpus", header_style="bold")
164
+ table.add_column("Repo")
165
+ table.add_column("Sessions", justify="right")
166
+ table.add_column("Resolved", justify="right")
167
+ table.add_column("Tool events", justify="right")
168
+ table.add_column("Tokens", justify="right")
169
+ for row in summary:
170
+ known = row["known_resolution"]
171
+ resolved = row["resolved"]
172
+ if known:
173
+ rate = resolved / known
174
+ resolved_text = f"{resolved} ({rate:.0%})"
175
+ else:
176
+ resolved_text = "n/a"
177
+ table.add_row(
178
+ escape(row["repo"]),
179
+ str(row["sessions"]),
180
+ resolved_text,
181
+ f"{row['events']:,}",
182
+ f"{row['tokens']:,}",
183
+ )
184
+ console.print(table)
185
+
186
+
187
+ def _print_detector_tables(mined: dict, limit: int = 10) -> None:
188
+ hotspots = mined["hotspots"][:limit]
189
+ if hotspots:
190
+ table = Table(title="Rediscovery hotspots (read-only)", header_style="bold", expand=True)
191
+ table.add_column("Repo")
192
+ table.add_column("Target")
193
+ table.add_column("Sessions", justify="right")
194
+ table.add_column("Wasted tokens", justify="right")
195
+ table.add_column("Coverage")
196
+ for finding in hotspots:
197
+ table.add_row(
198
+ escape(finding.repo),
199
+ escape(finding.title),
200
+ str(finding.sessions),
201
+ f"{finding.tokens:,}",
202
+ escape(finding.detail),
203
+ )
204
+ console.print(table)
205
+
206
+ recovery = mined["recovery"][:limit]
207
+ if recovery:
208
+ table = Table(title="Command fail -> recovery loops", header_style="bold", expand=True)
209
+ table.add_column("Repo")
210
+ table.add_column("Failed command")
211
+ table.add_column("Recovery command")
212
+ table.add_column("Sessions", justify="right")
213
+ table.add_column("Wasted tokens", justify="right")
214
+ for finding in recovery:
215
+ failed, _, recovered = finding.title.partition(" -> ")
216
+ table.add_row(
217
+ escape(finding.repo),
218
+ escape(failed),
219
+ escape(recovered),
220
+ str(finding.sessions),
221
+ f"{finding.tokens:,}",
222
+ )
223
+ console.print(table)
224
+
225
+ blasts = mined["context"][:limit]
226
+ if blasts:
227
+ table = Table(title="Context-blasting calls", header_style="bold", expand=True)
228
+ table.add_column("Repo")
229
+ table.add_column("Target")
230
+ table.add_column("Sessions", justify="right")
231
+ table.add_column("Total tokens", justify="right")
232
+ table.add_column("Profile")
233
+ for finding in blasts:
234
+ table.add_row(
235
+ escape(finding.repo),
236
+ escape(finding.title),
237
+ str(finding.sessions),
238
+ f"{finding.tokens:,}",
239
+ escape(finding.detail),
240
+ )
241
+ console.print(table)
242
+
243
+
244
+ def _print_clusters(mined: dict, top: int) -> None:
245
+ clusters = mined["clusters"][:top]
246
+ if not clusters:
247
+ console.print("[yellow]No multi-session friction clusters found.[/yellow]")
248
+ return
249
+ table = Table(
250
+ title=f"Top {len(clusters)} friction clusters",
251
+ header_style="bold",
252
+ expand=True,
253
+ show_lines=True,
254
+ )
255
+ table.add_column("#", width=3)
256
+ table.add_column("Repo", width=22)
257
+ table.add_column("Sessions", justify="right", width=8)
258
+ table.add_column("Wasted tokens", justify="right", width=13)
259
+ table.add_column("Medoid sequence")
260
+ table.add_column("Raw variants", width=40)
261
+ for rank, finding in enumerate(clusters, start=1):
262
+ table.add_row(
263
+ str(rank),
264
+ escape(finding.repo),
265
+ str(finding.sessions),
266
+ f"{finding.tokens:,}",
267
+ escape(finding.sequence),
268
+ escape("\n".join(finding.variants[:3])),
269
+ )
270
+ console.print(table)
271
+
272
+
273
+ def _mine_command(
274
+ top: Annotated[int, typer.Option(help="Clusters / rows per detector to show.")] = 25,
275
+ db: Annotated[Path, typer.Option(help="DuckDB database path.")] = DB_PATH,
276
+ ) -> None:
277
+ con = connect(db)
278
+ try:
279
+ session_count = con.execute("SELECT count(*) FROM sessions").fetchone()[0]
280
+ if session_count == 0:
281
+ console.print("[red]No sessions in the database. Run `trace2rules ingest` first.[/red]")
282
+ raise typer.Exit(1)
283
+ from .detectors import session_summary
284
+
285
+ _print_summary(session_summary(con))
286
+ mined = mine_friction(con, top=top)
287
+ _print_detector_tables(mined)
288
+ _print_clusters(mined, top)
289
+ console.print(
290
+ f"[dim]{len(mined['hotspots'])} hotspots, {len(mined['recovery'])} recovery loops, "
291
+ f"{len(mined['context'])} context blasts, {len(mined['clusters'])} clusters[/dim]"
292
+ )
293
+ finally:
294
+ con.close()
295
+
296
+
297
+ app.command("mine")(_mine_command)
298
+
299
+
300
+ def _report_command(
301
+ top: Annotated[int, typer.Option(help="Rows per detector / pattern cap.")] = 25,
302
+ repo: Annotated[
303
+ str | None,
304
+ typer.Option("--repo", help="Limit findings to one repository label."),
305
+ ] = None,
306
+ db: Annotated[Path, typer.Option(help="DuckDB database path.")] = DB_PATH,
307
+ ) -> None:
308
+ con = connect(db)
309
+ try:
310
+ session_count, instance_count = con.execute(
311
+ "SELECT count(*), count(DISTINCT instance_id) FROM sessions"
312
+ ).fetchone()
313
+ if session_count == 0:
314
+ console.print("[red]No sessions in the database. Run `trace2rules ingest` first.[/red]")
315
+ raise typer.Exit(1)
316
+ label_count = con.execute("SELECT count(*) FROM target_labels").fetchone()[0]
317
+ repo_rows = con.execute(
318
+ "SELECT repo, count(*) FROM sessions GROUP BY repo ORDER BY repo"
319
+ ).fetchall()
320
+
321
+ mined = mine_friction(con, top=top)
322
+ findings = [
323
+ finding
324
+ for key in ("hotspots", "recovery", "context", "clusters")
325
+ for finding in mined[key]
326
+ ]
327
+ exact = []
328
+ for length in EXACT_LENGTHS:
329
+ exact.extend(
330
+ exact_sequences(
331
+ con,
332
+ length=length,
333
+ min_sessions=3,
334
+ top=500,
335
+ min_instances=2,
336
+ min_lift=1.5,
337
+ )
338
+ )
339
+ findings.extend(exact)
340
+ if repo:
341
+ findings = [finding for finding in findings if finding.repo == repo]
342
+ repo_rows = [row for row in repo_rows if row[0] == repo]
343
+ exact = [finding for finding in exact if finding.repo == repo]
344
+ patterns = [
345
+ pattern
346
+ for pattern in mine_sequences(con, top=top)
347
+ if not repo or repo in pattern.repos
348
+ ]
349
+ payload = {
350
+ "schema_version": 1,
351
+ "generated_at": datetime.now(timezone.utc).isoformat(),
352
+ "db": str(db),
353
+ "sessions": session_count,
354
+ "instances": instance_count,
355
+ "labels": label_count,
356
+ "repos": [{"repo": name, "sessions": count} for name, count in repo_rows],
357
+ "findings": [
358
+ {**asdict(finding), "evidence": finding.evidence}
359
+ for finding in findings
360
+ ],
361
+ "patterns": [asdict(pattern) for pattern in patterns],
362
+ }
363
+ typer.echo(json.dumps(payload, indent=2))
364
+ finally:
365
+ con.close()
366
+
367
+
368
+ app.command("report")(_report_command)
369
+
370
+
371
+ def _label_command(
372
+ limit: Annotated[int, typer.Option(help="Max pending targets; 0 = all.")] = 0,
373
+ rpm: Annotated[int, typer.Option(help="Requests per minute cap.")] = 270,
374
+ workers: Annotated[int, typer.Option(help="Concurrent requests.")] = 6,
375
+ model: Annotated[
376
+ str,
377
+ typer.Option(
378
+ "--model",
379
+ help="clef-flash, clef, jev, gemini-decision-1, or gpt-6-luna; auto-detected if omitted.",
380
+ ),
381
+ ] = "",
382
+ db: Annotated[Path, typer.Option(help="DuckDB database path.")] = DB_PATH,
383
+ ) -> None:
384
+ try:
385
+ done, failed = label_targets(
386
+ db,
387
+ limit=limit or None,
388
+ rpm=rpm,
389
+ workers=workers,
390
+ model=model or os.getenv("TRACE2RULES_DECISION_MODEL"),
391
+ )
392
+ except RuntimeError as error:
393
+ console.print(f"[red]{escape(str(error))}[/red]")
394
+ raise typer.Exit(1) from None
395
+ console.print(f"Labeled [bold]{done}[/bold], failed [bold]{failed}[/bold].")
396
+
397
+
398
+ app.command("label")(_label_command)
399
+
400
+
401
+ def _patterns_command(
402
+ top: Annotated[int, typer.Option(help="Patterns to show.")] = 25,
403
+ min_sessions: Annotated[int, typer.Option(help="Minimum session support.")] = 3,
404
+ max_len: Annotated[int, typer.Option(help="Maximum sequence length.")] = 4,
405
+ min_confidence: Annotated[float, typer.Option(help="Minimum label confidence.")] = 0.4,
406
+ db: Annotated[Path, typer.Option(help="DuckDB database path.")] = DB_PATH,
407
+ ) -> None:
408
+ con = connect(db)
409
+ try:
410
+ session_count = con.execute("SELECT count(*) FROM sessions").fetchone()[0]
411
+ if session_count == 0:
412
+ console.print("[red]No sessions in the database. Run `trace2rules ingest` first.[/red]")
413
+ raise typer.Exit(1)
414
+ patterns = mine_sequences(
415
+ con,
416
+ min_sessions=min_sessions,
417
+ max_len=max_len,
418
+ top=top,
419
+ min_confidence=min_confidence,
420
+ )
421
+ table = Table(title="Semantic friction sequences", header_style="bold", expand=True)
422
+ table.add_column("#", width=3)
423
+ table.add_column("Sessions", justify="right", width=8)
424
+ table.add_column("Tokens", justify="right", width=10)
425
+ table.add_column("Repos", width=24)
426
+ table.add_column("Pattern")
427
+ table.add_column("Example", width=45)
428
+ for rank, pattern in enumerate(patterns, start=1):
429
+ table.add_row(
430
+ str(rank),
431
+ str(pattern.sessions),
432
+ f"{pattern.tokens:,}",
433
+ escape(", ".join(pattern.repos)),
434
+ escape(pattern.sequence),
435
+ escape(pattern.example[:220]),
436
+ )
437
+ console.print(table)
438
+ console.print(f"[dim]{len(patterns)} patterns shown, min support {min_sessions}[/dim]")
439
+ finally:
440
+ con.close()
441
+
442
+
443
+ app.command("patterns")(_patterns_command)
444
+
445
+
446
+ def _exact_command(
447
+ length: Annotated[int, typer.Option(help="Exact sequence length.")] = 3,
448
+ min_sessions: Annotated[int, typer.Option(help="Minimum session support.")] = 3,
449
+ min_instances: Annotated[int, typer.Option(help="Minimum distinct task instances.")] = 3,
450
+ min_rework: Annotated[int, typer.Option(help="Minimum repeated-error count.")] = 0,
451
+ min_lift: Annotated[float, typer.Option(help="Minimum lift over token marginals.")] = 1.5,
452
+ retry_weight: Annotated[int, typer.Option(help="Token cost assigned per rework retry.")] = 1000,
453
+ top: Annotated[int, typer.Option(help="Sequences to show.")] = 25,
454
+ include_ok: Annotated[bool, typer.Option("--include-ok", help="Include windows without an error.")] = False,
455
+ db: Annotated[Path, typer.Option(help="DuckDB database path.")] = DB_PATH,
456
+ ) -> None:
457
+ con = connect(db)
458
+ try:
459
+ findings = exact_sequences(
460
+ con,
461
+ length=length,
462
+ min_sessions=min_sessions,
463
+ top=top,
464
+ require_error=not include_ok,
465
+ min_instances=min_instances,
466
+ min_rework=min_rework,
467
+ min_lift=min_lift,
468
+ retry_weight=retry_weight,
469
+ )
470
+ table = Table(title=f"Exact {length}-step sequences", header_style="bold", expand=True)
471
+ table.add_column("#", width=3)
472
+ table.add_column("Repo", width=22)
473
+ table.add_column("Sessions", justify="right", width=8)
474
+ table.add_column("Lift", justify="right", width=7)
475
+ table.add_column("Rework", justify="right", width=7)
476
+ table.add_column("Setup", justify="right", width=8)
477
+ table.add_column("Cost", justify="right", width=10)
478
+ table.add_column("Sequence")
479
+ table.add_column("Variants", width=42)
480
+ for rank, finding in enumerate(findings, start=1):
481
+ table.add_row(
482
+ str(rank),
483
+ finding.repo,
484
+ str(finding.sessions),
485
+ f"{finding.lift:.1f}",
486
+ str(finding.rework),
487
+ f"{finding.setup_tax:,}",
488
+ f"{finding.cost:,}",
489
+ finding.sequence,
490
+ "\n".join(finding.variants[:3]),
491
+ )
492
+ console.print(table)
493
+ console.print(f"[dim]{len(findings)} exact sequences[/dim]")
494
+ finally:
495
+ con.close()
496
+
497
+
498
+ app.command("exact")(_exact_command)
499
+
500
+
501
+ def _synthesize_command(
502
+ out: Annotated[Path | None, typer.Option("--out", "-o", help="Output path for a single --repo; use '-' for stdout.")] = None,
503
+ out_dir: Annotated[Path, typer.Option("--out-dir", help="Directory for per-repo AGENTS files.")] = Path("."),
504
+ repo: Annotated[str | None, typer.Option("--repo", help="Synthesize only this repo.")] = None,
505
+ top: Annotated[int, typer.Option(help="Findings to pass to synthesis.")] = 25,
506
+ offline: Annotated[bool, typer.Option("--offline", help="Skip the LLM and use deterministic rules.")] = False,
507
+ db: Annotated[Path, typer.Option(help="DuckDB database path.")] = DB_PATH,
508
+ ) -> None:
509
+ if out is not None and repo is None:
510
+ raise typer.BadParameter("--out requires --repo; use --out-dir for multiple repos.")
511
+ cmd_console = Console(stderr=True) if out is not None and str(out) == "-" else console
512
+ con = connect(db)
513
+ try:
514
+ session_count = con.execute("SELECT count(*) FROM sessions").fetchone()[0]
515
+ if session_count == 0:
516
+ cmd_console.print("[red]No sessions in the database. Run `trace2rules ingest` first.[/red]")
517
+ raise typer.Exit(1)
518
+ try:
519
+ results = synthesize_rules(
520
+ con,
521
+ out_path=out,
522
+ out_dir=out_dir,
523
+ repo=repo,
524
+ top=top,
525
+ offline=offline,
526
+ console=cmd_console,
527
+ )
528
+ except ValueError as error:
529
+ cmd_console.print(f"[red]{escape(str(error))}[/red]")
530
+ raise typer.Exit(1) from None
531
+ for path, synthesis in results:
532
+ cmd_console.print(
533
+ f"Wrote [bold]{path}[/bold] with {len(synthesis.rules)} rules for {synthesis.repo}."
534
+ )
535
+ finally:
536
+ con.close()
537
+
538
+
539
+ app.command("synthesize")(_synthesize_command)
540
+
541
+
542
+ if __name__ == "__main__":
543
+ app()