traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/mappings/openhands.yaml

@@ -0,0 +1,320 @@
+# OpenHands event mapping for MappedJsonAdapter
+# Targets: openhands >= 0.30 legacy events and >= 1.0 SDK event-store files
+# Sources:
+#   - All-Hands-AI/OpenHands openhands/events/serialization/event.py (0.x)
+#   - OpenHands SDK event persistence (1.x): events/event-*.json
+#
+# NOTE: v1.0+ moved to SDK Pydantic events with kind=ActionEvent /
+# ObservationEvent / MessageEvent / SystemPromptEvent. The preprocessor
+# synthesizes ActionEvent.<tool_name>, ObservationEvent.<tool_name>, and
+# MessageEvent.<source> discriminators for those rows.
+#
+# CRITICAL: OpenHands uses a COMPOUND discriminator:
+#   - Action events have: {"action": "run", "args": {...}}
+#   - Observation events have: {"observation": "run", "content": "...", "extras": {...}}
+#
+# An OpenHandsPreProcessor synthesizes compound types:
+#   "action" key → type = action value (e.g. "run")
+#   "observation" key → type = "observation.<value>" (e.g. "observation.run")
+#
+# Serialization rules (event_to_dict):
+#   - TOP_KEYS hoisted: id, timestamp, source, message, cause, action/observation,
+#     tool_call_metadata, llm_metrics
+#   - Actions: all dataclass fields → "args" dict
+#   - Observations: "content" hoisted to top-level, remaining fields → "extras" dict
+#   - CmdOutputMetadata: serialized via model_dump() into extras.metadata
+
+framework: openhands
+framework_version: ">=0.30,<2.0"
+ingestion_mode: file_watch
+type_field: action
+timestamp_field: timestamp
+preprocessor: openhands
+
+events:
+  # ── OpenHands 1.x SDK event-store rows (real — discriminated by "kind") ──
+  SystemPromptEvent:
+    kind: message.system
+    payload:
+      content: system_prompt.text
+      tools: tools
+      source: source
+  MessageEvent.user:
+    kind: message.user
+    payload:
+      content: llm_message.content.0.text
+      source: source
+  MessageEvent.agent:
+    kind: message.assistant
+    payload:
+      content: llm_message.content.0.text
+      source: source
+  ActionEvent.terminal:
+    kind: command.started
+    payload:
+      command: action.command
+      summary: summary
+      tool_call_id: tool_call_id
+      source: source
+  ObservationEvent.terminal:
+    kind: command.completed
+    payload:
+      command: observation.command
+      content: observation.content.0.text
+      exit_code: observation.exit_code
+      tool_call_id: tool_call_id
+      source: source
+  ActionEvent.apply_patch:
+    kind: file.edited
+    payload:
+      patch: action.patch
+      summary: summary
+      tool_call_id: tool_call_id
+      source: source
+  ObservationEvent.apply_patch:
+    kind: tool.output
+    payload:
+      content: observation.content.0.text
+      is_error: observation.is_error
+      tool_call_id: tool_call_id
+      source: source
+  ActionEvent.task_tracker:
+    kind: session.info
+    payload:
+      command: action.command
+      summary: summary
+      tool_call_id: tool_call_id
+      source: source
+  ObservationEvent.task_tracker:
+    kind: session.info
+    payload:
+      content: observation.content.0.text
+      is_error: observation.is_error
+      tool_call_id: tool_call_id
+      source: source
+  ActionEvent.finish:
+    kind: session.ended
+    payload:
+      output: action.message
+      summary: summary
+      tool_call_id: tool_call_id
+      source: source
+  ObservationEvent.finish:
+    kind: session.ended
+    payload:
+      output: observation.content.0.text
+      is_error: observation.is_error
+      tool_call_id: tool_call_id
+      source: source
+
+  # ── Action events (real — discriminated by "action" field value) ──
+  run:
+    kind: command.started
+    payload:
+      command: args.command
+      thought: args.thought
+      source: source
+  run_ipython:
+    kind: command.started
+    payload:
+      command: args.code
+      source: source
+  think:
+    kind: reasoning.started
+    payload:
+      content: args.thought
+      source: source
+  finish:
+    kind: session.ended
+    payload:
+      output: args.outputs.content
+      source: source
+  message:
+    kind: message.user
+    payload:
+      content: args.content
+      source: source
+  delegate:
+    kind: agent.spawned
+    payload:
+      agent_id: args.agent
+      task: args.inputs.task
+      source: source
+  reject:
+    kind: session.abort
+    payload:
+      message: args.outputs.reason
+      source: source
+  browse:
+    kind: browser.launched
+    payload:
+      url: args.url
+      source: source
+  browse_interactive:
+    kind: browser.action
+    payload:
+      actions: args.browser_actions
+      source: source
+  read:
+    kind: file.read
+    payload:
+      path: args.path
+      source: source
+  write:
+    kind: file.edited
+    payload:
+      path: args.path
+      content: args.content
+      source: source
+  edit:
+    kind: file.edited
+    payload:
+      path: args.path
+      source: source
+  recall:
+    kind: memory.query.started
+    payload:
+      query: args.query
+      source: source
+  call_tool_mcp:
+    kind: mcp.tool.started
+    payload:
+      tool_name: args.name
+      arguments: args.arguments
+      thought: args.thought
+      source: source
+  condensation:
+    kind: session.info
+    payload:
+      summary: args.summary
+      source: source
+  change_agent_state:
+    kind: agent.state_changed
+    payload:
+      agent_state: args.agent_state
+      thought: args.thought
+      source: source
+  system:
+    kind: message.system
+    payload:
+      content: args.content
+      agent_class: args.agent_class
+      source: source
+
+  # ── New actions (#41: openhands 0.62 additive) ──
+  condensation_request:
+    kind: session.info
+    payload:
+      source: source
+  task_tracking:
+    kind: session.info
+    payload:
+      command: args.command
+      task_list: args.task_list
+      thought: args.thought
+      source: source
+  loop_recovery:
+    kind: session.info
+    payload:
+      option: args.option
+      source: source
+
+  # ── Observation events (preprocessor synthesizes action: "observation.<value>") ──
+  observation.run:
+    kind: command.completed
+    payload:
+      content: content
+      exit_code: extras.metadata.exit_code
+      source: source
+  observation.run_ipython:
+    kind: command.completed
+    payload:
+      content: content
+      source: source
+  observation.browse:
+    kind: browser.result
+    payload:
+      content: content
+      url: extras.url
+      source: source
+  observation.read:
+    kind: file.read
+    payload:
+      path: extras.path
+      content: content
+      source: source
+  observation.write:
+    kind: file.edited
+    payload:
+      path: extras.path
+      source: source
+  observation.edit:
+    kind: file.edited
+    payload:
+      path: extras.path
+      source: source
+  observation.error:
+    kind: session.error
+    payload:
+      message: content
+      source: source
+  observation.agent_state_changed:
+    kind: session.info
+    payload:
+      content: content
+      source: source
+  observation.delegate:
+    kind: agent.completed
+    payload:
+      output: content
+      source: source
+  observation.recall:
+    kind: memory.query.completed
+    payload:
+      content: content
+      source: source
+  observation.success:
+    kind: session.ended
+    payload:
+      output: content
+      source: source
+  observation.think:
+    kind: reasoning.completed
+    payload:
+      content: content
+      source: source
+  observation.user_rejected:
+    kind: session.abort
+    payload:
+      message: content
+      source: source
+  observation.condense:
+    kind: session.info
+    payload:
+      content: content
+      source: source
+  observation.mcp:
+    kind: mcp.tool.completed
+    payload:
+      content: content
+      source: source
+
+  # ── New observations (#41: openhands 0.62 additive) ──
+  observation.download:
+    kind: file.read
+    payload:
+      file_path: extras.file_path
+      content: content
+      source: source
+  observation.task_tracking:
+    kind: session.info
+    payload:
+      command: extras.command
+      task_list: extras.task_list
+      content: content
+      source: source
+  observation.loop_detection:
+    kind: session.info
+    payload:
+      content: content
+      source: source

