traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/classify/data/tool_classifications.yaml

@@ -0,0 +1,215 @@
+# Native tool classifications — maps canonical tool names to Classification objects.
+# Mechanism reflects the RESOURCE DOMAIN the tool accesses (not implementation).
+
+tool_classifications:
+  view:
+    mechanism: filesystem
+    effect: read_only
+    scope: [artifact.source_code]
+    role: [retriever.file_browser]
+    action: [retrieve.read]
+    capability: [filesystem_read]
+
+  edit:
+    mechanism: filesystem
+    effect: mutating
+    scope: [artifact.source_code]
+    role: [modifier.file_editor]
+    action: [modify.edit]
+    capability: [filesystem_write]
+
+  create:
+    mechanism: filesystem
+    effect: mutating
+    scope: [artifact.source_code]
+    role: [modifier.file_editor]
+    action: [persist.write]
+    capability: [filesystem_write]
+
+  grep:
+    mechanism: filesystem
+    effect: read_only
+    scope: [artifact.source_code]
+    role: [retriever.search_index]
+    action: [retrieve.search]
+    capability: [filesystem_read]
+
+  glob:
+    mechanism: filesystem
+    effect: read_only
+    scope: [artifact.source_code]
+    role: [retriever.file_browser]
+    action: [retrieve.browse]
+    capability: [filesystem_read]
+
+  git_commit:
+    mechanism: process.shell
+    effect: mutating
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [persist.commit]
+    capability: [filesystem_write]
+
+  git_push:
+    mechanism: process.shell
+    effect: mutating
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [deliver.push]
+    capability: [filesystem_write, network_outbound]
+
+  git_diff:
+    mechanism: process.shell
+    effect: read_only
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [retrieve.diff]
+    capability: [filesystem_read]
+
+  git_status:
+    mechanism: process.shell
+    effect: read_only
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [retrieve.browse]
+    capability: [filesystem_read]
+
+  git_log:
+    mechanism: process.shell
+    effect: read_only
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [retrieve.browse]
+    capability: [filesystem_read]
+
+  git_add:
+    mechanism: process.shell
+    effect: mutating
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [persist.stage]
+    capability: [filesystem_write]
+
+  git_pull:
+    mechanism: process.shell
+    effect: mutating
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [retrieve]
+    capability: [filesystem_write, network_outbound]
+
+  git_merge:
+    mechanism: process.shell
+    effect: mutating
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [modify.merge]
+    capability: [filesystem_write]
+
+  git_rebase:
+    mechanism: process.shell
+    effect: mutating
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [modify.rebase]
+    capability: [filesystem_write]
+
+  git_checkout:
+    mechanism: process.shell
+    effect: mutating
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [retrieve.browse]
+    capability: [filesystem_write]
+
+  git_branch:
+    mechanism: process.shell
+    effect: read_only
+    scope: [artifact.repository]
+    role: [persistence.version_control]
+    action: [retrieve.browse]
+    capability: [filesystem_read]
+
+  report_intent:
+    mechanism: communication.system
+    effect: read_only
+    role: [communicator.system_reporter]
+    action: []
+    capability: []
+
+  ask_user:
+    mechanism: communication.user
+    effect: read_only
+    role: [communicator.user_prompt]
+    action: []
+    capability: [human_interaction]
+
+  web_fetch:
+    mechanism: network.http
+    effect: read_only
+    role: [retriever.web_scraper]
+    action: [retrieve]
+    capability: [network_outbound]
+
+  web_search:
+    mechanism: network.http
+    effect: read_only
+    role: [retriever.search_index]
+    action: [retrieve.search]
+    capability: [network_outbound]
+
+  task:
+    mechanism: delegation.agent
+    role: []
+    action: []
+    capability: [subprocess]
+
+  shell:
+    mechanism: process.shell
+    role: [executor.script_runner]
+    action: [execute.run_script]
+    capability: [subprocess]
+
+  think:
+    mechanism: communication.system
+    effect: read_only
+    role: [communicator.system_reporter]
+    action: [analyze]
+    capability: []
+
+  state_write:
+    mechanism: communication.system
+    effect: mutating
+    role: [communicator.system_reporter]
+    action: [persist]
+    capability: []
+
+  state_read:
+    mechanism: communication.system
+    effect: read_only
+    role: [communicator.system_reporter]
+    action: [retrieve]
+    capability: []
+
+  web_browse:
+    mechanism: network.http
+    effect: read_only
+    role: [retriever.web_scraper]
+    action: [retrieve.browse]
+    capability: [network_outbound, human_interaction]
+
+  codebase_search:
+    mechanism: filesystem
+    effect: read_only
+    scope: [artifact.source_code]
+    role: [retriever.search_index]
+    action: [retrieve.search]
+    capability: [filesystem_read]
+
+  delete_file:
+    mechanism: filesystem
+    effect: destructive
+    scope: [artifact.source_code]
+    role: [modifier.file_editor]
+    action: [remove]
+    capability: [filesystem_write]

