traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/mappings/langgraph.yaml

@@ -0,0 +1,165 @@
+# LangGraph event mapping for MappedJsonAdapter
+# Targets: langgraph >= 1.0 / langchain-core >= 1.4.0 (astream_events version="v2")
+# Source: langchain-ai/langchain libs/core/langchain_core/tracers/event_stream.py
+#
+# astream_events(version="v2") emits flat dicts:
+#   {event, run_id, name, tags, metadata, data, parent_ids}
+#
+# Events confirmed emitted by _AstreamEventsCallbackHandler:
+#   on_chain_start/end/stream, on_chat_model_start/stream/end,
+#   on_llm_start/end/stream, on_tool_start/end/error,
+#   on_retriever_start/end, on_custom_event,
+#   on_prompt_start/end/stream, on_parser_start/end/stream
+#
+# NOT emitted (callback methods exist but handler does NOT override them):
+#   on_chain_error, on_llm_error, on_retriever_error
+#   (errors silently drop from the stream)
+#
+# "on_llm_new_token" is an INTERNAL callback name. The handler translates it to
+# "on_chat_model_stream" (run_type=chat_model) or "on_llm_stream" (run_type=llm).
+#
+# Token usage: on_chat_model_end → data.output.usage_metadata =
+#   {input_tokens, output_tokens, total_tokens, input_token_details?, output_token_details?}
+# Model name: metadata.ls_model_name (from LangSmithParams, merged into inheritable_metadata)
+
+framework: langgraph
+framework_version: ">=1.0"
+ingestion_mode: file_watch
+type_field: event
+timestamp_field: null
+
+events:
+  # ── Chain/graph lifecycle ──
+  on_chain_start:
+    kind: workflow.started
+    payload:
+      run_id: run_id
+      name: name
+      inputs: data.input
+  on_chain_end:
+    kind: workflow.completed
+    payload:
+      run_id: run_id
+      name: name
+      output: data.output
+
+  # ── LLM calls (non-chat models, e.g. completion LLMs) ──
+  on_llm_start:
+    kind: llm.call.started
+    payload:
+      model: metadata.ls_model_name
+      run_id: run_id
+  on_llm_end:
+    kind: llm.call.completed
+    payload:
+      model: metadata.ls_model_name
+      run_id: run_id
+      output: data.output
+  on_llm_stream:
+    kind: llm.output.chunk
+    payload:
+      content: data.chunk.text
+
+  # ── Chat model calls (primary path for modern LangGraph) ──
+  on_chat_model_start:
+    kind: llm.call.started
+    payload:
+      model: metadata.ls_model_name
+      run_id: run_id
+  on_chat_model_end:
+    kind: llm.call.completed
+    payload:
+      model: metadata.ls_model_name
+      run_id: run_id
+      output: data.output.content
+      input_tokens: data.output.usage_metadata.input_tokens
+      output_tokens: data.output.usage_metadata.output_tokens
+      total_tokens: data.output.usage_metadata.total_tokens
+  on_chat_model_stream:
+    kind: message.assistant.chunk
+    payload:
+      content: data.chunk.content
+
+  # ── Tool calls ──
+  on_tool_start:
+    kind: tool.call.started
+    payload:
+      tool_name: name
+      tool_call_id: run_id
+      arguments: data.input
+  on_tool_end:
+    kind: tool.call.completed
+    payload:
+      tool_call_id: run_id
+      tool_name: name
+      result: data.output
+  on_tool_error:
+    kind: tool.call.failed
+    payload:
+      tool_call_id: data.tool_call_id
+      run_id: run_id
+      tool_name: name
+      error: data.error
+      input: data.input
+
+  # ── Retriever ──
+  on_retriever_start:
+    kind: knowledge.query.started
+    payload:
+      query: data.input.query
+  on_retriever_end:
+    kind: knowledge.query.completed
+    payload:
+      results: data.output
+
+  # ── Node transitions (intermediate stream chunks) ──
+  on_chain_stream:
+    kind: workflow.stream
+    payload:
+      node: name
+      data: data.chunk
+
+  # ── Prompt template events (same shape as chain, run_type="prompt") ──
+  on_prompt_start:
+    kind: workflow.started
+    payload:
+      run_id: run_id
+      name: name
+      inputs: data.input
+  on_prompt_end:
+    kind: workflow.completed
+    payload:
+      run_id: run_id
+      name: name
+      output: data.output
+  on_prompt_stream:
+    kind: workflow.stream
+    payload:
+      node: name
+      data: data.chunk
+
+  # ── Parser events (same shape as chain, run_type="parser") ──
+  on_parser_start:
+    kind: workflow.started
+    payload:
+      run_id: run_id
+      name: name
+      inputs: data.input
+  on_parser_end:
+    kind: workflow.completed
+    payload:
+      run_id: run_id
+      name: name
+      output: data.output
+  on_parser_stream:
+    kind: workflow.stream
+    payload:
+      node: name
+      data: data.chunk
+
+  # ── Custom events (user-defined via adispatch_custom_event) ──
+  on_custom_event:
+    kind: custom.event
+    payload:
+      name: name
+      data: data