traceforge/mappings/pydantic_ai.yaml

@@ -0,0 +1,183 @@
+# PydanticAI event mapping for MappedJsonAdapter
+# Targets: pydantic-ai >= 1.0.0 (preprocessor-emitted JSONL)
+# Source: pydantic/pydantic-ai pydantic_ai_slim/pydantic_ai/messages.py
+#
+# CRITICAL: PydanticAI does NOT emit flat JSON events with a "type" field.
+# Its native format uses multi-level discrimination:
+#   - Messages: "kind" = "request" | "response"
+#   - Parts: "part_kind" = "system-prompt" | "user-prompt" | "text" | "tool-call" | ...
+#   - Stream events: "event_kind" = "part_start" | "part_delta" | "part_end" | ...
+#   - Usage: ModelResponse.usage = {input_tokens, output_tokens, ...}
+#
+# This YAML assumes a PydanticAIPreProcessor normalizes the native format to
+# flat JSONL with a "type" discriminator. The preprocessor MUST synthesize:
+#   {"type": "model_response", "usage": {...}, ...}
+#   {"type": "stream.part_start", "part": {...}, ...}
+#   {"type": "stream.part_delta", "delta": {...}, ...}
+#
+# Real UsageMetadata fields: input_tokens, output_tokens,
+#   cache_write_tokens, cache_read_tokens
+# NOTE: total_tokens is a @property (input+output), NOT a stored field.
+#   It will NOT appear in model_dump() unless explicitly computed by preprocessor.
+# Real tool call field: tool_call_id (not call_id — call_id is deprecated alias)
+
+framework: pydantic_ai
+framework_version: ">=1.0.0"
+ingestion_mode: file_watch
+type_field: type
+timestamp_field: timestamp
+preprocessor: pydantic_ai
+
+motivation:
+  sources:
+    - events: ["model_text_response"]
+      field: content
+      role: intent
+
+events:
+  # ── Agent lifecycle ──
+  agent_run_start:
+    kind: session.started
+    payload:
+      agent_name: agent_name
+      model: model_name
+  agent_run_end:
+    kind: session.ended
+    payload:
+      agent_name: agent_name
+      result: result
+  agent_run_error:
+    kind: session.error
+    payload:
+      agent_name: agent_name
+      message: error
+
+  # ── Model calls ──
+  model_request_start:
+    kind: llm.call.started
+    payload:
+      model: model_name
+      request_id: request_id
+  model_request:
+    kind: message.user
+    payload:
+      content: content
+  model_response:
+    kind: llm.call.completed
+    payload:
+      model: model_name
+      input_tokens: usage.input_tokens
+      output_tokens: usage.output_tokens
+      cache_read_tokens: usage.cache_read_tokens
+      cache_write_tokens: usage.cache_write_tokens
+      input_audio_tokens: usage.input_audio_tokens
+      output_audio_tokens: usage.output_audio_tokens
+      cache_audio_read_tokens: usage.cache_audio_read_tokens
+      content: content
+  model_request_error:
+    kind: llm.call.failed
+    payload:
+      model: model_name
+      error: error
+
+  # ── Tool calls ──
+  tool_call_start:
+    kind: tool.call.started
+    payload:
+      tool_name: tool_name
+      tool_call_id: tool_call_id
+      arguments: args
+  tool_call_end:
+    kind: tool.call.completed
+    payload:
+      tool_call_id: tool_call_id
+      tool_name: tool_name
+      result: result
+  tool_call_error:
+    kind: tool.call.failed
+    payload:
+      tool_call_id: tool_call_id
+      tool_name: tool_name
+      error: error
+
+  # ── Messages ──
+  user_message:
+    kind: message.user
+    payload:
+      content: content
+  model_text_response:
+    kind: message.assistant
+    payload:
+      content: content
+  model_structured_response:
+    kind: message.assistant
+    payload:
+      content: data
+
+  # ── Streaming (preprocessor synthesizes "stream.<event_kind>") ──
+  # PartStartEvent has .part (the part object), NOT .delta
+  stream.part_start:
+    kind: llm.output.chunk
+    payload:
+      content: part.content
+      part_kind: part.part_kind
+  # PartDeltaEvent has .delta with content_delta
+  # PartDeltaEvent: TextPartDelta has .content_delta; ToolCallPartDelta has .args_delta
+  # Discriminator: delta.part_delta_kind ("text" vs "tool_call")
+  stream.part_delta:
+    kind: llm.output.chunk
+    payload:
+      content: delta.content_delta
+      args_delta: delta.args_delta
+      part_delta_kind: delta.part_delta_kind
+  stream.part_end:
+    kind: message.assistant
+    payload:
+      content: part.content
+  # FinalResultEvent (event_kind="final_result") — signal-only, no content payload.
+  # Indicates which tool call produced the final result; actual data was in prior PartStart/Delta.
+  stream.final_result:
+    kind: session.ended
+    payload:
+      tool_name: tool_name
+      tool_call_id: tool_call_id
+  model_response_chunk:
+    kind: llm.output.chunk
+    payload:
+      content: chunk
+
+  # ── Retries / validation ──
+  validation_error:
+    kind: tool.validation.failed
+    payload:
+      tool_name: tool_name
+      error: error
+      retry_count: retry_count
+  retry:
+    kind: session.error
+    payload:
+      message: reason
+      attempt: attempt
+
+  # ── Telemetry (from model response usage) ──
+  token_usage:
+    kind: telemetry.usage
+    payload:
+      input_tokens: usage.input_tokens
+      output_tokens: usage.output_tokens
+      model: model_name
+
+  # ── Output validation (SDK calls this "output_validator") ──
+  output_validation_start:
+    kind: guardrail.started
+    payload:
+      validator: validator_name
+  output_validation_pass:
+    kind: guardrail.passed
+    payload:
+      validator: validator_name
+  output_validation_fail:
+    kind: guardrail.failed
+    payload:
+      validator: validator_name
+      reason: error

