traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/__init__.py

@@ -0,0 +1,72 @@
+"""traceforge — Agent event observation pipeline with pluggable storage backends."""
+
+from traceforge.adapters.base import Adapter, JsonLineAdapter
+from traceforge.adapters.mapped_json import MappedJsonAdapter
+from traceforge.adapters.otel import OtelSpanAdapter
+from traceforge.classify import (
+    ClassificationEngine,
+    Classification,
+    ClassifyConfig,
+    Phase,
+    Visibility,
+    classify_cmd_command,
+    classify_powershell_command,
+    classify_shell,
+    classify_tool,
+    get_default_registry,
+    load_config,
+    normalize_tool_name,
+)
+from traceforge.enricher import Enricher
+from traceforge.parsers.aider import AiderPreParser
+from traceforge.pipeline import EventPipeline
+from traceforge.sinks.base import StorageSink
+from traceforge.sinks.callback import CallbackSink
+from traceforge.trace import EventTrace
+from traceforge.types import (
+    KNOWN_KINDS,
+    EventKind,
+    EventMetadata,
+    IngestionMode,
+    SessionEvent,
+    TelemetrySpan,
+    TitleUpdate,
+    UsageRecord,
+    is_known_kind,
+)
+
+__all__ = [
+    # Adapters
+    "Adapter",
+    "JsonLineAdapter",
+    "MappedJsonAdapter",
+    "AiderPreParser",
+    "OtelSpanAdapter",
+    # Classification
+    "CallbackSink",
+    "Classification",
+    "ClassificationEngine",
+    "ClassifyConfig",
+    "Enricher",
+    "EventKind",
+    "EventMetadata",
+    "EventPipeline",
+    "IngestionMode",
+    "KNOWN_KINDS",
+    "Phase",
+    "SessionEvent",
+    "StorageSink",
+    "TelemetrySpan",
+    "EventTrace",
+    "TitleUpdate",
+    "UsageRecord",
+    "Visibility",
+    "classify_cmd_command",
+    "classify_powershell_command",
+    "classify_shell",
+    "classify_tool",
+    "get_default_registry",
+    "is_known_kind",
+    "load_config",
+    "normalize_tool_name",
+]