traceforge/mappings/maf.yaml

@@ -0,0 +1,90 @@
+# Microsoft 365 Agents SDK (MAF) span mapping for OtelSpanAdapter
+# Targets: microsoft-agents-hosting-core >= 1.0.0
+# Source: OpenTelemetry spans emitted by the MAF ActivityHandler pipeline.
+# Ingestion: OTel span dicts (from InMemorySpanExporter or OTLP collector)
+#
+# Unlike JSON-line mappings, this maps OTel span names to canonical kinds
+# and specifies which span attributes to extract into the event payload.
+
+framework: maf
+framework_version: ">=1.0.0"
+ingestion_mode: stream
+
+# Map span names to canonical event kinds.
+# Key = OTel span name, value = {kind, attributes?}
+# attributes maps payload_field_name → OTel attribute key.
+spans:
+  # ── Adapter layer (inbound/outbound message processing) ──
+  agents.adapter.process:
+    kind: message.user
+    attributes:
+      activity_type: activity.type
+      channel_id: activity.channel_id
+      activity_id: activity.id
+      conversation_id: activity.conversation.id
+      delivery_mode: activity.delivery_mode
+
+  agents.adapter.send_activities:
+    kind: message.assistant
+    attributes:
+      count: activities.count
+
+  agents.adapter.update_activity:
+    kind: message.assistant
+
+  agents.adapter.delete_activity:
+    kind: message.assistant
+
+  agents.adapter.continue_conversation:
+    kind: session.resumed
+
+  agents.adapter.create_connector_client:
+    kind: session.info
+
+  agents.adapter.create_user_token_client:
+    kind: session.info
+
+  agents.adapter.write_response:
+    kind: message.assistant
+
+  # ── App layer (request routing and turn lifecycle) ──
+  agents.app.run:
+    kind: turn.started
+    attributes:
+      activity_type: activity.type
+      is_agentic: activity.is_agentic_request
+
+  agents.app.route_handler:
+    kind: hook.started
+    attributes:
+      route_matched: route.matched
+      is_invoke: route.is_invoke
+
+  agents.app.before_turn:
+    kind: hook.started
+
+  agents.app.after_turn:
+    kind: hook.completed
+
+  agents.app.download_files:
+    kind: file.read
+
+  # ── Storage layer (state persistence) ──
+  agents.storage.read:
+    kind: memory.query.started
+    attributes:
+      key_count: storage.keys.count
+
+  agents.storage.write:
+    kind: memory.save.started
+    attributes:
+      key_count: storage.keys.count
+
+  agents.storage.delete:
+    kind: memory.save.completed
+    attributes:
+      key_count: storage.keys.count
+
+  # ── Turn context ──
+  agents.turn.send_activities:
+    kind: message.assistant

traceforge/mappings/maf_transcript.yaml