traceforge/mappings/smolagents.yaml

@@ -0,0 +1,89 @@
+# smolagents (HuggingFace) event mapping for MappedJsonAdapter
+# Targets: smolagents >= 1.0 (preprocessor-emitted JSONL)
+# Source: huggingface/smolagents src/smolagents/memory.py, agents.py
+#
+# CRITICAL: smolagents does NOT have a "step_type" discriminator field.
+# Step type is inferred from FIELD PRESENCE in the serialized dict:
+#   - has "step_number" → ActionStep
+#   - has "plan" → PlanningStep
+#   - has "task" (and no step_number) → TaskStep
+#   - has "system_prompt" → SystemPromptStep
+#   - has ONLY "output" key → FinalAnswerStep
+#
+# Real ActionStep.dict() keys:
+#   step_number, timing (start_time, end_time, duration), model_input_messages,
+#   tool_calls, error, model_output_message, model_output, observations,
+#   action_output, code_action, observations_images, token_usage, is_final_answer
+#
+# Real ToolCall dict: {id, type: "function", function: {name, arguments}}
+# Real TokenUsage: {input_tokens, output_tokens, total_tokens}
+#
+# FinalAnswer: When is_final_answer=true on ActionStep, the action_output IS the answer.
+# There is also a bare FinalAnswerStep with only {"output": value}.
+#
+# ManagedAgent does NOT exist as a class. Multi-agent calls appear as regular ToolCalls.
+#
+# This YAML assumes a SmolagentsPreProcessor that adds a "step_type" field:
+#   {"step_type": "ActionStep", "step_number": 1, ...}
+#   {"step_type": "ToolCall", "tool_name": "web_search", ...}
+
+framework: smolagents
+framework_version: ">=1.0"
+ingestion_mode: file_watch
+type_field: step_type
+timestamp_field: timestamp
+preprocessor: smolagents
+
+motivation:
+  sources:
+    - events: ["ActionStep"]
+      field: content
+      role: intent
+  targets: ["tool.call.started"]
+
+events:
+  # ── Real step types (preprocessor infers from field presence) ──
+  ActionStep:
+    kind: message.assistant
+    payload:
+      content: model_output
+      observations: observations
+      step_number: step_number
+      code_action: code_action
+      error: error
+      action_output: action_output
+      input_tokens: token_usage.input_tokens
+      output_tokens: token_usage.output_tokens
+      start_time: timing.start_time
+      end_time: timing.end_time
+      duration: timing.duration
+  PlanningStep:
+    kind: planning.started
+    payload:
+      content: plan
+      input_tokens: token_usage.input_tokens
+      output_tokens: token_usage.output_tokens
+      start_time: timing.start_time
+      end_time: timing.end_time
+      duration: timing.duration
+  TaskStep:
+    kind: session.started
+    payload:
+      task: task
+      task_images: task_images
+  SystemPromptStep:
+    kind: message.system
+    payload:
+      content: system_prompt
+  FinalAnswer:
+    kind: session.ended
+    payload:
+      output: output
+
+  # ── Tool calls (preprocessor splits from ActionStep.tool_calls array) ──
+  ToolCall:
+    kind: tool.call.started
+    payload:
+      tool_name: tool_name
+      tool_call_id: call_id
+      arguments: tool_input

