traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/mappings/aider.yaml

@@ -0,0 +1,216 @@
+# Aider analytics JSONL mapping for MappedJsonAdapter
+# Targets: aider >= 0.70 analytics log (--analytics-log <path>)
+# Source: Aider-AI/aider:aider/analytics.py — verified 2026-06-14
+#
+# Aider writes JSONL to a USER-SPECIFIED path via --analytics-log flag.
+# There is NO default structured output file. Users must configure:
+#   aider --analytics-log .aider.analytics.jsonl
+#
+# JSONL schema (4 top-level fields):
+#   {"event": str, "properties": dict, "user_id": str, "time": unix_int}
+#
+# The markdown chat history (.aider.chat.history.md) uses AiderPreParser
+# via aider_markdown.yaml — that mapping is separate and independent.
+
+framework: aider
+framework_version: ">=0.70"
+ingestion_mode: file_watch
+type_field: event
+timestamp_field: time
+default_kind: raw
+
+# ── Event Definitions ──
+# 21 real events verified from source (main.py, base_coder.py, watch.py, onboarding.py)
+
+events:
+  # ── Core LLM interaction ──
+  message_send:
+    kind: llm.call.completed
+    payload:
+      model: properties.main_model
+      edit_format: properties.edit_format
+      input_tokens: properties.prompt_tokens
+      output_tokens: properties.completion_tokens
+      total_tokens: properties.total_tokens
+      cost: properties.cost
+      total_cost: properties.total_cost
+
+  message_send_starting:
+    kind: llm.call.started
+    payload: {}
+
+  message_send_exception:
+    kind: llm.call.error
+    payload:
+      error: properties.exception
+
+  # ── Session lifecycle ──
+  launched:
+    kind: session.started
+    payload: {}
+
+  "cli session":
+    kind: session.configured
+    payload:
+      model: properties.main_model
+      weak_model: properties.weak_model
+      editor_model: properties.editor_model
+      edit_format: properties.edit_format
+
+  "gui session":
+    kind: session.configured
+    payload: {}
+
+  exit:
+    kind: session.ended
+    payload:
+      reason: properties.reason
+
+  # ── Repository context ──
+  repo:
+    kind: context.repository
+    payload:
+      num_files: properties.num_files
+
+  no-repo:
+    kind: context.no_repository
+    payload: {}
+
+  # ── Configuration ──
+  auto_commits:
+    kind: config.auto_commits
+    payload:
+      enabled: properties.enabled
+
+  "copy-paste mode":
+    kind: config.copy_paste
+    payload: {}
+
+  "model warning":
+    kind: config.model_warning
+    payload:
+      model: properties.main_model
+      weak_model: properties.weak_model
+      editor_model: properties.editor_model
+
+  # ── AI-comment file watcher ──
+  "ai-comments file-add":
+    kind: watch.file_added
+    payload: {}
+
+  "ai-comments execute":
+    kind: watch.execute
+    payload: {}
+
+  # ── OAuth onboarding ──
+  oauth_flow_initiated:
+    kind: auth.oauth_started
+    payload:
+      provider: properties.provider
+
+  oauth_flow_success:
+    kind: auth.oauth_success
+    payload:
+      provider: properties.provider
+
+  oauth_flow_failure:
+    kind: auth.oauth_failed
+    payload: {}
+
+  oauth_flow_failed:
+    kind: auth.oauth_failed
+    payload:
+      provider: properties.provider
+      reason: properties.reason
+
+  oauth_flow_code_received:
+    kind: auth.oauth_code_received
+    payload:
+      provider: properties.provider
+
+  oauth_flow_save_failed:
+    kind: auth.oauth_save_failed
+    payload:
+      provider: properties.provider
+      reason: properties.reason
+
+  auto_model_selection:
+    kind: config.auto_model
+    payload:
+      model: properties.model
+
+  # ── User commands (dynamically generated from /command input) ──
+  # These all have empty properties — they record which slash-command was used.
+  # Unmapped command_* variants fall through to default_kind: raw.
+  command_add:
+    kind: user.command
+    payload: {}
+
+  command_drop:
+    kind: user.command
+    payload: {}
+
+  command_ask:
+    kind: user.command
+    payload: {}
+
+  command_code:
+    kind: user.command
+    payload: {}
+
+  command_commit:
+    kind: user.command
+    payload: {}
+
+  command_run:
+    kind: user.command
+    payload: {}
+
+  command_undo:
+    kind: user.command
+    payload: {}
+
+  command_clear:
+    kind: user.command
+    payload: {}
+
+  command_model:
+    kind: user.command
+    payload: {}
+
+  command_paste:
+    kind: user.command
+    payload: {}
+
+  command_web:
+    kind: user.command
+    payload: {}
+
+  command_exit:
+    kind: user.command
+    payload: {}
+
+  command_edit:
+    kind: user.command
+    payload: {}
+
+  command_read-only:
+    kind: user.command
+    payload: {}
+
+  command_chat-mode:
+    kind: user.command
+    payload: {}
+
+  command_reasoning-effort:
+    kind: user.command
+    payload: {}
+
+  command_ok:
+    kind: user.command
+    payload: {}
+
+  # ── Interactive help (#41: fires on /help <query>, no properties) ──
+  "interactive help":
+    kind: user.command
+    payload: {}