@@ -0,0 +1,99 @@
+# Microsoft 365 Agents SDK (MAF) transcript mapping for MappedJsonAdapter
+# Targets: microsoft-agents-hosting-core >= 1.0.0
+# Source: JSONL from FileTranscriptStore / ConsoleTranscriptLogger
+# Ingestion: file_watch on <root>/<channelId>/<conversationId>.transcript
+#
+# Each JSONL line is a full Activity object serialized via model_dump_json().
+# The maf_transcript preprocessor normalizes into flat dicts with a compound
+# _event_type field: "{activity_type}.{from_role}" (e.g. "message.bot").
+#
+# Key Activity fields:
+#   type: "message" | "typing" | "event" | "invoke" | "trace" | ...
+#   text: str (message body)
+#   from: {id, name, role}   where role is "bot" or "user"
+#   timestamp: ISO 8601
+#   conversation: {id}
+#   attachments: [{contentType, content, ...}]
+#   value: Any (invoke payloads, adaptive card data)
+#
+# This mapping complements the OTel span adapter (maf.yaml) — use both together
+# for full coverage: OTel gives structure/timing, transcript gives content.
+
+framework: maf_transcript
+framework_version: ">=1.0.0"
+ingestion_mode: file_watch
+preprocessor: maf_transcript
+type_field: _event_type
+timestamp_field: timestamp
+
+motivation:
+  sources:
+    - events: ["message.bot"]
+      field: content
+      role: intent
+  targets: ["tool.call.started"]
+
+events:
+  # ── Messages ──
+  message.bot:
+    kind: message.assistant
+    payload:
+      content: text
+      activity_id: activity_id
+      from_name: from_name
+
+  message.user:
+    kind: message.user
+    payload:
+      content: text
+      activity_id: activity_id
+      from_name: from_name
+
+  # ── Typing indicators ──
+  typing.bot:
+    kind: session.info
+    payload:
+      activity_id: activity_id
+
+  typing.user:
+    kind: session.info
+    payload:
+      activity_id: activity_id
+
+  # ── Invoke activities (tool calls via adaptive cards, skill invocations) ──
+  invoke.bot:
+    kind: tool.call.started
+    payload:
+      input: value
+      activity_id: activity_id
+
+  invoke.user:
+    kind: hook.started
+    payload:
+      input: value
+      activity_id: activity_id
+
+  # ── Event activities (proactive notifications, skill responses) ──
+  event.bot:
+    kind: hook.completed
+    payload:
+      content: text
+      value: value
+      activity_id: activity_id
+
+  event.user:
+    kind: hook.started
+    payload:
+      content: text
+      value: value
+      activity_id: activity_id
+
+  # ── Trace activities (diagnostic/debug) ──
+  trace.bot:
+    kind: session.info
+    payload:
+      content: text
+      value: value
+      activity_id: activity_id
+
+# Default: unmapped activity types get dropped (no default_kind)

traceforge/mappings/openai_agents.yaml

@@ -0,0 +1,144 @@
+# OpenAI Agents SDK mapping for native Trace.export()/Span.export() JSONL.
+# Targets: openai-agents >= 0.3.3
+# Source: openai-agents-python agents.tracing Trace/Span export() objects.
+
+framework: openai_agents
+framework_version: ">=0.3.3"
+ingestion_mode: file_watch
+type_field: event_type
+timestamp_field: timestamp
+preprocessor: openai_agents
+
+motivation:
+  sources:
+    - events: ["generation.completed"]
+      field: output
+      role: intent
+
+events:
+  trace:
+    kind: session.started
+    payload:
+      trace_id: trace_id
+      workflow_name: workflow_name
+      group_id: group_id
+      metadata: metadata
+
+  agent.completed:
+    kind: agent.completed
+    payload:
+      agent_name: span_data.name
+      tools: span_data.tools
+      handoffs: span_data.handoffs
+      output_type: span_data.output_type
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  response.completed:
+    kind: llm.call.completed
+    payload:
+      response_id: span_data.response_id
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  generation.completed:
+    kind: llm.call.completed
+    payload:
+      model: span_data.model
+      model_config: span_data.model_config
+      input: span_data.input
+      output: span_data.output
+      input_tokens: span_data.usage.input_tokens
+      output_tokens: span_data.usage.output_tokens
+      usage: span_data.usage
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  function.started:
+    kind: tool.call.started
+    payload:
+      tool_name: tool_name
+      tool_call_id: span_id
+      arguments: arguments
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  function.completed:
+    kind: tool.call.completed
+    payload:
+      tool_name: tool_name
+      tool_call_id: span_id
+      result: result
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  function.failed:
+    kind: tool.call.failed
+    payload:
+      tool_name: tool_name
+      tool_call_id: span_id
+      error: error
+      result: result
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  handoff.completed:
+    kind: agent.handoff
+    payload:
+      from_agent: span_data.from_agent
+      to_agent: span_data.to_agent
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  guardrail.completed:
+    kind: guardrail.passed
+    payload:
+      name: span_data.name
+      triggered: span_data.triggered
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  custom.completed:
+    kind: session.info
+    payload:
+      name: span_data.name
+      data: span_data.data
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  speech.completed:
+    kind: llm.call.completed
+    payload:
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  speech_group.completed:
+    kind: llm.call.completed
+    payload:
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  transcription.completed:
+    kind: llm.call.completed
+    payload:
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id
+
+  mcp_tools.completed:
+    kind: mcp.connection.completed
+    payload:
+      span_id: span_id
+      trace_id: trace_id
+      parent_id: parent_id