traceforge/mappings/sweagent.yaml

@@ -0,0 +1,82 @@
+# SWE-agent trajectory mapping for MappedJsonAdapter
+# Targets: sweagent >= 1.0 (trajectory JSON files with history[] array)
+# Source: SWE-agent/SWE-agent sweagent/types.py, sweagent/agent/agents.py
+#
+# SWE-agent stores two arrays in .traj files:
+#   - trajectory[]: action/observation pairs (unmapped — no role discriminator)
+#   - history[]: chat messages with role (system/user/assistant/tool)
+#
+# This YAML maps the history[] format (role-discriminated).
+#
+# IMPORTANT: history entries have NO per-entry timestamps.
+# Each entry has: role, content, agent, message_type, and optionally
+# tool_calls (OpenAI format), tool_call_ids, is_demo, tags, cache_control.
+# NOTE: thinking_blocks exists in unreleased HEAD but NOT in v1.1.0 stable.
+#
+# message_type values: "action" (assistant), "observation" (user/tool),
+#   "system_prompt" (system), "demonstration" (user)
+#
+# Top-level .traj also has info.model_stats (InstanceStats) with:
+#   instance_cost, tokens_sent, tokens_received, api_calls
+# These require a preprocessor to extract (not role-discriminated history entries).
+
+framework: sweagent
+framework_version: ">=1.0"
+ingestion_mode: file_watch
+type_field: role
+timestamp_field: null
+
+motivation:
+  sources:
+    - events: ["assistant"]
+      field: content
+      role: intent
+  targets: ["tool.output"]
+
+events:
+  # ── Agent actions (assistant entries always have message_type="action") ──
+  assistant:
+    kind: message.assistant
+    payload:
+      content: content
+      thought: thought
+      action: action
+      tool_calls: tool_calls
+      thinking_blocks: thinking_blocks
+      agent: agent
+      message_type: message_type
+      is_demo: is_demo
+      tags: tags
+      cache_control: cache_control
+
+  # ── Tool responses (role: tool — OpenAI function-calling responses) ──
+  tool:
+    kind: tool.output
+    payload:
+      content: content
+      tool_call_ids: tool_call_ids
+      agent: agent
+      message_type: message_type
+      is_demo: is_demo
+      tags: tags
+      cache_control: cache_control
+
+  # ── System prompt (role: system, message_type="system_prompt") ──
+  system:
+    kind: message.system
+    payload:
+      content: content
+      agent: agent
+      message_type: message_type
+      cache_control: cache_control
+
+  # ── User messages (task setup, observations in non-FC mode, demos) ──
+  user:
+    kind: message.user
+    payload:
+      content: content
+      message_type: message_type
+      agent: agent
+      is_demo: is_demo
+      tags: tags
+      cache_control: cache_control

traceforge/migrations/__init__.py

@@ -0,0 +1 @@
+"""Alembic migrations for traceforge system storage."""