traceforge/mappings/aider_markdown.yaml

@@ -0,0 +1,113 @@
+# Aider Markdown Pre-Parser output mapping for MappedJsonAdapter
+# Maps event dicts emitted by AiderPreParser → canonical event kinds.
+# Input: AiderPreParser.parse_text() output, serialized as JSONL
+# Source format: .aider.chat.history.md (append-only markdown session log)
+#
+# This mapping handles the pre-parser's output types. For aider's native
+# structured JSON events (.aider.events.json), use aider.yaml instead.
+
+framework: aider_markdown
+framework_version: ">=0.70"
+ingestion_mode: file_watch
+type_field: type
+timestamp_field: timestamp
+
+motivation:
+  sources:
+    - events: ["assistant_message"]
+      field: content
+      role: intent
+  targets: ["tool.call.completed"]
+
+events:
+  # ── Session lifecycle ──
+  session_start:
+    kind: session.started
+    payload:
+      session_id: session_id
+      started_at: started_at
+
+  # ── Messages ──
+  user_message:
+    kind: message.user
+    payload:
+      content: content
+
+  assistant_message:
+    kind: message.assistant
+    payload:
+      content: content
+
+  # ── Commands ──
+  slash_command:
+    kind: command.started
+    payload:
+      command: command
+      arguments: args
+
+  # ── File operations ──
+  file_edit:
+    kind: file.edited
+    payload:
+      path: file_path
+      search: search
+      replace: replace
+
+  file_edit_applied:
+    kind: file.edited
+    payload:
+      path: file_path
+
+  file_add:
+    kind: input.received
+    payload:
+      path: file_path
+
+  # ── Git ──
+  git_commit:
+    kind: tool.call.completed
+    payload:
+      tool_name: git
+      result: commit_sha
+      message: commit_message
+
+  # ── Telemetry / info ──
+  token_usage:
+    kind: telemetry.usage
+    payload:
+      tokens_sent: tokens_sent
+      tokens_received: tokens_received
+
+  version_info:
+    kind: session.info
+    payload:
+      version: version
+
+  model_info:
+    kind: session.info
+    payload:
+      model: model
+      edit_format: edit_format
+
+  repo_info:
+    kind: session.info
+    payload:
+      repo_path: repo_path
+      file_count: file_count
+
+  repo_map:
+    kind: knowledge.query.completed
+    payload:
+      content: repo_map_info
+
+  # ── Errors ──
+  error:
+    kind: session.error
+    payload:
+      message: message
+
+  # ── Generic tool output ──
+  tool_output:
+    kind: tool.output
+    payload:
+      text: text