traceforge/classify/data/verb_inference.yaml

@@ -0,0 +1,218 @@
+# Verb prefix → (effect, action) inference for MCP tool names.
+# When a tool name contains a recognized verb prefix, these defaults apply.
+# Used by mcp.py for tools not matched by any server profile.
+
+verb_inference:
+  # ─── Read-only verbs ─────────────────────────────────────────────────────────
+  get:
+    effect: read_only
+    action: retrieve
+  list:
+    effect: read_only
+    action: retrieve
+  read:
+    effect: read_only
+    action: retrieve
+  search:
+    effect: read_only
+    action: retrieve
+  query:
+    effect: read_only
+    action: retrieve
+  describe:
+    effect: read_only
+    action: analyze
+  fetch:
+    effect: read_only
+    action: retrieve
+  browse:
+    effect: read_only
+    action: retrieve
+  find:
+    effect: read_only
+    action: retrieve
+  show:
+    effect: read_only
+    action: retrieve
+  inspect:
+    effect: read_only
+    action: analyze
+  check:
+    effect: read_only
+    action: validate
+  scan:
+    effect: read_only
+    action: validate
+  view:
+    effect: read_only
+    action: retrieve
+
+  # ─── Mutating verbs (create/modify) ─────────────────────────────────────────
+  create:
+    effect: mutating
+    action: generate
+  update:
+    effect: mutating
+    action: modify
+  write:
+    effect: mutating
+    action: persist
+  set:
+    effect: mutating
+    action: persist
+  add:
+    effect: mutating
+    action: persist
+  append:
+    effect: mutating
+    action: persist
+  apply:
+    effect: mutating
+    action: execute
+  run:
+    effect: mutating
+    action: execute
+  execute:
+    effect: mutating
+    action: execute
+  start:
+    effect: mutating
+    action: execute
+  trigger:
+    effect: mutating
+    action: execute
+  deploy:
+    effect: mutating
+    action: deliver
+  publish:
+    effect: mutating
+    action: deliver
+  push:
+    effect: mutating
+    action: deliver
+  send:
+    effect: mutating
+    action: deliver
+  post:
+    effect: mutating
+    action: deliver
+  submit:
+    effect: mutating
+    action: deliver
+  upload:
+    effect: mutating
+    action: deliver
+  fork:
+    effect: mutating
+    action: generate
+  star:
+    effect: mutating
+    action: persist
+  assign:
+    effect: mutating
+    action: modify
+  merge:
+    effect: mutating
+    action: modify
+  approve:
+    effect: mutating
+    action: modify
+  dismiss:
+    effect: mutating
+    action: modify
+  resolve:
+    effect: mutating
+    action: modify
+  configure:
+    effect: mutating
+    action: configure
+  install:
+    effect: mutating
+    action: configure
+  scale:
+    effect: mutating
+    action: configure
+  build:
+    effect: mutating
+    action: transform
+  pull:
+    effect: mutating
+    action: retrieve
+  edit:
+    effect: mutating
+    action: modify
+  replace:
+    effect: mutating
+    action: modify
+  rename:
+    effect: mutating
+    action: modify
+  restore:
+    effect: mutating
+    action: modify
+  archive:
+    effect: mutating
+    action: modify
+  manage:
+    effect: mutating
+    action: modify
+  move:
+    effect: mutating
+    action: modify
+
+  # ─── Mutating verbs (browser/UI interaction) ────────────────────────────────
+  navigate:
+    effect: mutating
+    action: execute
+  click:
+    effect: mutating
+    action: execute
+  type:
+    effect: mutating
+    action: execute
+  fill:
+    effect: mutating
+    action: execute
+  select:
+    effect: mutating
+    action: execute
+  hover:
+    effect: mutating
+    action: execute
+  press:
+    effect: mutating
+    action: execute
+  drag:
+    effect: mutating
+    action: execute
+
+  # ─── Destructive verbs ──────────────────────────────────────────────────────
+  delete:
+    effect: destructive
+    action: remove
+  destroy:
+    effect: destructive
+    action: remove
+  drop:
+    effect: destructive
+    action: remove
+  remove:
+    effect: destructive
+    action: remove
+  clear:
+    effect: destructive
+    action: remove
+  terminate:
+    effect: destructive
+    action: remove
+
+  # ─── Lifecycle/cancel ───────────────────────────────────────────────────────
+  unstar:
+    effect: mutating
+    action: modify
+  stop:
+    effect: mutating
+    action: execute
+  cancel:
+    effect: mutating
+    action: execute