traceforge/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m traceforge` to invoke the CLI."""
+
+from traceforge.cli import main
+
+main()

traceforge/_generated.py

@@ -0,0 +1,254 @@
+# generated by datamodel-codegen:
+#   filename:  schema.yaml
+#   timestamp: 2026-06-14T10:43:42+00:00
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class EventKind(StrEnum):
+    agent_completed = "agent.completed"
+    agent_failed = "agent.failed"
+    agent_handoff = "agent.handoff"
+    agent_spawned = "agent.spawned"
+    browser_action = "browser.action"
+    browser_launched = "browser.launched"
+    browser_result = "browser.result"
+    checkpoint_created = "checkpoint.created"
+    checkpoint_restored = "checkpoint.restored"
+    command_completed = "command.completed"
+    command_failed = "command.failed"
+    command_output = "command.output"
+    command_started = "command.started"
+    file_created = "file.created"
+    file_deleted = "file.deleted"
+    file_edited = "file.edited"
+    file_read = "file.read"
+    guardrail_failed = "guardrail.failed"
+    guardrail_passed = "guardrail.passed"
+    guardrail_started = "guardrail.started"
+    hook_completed = "hook.completed"
+    hook_failed = "hook.failed"
+    hook_started = "hook.started"
+    input_received = "input.received"
+    input_requested = "input.requested"
+    knowledge_query_completed = "knowledge.query.completed"
+    knowledge_query_started = "knowledge.query.started"
+    llm_call_completed = "llm.call.completed"
+    llm_call_failed = "llm.call.failed"
+    llm_call_started = "llm.call.started"
+    llm_output_chunk = "llm.output.chunk"
+    llm_thinking_chunk = "llm.thinking.chunk"
+    mcp_connection_completed = "mcp.connection.completed"
+    mcp_connection_failed = "mcp.connection.failed"
+    mcp_connection_started = "mcp.connection.started"
+    memory_query_completed = "memory.query.completed"
+    memory_query_started = "memory.query.started"
+    memory_save_completed = "memory.save.completed"
+    memory_save_started = "memory.save.started"
+    message_assistant = "message.assistant"
+    message_assistant_chunk = "message.assistant.chunk"
+    message_system = "message.system"
+    message_user = "message.user"
+    permission_denied = "permission.denied"
+    permission_granted = "permission.granted"
+    permission_requested = "permission.requested"
+    planning_completed = "planning.completed"
+    planning_failed = "planning.failed"
+    planning_started = "planning.started"
+    raw = "raw"
+    reasoning_completed = "reasoning.completed"
+    reasoning_started = "reasoning.started"
+    session_abort = "session.abort"
+    session_ended = "session.ended"
+    session_error = "session.error"
+    session_idle = "session.idle"
+    session_info = "session.info"
+    session_paused = "session.paused"
+    session_resumed = "session.resumed"
+    session_started = "session.started"
+    session_warning = "session.warning"
+    skill_invoked = "skill.invoked"
+    task_completed = "task.completed"
+    task_failed = "task.failed"
+    task_started = "task.started"
+    telemetry_usage = "telemetry.usage"
+    tool_call_completed = "tool.call.completed"
+    tool_call_failed = "tool.call.failed"
+    tool_call_started = "tool.call.started"
+    tool_output = "tool.output"
+    tool_progress = "tool.progress"
+    tool_result_chunk = "tool.result.chunk"
+    tool_validation_failed = "tool.validation.failed"
+    turn_ended = "turn.ended"
+    turn_skipped = "turn.skipped"
+    turn_started = "turn.started"
+    workflow_completed = "workflow.completed"
+    workflow_failed = "workflow.failed"
+    workflow_started = "workflow.started"
+
+
+class Mechanism(StrEnum):
+    communication_system = "communication.system"
+    communication_user = "communication.user"
+    database = "database"
+    database_nosql = "database.nosql"
+    database_sql = "database.sql"
+    delegation_agent = "delegation.agent"
+    filesystem = "filesystem"
+    network_http = "network.http"
+    process = "process"
+    process_shell = "process.shell"
+    unknown = "unknown"
+
+
+class Effect(StrEnum):
+    destructive = "destructive"
+    mutating = "mutating"
+    read_only = "read_only"
+
+
+class Scope(StrEnum):
+    artifact_build_output = "artifact.build_output"
+    artifact_config = "artifact.config"
+    artifact_container_image = "artifact.container_image"
+    artifact_dependency = "artifact.dependency"
+    artifact_documentation = "artifact.documentation"
+    artifact_repository = "artifact.repository"
+    artifact_source_code = "artifact.source_code"
+    artifact_test_code = "artifact.test_code"
+    configuration_ci_cd = "configuration.ci_cd"
+    configuration_dependency = "configuration.dependency"
+    configuration_infrastructure = "configuration.infrastructure"
+    external_api = "external.api"
+    external_service = "external.service"
+    state_deployment = "state.deployment"
+    state_repository = "state.repository"
+    system_network = "system.network"
+    system_os = "system.os"
+    system_secrets = "system.secrets"
+
+
+class Role(StrEnum):
+    communicator_system_reporter = "communicator.system_reporter"
+    communicator_user_prompt = "communicator.user_prompt"
+    executor_container_runtime = "executor.container_runtime"
+    executor_script_runner = "executor.script_runner"
+    modifier_file_editor = "modifier.file_editor"
+    orchestrator_ci_cd = "orchestrator.ci_cd"
+    orchestrator_package_manager = "orchestrator.package_manager"
+    orchestrator_task_runner = "orchestrator.task_runner"
+    persistence_cache = "persistence.cache"
+    persistence_database = "persistence.database"
+    persistence_version_control = "persistence.version_control"
+    retriever_api_client = "retriever.api_client"
+    retriever_file_browser = "retriever.file_browser"
+    retriever_search_index = "retriever.search_index"
+    retriever_web_scraper = "retriever.web_scraper"
+    validator_security_scanner = "validator.security_scanner"
+    validator_test_runner = "validator.test_runner"
+
+
+class Action(StrEnum):
+    analyze = "analyze"
+    analyze_diff = "analyze.diff"
+    analyze_measure = "analyze.measure"
+    analyze_profile = "analyze.profile"
+    configure = "configure"
+    configure_install = "configure.install"
+    configure_provision = "configure.provision"
+    configure_setup = "configure.setup"
+    deliver = "deliver"
+    deliver_deploy = "deliver.deploy"
+    deliver_publish = "deliver.publish"
+    deliver_push = "deliver.push"
+    deliver_release = "deliver.release"
+    execute = "execute"
+    execute_repl = "execute.repl"
+    execute_run_script = "execute.run_script"
+    execute_script = "execute.script"
+    execute_service = "execute.service"
+    generate = "generate"
+    generate_code = "generate.code"
+    generate_documentation = "generate.documentation"
+    generate_scaffold = "generate.scaffold"
+    modify = "modify"
+    modify_edit = "modify.edit"
+    modify_merge = "modify.merge"
+    modify_rebase = "modify.rebase"
+    persist = "persist"
+    persist_commit = "persist.commit"
+    persist_install = "persist.install"
+    persist_stage = "persist.stage"
+    persist_write = "persist.write"
+    remove = "remove"
+    remove_clean = "remove.clean"
+    remove_delete = "remove.delete"
+    remove_teardown = "remove.teardown"
+    remove_uninstall = "remove.uninstall"
+    retrieve = "retrieve"
+    retrieve_browse = "retrieve.browse"
+    retrieve_diff = "retrieve.diff"
+    retrieve_query = "retrieve.query"
+    retrieve_read = "retrieve.read"
+    retrieve_search = "retrieve.search"
+    transform = "transform"
+    transform_bundle = "transform.bundle"
+    transform_compile = "transform.compile"
+    transform_format = "transform.format"
+    transform_refactor = "transform.refactor"
+    transform_transpile = "transform.transpile"
+    validate = "validate"
+    validate_build_check = "validate.build_check"
+    validate_lint = "validate.lint"
+    validate_security_scan = "validate.security_scan"
+    validate_test = "validate.test"
+    validate_typecheck = "validate.typecheck"
+
+
+class Capability(StrEnum):
+    budget_pressure = "budget_pressure"
+    credential_exposure = "credential_exposure"
+    elevated_privilege = "elevated_privilege"
+    filesystem_read = "filesystem_read"
+    filesystem_write = "filesystem_write"
+    human_interaction = "human_interaction"
+    integrity_unverified = "integrity_unverified"
+    mcp_drift = "mcp_drift"
+    network_inbound = "network_inbound"
+    network_outbound = "network_outbound"
+    pii_exposure = "pii_exposure"
+    subprocess = "subprocess"
+    uses_credentials = "uses_credentials"
+
+
+class Structure(StrEnum):
+    conditional = "conditional"
+    ifc_violation = "ifc_violation"
+    interactive = "interactive"
+    parallel = "parallel"
+    phase_anomaly = "phase_anomaly"
+    piped = "piped"
+    sequential = "sequential"
+    tainted_flow = "tainted_flow"
+
+
+class RiskBand(StrEnum):
+    safe = "safe"
+    caution = "caution"
+    danger = "danger"
+    critical = "critical"
+    unknown = "unknown"
+
+
+class Recommendation(StrEnum):
+    allow = "allow"
+    deny = "deny"
+    escalate = "escalate"
+    warn = "warn"
+
+
+class Decision(StrEnum):
+    allow = "allow"
+    deny = "deny"

traceforge/adapters/__init__.py

@@ -0,0 +1,12 @@
+"""Adapters for parsing raw agent output into SessionEvents."""
+
+from traceforge.adapters.base import Adapter, JsonLineAdapter
+from traceforge.adapters.mapped_json import MappedJsonAdapter
+from traceforge.adapters.otel import OtelSpanAdapter
+
+__all__ = [
+    "Adapter",
+    "JsonLineAdapter",
+    "MappedJsonAdapter",
+    "OtelSpanAdapter",
+]

traceforge/adapters/base.py

@@ -0,0 +1,82 @@
+"""Base adapter interfaces for parsing raw input into SessionEvents."""
+
+from __future__ import annotations
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from typing import Any
+
+from traceforge.types import SessionEvent
+
+logger = logging.getLogger(__name__)
+
+
+class Adapter(ABC):
+    """Root interface: parse raw bytes/str into SessionEvents."""
+
+    @abstractmethod
+    def parse(self, raw: bytes | str) -> Iterator[SessionEvent]:
+        """Parse raw input and yield zero or more SessionEvents.
+
+        Must never raise — log warnings for unparseable input and continue.
+        """
+        ...
+
+
+class JsonLineAdapter(Adapter):
+    """Base for adapters that consume one JSON object per line.
+
+    Handles the common boilerplate:
+    - bytes → str decoding
+    - JSON parsing with error logging
+    - dict validation
+    - Delegates to ``parse_dict()`` which subclasses implement
+
+    The parsed dict is automatically attached as ``raw_event`` on every
+    SessionEvent yielded by ``parse_dict()``.
+    """
+
+    @abstractmethod
+    def parse_dict(self, obj: dict[str, Any]) -> Iterator[SessionEvent]:
+        """Convert a parsed JSON dict into SessionEvents.
+
+        Subclasses implement framework-specific deserialization here.
+        The ``raw_event`` field is set automatically by the base class.
+        """
+        ...
+
+    def parse(self, raw: bytes | str) -> Iterator[SessionEvent]:
+        if isinstance(raw, bytes):
+            try:
+                text = raw.decode("utf-8")
+            except (UnicodeDecodeError, ValueError):
+                logger.warning("%s: failed to decode bytes as UTF-8", self.__class__.__name__)
+                return
+        else:
+            text = raw
+        text = text.strip()
+        if not text:
+            return
+
+        try:
+            obj = json.loads(text)
+        except (json.JSONDecodeError, ValueError):
+            logger.warning("%s: failed to parse JSON line", self.__class__.__name__)
+            return
+
+        if not isinstance(obj, dict):
+            logger.warning(
+                "%s: expected JSON object, got %s", self.__class__.__name__, type(obj).__name__
+            )
+            return
+
+        try:
+            for event in self.parse_dict(obj):
+                if event.raw_event is None:
+                    yield event.model_copy(update={"raw_event": obj})
+                else:
+                    yield event
+        except Exception as exc:
+            logger.warning("%s: parse_dict raised: %s", self.__class__.__name__, exc)

traceforge/adapters/genai_otel.py

@@ -0,0 +1,164 @@
+"""Generic GenAI OTel adapter — universal receiver for gen_ai.* semantic conventions.
+
+Handles any framework following OpenTelemetry GenAI semantic conventions:
+- AutoGen, Semantic Kernel, Vercel AI SDK, Mastra, Agno, Codex CLI (OTel mode)
+
+When tool arguments are absent (most frameworks gate them as "sensitive"),
+the adapter still emits events but flags governance confidence as LOW.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from datetime import datetime, timezone
+from typing import Any
+
+from traceforge.adapters.base import Adapter
+from traceforge.types import EventKind, EventMetadata, SessionEvent
+
+logger = logging.getLogger(__name__)
+
+# GenAI semantic convention attribute keys
+_TOOL_NAME = "gen_ai.tool.name"
+_TOOL_CALL_ID = "gen_ai.tool.call.id"
+_TOOL_ARGUMENTS = "gen_ai.tool.call.arguments"
+_TOOL_RESULT = "gen_ai.tool.call.result"
+_TOOL_DESCRIPTION = "gen_ai.tool.description"
+_OPERATION = "gen_ai.operation.name"
+_SYSTEM = "gen_ai.system"
+_MODEL = "gen_ai.request.model"
+_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+
+
+class GenAIOtelAdapter(Adapter):
+    """Ingests OTel spans following GenAI semantic conventions.
+
+    Works with any framework that emits gen_ai.* attributes on spans.
+    Extracts tool calls, model invocations, and agent operations.
+    """
+
+    def __init__(self, session_id: str | None = None) -> None:
+        self._session_id = session_id or "otel-session"
+
+    def parse(self, raw: str | bytes) -> Iterator[SessionEvent]:
+        """Parse a JSON string containing one or more OTel spans."""
+        import json
+
+        if isinstance(raw, bytes):
+            try:
+                raw = raw.decode("utf-8")
+            except (UnicodeDecodeError, ValueError):
+                return
+
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            return
+
+        if isinstance(data, dict):
+            yield from self._parse_span(data)
+        elif isinstance(data, list):
+            for item in data:
+                if isinstance(item, dict):
+                    yield from self._parse_span(item)
+
+    def _parse_span(self, span: dict[str, Any]) -> Iterator[SessionEvent]:
+        """Convert a single OTel span dict to SessionEvent(s)."""
+        attributes = _normalize_attributes(span.get("attributes", {}))
+        operation = attributes.get(_OPERATION, "")
+        tool_name = attributes.get(_TOOL_NAME)
+
+        # Determine event kind
+        if tool_name or operation == "execute_tool":
+            kind = EventKind.TOOL_CALL
+        elif operation in ("chat", "text_completion", "generate"):
+            kind = EventKind.LLM_CALL
+        else:
+            kind = EventKind.RAW
+
+        # Extract timestamp
+        start_ns = span.get("startTimeUnixNano") or span.get("start_time_unix_nano")
+        if start_ns:
+            timestamp = datetime.fromtimestamp(int(start_ns) / 1_000_000_000, tz=timezone.utc)
+        else:
+            timestamp = datetime.now(timezone.utc)
+
+        # Build payload
+        payload: dict[str, Any] = {}
+        if tool_name:
+            payload["tool_name"] = tool_name
+
+        tool_args = attributes.get(_TOOL_ARGUMENTS)
+        if tool_args:
+            payload["arguments"] = tool_args
+
+        tool_result = attributes.get(_TOOL_RESULT)
+        if tool_result:
+            payload["result"] = tool_result
+
+        tool_call_id = attributes.get(_TOOL_CALL_ID)
+        if tool_call_id:
+            payload["tool_call_id"] = tool_call_id
+
+        system = attributes.get(_SYSTEM)
+        if system:
+            payload["system"] = system
+
+        model = attributes.get(_MODEL)
+        if model:
+            payload["model"] = model
+
+        # Flag confidence based on data completeness
+        has_args = bool(tool_args)
+        payload["governance_confidence"] = "high" if has_args else "low"
+        if not has_args and tool_name:
+            payload["governance_note"] = (
+                "Tool arguments not included in span — governance classification is best-effort. "
+                "Enable sensitive content export in your framework for full governance."
+            )
+
+        # Session ID from span attributes or default
+        session_id = (
+            attributes.get("session.id")
+            or attributes.get("gen_ai.session.id")
+            or span.get("traceId", "")[:16]
+            or self._session_id
+        )
+
+        metadata = EventMetadata(
+            source_framework=system or "genai-otel",
+            ingestion_mode="stream",
+            raw_kind=span.get("name", ""),
+            span_id=span.get("spanId") or span.get("span_id"),
+            parent_id=span.get("parentSpanId") or span.get("parent_span_id"),
+        )
+
+        yield SessionEvent(
+            kind=kind,
+            session_id=session_id,
+            timestamp=timestamp,
+            payload=payload,
+            metadata=metadata,
+            raw_event=span,
+        )
+
+
+def _normalize_attributes(attrs: Any) -> dict[str, Any]:
+    """Normalize OTel attributes from either list-of-dicts or flat dict format."""
+    if isinstance(attrs, dict):
+        return attrs
+    if isinstance(attrs, list):
+        result: dict[str, Any] = {}
+        for item in attrs:
+            if isinstance(item, dict) and "key" in item:
+                val = item.get("value", {})
+                if isinstance(val, dict):
+                    for v in val.values():
+                        result[item["key"]] = v
+                        break
+                else:
+                    result[item["key"]] = val
+        return result
+    return {}