trace2rules 0.1.0__tar.gz

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,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rakha Kanz Kautsar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,323 @@
1
+ Metadata-Version: 2.4
2
+ Name: trace2rules
3
+ Version: 0.1.0
4
+ Summary: Mine coding-agent trajectories into evidence-backed AGENTS.md rules
5
+ Keywords: agents,coding-agents,agents.md,trajectories,duckdb
6
+ Author: Rakha Kanz Kautsar
7
+ Author-email: Rakha Kanz Kautsar <rkkautsar@gmail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Topic :: Software Development :: Quality Assurance
16
+ Requires-Dist: duckdb>=2.0.0
17
+ Requires-Dist: openai>=3.51.0
18
+ Requires-Dist: pydantic>=2.14.3
19
+ Requires-Dist: python-dotenv>=1.2.4
20
+ Requires-Dist: rich>=15.0.0
21
+ Requires-Dist: scikit-learn>=1.9.1
22
+ Requires-Dist: typer>=0.29.1
23
+ Requires-Dist: agent-trajectory>=0.4.4
24
+ Requires-Python: >=3.12
25
+ Project-URL: Homepage, https://github.com/rkkautsar/trace2rules
26
+ Project-URL: Repository, https://github.com/rkkautsar/trace2rules
27
+ Project-URL: Issues, https://github.com/rkkautsar/trace2rules/issues
28
+ Description-Content-Type: text/markdown
29
+
30
+ # trace2rules
31
+
32
+ Mine coding-agent sessions into evidence-backed `AGENTS.md` rules.
33
+
34
+ `trace2rules` is a local-first CLI. It ingests agent trajectories, detects recurring friction (setup failures, repeated exceptions, oversized output, rediscovery hotspots), and proposes a small number of repository-specific rules with the evidence attached.
35
+
36
+ Status: beta. The output is a proposal, not an automatically applied `AGENTS.md`.
37
+
38
+ ## Example finding
39
+
40
+ On the demo corpus, [PDM](https://github.com/pdm-project/pdm), a Python package manager, showed its most expensive repeated friction as a setup loop: `import pdm` failed until `pip install -e .` was run. It appeared in 56 sessions and accounted for ~82,966 setup tokens.
41
+
42
+ `synthesize` turns that into:
43
+
44
+ ```bash
45
+ trace2rules ingest --format swe-rebench --repos pdm-project__pdm --limit 200
46
+ trace2rules synthesize --repo pdm-project/pdm --out -
47
+ ```
48
+
49
+ The default path is LLM-backed. Add `--offline` to force deterministic rules.
50
+
51
+ Example output (abridged; model output varies):
52
+
53
+ ```markdown
54
+ # AGENTS.md
55
+
56
+ Generated by trace2rules from 200 sessions in pdm-project/pdm.
57
+
58
+ ## convention
59
+ - **Rule:** Run `pip install -e .` once at the start of a session before importing `pdm` or invoking the `pdm` CLI. Skipping editable installation causes `ImportError` and `which pdm` failures that trigger repeated setup retries.
60
+ **Evidence:** 56 sessions with ImportError recovery (82,966 tokens) and 28+14+12 exact setup sequences (~73,149 setup_tax tokens).
61
+
62
+ ## test_command
63
+ - **Rule:** Run scoped tests directly with `python -m pytest tests/ -x -q -k "<expr>"` instead of running `python -m pytest --version` and separate `python -c "import pdm"` probes first.
64
+ **Evidence:** 12 exact test-setup sessions (26,806 total tokens, 14,565 setup_tax tokens) and 199 sessions running run_tests.
65
+
66
+ ## convention
67
+ - **Rule:** Read the exact exception signature on any `exit:1` or `ImportError` failure; if the same signature repeats after an edit, fix the product code or test scope instead of editing or re-running the harness.
68
+ **Evidence:** 3 sessions with paired_instances=2 and delta_rework=+2.13 (26,079 tokens), plus 68 exit:1 recovery sessions (117,440 tokens).
69
+
70
+ ## context_hygiene
71
+ - **Rule:** Truncate verbose `execute_bash` output with `-q` or `| head`/`| tail`, and skip redundant `view /workspace` and `pwd` checks before reading `README.md` or `tests/`.
72
+ **Evidence:** 181 sessions averaging 1,804 tokens per bash call (373,521 tokens) and 143 workspace-exploration cluster sessions (782,785 tokens).
73
+ ```
74
+
75
+ Rules are capped at 5 rules, 60 lines, and 2,500 characters per repo.
76
+
77
+ ## Synthesis
78
+
79
+ Synthesis is LLM-first. `trace2rules synthesize` sends the gated findings for each repo to an OpenAI-compatible chat model and asks for structured rules.
80
+
81
+ Provider selection:
82
+
83
+ 1. `TRACE2RULES_LLM_API_KEY` — API key for a custom OpenAI-compatible endpoint.
84
+ 2. `GEMINI_API_KEY` or `GOOGLE_API_KEY` — Gemini OpenAI-compatible endpoint.
85
+ 3. `OPENAI_API_KEY` — OpenAI.
86
+
87
+ If no key is configured, or the call fails, synthesis falls back to deterministic rules and continues. `--offline` forces the deterministic path without a network call.
88
+
89
+ `TRACE2RULES_BASE_URL` makes any OpenAI-compatible endpoint usable, including a LiteLLM proxy.
90
+
91
+ ## Supported inputs
92
+
93
+ | Format | What it reads | Notes |
94
+ |---|---|---|
95
+ | `swe-rebench` | `nebius/SWE-rebench-openhands-trajectories` parquet | Opt-in; streamed from Hugging Face |
96
+ | `agent-trajectory` | Local Claude Code, Codex, Pi, OMP, OpenCode SQLite/JSON | Default; Node.js 20+ required for non-OpenCode sources |
97
+
98
+ SWE-chat is not a primary input. It is used below as an optional example corpus.
99
+
100
+ Datasets are not included in this repository.
101
+
102
+ ## Install
103
+
104
+ Use the published package:
105
+
106
+ ```bash
107
+ uv tool install trace2rules
108
+ # or
109
+ pip install trace2rules
110
+ ```
111
+
112
+ For development from a clone:
113
+
114
+ ```bash
115
+ uv sync
116
+ ```
117
+
118
+ `agent-trajectory` calls its bundled JS bridge through the system Node runtime for Claude Code, Codex, Pi, and OMP. Install Node.js 20 or newer; OpenCode SQLite ingestion is pure Python.
119
+
120
+ ## Quick start: your own sessions
121
+
122
+ Analyze the sessions already on your machine. This example uses OMP; point `--source` at Claude Code, Codex, or Pi instead if that is what you use.
123
+
124
+ ```bash
125
+ uv tool install trace2rules
126
+ trace2rules ingest --source ~ --limit 50
127
+ trace2rules mine
128
+ trace2rules synthesize
129
+ ```
130
+
131
+ `--source` is repeatable. `--source ~` scans all standard local stores: `~/.claude/projects`, `~/.codex/sessions`, `~/.pi/agent/sessions`, and `~/.omp/agent/sessions`. The example imports 50 sessions per source; use `--limit 0` for all.
132
+
133
+ LLM synthesis is the default. Add `--offline` if you do not have an API key.
134
+
135
+ `ingest` writes to `data/trace2rules.duckdb` by default. `mine`, `exact`, and `synthesize` read from it.
136
+
137
+ ## Public dataset: SWE-rebench
138
+
139
+ To reproduce the PDM example above without local sessions, ingest the default **SWE-rebench OpenHands parquet** from Hugging Face. `django__django` is an `instance_id` prefix, not a GitHub slug.
140
+
141
+ ```bash
142
+ uv run trace2rules ingest --format swe-rebench --repos django__django --limit 50
143
+ uv run trace2rules mine
144
+ uv run trace2rules synthesize
145
+ ```
146
+
147
+ ## Optional example corpus: SWE-chat
148
+
149
+ SWE-chat is an optional example corpus, not a core input format. It is useful for reproducing the PDM finding above.
150
+
151
+ Request access on the [dataset page](https://huggingface.co/datasets/SALT-NLP/SWE-chat), then download the two tables:
152
+
153
+ ```bash
154
+ uvx --from huggingface_hub hf download SALT-NLP/SWE-chat \
155
+ --repo-type dataset \
156
+ --include "sessions.parquet" \
157
+ --include "conversations.parquet" \
158
+ --local-dir data/swe-chat
159
+
160
+ uv run trace2rules ingest \
161
+ --format swe-chat \
162
+ --source data/swe-chat \
163
+ --limit 0
164
+
165
+ uv run trace2rules mine
166
+ uv run trace2rules synthesize
167
+ ```
168
+
169
+ `--limit 0` imports the full corpus. The default limit is 200 sessions. For `swe-rebench`, `--limit 0` also means all matching sessions.
170
+
171
+ ## Local agent sessions
172
+
173
+ ```bash
174
+ uv run trace2rules ingest \
175
+ --format agent-trajectory \
176
+ --source ~ \
177
+ --limit 0
178
+ ```
179
+
180
+ With `--source ~`, it scans the standard stores:
181
+
182
+ - `~/.claude/projects`
183
+ - `~/.codex/sessions`
184
+ - `~/.pi/agent/sessions`
185
+ - `~/.omp/agent/sessions`
186
+ - `~/.local/share/opencode`
187
+
188
+ OpenCode is read directly from its SQLite database; JSON exports are still accepted:
189
+
190
+ ```bash
191
+ uv run trace2rules ingest --format agent-trajectory --source ~/.local/share/opencode
192
+ ```
193
+
194
+ Use `--repo owner/name` to override the repository label for local sessions.
195
+
196
+ ## Commands
197
+
198
+ | Command | Purpose |
199
+ |---|---|
200
+ | `ingest` | Load sessions and tool events into DuckDB |
201
+ | `mine` | Show friction clusters, hotspots, recovery loops, and context blasts |
202
+ | `report` | Emit all findings and patterns as evidence-rich JSON for an agent |
203
+ | `label` | Optional: classify targets with a decision model (`intent`, `object_type`, confidence) |
204
+ | `patterns` | Mine structural multi-step friction; labels refine when available |
205
+ | `exact` | Show exact recurring sequences with evidence |
206
+ | `synthesize` | Write per-repo `.proposed.md` files |
207
+
208
+ Useful options:
209
+
210
+ ```bash
211
+ trace2rules ingest # ~, all detected local stores
212
+ trace2rules ingest --label # auto-detect clef/Gemini/OpenAI
213
+ trace2rules ingest --format swe-rebench # opt into the public dataset
214
+ trace2rules ingest --source PATH --limit 200
215
+ trace2rules synthesize
216
+ trace2rules synthesize --offline
217
+ trace2rules synthesize --repo owner/name --out AGENTS.proposed.md
218
+ trace2rules synthesize --repo owner/name --out -
219
+ trace2rules synthesize --out-dir ./proposals
220
+ ```
221
+
222
+ `--label` auto-detects an authenticated `wrangler` first, then `GEMINI_API_KEY`/`GOOGLE_API_KEY`, then `OPENAI_API_KEY`. It is opt-in because a full local run can have thousands of unique targets.
223
+
224
+ ## Agentic workflow
225
+
226
+ The built-in synthesizer is optional. An agent can consume the evidence directly:
227
+
228
+ ```bash
229
+ trace2rules ingest
230
+ trace2rules report > /tmp/trace2rules-report.json
231
+ ```
232
+
233
+ `report` emits JSON with repo/session/instance counts, findings, labels, exact sequences, and label-driven patterns. Each finding carries `sessions`, `tokens`, `evidence`, and detector-specific fields such as `lift`, `rework`, `setup_tax`, `cost`, and `paired_instances`.
234
+
235
+ The calling agent can then write `AGENTS.md` rules from that evidence without invoking `trace2rules synthesize` or configuring an LLM key.
236
+
237
+ `--out -` writes the markdown to stdout and sends progress/findings to stderr.
238
+
239
+ Synthesis is LLM-first. `--offline` skips the LLM and uses deterministic rules.
240
+
241
+ ### Decision labels
242
+
243
+ `trace2rules label` classifies each distinct normalized target with a decision model:
244
+ - `intent`: explore, read, search, edit, run_tests, run_script, install, env_check, git, other
245
+ - `object_type`: file, directory, test_scope, package, module, config, unknown
246
+
247
+ It stores the chosen labels and confidence in `target_labels`. `synthesize` annotates matching findings, sends the label summary to the LLM prompt, and drops low-confidence or `other` labels from deterministic rules. `patterns` mines structural object-level sequences without labels and uses labels only to name events when confidence is high.
248
+
249
+ Supported models:
250
+
251
+ | `--model` | Provider | Credential |
252
+ |---|---|---|
253
+ | `clef-flash` (default) | Cloudflare Workers AI | `wrangler login` |
254
+ | `clef` | Cloudflare Workers AI | `wrangler login` |
255
+ | `jev` | Cloudflare Workers AI (`typesafe/jev`) | `wrangler login` |
256
+ | `gemini-decision-1` | Gemini Decisions API | `GEMINI_API_KEY` / `GOOGLE_API_KEY` |
257
+ | `gpt-6-luna` (alias `luna`) | OpenAI Decisions API | `OPENAI_API_KEY` |
258
+
259
+ `TRACE2RULES_DECISION_MODEL` sets the default; `--model` overrides it.
260
+
261
+ ```bash
262
+ # default: clef-flash
263
+ trace2rules label
264
+ trace2rules label --model jev
265
+ trace2rules label --model gemini-decision-1
266
+ trace2rules label --model gpt-6-luna
267
+ trace2rules patterns --min-confidence 0.4
268
+ ```
269
+
270
+ Cloudflare models authenticate through `wrangler auth token --json` and `wrangler whoami --json`; the first account is used. Gemini and OpenAI use their standard keys. Labeling defaults to 270 requests/minute with 6 workers and retries 429/5xx responses.
271
+
272
+ `label` sends the tool name, action type, normalized target, and a raw command example to the selected provider. Do not run it on private sessions without review.
273
+
274
+ ## Configuration
275
+
276
+ | Variable | Purpose |
277
+ |---|---|
278
+ | `GEMINI_API_KEY` | Gemini synthesis provider |
279
+ | `GOOGLE_API_KEY` | Alternate Gemini key |
280
+ | `OPENAI_API_KEY` | OpenAI synthesis provider |
281
+ | `TRACE2RULES_LLM_API_KEY` | API key for a custom OpenAI-compatible endpoint |
282
+ | `TRACE2RULES_BASE_URL` | OpenAI-compatible base URL (including LiteLLM) |
283
+ | `TRACE2RULES_MODEL` | Synthesis model, e.g. `gemini-4-hydrogen` |
284
+ | `TRACE2RULES_DECISION_MODEL` | Labeling backend: `clef-flash` (default), `clef`, `jev`, `gemini-decision-1`, `gpt-6-luna` |
285
+ | `HF_TOKEN` | Used by `hf download` for gated datasets; not read by trace2rules |
286
+
287
+ `TRACE2RULES_BASE_URL` also works with an OpenAI-compatible LiteLLM proxy.
288
+
289
+ ## How it works
290
+
291
+ 1. **Ingest** normalizes tool calls into DuckDB (`sessions`, `tool_events`).
292
+ 2. **Detectors** find high-coverage setup failures, repeated exception signatures, read-only hotspots, and large output calls.
293
+ 3. **Exact n-gram mining** groups recurring 3–5-step tool sequences with lift and paired-rework evidence. Windows never cross a compaction boundary; nested sequences are deduplicated before selection.
294
+ 4. **Decision labels** (optional) classify normalized targets with clef/Jev/Gemini Decisions/Luna; `synthesize` uses them for category and filtering, and `patterns` uses them for intent-aware sequence mining.
295
+ 5. **Synthesis** is LLM-first. It selects gated findings and asks the configured model for structured rules; `--offline` forces deterministic rules.
296
+
297
+ Generated verifier scripts and low-support task-specific sequences are filtered before synthesis.
298
+
299
+ ## Data and privacy
300
+
301
+ - Session data stays in your local DuckDB database.
302
+ - `--offline` performs no LLM calls.
303
+ - LLM synthesis sends mined findings, not the full raw session database. Findings can still contain commands, paths, and repository names; review before using an external provider.
304
+ - `label` sends a normalized target plus a raw example to Cloudflare Workers AI; do not use it on sensitive private sessions without review.
305
+ - `data/` and generated `AGENTS.*.proposed.md` files are gitignored.
306
+
307
+ ## Known limits
308
+
309
+ - Detectors are heuristics. Review every proposed rule.
310
+ - Local-session formats change frequently. `agent-trajectory` is the compatibility layer; pin its version.
311
+ - Decision-model labels are probabilistic; inspect low-confidence labels before relying on them.
312
+
313
+ ## Development
314
+
315
+ ```bash
316
+ uv sync
317
+ uv run pytest
318
+ uv build
319
+ ```
320
+
321
+ ## License
322
+
323
+ MIT. See `LICENSE`.
@@ -0,0 +1,294 @@
1
+ # trace2rules
2
+
3
+ Mine coding-agent sessions into evidence-backed `AGENTS.md` rules.
4
+
5
+ `trace2rules` is a local-first CLI. It ingests agent trajectories, detects recurring friction (setup failures, repeated exceptions, oversized output, rediscovery hotspots), and proposes a small number of repository-specific rules with the evidence attached.
6
+
7
+ Status: beta. The output is a proposal, not an automatically applied `AGENTS.md`.
8
+
9
+ ## Example finding
10
+
11
+ On the demo corpus, [PDM](https://github.com/pdm-project/pdm), a Python package manager, showed its most expensive repeated friction as a setup loop: `import pdm` failed until `pip install -e .` was run. It appeared in 56 sessions and accounted for ~82,966 setup tokens.
12
+
13
+ `synthesize` turns that into:
14
+
15
+ ```bash
16
+ trace2rules ingest --format swe-rebench --repos pdm-project__pdm --limit 200
17
+ trace2rules synthesize --repo pdm-project/pdm --out -
18
+ ```
19
+
20
+ The default path is LLM-backed. Add `--offline` to force deterministic rules.
21
+
22
+ Example output (abridged; model output varies):
23
+
24
+ ```markdown
25
+ # AGENTS.md
26
+
27
+ Generated by trace2rules from 200 sessions in pdm-project/pdm.
28
+
29
+ ## convention
30
+ - **Rule:** Run `pip install -e .` once at the start of a session before importing `pdm` or invoking the `pdm` CLI. Skipping editable installation causes `ImportError` and `which pdm` failures that trigger repeated setup retries.
31
+ **Evidence:** 56 sessions with ImportError recovery (82,966 tokens) and 28+14+12 exact setup sequences (~73,149 setup_tax tokens).
32
+
33
+ ## test_command
34
+ - **Rule:** Run scoped tests directly with `python -m pytest tests/ -x -q -k "<expr>"` instead of running `python -m pytest --version` and separate `python -c "import pdm"` probes first.
35
+ **Evidence:** 12 exact test-setup sessions (26,806 total tokens, 14,565 setup_tax tokens) and 199 sessions running run_tests.
36
+
37
+ ## convention
38
+ - **Rule:** Read the exact exception signature on any `exit:1` or `ImportError` failure; if the same signature repeats after an edit, fix the product code or test scope instead of editing or re-running the harness.
39
+ **Evidence:** 3 sessions with paired_instances=2 and delta_rework=+2.13 (26,079 tokens), plus 68 exit:1 recovery sessions (117,440 tokens).
40
+
41
+ ## context_hygiene
42
+ - **Rule:** Truncate verbose `execute_bash` output with `-q` or `| head`/`| tail`, and skip redundant `view /workspace` and `pwd` checks before reading `README.md` or `tests/`.
43
+ **Evidence:** 181 sessions averaging 1,804 tokens per bash call (373,521 tokens) and 143 workspace-exploration cluster sessions (782,785 tokens).
44
+ ```
45
+
46
+ Rules are capped at 5 rules, 60 lines, and 2,500 characters per repo.
47
+
48
+ ## Synthesis
49
+
50
+ Synthesis is LLM-first. `trace2rules synthesize` sends the gated findings for each repo to an OpenAI-compatible chat model and asks for structured rules.
51
+
52
+ Provider selection:
53
+
54
+ 1. `TRACE2RULES_LLM_API_KEY` — API key for a custom OpenAI-compatible endpoint.
55
+ 2. `GEMINI_API_KEY` or `GOOGLE_API_KEY` — Gemini OpenAI-compatible endpoint.
56
+ 3. `OPENAI_API_KEY` — OpenAI.
57
+
58
+ If no key is configured, or the call fails, synthesis falls back to deterministic rules and continues. `--offline` forces the deterministic path without a network call.
59
+
60
+ `TRACE2RULES_BASE_URL` makes any OpenAI-compatible endpoint usable, including a LiteLLM proxy.
61
+
62
+ ## Supported inputs
63
+
64
+ | Format | What it reads | Notes |
65
+ |---|---|---|
66
+ | `swe-rebench` | `nebius/SWE-rebench-openhands-trajectories` parquet | Opt-in; streamed from Hugging Face |
67
+ | `agent-trajectory` | Local Claude Code, Codex, Pi, OMP, OpenCode SQLite/JSON | Default; Node.js 20+ required for non-OpenCode sources |
68
+
69
+ SWE-chat is not a primary input. It is used below as an optional example corpus.
70
+
71
+ Datasets are not included in this repository.
72
+
73
+ ## Install
74
+
75
+ Use the published package:
76
+
77
+ ```bash
78
+ uv tool install trace2rules
79
+ # or
80
+ pip install trace2rules
81
+ ```
82
+
83
+ For development from a clone:
84
+
85
+ ```bash
86
+ uv sync
87
+ ```
88
+
89
+ `agent-trajectory` calls its bundled JS bridge through the system Node runtime for Claude Code, Codex, Pi, and OMP. Install Node.js 20 or newer; OpenCode SQLite ingestion is pure Python.
90
+
91
+ ## Quick start: your own sessions
92
+
93
+ Analyze the sessions already on your machine. This example uses OMP; point `--source` at Claude Code, Codex, or Pi instead if that is what you use.
94
+
95
+ ```bash
96
+ uv tool install trace2rules
97
+ trace2rules ingest --source ~ --limit 50
98
+ trace2rules mine
99
+ trace2rules synthesize
100
+ ```
101
+
102
+ `--source` is repeatable. `--source ~` scans all standard local stores: `~/.claude/projects`, `~/.codex/sessions`, `~/.pi/agent/sessions`, and `~/.omp/agent/sessions`. The example imports 50 sessions per source; use `--limit 0` for all.
103
+
104
+ LLM synthesis is the default. Add `--offline` if you do not have an API key.
105
+
106
+ `ingest` writes to `data/trace2rules.duckdb` by default. `mine`, `exact`, and `synthesize` read from it.
107
+
108
+ ## Public dataset: SWE-rebench
109
+
110
+ To reproduce the PDM example above without local sessions, ingest the default **SWE-rebench OpenHands parquet** from Hugging Face. `django__django` is an `instance_id` prefix, not a GitHub slug.
111
+
112
+ ```bash
113
+ uv run trace2rules ingest --format swe-rebench --repos django__django --limit 50
114
+ uv run trace2rules mine
115
+ uv run trace2rules synthesize
116
+ ```
117
+
118
+ ## Optional example corpus: SWE-chat
119
+
120
+ SWE-chat is an optional example corpus, not a core input format. It is useful for reproducing the PDM finding above.
121
+
122
+ Request access on the [dataset page](https://huggingface.co/datasets/SALT-NLP/SWE-chat), then download the two tables:
123
+
124
+ ```bash
125
+ uvx --from huggingface_hub hf download SALT-NLP/SWE-chat \
126
+ --repo-type dataset \
127
+ --include "sessions.parquet" \
128
+ --include "conversations.parquet" \
129
+ --local-dir data/swe-chat
130
+
131
+ uv run trace2rules ingest \
132
+ --format swe-chat \
133
+ --source data/swe-chat \
134
+ --limit 0
135
+
136
+ uv run trace2rules mine
137
+ uv run trace2rules synthesize
138
+ ```
139
+
140
+ `--limit 0` imports the full corpus. The default limit is 200 sessions. For `swe-rebench`, `--limit 0` also means all matching sessions.
141
+
142
+ ## Local agent sessions
143
+
144
+ ```bash
145
+ uv run trace2rules ingest \
146
+ --format agent-trajectory \
147
+ --source ~ \
148
+ --limit 0
149
+ ```
150
+
151
+ With `--source ~`, it scans the standard stores:
152
+
153
+ - `~/.claude/projects`
154
+ - `~/.codex/sessions`
155
+ - `~/.pi/agent/sessions`
156
+ - `~/.omp/agent/sessions`
157
+ - `~/.local/share/opencode`
158
+
159
+ OpenCode is read directly from its SQLite database; JSON exports are still accepted:
160
+
161
+ ```bash
162
+ uv run trace2rules ingest --format agent-trajectory --source ~/.local/share/opencode
163
+ ```
164
+
165
+ Use `--repo owner/name` to override the repository label for local sessions.
166
+
167
+ ## Commands
168
+
169
+ | Command | Purpose |
170
+ |---|---|
171
+ | `ingest` | Load sessions and tool events into DuckDB |
172
+ | `mine` | Show friction clusters, hotspots, recovery loops, and context blasts |
173
+ | `report` | Emit all findings and patterns as evidence-rich JSON for an agent |
174
+ | `label` | Optional: classify targets with a decision model (`intent`, `object_type`, confidence) |
175
+ | `patterns` | Mine structural multi-step friction; labels refine when available |
176
+ | `exact` | Show exact recurring sequences with evidence |
177
+ | `synthesize` | Write per-repo `.proposed.md` files |
178
+
179
+ Useful options:
180
+
181
+ ```bash
182
+ trace2rules ingest # ~, all detected local stores
183
+ trace2rules ingest --label # auto-detect clef/Gemini/OpenAI
184
+ trace2rules ingest --format swe-rebench # opt into the public dataset
185
+ trace2rules ingest --source PATH --limit 200
186
+ trace2rules synthesize
187
+ trace2rules synthesize --offline
188
+ trace2rules synthesize --repo owner/name --out AGENTS.proposed.md
189
+ trace2rules synthesize --repo owner/name --out -
190
+ trace2rules synthesize --out-dir ./proposals
191
+ ```
192
+
193
+ `--label` auto-detects an authenticated `wrangler` first, then `GEMINI_API_KEY`/`GOOGLE_API_KEY`, then `OPENAI_API_KEY`. It is opt-in because a full local run can have thousands of unique targets.
194
+
195
+ ## Agentic workflow
196
+
197
+ The built-in synthesizer is optional. An agent can consume the evidence directly:
198
+
199
+ ```bash
200
+ trace2rules ingest
201
+ trace2rules report > /tmp/trace2rules-report.json
202
+ ```
203
+
204
+ `report` emits JSON with repo/session/instance counts, findings, labels, exact sequences, and label-driven patterns. Each finding carries `sessions`, `tokens`, `evidence`, and detector-specific fields such as `lift`, `rework`, `setup_tax`, `cost`, and `paired_instances`.
205
+
206
+ The calling agent can then write `AGENTS.md` rules from that evidence without invoking `trace2rules synthesize` or configuring an LLM key.
207
+
208
+ `--out -` writes the markdown to stdout and sends progress/findings to stderr.
209
+
210
+ Synthesis is LLM-first. `--offline` skips the LLM and uses deterministic rules.
211
+
212
+ ### Decision labels
213
+
214
+ `trace2rules label` classifies each distinct normalized target with a decision model:
215
+ - `intent`: explore, read, search, edit, run_tests, run_script, install, env_check, git, other
216
+ - `object_type`: file, directory, test_scope, package, module, config, unknown
217
+
218
+ It stores the chosen labels and confidence in `target_labels`. `synthesize` annotates matching findings, sends the label summary to the LLM prompt, and drops low-confidence or `other` labels from deterministic rules. `patterns` mines structural object-level sequences without labels and uses labels only to name events when confidence is high.
219
+
220
+ Supported models:
221
+
222
+ | `--model` | Provider | Credential |
223
+ |---|---|---|
224
+ | `clef-flash` (default) | Cloudflare Workers AI | `wrangler login` |
225
+ | `clef` | Cloudflare Workers AI | `wrangler login` |
226
+ | `jev` | Cloudflare Workers AI (`typesafe/jev`) | `wrangler login` |
227
+ | `gemini-decision-1` | Gemini Decisions API | `GEMINI_API_KEY` / `GOOGLE_API_KEY` |
228
+ | `gpt-6-luna` (alias `luna`) | OpenAI Decisions API | `OPENAI_API_KEY` |
229
+
230
+ `TRACE2RULES_DECISION_MODEL` sets the default; `--model` overrides it.
231
+
232
+ ```bash
233
+ # default: clef-flash
234
+ trace2rules label
235
+ trace2rules label --model jev
236
+ trace2rules label --model gemini-decision-1
237
+ trace2rules label --model gpt-6-luna
238
+ trace2rules patterns --min-confidence 0.4
239
+ ```
240
+
241
+ Cloudflare models authenticate through `wrangler auth token --json` and `wrangler whoami --json`; the first account is used. Gemini and OpenAI use their standard keys. Labeling defaults to 270 requests/minute with 6 workers and retries 429/5xx responses.
242
+
243
+ `label` sends the tool name, action type, normalized target, and a raw command example to the selected provider. Do not run it on private sessions without review.
244
+
245
+ ## Configuration
246
+
247
+ | Variable | Purpose |
248
+ |---|---|
249
+ | `GEMINI_API_KEY` | Gemini synthesis provider |
250
+ | `GOOGLE_API_KEY` | Alternate Gemini key |
251
+ | `OPENAI_API_KEY` | OpenAI synthesis provider |
252
+ | `TRACE2RULES_LLM_API_KEY` | API key for a custom OpenAI-compatible endpoint |
253
+ | `TRACE2RULES_BASE_URL` | OpenAI-compatible base URL (including LiteLLM) |
254
+ | `TRACE2RULES_MODEL` | Synthesis model, e.g. `gemini-4-hydrogen` |
255
+ | `TRACE2RULES_DECISION_MODEL` | Labeling backend: `clef-flash` (default), `clef`, `jev`, `gemini-decision-1`, `gpt-6-luna` |
256
+ | `HF_TOKEN` | Used by `hf download` for gated datasets; not read by trace2rules |
257
+
258
+ `TRACE2RULES_BASE_URL` also works with an OpenAI-compatible LiteLLM proxy.
259
+
260
+ ## How it works
261
+
262
+ 1. **Ingest** normalizes tool calls into DuckDB (`sessions`, `tool_events`).
263
+ 2. **Detectors** find high-coverage setup failures, repeated exception signatures, read-only hotspots, and large output calls.
264
+ 3. **Exact n-gram mining** groups recurring 3–5-step tool sequences with lift and paired-rework evidence. Windows never cross a compaction boundary; nested sequences are deduplicated before selection.
265
+ 4. **Decision labels** (optional) classify normalized targets with clef/Jev/Gemini Decisions/Luna; `synthesize` uses them for category and filtering, and `patterns` uses them for intent-aware sequence mining.
266
+ 5. **Synthesis** is LLM-first. It selects gated findings and asks the configured model for structured rules; `--offline` forces deterministic rules.
267
+
268
+ Generated verifier scripts and low-support task-specific sequences are filtered before synthesis.
269
+
270
+ ## Data and privacy
271
+
272
+ - Session data stays in your local DuckDB database.
273
+ - `--offline` performs no LLM calls.
274
+ - LLM synthesis sends mined findings, not the full raw session database. Findings can still contain commands, paths, and repository names; review before using an external provider.
275
+ - `label` sends a normalized target plus a raw example to Cloudflare Workers AI; do not use it on sensitive private sessions without review.
276
+ - `data/` and generated `AGENTS.*.proposed.md` files are gitignored.
277
+
278
+ ## Known limits
279
+
280
+ - Detectors are heuristics. Review every proposed rule.
281
+ - Local-session formats change frequently. `agent-trajectory` is the compatibility layer; pin its version.
282
+ - Decision-model labels are probabilistic; inspect low-confidence labels before relying on them.
283
+
284
+ ## Development
285
+
286
+ ```bash
287
+ uv sync
288
+ uv run pytest
289
+ uv build
290
+ ```
291
+
292
+ ## License
293
+
294
+ MIT. See `LICENSE`.
@@ -0,0 +1,55 @@
1
+ [project]
2
+ name = "trace2rules"
3
+ version = "0.1.0"
4
+ description = "Mine coding-agent trajectories into evidence-backed AGENTS.md rules"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.12"
9
+ keywords = [
10
+ "agents",
11
+ "coding-agents",
12
+ "agents.md",
13
+ "trajectories",
14
+ "duckdb",
15
+ ]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ "Topic :: Software Development :: Quality Assurance",
23
+ ]
24
+ dependencies = [
25
+ "duckdb>=2.0.0",
26
+ "openai>=3.51.0",
27
+ "pydantic>=2.14.3",
28
+ "python-dotenv>=1.2.4",
29
+ "rich>=15.0.0",
30
+ "scikit-learn>=1.9.1",
31
+ "typer>=0.29.1",
32
+ "agent-trajectory>=0.4.4",
33
+ ]
34
+
35
+ [[project.authors]]
36
+ name = "Rakha Kanz Kautsar"
37
+ email = "rkkautsar@gmail.com"
38
+
39
+ [project.urls]
40
+ Homepage = "https://github.com/rkkautsar/trace2rules"
41
+ Repository = "https://github.com/rkkautsar/trace2rules"
42
+ Issues = "https://github.com/rkkautsar/trace2rules/issues"
43
+
44
+ [project.scripts]
45
+ trace2rules = "trace2rules.cli:app"
46
+
47
+ [build-system]
48
+ requires = ["uv_build>=0.13.4,<0.14.0"]
49
+ build-backend = "uv_build"
50
+
51
+ [dependency-groups]
52
+ dev = ["pytest>=9.2.0"]
53
+
54
+ [tool.pytest.ini_options]
55
+ testpaths = ["tests"]