traceforge/mappings/amazonq.yaml

@@ -0,0 +1,56 @@
+# Amazon Q Developer — YAML mapping for traceforge
+#
+# Amazon Q Developer stores conversations in SQLite:
+#   ~/.local/share/amazon-q/data.sqlite3 (Linux)
+#   ~/Library/Application Support/amazon-q/data.sqlite3 (macOS)
+#
+# The conversations table has a JSON `value` column with the full message
+# history. The "amazonq" preprocessor extracts and flattens messages and
+# tool calls into per-block events with a "block_type" discriminator.
+#
+# Tool calls use the Anthropic-style content block format:
+#   - type: "tool_use" → tool invocation (name + input)
+#   - type: "tool_result" → tool output (content + is_error)
+#
+# Source: Amazon Q Developer CLI / VS Code extension
+# Storage: SQLite with JSON blob per conversation
+
+framework: amazonq
+framework_version: "1.x"
+ingestion_mode: poll
+type_field: block_type
+default_kind: raw
+preprocessor: amazonq
+
+motivation:
+  sources:
+    - events: ["message.assistant"]
+      field: content
+      role: intent
+
+events:
+  # ── Tool calls ─────────────────────────────────────────────────────────────
+  tool.call:
+    kind: tool.call.started
+    payload:
+      tool_call_id: tool_call_id
+      tool_name: tool_name
+      arguments: arguments
+
+  tool.result:
+    kind: tool.call.completed
+    payload:
+      tool_call_id: tool_call_id
+      is_error: is_error
+      result: output
+
+  # ── Messages ───────────────────────────────────────────────────────────────
+  message.user:
+    kind: message.user
+    payload:
+      content: content
+
+  message.assistant:
+    kind: message.assistant
+    payload:
+      content: content

traceforge/mappings/antigravity.yaml

@@ -0,0 +1,88 @@
+# Google Antigravity — YAML mapping for traceforge
+#
+# Native source: the Antigravity Python SDK's ``agent.conversation.history`` —
+# a ``list[google.antigravity.types.Step]`` dumped verbatim per line with
+# ``model_dump(mode="json")`` by scripts/capture_traces/capture_antigravity.py
+# (or synthesize_antigravity_fixture.py for the shape fixture).
+#
+# Each Step's identity is a compound of ``type`` (StepType) + ``source``
+# (StepSource), so there is no single native type_field. The ``antigravity``
+# preprocessor synthesizes a flat ``event_type`` discriminator and fans a
+# TOOL_CALL step out into one ``tool_call`` event per entry in ``tool_calls``.
+#
+# Antigravity has no Windows IDE; the SDK runs under WSL/Docker (the manylinux
+# localharness binary needs glibc >= 2.36). Tool *results* are consumed inside
+# the Go localharness and never surface on a history Step, so this mapping emits
+# tool calls but no tool-result event.
+
+framework: antigravity
+framework_version: "google-antigravity-sdk"
+ingestion_mode: file_watch
+type_field: event_type
+preprocessor: antigravity
+default_kind: raw
+
+motivation:
+  sources:
+    - events: ["assistant_message"]
+      field: content
+      role: intent
+    - events: ["thinking"]
+      field: content
+      role: reasoning
+  targets: ["tool.call.started"]
+
+events:
+  # ── Messages ───────────────────────────────────────────────────────────────
+  user_message:
+    kind: message.user
+    payload:
+      content: content
+      step_index: step_index
+      source: source
+
+  assistant_message:
+    kind: message.assistant
+    payload:
+      content: content
+      step_index: step_index
+      source: source
+
+  system_message:
+    kind: message.system
+    payload:
+      content: content
+      step_index: step_index
+
+  # ── Reasoning ────────────────────────────────────────────────────────────
+  thinking:
+    kind: reasoning.started
+    payload:
+      content: content
+      step_index: step_index
+
+  # ── Tool invocations (fanned out from Step.tool_calls[]) ─────────────────────
+  # The SDK history records the CALL (name + args); builtin tool output is fed
+  # back to the model inside the Go localharness and is not a history field.
+  tool_call:
+    kind: tool.call.started
+    payload:
+      tool_name: tool_name
+      args: args
+      tool_call_id: tool_call_id
+      path: path
+      step_index: step_index
+
+  # ── Context compaction marker ────────────────────────────────────────────────
+  compaction:
+    kind: session.info
+    payload:
+      step_index: step_index
+
+  # ── Terminal finish step (carries structured_output) ─────────────────────────
+  finish:
+    kind: task.completed
+    payload:
+      content: content
+      structured_output: structured_output
+      step_index: step_index