traceforge/classify/mcp.py

@@ -0,0 +1,181 @@
+"""MCP (Model Context Protocol) tool classification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from traceforge.classify.core import Classification
+from traceforge.classify.phases import with_phase_map
+
+if TYPE_CHECKING:
+    from traceforge.classify.config import ClassificationEngine
+
+
+@dataclass(frozen=True)
+class McpToolOverride:
+    """Per-tool classification override within an MCP server profile."""
+
+    effect: str | None = None
+    mechanism: str | None = None
+    role: frozenset[str] | None = None
+    action: frozenset[str] | None = None
+    scope: frozenset[str] | None = None
+    capability: frozenset[str] | None = None
+
+
+@dataclass(frozen=True)
+class McpServerProfile:
+    """Classification profile for a known MCP server."""
+
+    namespace_aliases: tuple[str, ...]
+    mechanism: str
+    role: frozenset[str] = frozenset()
+    default_effect: str | None = None
+    scope: frozenset[str] = frozenset()
+    action: frozenset[str] = frozenset()
+    capability: frozenset[str] = frozenset()
+    tool_overrides: dict[str, McpToolOverride] = field(default_factory=dict)
+
+
+def extract_mcp_namespace(raw_name: str) -> str:
+    """Extract the MCP server namespace from a raw tool name."""
+    name = raw_name.strip()
+    if name.startswith("mcp__"):
+        parts = name.split("__", 2)
+        if len(parts) == 3:
+            return parts[1].lower()
+    return ""
+
+
+def _normalize_mcp_suffix(raw_name: str) -> str:
+    """Extract and normalize the tool suffix from an MCP tool name."""
+    name = raw_name.strip()
+    if name.startswith("mcp__"):
+        parts = name.split("__", 2)
+        if len(parts) == 3:
+            return parts[2].lower().replace("-", "_")
+    return name.lower().replace("-", "_")
+
+
+def _infer_from_verb(
+    tool_suffix: str,
+    *,
+    engine: ClassificationEngine,
+) -> tuple[str | None, str | None]:
+    """Infer effect and action from tool name verb prefix."""
+    verb_map = engine.verb_inference
+    lower = tool_suffix.lower()
+    for verb, (effect, action) in verb_map.items():
+        if lower.startswith(verb + "_") or lower == verb:
+            return effect, action
+    return None, None
+
+
+_EFFECT_SEVERITY: dict[str | None, int] = {
+    None: 0,
+    "null": 0,
+    "read_only": 1,
+    "mutating": 2,
+    "destructive": 3,
+}
+
+_WRITE_EFFECTS = frozenset({"mutating", "destructive"})
+_FS_MECHANISMS = frozenset({"filesystem", "filesystem.local", "filesystem.remote"})
+
+
+def _build_classification(
+    profile: McpServerProfile,
+    override: McpToolOverride | None,
+    tool_suffix: str,
+    *,
+    engine: ClassificationEngine,
+) -> Classification:
+    """Build a Classification from profile defaults plus any tool override."""
+    mechanism = profile.mechanism
+    role = profile.role
+    scope = profile.scope
+    action = profile.action
+    capability = profile.capability
+    effect = profile.default_effect
+
+    if override is not None:
+        if override.mechanism is not None:
+            mechanism = override.mechanism
+        if override.role is not None:
+            role = override.role
+        if override.scope is not None:
+            scope = override.scope
+        if override.action is not None:
+            action = override.action
+        if override.capability is not None:
+            capability = override.capability
+        if override.effect is not None:
+            effect = override.effect
+
+    verb_effect, verb_action = _infer_from_verb(tool_suffix, engine=engine)
+    if verb_effect is None:
+        for alias in profile.namespace_aliases:
+            prefix = alias + "_"
+            if tool_suffix.startswith(prefix):
+                verb_effect, verb_action = _infer_from_verb(
+                    tool_suffix[len(prefix) :],
+                    engine=engine,
+                )
+                if verb_effect is not None:
+                    break
+    # Verb inference: upgrade effect when inferred verb is more dangerous than
+    # the profile default (destructive > mutating > read_only > null).
+    # Explicit per-tool overrides take priority over verb inference.
+    has_explicit_override = override is not None and override.effect is not None
+    if not has_explicit_override and verb_effect is not None:
+        if _EFFECT_SEVERITY.get(verb_effect, 0) > _EFFECT_SEVERITY.get(effect, 0):
+            effect = verb_effect
+    elif effect is None and verb_effect is not None:
+        effect = verb_effect
+
+    has_action_override = override is not None and override.action is not None
+    if not has_action_override and verb_action is not None:
+        action = frozenset({verb_action}) | action
+
+    # When verb inference upgraded the effect, ensure capabilities are consistent.
+    if (
+        effect in _WRITE_EFFECTS
+        and mechanism in _FS_MECHANISMS
+        and "filesystem_write" not in capability
+    ):
+        capability = capability | frozenset({"filesystem_write"})
+        # Upgrade role from retriever → modifier.file_editor for filesystem write ops
+        if any(r.startswith("retriever.") for r in role):
+            upgraded = frozenset(
+                "modifier.file_editor" if r.startswith("retriever.") else r for r in role
+            )
+            role = upgraded
+
+    return Classification(
+        mechanism=mechanism,
+        effect=effect,
+        scope=scope,
+        role=role,
+        action=action,
+        capability=capability,
+    )
+
+
+def classify_mcp_tool(
+    raw_name: str,
+    *,
+    engine: ClassificationEngine,
+) -> Classification | None:
+    """Classify a tool using engine-provided MCP server profiles."""
+    namespace = extract_mcp_namespace(raw_name)
+    tool_suffix = _normalize_mcp_suffix(raw_name)
+
+    alias_index = engine.mcp_alias_index
+    profile = alias_index.get(namespace) if namespace else None
+    if profile is None:
+        return None
+
+    override = profile.tool_overrides.get(tool_suffix)
+    cls = _build_classification(profile, override, tool_suffix, engine=engine)
+    return with_phase_map(cls)

traceforge/classify/phases.py

@@ -0,0 +1,75 @@
+"""Phase derivation logic — shared across tool, MCP, and shell classifiers.
+
+Extracted to its own module to avoid circular imports between tools.py and mcp.py.
+"""
+
+from __future__ import annotations
+
+from traceforge.classify.core import Classification, PhaseSegment
+from traceforge.classify.workflow import Phase
+
+# Rule table: (predicate, phase) — evaluated in order, first match wins for single-phase
+_DERIVE_RULES: list[tuple[str, str, str]] = [
+    # (kind, value, phase)
+    ("action", "validate", Phase.VERIFICATION),
+    ("action", "deliver", Phase.REVIEW),
+    ("action", "retrieve", Phase.EXPLORATION),
+    ("action", "analyze", Phase.EXPLORATION),
+    ("action", "configure", Phase.IMPLEMENTATION),
+    ("action", "execute", Phase.IMPLEMENTATION),
+    ("action", "modify", Phase.IMPLEMENTATION),
+    ("action", "persist", Phase.IMPLEMENTATION),
+]
+
+
+def derive_phase(cls: Classification) -> str:
+    """Derive a single phase for a tool classification.
+
+    Uses a rule table consistent with _phases_from_classification in the enricher.
+    Returns the first matching phase; VCS persist/deliver is special-cased to REVIEW.
+    """
+    # Special case: VCS persist/deliver → review
+    if cls.has_role("persistence.version_control") and (
+        cls.has_action("persist") or cls.has_action("deliver")
+    ):
+        return Phase.REVIEW
+
+    for kind, value, phase in _DERIVE_RULES:
+        if kind == "action" and cls.has_action(value):
+            return phase
+
+    # Mechanism-based fallbacks
+    if cls.mechanism.startswith("communication"):
+        return Phase.PLANNING
+    if cls.mechanism.startswith("delegation"):
+        return Phase.IMPLEMENTATION
+    if cls.mechanism == "filesystem" and cls.effect == "read_only":
+        return Phase.EXPLORATION
+    return Phase.IMPLEMENTATION
+
+
+def with_phase_map(cls: Classification) -> Classification:
+    """Add a single-segment phase_map to a Classification.
+
+    Reuses derive_phase() to keep phase assignment consistent across all
+    tool types (native, MCP, shell single-command).
+    """
+    phase = derive_phase(cls)
+    seg = PhaseSegment(
+        phase=phase,
+        actions=cls.action,
+        scopes=cls.scope,
+        roles=cls.role,
+    )
+    return Classification(
+        mechanism=cls.mechanism,
+        effect=cls.effect,
+        scope=cls.scope,
+        role=cls.role,
+        action=cls.action,
+        capability=cls.capability,
+        structure=cls.structure,
+        shell_dialect=cls.shell_dialect,
+        binaries=cls.binaries,
+        phase_map=(seg,),
+    )