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,456 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ import json
5
+ from dataclasses import dataclass, field
6
+ from pathlib import Path
7
+
8
+ from ..models import Session, ToolCall
9
+ from .common import classify_tool_call, parse_arguments, target_from_args
10
+
11
+ SOURCE_DIRS = {
12
+ "claude-code": ("claude_code", ".claude/projects"),
13
+ "codex": ("codex", ".codex/sessions"),
14
+ "pi": ("pi", ".pi/agent/sessions"),
15
+ "omp": ("omp", ".omp/agent/sessions"),
16
+ "opencode": ("opencode", ""),
17
+ }
18
+
19
+ TOOL_CALL_TYPES = {
20
+ "tool_use",
21
+ "toolCall",
22
+ "tool_call",
23
+ "function_call",
24
+ "custom_tool_call",
25
+ "local_shell_call",
26
+ "web_search_call",
27
+ "mcp_tool_call",
28
+ }
29
+
30
+
31
+ @dataclass(slots=True)
32
+ class TranscriptMeta:
33
+ """Source-neutral session/episode metadata extracted from raw JSONL."""
34
+
35
+ session_id: str = ""
36
+ parent_session_id: str = ""
37
+ instance_id: str = ""
38
+ title: str = ""
39
+ is_continuation: bool = False
40
+ segment_of_call: dict[str, int] = field(default_factory=dict)
41
+ segments: int = 1
42
+
43
+
44
+ def _child_meta(row: dict, *keys: str) -> str:
45
+ value: object = row
46
+ for key in keys:
47
+ if not isinstance(value, dict):
48
+ return ""
49
+ value = value.get(key)
50
+ return value if isinstance(value, str) else ""
51
+
52
+
53
+ def _is_compaction(row: dict, source: str) -> bool:
54
+ if source == "codex":
55
+ return row.get("type") == "response_item" and _child_meta(
56
+ row, "payload", "type"
57
+ ) == "compaction"
58
+ if source in {"omp", "pi"}:
59
+ return row.get("type") == "compaction"
60
+ if source == "claude-code":
61
+ message = row.get("message") or {}
62
+ return (
63
+ row.get("type") in {"summary", "compaction"}
64
+ or row.get("isCompactSummary") is True
65
+ or message.get("isCompactSummary") is True
66
+ )
67
+ return str(row.get("type", "")).lower().startswith("compact")
68
+
69
+
70
+ def _walk_tool_ids(value: object):
71
+ if isinstance(value, dict):
72
+ if value.get("type") in TOOL_CALL_TYPES:
73
+ call_id = value.get("id") or value.get("call_id")
74
+ if isinstance(call_id, str) and call_id:
75
+ yield call_id
76
+ for child in value.values():
77
+ yield from _walk_tool_ids(child)
78
+ elif isinstance(value, list):
79
+ for child in value:
80
+ yield from _walk_tool_ids(child)
81
+
82
+
83
+ def extract_transcript_meta(path: Path, source: str, text: str) -> TranscriptMeta:
84
+ """Extract header id, parent id, and compaction episode boundaries.
85
+
86
+ The trajectory normalizer drops source-specific boundary records, so this
87
+ pre-pass runs over the same raw transcript before normalization.
88
+ """
89
+ meta = TranscriptMeta()
90
+ segment = 0
91
+ for line in text.splitlines():
92
+ if not line.strip():
93
+ continue
94
+ try:
95
+ row = json.loads(line)
96
+ except json.JSONDecodeError:
97
+ continue
98
+ if not isinstance(row, dict):
99
+ continue
100
+
101
+ if source == "codex" and row.get("type") == "session_meta":
102
+ payload = row.get("payload") or {}
103
+ meta.session_id = str(payload.get("id") or payload.get("session_id") or "")
104
+ meta.parent_session_id = str(
105
+ payload.get("parent_thread_id")
106
+ or _child_meta(payload, "source", "subagent", "thread_spawn", "parent_thread_id")
107
+ or ""
108
+ )
109
+ meta.title = str(payload.get("title") or "")
110
+ elif source in {"omp", "pi"} and row.get("type") == "session":
111
+ meta.session_id = str(row.get("id") or "")
112
+ meta.parent_session_id = str(
113
+ row.get("parentSession") or row.get("continuationOf") or ""
114
+ )
115
+ meta.is_continuation = bool(row.get("continuationOf"))
116
+ meta.title = str(row.get("title") or "")
117
+ elif source == "claude-code":
118
+ meta.session_id = meta.session_id or str(
119
+ row.get("sessionId") or row.get("session_id") or ""
120
+ )
121
+ meta.parent_session_id = meta.parent_session_id or str(
122
+ row.get("parentSessionId") or row.get("parent_session_id") or ""
123
+ )
124
+ meta.title = meta.title or str(row.get("title") or "")
125
+
126
+ if _is_compaction(row, source):
127
+ segment += 1
128
+ continue
129
+ for call_id in _walk_tool_ids(row):
130
+ meta.segment_of_call[call_id] = segment
131
+
132
+ meta.segments = segment + 1
133
+ return meta
134
+
135
+
136
+ def _normalize_parent(value: str) -> str:
137
+ if not value:
138
+ return ""
139
+ if value.endswith(".jsonl"):
140
+ return Path(value).stem.split("_")[-1].removesuffix(".jsonl")
141
+ return value
142
+
143
+
144
+ def _resolve_instance(
145
+ session_id: str,
146
+ metas: dict[str, TranscriptMeta],
147
+ seen: tuple[str, ...] = (),
148
+ ) -> str:
149
+ meta = metas.get(session_id)
150
+ if meta is None:
151
+ return session_id
152
+ parent = _normalize_parent(meta.parent_session_id)
153
+ if not parent or parent not in metas or parent in seen:
154
+ return session_id
155
+ if meta.is_continuation and metas[parent].title != meta.title:
156
+ return session_id
157
+ return _resolve_instance(parent, metas, seen + (session_id,))
158
+
159
+
160
+ def _detect_source(path: Path) -> str | None:
161
+ if path.is_file() and path.suffix == ".db":
162
+ return "opencode"
163
+ if path.is_dir() and any(path.glob("opencode*.db")):
164
+ return "opencode"
165
+ if path.is_file() and path.suffix == ".json":
166
+ return "opencode"
167
+ if path.is_dir() and any(path.glob("*.json")):
168
+ return "opencode"
169
+ parts = path.parts
170
+ for source, markers in SOURCE_DIRS.items():
171
+ for marker in markers:
172
+ if not marker:
173
+ continue
174
+ if marker in parts or marker in path.as_posix():
175
+ return source
176
+ if any(part == "sessions" for part in parts):
177
+ for source, (marker, _) in SOURCE_DIRS.items():
178
+ if marker in parts:
179
+ return source
180
+ return None
181
+
182
+
183
+ WINDOWS_AGENT_STORES = (
184
+ (".codex/sessions", "codex"),
185
+ (".claude/projects", "claude-code"),
186
+ (".pi/agent/sessions", "pi"),
187
+ (".local/share/opencode", "opencode"),
188
+ ("AppData/Roaming/opencode", "opencode"),
189
+ ("AppData/Local/opencode", "opencode"),
190
+ )
191
+
192
+
193
+ def _append_root(
194
+ roots: list[tuple[str, Path]],
195
+ seen: set[Path],
196
+ source: str,
197
+ candidate: Path,
198
+ ) -> None:
199
+ try:
200
+ exists = candidate.exists()
201
+ except OSError:
202
+ return
203
+ if exists and candidate not in seen:
204
+ seen.add(candidate)
205
+ roots.append((source, candidate))
206
+
207
+
208
+ def _source_roots(root: Path) -> list[tuple[str, Path]]:
209
+ roots: list[tuple[str, Path]] = []
210
+ seen: set[Path] = set()
211
+ opencode = root / ".local" / "share" / "opencode"
212
+ _append_root(roots, seen, "opencode", opencode)
213
+ for relative, source in (
214
+ ("AppData/Roaming/opencode", "opencode"),
215
+ ("AppData/Local/opencode", "opencode"),
216
+ ):
217
+ _append_root(roots, seen, source, root / relative)
218
+ for source, (marker, suffix) in SOURCE_DIRS.items():
219
+ if not marker:
220
+ continue
221
+ candidates = [root / suffix] if suffix else []
222
+ candidates.extend(
223
+ [
224
+ root / marker,
225
+ root / "sessions" / marker,
226
+ ]
227
+ )
228
+ for candidate in candidates:
229
+ _append_root(roots, seen, source, candidate)
230
+ if root.resolve() == Path.home().resolve():
231
+ for user in sorted(Path("/mnt/c/Users").glob("*")):
232
+ for relative, source in WINDOWS_AGENT_STORES:
233
+ _append_root(roots, seen, source, user / relative)
234
+ return roots
235
+
236
+
237
+ def _iter_files(root: Path, source: str, limit: int | None) -> list[Path]:
238
+ if root.is_file():
239
+ return [root]
240
+ suffix = ".json" if source == "opencode" else ".jsonl"
241
+ skip = {"changes.jsonl"}
242
+ files = [
243
+ path
244
+ for path in sorted(root.rglob(f"*{suffix}"))
245
+ if path.is_file() and path.name not in skip
246
+ ]
247
+ return files[:limit] if limit else files
248
+
249
+
250
+ def _repo_from_cwd(cwd: str | None) -> str:
251
+ if not cwd:
252
+ return ""
253
+ return Path(cwd).name
254
+
255
+
256
+ def _session_id(path: Path) -> str:
257
+ digest = hashlib.sha1(str(path.resolve()).encode()).hexdigest()[:12]
258
+ return f"{path.stem}-{digest}"
259
+
260
+
261
+ def _records_to_session(
262
+ path: Path,
263
+ source: str,
264
+ records: list[dict],
265
+ repo_override: str | None,
266
+ *,
267
+ meta: TranscriptMeta | None = None,
268
+ ) -> Session:
269
+ meta_record = next((record for record in records if record.get("role") == "meta"), {})
270
+ repo = repo_override or _repo_from_cwd(meta_record.get("cwd")) or "unknown"
271
+ session_id = (meta.session_id if meta and meta.session_id else _session_id(path))
272
+ session = Session(
273
+ session_id=session_id,
274
+ repo=repo,
275
+ instance_id=(meta.instance_id if meta and meta.instance_id else session_id),
276
+ source="agent-trajectory",
277
+ agent=source,
278
+ )
279
+ pending: dict[str, ToolCall] = {}
280
+ for record in records:
281
+ role = record.get("role")
282
+ if role == "assistant" and record.get("tool_calls"):
283
+ for tool_call in record["tool_calls"]:
284
+ name = tool_call.get("name") or ""
285
+ args = parse_arguments(tool_call.get("args"))
286
+ raw_target = target_from_args(name, args, tool_call.get("args") or name)
287
+ action, target, verb, object_id = classify_tool_call(name, args, raw_target)
288
+ call = ToolCall(
289
+ tool_name=name,
290
+ raw_target=raw_target,
291
+ action_type=action,
292
+ target=target,
293
+ verb=verb,
294
+ object_id=object_id,
295
+ segment_idx=(
296
+ meta.segment_of_call.get(tool_call.get("id") or "", 0)
297
+ if meta
298
+ else 0
299
+ ),
300
+ )
301
+ session.calls.append(call)
302
+ if tool_call.get("id"):
303
+ pending[tool_call["id"]] = call
304
+ elif role == "tool":
305
+ call = pending.get(record.get("tool_call_id") or "")
306
+ if call is not None:
307
+ call.observation = record.get("content") or ""
308
+ if "ok" in record:
309
+ call.is_error = not record["ok"]
310
+ return session
311
+
312
+
313
+ def ingest_agent_sessions(
314
+ source: str | Path,
315
+ db_path: str | Path,
316
+ *,
317
+ limit: int | None = None,
318
+ repo: str | None = None,
319
+ ):
320
+ """Normalize local agent sessions with @letta-ai/trajectory."""
321
+ try:
322
+ from trajectory import NodeUnavailableError, NormalizationError, normalize_many
323
+ except ImportError as error:
324
+ raise RuntimeError(
325
+ "agent-trajectory is not installed; install the local extra: "
326
+ "pip install 'trace2rules[local]'."
327
+ ) from error
328
+
329
+ from ..ingest import IngestStats, write_sessions
330
+
331
+ root = Path(source).expanduser()
332
+ if not root.exists():
333
+ raise FileNotFoundError(f"Session source does not exist: {root}")
334
+ if (root.is_file() and root.suffix == ".db") or (
335
+ root.is_dir() and any(root.glob("opencode*.db"))
336
+ ):
337
+ from .opencode import ingest_opencode
338
+
339
+ return ingest_opencode(root, db_path, limit=limit, repo=repo)
340
+
341
+ if root.is_file():
342
+ detected = _detect_source(root)
343
+ if detected is None:
344
+ raise ValueError(f"Cannot detect agent format from {root}")
345
+ roots = [(detected, root)]
346
+ else:
347
+ roots = _source_roots(root)
348
+ if not roots:
349
+ detected = _detect_source(root)
350
+ if detected is None:
351
+ raise ValueError(
352
+ f"No known agent session stores under {root}; pass --source with "
353
+ "a Claude Code, Codex, Pi, or OMP session directory."
354
+ )
355
+ roots = [(detected, root)]
356
+
357
+ stats: list[IngestStats] = []
358
+ all_sessions: list[Session] = []
359
+ seen_session_ids: set[str] = set()
360
+ bounds = {"toolResults": {"maxCharacters": 20000, "strategy": "head-tail"}}
361
+ try:
362
+ for source_name, source_root in roots:
363
+ if source_name == "opencode" and (
364
+ (source_root.is_file() and source_root.suffix == ".db")
365
+ or (source_root.is_dir() and any(source_root.glob("opencode*.db")))
366
+ ):
367
+ from .opencode import ingest_opencode
368
+
369
+ stats.extend(
370
+ ingest_opencode(source_root, db_path, limit=limit, repo=repo)
371
+ )
372
+ continue
373
+ files = _iter_files(source_root, source_name, limit)
374
+ if not files:
375
+ if source_name == "opencode":
376
+ raise ValueError(
377
+ "agent-trajectory does not read OpenCode SQLite directly; "
378
+ "export sessions with `opencode export <session-id>` first."
379
+ )
380
+ continue
381
+ transcripts: list[tuple[Path, str]] = [
382
+ (path, path.read_text(encoding="utf-8", errors="replace")) for path in files
383
+ ]
384
+ metas_by_id: dict[str, TranscriptMeta] = {}
385
+ transcript_metas: list[tuple[Path, str, TranscriptMeta]] = []
386
+ for path, text in transcripts:
387
+ meta = extract_transcript_meta(path, source_name, text)
388
+ meta.session_id = meta.session_id or _session_id(path)
389
+ if meta.session_id in metas_by_id:
390
+ continue
391
+ metas_by_id[meta.session_id] = meta
392
+ transcript_metas.append((path, text, meta))
393
+ for meta in metas_by_id.values():
394
+ meta.instance_id = _resolve_instance(meta.session_id, metas_by_id)
395
+
396
+ results: list[dict] = []
397
+ BATCH = 32
398
+ for start in range(0, len(transcript_metas), BATCH):
399
+ batch = transcript_metas[start : start + BATCH]
400
+ try:
401
+ results.extend(
402
+ normalize_many(
403
+ [
404
+ {
405
+ "source": source_name,
406
+ "transcript": text,
407
+ "bounds": bounds,
408
+ }
409
+ for _, text, _ in batch
410
+ ]
411
+ )
412
+ )
413
+ except NormalizationError:
414
+ for path, text, _ in batch:
415
+ try:
416
+ results.extend(
417
+ [
418
+ normalize_many(
419
+ [
420
+ {
421
+ "source": source_name,
422
+ "transcript": text,
423
+ "bounds": bounds,
424
+ }
425
+ ]
426
+ )[0]
427
+ ]
428
+ )
429
+ except NormalizationError as error:
430
+ print(f"Skipping {path}: {error}")
431
+ results.append({"records": [], "diagnostics": []})
432
+ for (path, _text, meta), result in zip(transcript_metas, results):
433
+ if not result.get("records"):
434
+ continue
435
+ session = _records_to_session(
436
+ path, source_name, result["records"], repo, meta=meta
437
+ )
438
+ if session.session_id in seen_session_ids:
439
+ continue
440
+ seen_session_ids.add(session.session_id)
441
+ all_sessions.append(session)
442
+ stats.append(
443
+ IngestStats(
444
+ f"agent-trajectory:{source_name}",
445
+ len(files),
446
+ len([s for s in all_sessions if s.agent == source_name]),
447
+ sum(len(s.calls) for s in all_sessions if s.agent == source_name),
448
+ )
449
+ )
450
+ except NodeUnavailableError as error:
451
+ raise RuntimeError(
452
+ "agent-trajectory requires Node.js 20 or newer on PATH."
453
+ ) from error
454
+
455
+ write_sessions(db_path, all_sessions)
456
+ return stats
@@ -0,0 +1,99 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from typing import Any
5
+
6
+ from ..ingest import _classify_shell, _object_id, _parameterize, _shell_verb_tokens, normalize_path
7
+
8
+ SHELL_TOOLS = {
9
+ "bash",
10
+ "cmd",
11
+ "exec",
12
+ "exec_command",
13
+ "execute",
14
+ "local_shell",
15
+ "powershell",
16
+ "run_command",
17
+ "shell",
18
+ "shell_command",
19
+ "terminal",
20
+ }
21
+ READ_TOOLS = {"cat", "head", "open", "read", "read_file", "tail", "view"}
22
+ EDIT_TOOLS = {
23
+ "apply_patch",
24
+ "create",
25
+ "edit",
26
+ "edit_file",
27
+ "multiedit",
28
+ "patch",
29
+ "replace",
30
+ "str_replace",
31
+ "write",
32
+ "write_file",
33
+ }
34
+ SEARCH_TOOLS = {"find", "glob", "grep", "ls", "list_directory", "rg", "search"}
35
+
36
+
37
+ def parse_arguments(raw: Any) -> dict[str, Any]:
38
+ if isinstance(raw, dict):
39
+ return raw
40
+ if not raw:
41
+ return {}
42
+ try:
43
+ value = json.loads(str(raw))
44
+ except (TypeError, ValueError):
45
+ return {}
46
+ return value if isinstance(value, dict) else {}
47
+
48
+
49
+ def target_from_args(tool_name: str, args: dict[str, Any], fallback: str = "") -> str:
50
+ """Return the most useful command/path/pattern for a tool call."""
51
+ name = tool_name.lower()
52
+ for key in ("command", "cmd", "command_line", "script"):
53
+ value = args.get(key)
54
+ if isinstance(value, str) and value.strip():
55
+ return value.strip()
56
+ for key in ("file_path", "filePath", "path", "filename", "file"):
57
+ value = args.get(key)
58
+ if isinstance(value, str) and value.strip():
59
+ return value.strip()
60
+ for key in ("pattern", "query", "description", "prompt"):
61
+ value = args.get(key)
62
+ if isinstance(value, str) and value.strip() and name in SEARCH_TOOLS:
63
+ return value.strip()
64
+ if fallback:
65
+ return fallback
66
+ return json.dumps(args, ensure_ascii=False, sort_keys=True)
67
+
68
+
69
+ def _path_from_args(args: dict[str, Any]) -> str:
70
+ for key in ("file_path", "filePath", "path", "filename", "file"):
71
+ value = args.get(key)
72
+ if isinstance(value, str) and value.strip():
73
+ return value.strip()
74
+ return ""
75
+
76
+
77
+ def classify_tool_call(tool_name: str, args: dict[str, Any], raw_target: str) -> tuple[str, str, str, str]:
78
+ """Map a normalized tool call to action/target/verb/object_id."""
79
+ name = tool_name.strip().lower()
80
+ if name in SHELL_TOOLS:
81
+ action, target = _classify_shell(raw_target, "")
82
+ verb, tokens = _shell_verb_tokens(raw_target)
83
+ object_id = _object_id(action, verb, tokens, raw_target, target)
84
+ return action, target, verb, object_id
85
+
86
+ path = _path_from_args(args)
87
+ if name in READ_TOOLS:
88
+ target = normalize_path(path) if path else raw_target
89
+ return "read", target, name, target or name
90
+ if name in EDIT_TOOLS:
91
+ target = normalize_path(path) if path else normalize_path(".", "")
92
+ object_id = target if path else name
93
+ return "edit", target, name, object_id
94
+ if name in SEARCH_TOOLS:
95
+ target = normalize_path(path) if path else raw_target
96
+ return "search", target, name, target or name
97
+
98
+ target = _parameterize(raw_target, "")
99
+ return "other", target, name, target or name