traceforge/mappings/claude.yaml

@@ -0,0 +1,93 @@
+# Claude (Anthropic Claude Code / Agent SDK) — YAML mapping for traceforge
+#
+# Wire format: JSONL lines with shapes:
+#   User:      {type: "user", message: {content: "..." | [blocks]}}
+#   Assistant: {type: "assistant", message: {content: [blocks]}}
+#   Result:    {type: "result", subtype: ..., duration_ms: ..., usage: {...}}
+#   System:    {type: "system", subtype: ...}
+#
+# Content blocks in assistant messages can be:
+#   {type: "text", text: "..."}
+#   {type: "tool_use", id: "...", name: "...", input: {...}}
+#   {type: "tool_result", tool_use_id: "...", content: "...", is_error: bool}
+#   {type: "thinking", thinking: "...", signature: "..."}
+#
+# The "claude" preprocessor flattens content blocks into individual dicts
+# with a synthesized `block_type` field (e.g. "assistant.text",
+# "assistant.tool_use", "user.text", "result").
+#
+# Source: Claude Agent SDK JSONL output
+# Verified against: claude_session.jsonl fixture
+
+framework: claude
+framework_version: "0.x"
+ingestion_mode: file_watch
+type_field: block_type
+default_kind: ""
+preprocessor: claude
+
+motivation:
+  sources:
+    - events: ["assistant.text"]
+      field: content
+      role: intent
+    - events: ["assistant.thinking"]
+      field: content
+      role: reasoning
+
+events:
+  # ── User messages ──────────────────────────────────────────────────────────
+  user.text:
+    kind: message.user
+    payload:
+      content: content
+
+  # ── Assistant text ─────────────────────────────────────────────────────────
+  assistant.text:
+    kind: message.assistant
+    payload:
+      content: text
+
+  # ── Tool use (call started) ────────────────────────────────────────────────
+  assistant.tool_use:
+    kind: tool.call.started
+    payload:
+      tool_call_id: id
+      tool_name: name
+      arguments: input
+
+  # ── Tool result (call completed) ───────────────────────────────────────────
+  # Note: tool_result blocks appear in assistant messages (not user messages)
+  # because Claude's wire format wraps tool results in assistant turns.
+  assistant.tool_result:
+    kind: tool.call.completed
+    payload:
+      tool_call_id: tool_use_id
+      success: success
+      result: content_text
+
+  # Also handle tool results that appear in user context
+  user.tool_result:
+    kind: tool.call.completed
+    payload:
+      tool_call_id: tool_use_id
+      success: success
+      result: content_text
+
+  # ── Thinking ───────────────────────────────────────────────────────────────
+  assistant.thinking:
+    kind: llm.thinking.chunk
+    payload:
+      content: thinking
+
+  # ── Result (session summary with usage) ────────────────────────────────────
+  result:
+    kind: telemetry.usage
+    payload:
+      duration_ms: duration_ms
+      cost_usd: total_cost_usd
+      num_turns: num_turns
+      input_tokens: usage_input_tokens
+      output_tokens: usage_output_tokens
+      cache_read_tokens: usage_cache_read_input_tokens
+      cache_write_tokens: usage_cache_creation_input_tokens