fableforge-agent-profiler 0.1.0__py3-none-any.whl

agent_profiler/__init__.py

@@ -0,0 +1,13 @@
+"""Agent Profiler - Profile and classify agent behavior patterns."""
+
+from agent_profiler.profiler import AgentProfiler, ProfileResult
+from agent_profiler.classifier import BehaviorClassifier
+from agent_profiler.visualizer import ProfileVisualizer
+
+__all__ = [
+    "AgentProfiler",
+    "ProfileResult",
+    "BehaviorClassifier",
+    "ProfileVisualizer",
+]
+__version__ = "0.1.0"

agent_profiler/classifier.py

@@ -0,0 +1,266 @@
+"""Behavior classification using pretrained profiles and transition matrices."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+
+@dataclass
+class BehaviorProfile:
+    """A predefined behavior profile template."""
+
+    name: str
+    description: str
+    edit_weight: float = 0.0
+    read_weight: float = 0.0
+    grep_weight: float = 0.0
+    bash_weight: float = 0.0
+    write_weight: float = 0.0
+    error_rate_weight: float = 0.0
+    error_recovery_weight: float = 0.0
+    circular_weight: float = 0.0
+    entropy_weight: float = 0.0
+    min_turns: int = 0
+
+
+class DebuggingProfile(BehaviorProfile):
+    """Profile for debugging sessions: high edit+bash, many errors, recoveries."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="debugging",
+            description="Active debugging with edits and error recovery loops",
+            edit_weight=0.25,
+            read_weight=0.15,
+            grep_weight=0.10,
+            bash_weight=0.30,
+            write_weight=0.05,
+            error_rate_weight=0.40,
+            error_recovery_weight=0.35,
+            circular_weight=0.20,
+            entropy_weight=0.15,
+            min_turns=5,
+        )
+
+
+class BuildingProfile(BehaviorProfile):
+    """Profile for productive building: high write+bash, low read."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="building",
+            description="Active feature development with writes and executions",
+            edit_weight=0.15,
+            read_weight=0.10,
+            grep_weight=0.05,
+            bash_weight=0.25,
+            write_weight=0.30,
+            error_rate_weight=-0.10,
+            error_recovery_weight=0.10,
+            circular_weight=0.05,
+            entropy_weight=0.20,
+            min_turns=3,
+        )
+
+
+class ExploringProfile(BehaviorProfile):
+    """Profile for exploration: high read+grep, low edit."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="exploring",
+            description="Code exploration with reads and searches, minimal edits",
+            edit_weight=0.05,
+            read_weight=0.35,
+            grep_weight=0.30,
+            bash_weight=0.10,
+            write_weight=0.02,
+            error_rate_weight=-0.20,
+            error_recovery_weight=0.05,
+            circular_weight=0.10,
+            entropy_weight=0.25,
+            min_turns=3,
+        )
+
+
+class LostProfile(BehaviorProfile):
+    """Profile for lost/confused sessions: circular transitions, high read."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="lost",
+            description="Confused or circular behavior, reading without progress",
+            edit_weight=0.05,
+            read_weight=0.35,
+            grep_weight=0.15,
+            bash_weight=0.05,
+            write_weight=0.02,
+            error_rate_weight=0.10,
+            error_recovery_weight=-0.10,
+            circular_weight=0.40,
+            entropy_weight=0.10,
+            min_turns=5,
+        )
+
+
+class VerifyingProfile(BehaviorProfile):
+    """Profile for verification: read after edit, test runs."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="verifying",
+            description="Verifying changes with reads after edits and test execution",
+            edit_weight=0.20,
+            read_weight=0.30,
+            grep_weight=0.10,
+            bash_weight=0.25,
+            write_weight=0.05,
+            error_rate_weight=-0.05,
+            error_recovery_weight=0.25,
+            circular_weight=0.15,
+            entropy_weight=0.15,
+            min_turns=4,
+        )
+
+
+class BehaviorClassifier:
+    """Classify agent behavior using pretrained profiles and scoring."""
+
+    def __init__(self) -> None:
+        self.profiles: dict[str, BehaviorProfile] = {
+            "debugging": DebuggingProfile(),
+            "building": BuildingProfile(),
+            "exploring": ExploringProfile(),
+            "lost": LostProfile(),
+            "verifying": VerifyingProfile(),
+        }
+
+    def compute_scores(
+        self,
+        edit_ratio: float = 0.0,
+        read_ratio: float = 0.0,
+        grep_ratio: float = 0.0,
+        bash_ratio: float = 0.0,
+        write_ratio: float = 0.0,
+        error_rate: float = 0.0,
+        error_recovery_rate: float = 0.0,
+        circular_ratio: float = 0.0,
+        entropy: float = 0.0,
+        num_turns: int = 0,
+    ) -> dict[str, float]:
+        """Compute profile scores for each behavior category.
+
+        Args:
+            edit_ratio: Ratio of edit tool calls.
+            read_ratio: Ratio of read tool calls.
+            grep_ratio: Ratio of grep/search tool calls.
+            bash_ratio: Ratio of bash/shell tool calls.
+            write_ratio: Ratio of write tool calls.
+            error_rate: Rate of errors in the session.
+            error_recovery_rate: Rate of error recovery.
+            circular_ratio: Ratio of circular tool transitions.
+            entropy: Entropy of tool distribution.
+            num_turns: Number of turns in the session.
+
+        Returns:
+            Dict mapping category name to confidence score (0-1).
+        """
+        scores: dict[str, float] = {}
+
+        features = {
+            "edit": edit_ratio,
+            "read": read_ratio,
+            "grep": grep_ratio,
+            "bash": bash_ratio,
+            "write": write_ratio,
+            "error_rate": error_rate,
+            "error_recovery": error_recovery_rate,
+            "circular": circular_ratio,
+            "entropy": entropy,
+        }
+
+        for name, profile in self.profiles.items():
+            profile_features = {
+                "edit": profile.edit_weight,
+                "read": profile.read_weight,
+                "grep": profile.grep_weight,
+                "bash": profile.bash_weight,
+                "write": profile.write_weight,
+                "error_rate": profile.error_rate_weight,
+                "error_recovery": profile.error_recovery_weight,
+                "circular": profile.circular_weight,
+                "entropy": profile.entropy_weight,
+            }
+
+            dot_product = sum(
+                features.get(k, 0.0) * profile_features.get(k, 0.0)
+                for k in set(list(features.keys()) + list(profile_features.keys()))
+            )
+
+            obs_vec = np.array([features.get(k, 0.0) for k in sorted(features.keys())])
+            prof_vec = np.array([profile_features.get(k, 0.0) for k in sorted(features.keys())])
+
+            obs_norm = np.linalg.norm(obs_vec)
+            prof_norm = np.linalg.norm(prof_vec)
+
+            if obs_norm > 0 and prof_norm > 0:
+                cosine_sim = float(np.dot(obs_vec, prof_vec) / (obs_norm * prof_norm))
+            else:
+                cosine_sim = 0.0
+
+            score = (dot_product + (cosine_sim + 1) / 2) / 2.0
+
+            if num_turns < profile.min_turns:
+                score *= 0.5
+
+            scores[name] = max(0.0, min(1.0, score))
+
+        total = sum(scores.values())
+        if total > 0:
+            scores = {k: v / total for k, v in scores.items()}
+
+        return scores
+
+    def classify(
+        self,
+        edit_ratio: float = 0.0,
+        read_ratio: float = 0.0,
+        grep_ratio: float = 0.0,
+        bash_ratio: float = 0.0,
+        write_ratio: float = 0.0,
+        error_rate: float = 0.0,
+        error_recovery_rate: float = 0.0,
+        circular_ratio: float = 0.0,
+        entropy: float = 0.0,
+        num_turns: int = 0,
+    ) -> tuple[str, float, dict[str, float]]:
+        """Classify behavior into a category.
+
+        Returns:
+            Tuple of (category, confidence, all_scores).
+        """
+        scores = self.compute_scores(
+            edit_ratio=edit_ratio,
+            read_ratio=read_ratio,
+            grep_ratio=grep_ratio,
+            bash_ratio=bash_ratio,
+            write_ratio=write_ratio,
+            error_rate=error_rate,
+            error_recovery_rate=error_recovery_rate,
+            circular_ratio=circular_ratio,
+            entropy=entropy,
+            num_turns=num_turns,
+        )
+        best = max(scores, key=scores.get)  # type: ignore[arg-type]
+        return best, scores[best], scores
+
+    def get_profile(self, name: str) -> BehaviorProfile | None:
+        """Get a profile by name."""
+        return self.profiles.get(name)
+
+    def list_profiles(self) -> dict[str, str]:
+        """List all available profiles with descriptions."""
+        return {name: p.description for name, p in self.profiles.items()}

agent_profiler/cli.py

@@ -0,0 +1,180 @@
+"""CLI for Agent Profiler."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.columns import Columns
+
+from agent_profiler.profiler import AgentProfiler
+from agent_profiler.classifier import BehaviorClassifier
+from agent_profiler.visualizer import ProfileVisualizer
+
+console = Console()
+
+
+@click.group()
+def cli() -> None:
+    """Agent Profiler - Profile and classify agent behavior patterns."""
+    pass
+
+
+@cli.command()
+@click.argument("trace_file", type=click.Path(exists=True))
+@click.option("--output", "-o", type=click.Path(), default=None, help="Output file path (JSON)")
+def profile(trace_file: str, output: str | None) -> None:
+    """Profile an agent session from a trace file."""
+    profiler = AgentProfiler()
+
+    with console.status("[bold green]Profiling session..."):
+        result = profiler.profile(trace_file)
+
+    category_colors = {
+        "debugging": "red", "building": "green", "exploring": "blue",
+        "lost": "yellow", "verifying": "magenta",
+    }
+    color = category_colors.get(result.category, "white")
+
+    console.print(Panel(
+        f"[bold {color}]{result.category.upper()}[/bold {color}]\n"
+        f"Confidence: {result.confidence:.1%}\n"
+        f"Turns: {result.num_turns}\n"
+        f"Duration: {result.session_duration:.0f}s\n"
+        f"Error Rate: {result.error_rate:.1%}\n"
+        f"Edit Ratio: {result.edit_ratio:.1%}\n"
+        f"Read Ratio: {result.read_ratio:.1%}\n"
+        f"Write Ratio: {result.write_ratio:.1%}\n"
+        f"Bash Ratio: {result.bash_ratio:.1%}\n"
+        f"Grep Ratio: {result.grep_ratio:.1%}",
+        title="Profile Result",
+    ))
+
+    if result.profile_scores:
+        score_table = Table(title="Profile Scores", show_lines=True)
+        score_table.add_column("Category", style="bold")
+        score_table.add_column("Score", justify="right")
+        score_table.add_column("Bar")
+
+        for cat, score in sorted(result.profile_scores.items(), key=lambda x: -x[1]):
+            bar_len = int(score * 20)
+            bar = "█" * bar_len + "░" * (20 - bar_len)
+            cat_color = category_colors.get(cat, "white")
+            is_best = cat == result.category
+            score_table.add_row(
+                f"[{cat_color}]{cat}[/{cat_color}]{' ←' if is_best else ''}",
+                f"{score:.1%}",
+                f"[{cat_color}]{bar}[/{cat_color}]",
+            )
+        console.print(score_table)
+
+    if result.tool_distribution.tool_counts:
+        tool_table = Table(title="Tool Distribution", show_lines=True)
+        tool_table.add_column("Tool", style="cyan")
+        tool_table.add_column("Count", justify="right")
+        tool_table.add_column("Frequency", justify="right")
+
+        for tool, count in sorted(result.tool_distribution.tool_counts.items(), key=lambda x: -x[1]):
+            freq = result.tool_distribution.frequencies.get(tool, 0.0)
+            tool_table.add_row(tool.title(), str(count), f"{freq:.1%}")
+        console.print(tool_table)
+
+    if output:
+        result_dict = {
+            "category": result.category,
+            "confidence": result.confidence,
+            "num_turns": result.num_turns,
+            "session_duration": result.session_duration,
+            "error_rate": result.error_rate,
+            "edit_ratio": result.edit_ratio,
+            "read_ratio": result.read_ratio,
+            "bash_ratio": result.bash_ratio,
+            "write_ratio": result.write_ratio,
+            "grep_ratio": result.grep_ratio,
+            "error_recovery_rate": result.error_recovery_rate,
+            "profile_scores": result.profile_scores,
+            "tool_distribution": {
+                "counts": result.tool_distribution.tool_counts,
+                "total_calls": result.tool_distribution.total_calls,
+                "entropy": result.tool_distribution.entropy,
+            },
+        }
+        Path(output).write_text(json.dumps(result_dict, indent=2))
+        console.print(f"\n[green]Results saved to {output}[/green]")
+
+
+@cli.command()
+@click.argument("trace_file", type=click.Path(exists=True))
+def classify(trace_file: str) -> None:
+    """Classify agent behavior from a trace file."""
+    profiler = AgentProfiler()
+
+    with console.status("[bold green]Classifying behavior..."):
+        result = profiler.profile(trace_file)
+
+    classifier = BehaviorClassifier()
+    profiles = classifier.list_profiles()
+
+    console.print(Panel(
+        f"[bold]Category: {result.category}[/bold]\n"
+        f"Confidence: {result.confidence:.1%}",
+        title="Classification Result",
+    ))
+
+    category_descriptions = {
+        "debugging": "Active debugging with edits and error recovery loops",
+        "building": "Active feature development with writes and executions",
+        "exploring": "Code exploration with reads and searches, minimal edits",
+        "lost": "Confused or circular behavior, reading without progress",
+        "verifying": "Verifying changes with reads after edits and test execution",
+    }
+
+    desc_table = Table(title="Profile Descriptions", show_lines=True)
+    desc_table.add_column("Profile", style="bold")
+    desc_table.add_column("Description")
+    desc_table.add_column("Your Score", justify="right")
+
+    for name, desc in profiles.items():
+        score = result.profile_scores.get(name, 0.0)
+        is_match = name == result.category
+        desc_table.add_row(
+            f"{'→ ' if is_match else '  '}{name}",
+            desc,
+            f"[bold]{score:.1%}[/bold]" if is_match else f"{score:.1%}",
+        )
+    console.print(desc_table)
+
+
+@cli.command()
+@click.argument("trace_file", type=click.Path(exists=True))
+@click.option("--output", "-o", type=click.Path(), default="profile_chart.png", help="Output image path")
+def visualize(trace_file: str, output: str) -> None:
+    """Generate visualization charts for an agent session."""
+    profiler = AgentProfiler()
+    visualizer = ProfileVisualizer()
+
+    with console.status("[bold green]Profiling and generating charts..."):
+        result = profiler.profile(trace_file)
+
+    console.print("[bold]Generating profile radar chart...[/bold]")
+    fig1 = visualizer.generate_profile_chart(result, output=output)
+    console.print(f"  [green]Saved: {output}[/green]")
+
+    heatmap_path = str(Path(output).with_name(Path(output).stem + "_heatmap.png"))
+    console.print("[bold]Generating transition heatmap...[/bold]")
+    fig2 = visualizer.generate_transition_heatmap(trace_file, output=heatmap_path)
+    console.print(f"  [green]Saved: {heatmap_path}[/green]")
+
+    pie_path = str(Path(output).with_name(Path(output).stem + "_tools.png"))
+    console.print("[bold]Generating tool distribution pie chart...[/bold]")
+    fig3 = visualizer.generate_tool_distribution_pie(trace_file, output=pie_path)
+    console.print(f"  [green]Saved: {pie_path}[/green]")
+
+
+if __name__ == "__main__":
+    cli()

agent_profiler/profiler.py

@@ -0,0 +1,308 @@
+"""Core profiler for analyzing agent sessions."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from agent_profiler.classifier import BehaviorClassifier
+
+
+@dataclass
+class ToolDistribution:
+    """Distribution of tool usage in a session."""
+
+    tool_counts: dict[str, int] = field(default_factory=dict)
+    total_calls: int = 0
+
+    @property
+    def frequencies(self) -> dict[str, float]:
+        if self.total_calls == 0:
+            return {}
+        return {tool: count / self.total_calls for tool, count in self.tool_counts.items()}
+
+    @property
+    def dominant_tool(self) -> str:
+        if not self.tool_counts:
+            return "none"
+        return max(self.tool_counts, key=self.tool_counts.get)  # type: ignore[arg-type]
+
+    @property
+    def entropy(self) -> float:
+        freqs = list(self.frequencies.values())
+        if not freqs or sum(freqs) == 0:
+            return 0.0
+        freqs_arr = np.array(freqs)
+        freqs_arr = freqs_arr[freqs_arr > 0]
+        return float(-np.sum(freqs_arr * np.log2(freqs_arr)))
+
+
+@dataclass
+class TransitionAnalysis:
+    """Analysis of tool transition patterns."""
+
+    transitions: dict[str, dict[str, int]] = field(default_factory=dict)
+    total_transitions: int = 0
+
+    @property
+    def transition_probabilities(self) -> dict[str, dict[str, float]]:
+        probs: dict[str, dict[str, float]] = {}
+        for from_tool, to_tools in self.transitions.items():
+            total = sum(to_tools.values())
+            if total > 0:
+                probs[from_tool] = {t: c / total for t, c in to_tools.items()}
+            else:
+                probs[from_tool] = {}
+        return probs
+
+    @property
+    def circular_ratio(self) -> float:
+        """Ratio of transitions that go back to a recently-used tool (A→B→A pattern)."""
+        if self.total_transitions == 0:
+            return 0.0
+        circular_count = 0
+        for from_tool, to_tools in self.transitions.items():
+            if from_tool in to_tools:
+                circular_count += to_tools[from_tool]
+        return circular_count / self.total_transitions
+
+
+@dataclass
+class ProfileResult:
+    """Result of agent session profiling."""
+
+    category: str                # debugging, building, exploring, lost, verifying
+    confidence: float            # 0.0 - 1.0
+    tool_distribution: ToolDistribution = field(default_factory=ToolDistribution)
+    transition_analysis: TransitionAnalysis = field(default_factory=TransitionAnalysis)
+    session_duration: float = 0.0    # seconds
+    num_turns: int = 0
+    error_rate: float = 0.0
+    edit_ratio: float = 0.0     # edit calls / total calls
+    read_ratio: float = 0.0     # read calls / total calls
+    grep_ratio: float = 0.0     # grep/search calls / total calls
+    bash_ratio: float = 0.0     # bash/shell calls / total calls
+    write_ratio: float = 0.0    # write calls / total calls
+    error_recovery_rate: float = 0.0
+    sub_categories: list[str] = field(default_factory=list)
+    profile_scores: dict[str, float] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        return (f"ProfileResult(category={self.category}, confidence={self.confidence:.2f}, "
+                f"turns={self.num_turns}, duration={self.session_duration:.1f}s)")
+
+
+def _load_traces(path: str | Path) -> list[dict[str, Any]]:
+    traces = []
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                traces.append(json.loads(line))
+    return traces
+
+
+def _extract_tool(entry: dict[str, Any]) -> str:
+    """Extract tool name from a trace entry."""
+    content = entry.get("content", [])
+    if isinstance(content, list):
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "tool_use":
+                name = block.get("name", "")
+                if name:
+                    return name
+    tool = entry.get("tool", entry.get("tool_name", entry.get("function", "")))
+    return str(tool).lower() if tool else ""
+
+
+def _normalize_tool(raw_tool: str) -> str:
+    """Normalize tool names to canonical forms."""
+    tool = raw_tool.lower().strip()
+    read_names = {"read", "file_read", "cat", "get_file_contents", "view", "open"}
+    edit_names = {"edit", "file_edit", "apply_edit", "replace", "str_replace_editor"}
+    write_names = {"write", "file_write", "create_file", "create"}
+    bash_names = {"bash", "shell", "run", "execute", "terminal", "command"}
+    grep_names = {"grep", "search", "find", "glob", "rg", "ag"}
+    test_names = {"test", "pytest", "run_test", "unittest"}
+
+    if tool in read_names:
+        return "read"
+    if tool in edit_names:
+        return "edit"
+    if tool in write_names:
+        return "write"
+    if tool in bash_names:
+        return "bash"
+    if tool in grep_names:
+        return "grep"
+    if tool in test_names:
+        return "bash"
+    return tool if tool else "unknown"
+
+
+def _has_error(entry: dict[str, Any]) -> bool:
+    """Check if a trace entry indicates an error."""
+    content = entry.get("content", [])
+    if isinstance(content, list):
+        for block in content:
+            if isinstance(block, dict):
+                if block.get("type") == "tool_result" and block.get("is_error", False):
+                    return True
+                text = block.get("text", "")
+                if isinstance(text, str):
+                    error_markers = ["error", "exception", "traceback", "failed", "failure"]
+                    if any(m in text.lower() for m in error_markers):
+                        return True
+    role = entry.get("role", "")
+    if role == "assistant":
+        text = ""
+        if isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    text += block.get("text", "")
+        elif isinstance(content, str):
+            text = content
+        error_in_response = ["sorry", "i made a mistake", "let me fix", "correction", "that was wrong"]
+        return any(m in text.lower() for m in error_in_response)
+    return False
+
+
+class AgentProfiler:
+    """Profile agent sessions and classify behavior patterns."""
+
+    def __init__(self) -> None:
+        self.classifier = BehaviorClassifier()
+
+    def profile(self, session: str | Path | list[dict[str, Any]]) -> ProfileResult:
+        """Profile an agent session and classify its behavior.
+
+        Args:
+            session: Path to JSONL trace file, or list of trace dicts.
+
+        Returns:
+            ProfileResult with category, confidence, and detailed metrics.
+        """
+        if isinstance(session, (str, Path)):
+            trace_data = _load_traces(session)
+        else:
+            trace_data = session
+
+        tool_dist = self._compute_tool_distribution(trace_data)
+        transitions = self._compute_transitions(trace_data)
+        error_rate = self._compute_error_rate(trace_data)
+        duration = self._compute_duration(trace_data)
+
+        edit_ratio = tool_dist.frequencies.get("edit", 0.0)
+        read_ratio = tool_dist.frequencies.get("read", 0.0)
+        grep_ratio = tool_dist.frequencies.get("grep", 0.0)
+        bash_ratio = tool_dist.frequencies.get("bash", 0.0)
+        write_ratio = tool_dist.frequencies.get("write", 0.0)
+        error_recovery = self._compute_error_recovery(trace_data)
+
+        profile_scores = self.classifier.compute_scores(
+            edit_ratio=edit_ratio,
+            read_ratio=read_ratio,
+            grep_ratio=grep_ratio,
+            bash_ratio=bash_ratio,
+            write_ratio=write_ratio,
+            error_rate=error_rate,
+            error_recovery_rate=error_recovery,
+            circular_ratio=transitions.circular_ratio,
+            entropy=tool_dist.entropy,
+            num_turns=len(trace_data),
+        )
+
+        best_category = max(profile_scores, key=profile_scores.get)  # type: ignore[arg-type]
+        confidence = profile_scores[best_category]
+
+        sub_categories = [cat for cat, score in profile_scores.items()
+                         if score > 0.3 and cat != best_category]
+
+        return ProfileResult(
+            category=best_category,
+            confidence=confidence,
+            tool_distribution=tool_dist,
+            transition_analysis=transitions,
+            session_duration=duration,
+            num_turns=len(trace_data),
+            error_rate=error_rate,
+            edit_ratio=edit_ratio,
+            read_ratio=read_ratio,
+            grep_ratio=grep_ratio,
+            bash_ratio=bash_ratio,
+            write_ratio=write_ratio,
+            error_recovery_rate=error_recovery,
+            sub_categories=sub_categories,
+            profile_scores=profile_scores,
+        )
+
+    def _compute_tool_distribution(self, trace_data: list[dict[str, Any]]) -> ToolDistribution:
+        tool_counts: dict[str, int] = {}
+        total = 0
+        for entry in trace_data:
+            raw_tool = _extract_tool(entry)
+            if raw_tool:
+                tool = _normalize_tool(raw_tool)
+                tool_counts[tool] = tool_counts.get(tool, 0) + 1
+                total += 1
+        return ToolDistribution(tool_counts=tool_counts, total_calls=total)
+
+    def _compute_transitions(self, trace_data: list[dict[str, Any]]) -> TransitionAnalysis:
+        transitions: dict[str, dict[str, int]] = {}
+        total = 0
+        prev_tool = ""
+        for entry in trace_data:
+            raw_tool = _extract_tool(entry)
+            if raw_tool:
+                tool = _normalize_tool(raw_tool)
+                if prev_tool and tool:
+                    if prev_tool not in transitions:
+                        transitions[prev_tool] = {}
+                    transitions[prev_tool][tool] = transitions[prev_tool].get(tool, 0) + 1
+                    total += 1
+                prev_tool = tool
+        return TransitionAnalysis(transitions=transitions, total_transitions=total)
+
+    def _compute_error_rate(self, trace_data: list[dict[str, Any]]) -> float:
+        if not trace_data:
+            return 0.0
+        errors = sum(1 for entry in trace_data if _has_error(entry))
+        return errors / len(trace_data)
+
+    def _compute_duration(self, trace_data: list[dict[str, Any]]) -> float:
+        if not trace_data:
+            return 0.0
+        timestamps: list[float] = []
+        for entry in trace_data:
+            ts = entry.get("timestamp", entry.get("created_at", ""))
+            if isinstance(ts, (int, float)):
+                timestamps.append(float(ts))
+            elif isinstance(ts, str) and ts:
+                try:
+                    from datetime import datetime
+                    dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+                    timestamps.append(dt.timestamp())
+                except (ValueError, AttributeError):
+                    pass
+        if len(timestamps) >= 2:
+            return max(timestamps) - min(timestamps)
+        return 0.0
+
+    def _compute_error_recovery(self, trace_data: list[dict[str, Any]]) -> float:
+        errors = 0
+        recoveries = 0
+        had_error = False
+        for entry in trace_data:
+            if _has_error(entry):
+                errors += 1
+                had_error = True
+            elif had_error:
+                recoveries += 1
+                had_error = False
+        if errors == 0:
+            return 1.0
+        return recoveries / errors

agent_profiler/visualizer.py

@@ -0,0 +1,224 @@
+"""Visualization tools for agent profiling results."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from agent_profiler.profiler import ProfileResult, AgentProfiler, ToolDistribution, TransitionAnalysis
+
+
+class ProfileVisualizer:
+    """Generate charts and visualizations for agent profiles."""
+
+    def __init__(self, style: str = "default") -> None:
+        self.style = style
+        self._setup_matplotlib()
+
+    def _setup_matplotlib(self) -> None:
+        try:
+            import matplotlib
+            matplotlib.use("Agg")
+            import matplotlib.pyplot as plt
+            plt.style.use(self.style if self.style != "default" else "seaborn-v0_8-whitegrid")
+        except (ImportError, OSError):
+            pass
+
+    def generate_profile_chart(self, profile: ProfileResult, output: str | Path | None = None) -> Any:
+        """Generate a radar chart showing profile scores.
+
+        Args:
+            profile: ProfileResult from AgentProfiler.
+            output: Path to save the chart. If None, displays interactively.
+
+        Returns:
+            matplotlib Figure object.
+        """
+        import matplotlib.pyplot as plt
+        import numpy as np
+
+        categories = list(profile.profile_scores.keys())
+        values = [profile.profile_scores.get(c, 0.0) for c in categories]
+
+        N = len(categories)
+        angles = np.linspace(0, 2 * np.pi, N, endpoint=False).tolist()
+        values_closed = values + [values[0]]
+        angles_closed = angles + [angles[0]]
+
+        fig, ax = plt.subplots(figsize=(8, 8), subplot_kw=dict(polar=True))
+
+        ax.fill(angles_closed, values_closed, alpha=0.25, color="steelblue")
+        ax.plot(angles_closed, values_closed, linewidth=2, color="steelblue")
+
+        ax.set_xticks(angles)
+        ax.set_xticklabels([c.title() for c in categories], fontsize=11)
+        ax.set_ylim(0, 1)
+        ax.set_yticks([0.2, 0.4, 0.6, 0.8, 1.0])
+
+        ax.set_title(
+            f"Agent Profile: {profile.category.title()}\n"
+            f"Confidence: {profile.confidence:.1%} | Turns: {profile.num_turns} | "
+            f"Duration: {profile.session_duration:.0f}s",
+            fontsize=13,
+            fontweight="bold",
+            pad=20,
+        )
+
+        highlight_idx = categories.index(profile.category) if profile.category in categories else 0
+        ax.plot(
+            [angles[highlight_idx], angles[highlight_idx]],
+            [0, values[highlight_idx]],
+            linewidth=3,
+            color="coral",
+            linestyle="--",
+        )
+        ax.scatter(
+            [angles[highlight_idx]],
+            [values[highlight_idx]],
+            color="coral",
+            s=100,
+            zorder=5,
+        )
+
+        fig.tight_layout()
+
+        if output:
+            fig.savefig(str(output), dpi=150, bbox_inches="tight")
+            plt.close(fig)
+
+        return fig
+
+    def generate_transition_heatmap(self, session: str | Path | list[dict[str, Any]], output: str | Path | None = None) -> Any:
+        """Generate a heatmap of tool transition probabilities.
+
+        Args:
+            session: JSONL trace file or list of trace dicts.
+            output: Path to save the chart.
+
+        Returns:
+            matplotlib Figure object.
+        """
+        import matplotlib.pyplot as plt
+        import numpy as np
+
+        profiler = AgentProfiler()
+        if isinstance(session, (str, Path)):
+            result = profiler.profile(session)
+        else:
+            result = profiler.profile(session)
+
+        transitions = result.transition_analysis
+        tools = sorted(set(list(transitions.transitions.keys()) +
+                          [t for tos in transitions.transitions.values() for t in tos.keys()]))
+
+        if not tools:
+            fig, ax = plt.subplots(figsize=(8, 6))
+            ax.text(0.5, 0.5, "No transitions found", ha="center", va="center", fontsize=14)
+            ax.set_title("Tool Transition Heatmap", fontsize=13, fontweight="bold")
+            fig.tight_layout()
+            if output:
+                fig.savefig(str(output), dpi=150, bbox_inches="tight")
+                plt.close(fig)
+            return fig
+
+        n = len(tools)
+        matrix = np.zeros((n, n))
+        probs = transitions.transition_probabilities
+
+        for i, from_tool in enumerate(tools):
+            for j, to_tool in enumerate(tools):
+                matrix[i][j] = probs.get(from_tool, {}).get(to_tool, 0.0)
+
+        fig, ax = plt.subplots(figsize=(max(8, n + 2), max(6, n)))
+        im = ax.imshow(matrix, cmap="YlOrRd", vmin=0, vmax=1.0)
+
+        ax.set_xticks(range(n))
+        ax.set_yticks(range(n))
+        ax.set_xticklabels(tools, rotation=45, ha="right", fontsize=10)
+        ax.set_yticklabels(tools, fontsize=10)
+
+        for i in range(n):
+            for j in range(n):
+                if matrix[i][j] > 0.01:
+                    ax.text(j, i, f"{matrix[i][j]:.2f}", ha="center", va="center",
+                            fontsize=8, color="white" if matrix[i][j] > 0.5 else "black")
+
+        ax.set_title("Tool Transition Probabilities", fontsize=13, fontweight="bold", pad=10)
+        ax.set_xlabel("To Tool", fontsize=11)
+        ax.set_ylabel("From Tool", fontsize=11)
+
+        cbar = fig.colorbar(im, ax=ax, shrink=0.8)
+        cbar.set_label("Transition Probability", fontsize=10)
+
+        fig.tight_layout()
+
+        if output:
+            fig.savefig(str(output), dpi=150, bbox_inches="tight")
+            plt.close(fig)
+
+        return fig
+
+    def generate_tool_distribution_pie(self, session: str | Path | list[dict[str, Any]], output: str | Path | None = None) -> Any:
+        """Generate a pie chart of tool usage distribution.
+
+        Args:
+            session: JSONL trace file or list of trace dicts.
+            output: Path to save the chart.
+
+        Returns:
+            matplotlib Figure object.
+        """
+        import matplotlib.pyplot as plt
+
+        profiler = AgentProfiler()
+        if isinstance(session, (str, Path)):
+            result = profiler.profile(session)
+        else:
+            result = profiler.profile(session)
+
+        dist = result.tool_distribution
+
+        if not dist.tool_counts:
+            fig, ax = plt.subplots(figsize=(8, 6))
+            ax.text(0.5, 0.5, "No tool usage data", ha="center", va="center", fontsize=14)
+            ax.set_title("Tool Distribution", fontsize=13, fontweight="bold")
+            fig.tight_layout()
+            if output:
+                fig.savefig(str(output), dpi=150, bbox_inches="tight")
+                plt.close(fig)
+            return fig
+
+        tools = list(dist.tool_counts.keys())
+        counts = list(dist.tool_counts.values())
+
+        colors = {
+            "read": "#4e79a7", "edit": "#f28e2b", "write": "#e15759",
+            "bash": "#59a14f", "grep": "#76b7b2", "unknown": "#b07aa1",
+        }
+        pie_colors = [colors.get(t, "#bab0ac") for t in tools]
+
+        fig, ax = plt.subplots(figsize=(8, 6))
+        wedges, texts, autotexts = ax.pie(
+            counts, labels=[t.title() for t in tools], autopct="%1.1f%%",
+            colors=pie_colors, startangle=90, pctdistance=0.8,
+        )
+        for t in texts:
+            t.set_fontsize(10)
+        for t in autotexts:
+            t.set_fontsize(9)
+
+        ax.set_title(
+            f"Tool Distribution ({dist.total_calls} calls)\n"
+            f"Dominant: {dist.dominant_tool.title()} | Entropy: {dist.entropy:.2f}",
+            fontsize=13,
+            fontweight="bold",
+        )
+
+        fig.tight_layout()
+
+        if output:
+            fig.savefig(str(output), dpi=150, bbox_inches="tight")
+            plt.close(fig)
+
+        return fig

fableforge_agent_profiler-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: fableforge-agent-profiler
+Version: 0.1.0
+Summary: Profile and classify agent behavior patterns from traces
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: rich>=13.0
+Requires-Dist: click>=8.0
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Agent Profiler
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![Tests](https://img.shields.io/badge/tests-0-yellow.svg)](tests/)
+
+
+Profile and classify agent behavior patterns from traces using transition matrices and tool distributions.
+
+## Installation
+
+```bash
+pip install agent-profiler
+```
+
+## Quick Start
+
+### Profile a Session
+
+```bash
+# Profile and classify behavior
+aprof profile trace.jsonl
+
+# Save results to JSON
+aprof profile trace.jsonl -o results.json
+```
+
+### Classify Behavior
+
+```bash
+aprof classify trace.jsonl
+```
+
+### Generate Visualizations
+
+```bash
+aprof visualize trace.jsonl --output profile_chart.png
+```
+
+## Programming API
+
+```python
+from agent_profiler import AgentProfiler, BehaviorClassifier, ProfileVisualizer
+
+# Profile a session
+profiler = AgentProfiler()
+result = profiler.profile("trace.jsonl")
+print(f"Category: {result.category} (confidence: {result.confidence:.1%})")
+print(f"Tool distribution: {result.tool_distribution.tool_counts}")
+
+# Classify directly
+classifier = BehaviorClassifier()
+category, confidence, scores = classifier.classify(
+    edit_ratio=0.25, read_ratio=0.15, bash_ratio=0.30,
+    error_rate=0.4, error_recovery_rate=0.35
+)
+
+# Generate visualizations
+visualizer = ProfileVisualizer()
+visualizer.generate_profile_chart(result, output="profile.png")
+visualizer.generate_transition_heatmap("trace.jsonl", output="heatmap.png")
+visualizer.generate_tool_distribution_pie("trace.jsonl", output="tools.png")
+```
+
+## Behavior Categories
+
+| Category | Description | Key Indicators |
+|----------|-------------|----------------|
+| Debugging | Active debugging sessions | High Edit+Bash, many errors, recoveries |
+| Building | Feature development | High Write+Bash, low Read |
+| Exploring | Code investigation | High Read+Grep, low Edit |
+| Lost | Confused/circular behavior | Circular transitions, high Read |
+| Verifying | Change verification | Read after Edit, test runs |
+
+## License
+
+MIT
+
+## Ecosystem
+
+Part of the [FableForge](../) ecosystem — 21 open-source projects built from 210K real agent traces:
+
+| Project | Description |
+| --- | --- |
+| **[Anvil](../anvil)** | Self-verified coding agent |
+| **[VerifyLoop](../verifyloop)** | Plan→Execute→Verify→Recover framework |
+| **[ErrorRecovery](../error-recovery)** | Self-healing middleware (3,725 error patterns) |
+| **[FableForge-14B](../fableforge-14b)** | The fine-tuned 14B model (4-stage training) |
+| **[ShellWhisperer](../shell-whisperer)** | 1.5B edge agent (phone/RPi, 50ms) |
+| **[ReasonCritic](../reason-critic)** | Verification model (130 benchmark tasks) |
+| **[TraceCompiler](../trace-compiler)** | Compile traces → LoRA skills |
+| **[AgentRuntime](../agent-runtime)** | Persistent agent daemon (systemd for AI) |
+| **[AgentSwarm](../agent-swarm)** | Multi-agent from real trace transitions |
+| **[AgentTelemetry](../agent-telemetry)** | Datadog for agents (token tracking, costs) |
+| **[BenchAgent](../bench-agent)** | HumanEval for tool-use (107 tasks) |
+| **[AgentDev](../agent-dev)** | VSCode extension with verification |
+| **[TraceViz](../trace-viz)** | Trace replay visualizer (Next.js) |
+| **[AgentSkills](../agent-skills)** | npm for agent behaviors |
+| **[AgentCurriculum](../agent-curriculum)** | 5-stage progressive training |
+| **[AgentFuzzer](../agent-fuzzer)** | Adversarial testing for agents |
+| **[AgentConstitution](../agent-constitution)** | Safety guardrails from traces |
+| **[CostOptimizer](../cost-optimizer)** | Token cost reduction (50-80%) |
+| **[AgentProfiler](../agent-profiler)** | Behavioral fingerprinting |
+| **[TrajectoryDistiller](../trajectory-distiller)** | Trace→training data pipeline |
+| **[Fable5-Dataset](../fable5-dataset)** | HuggingFace dataset release |

fableforge_agent_profiler-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agent_profiler/__init__.py,sha256=LvEROPWfrYPxKgp6aBALZ4dF-JxRF84n70-YJ6ouAiI,378
+agent_profiler/classifier.py,sha256=0yONLxn3uhQPkD-2lRSJvuDRjEFeVM0a7FcKUh-PqSQ,8587
+agent_profiler/cli.py,sha256=ciSwhyRwS5VYLvYr52PDFaDx_-SGxZizjvvbIzFp5bk,6987
+agent_profiler/profiler.py,sha256=a4XPrHjfnQHk7fpSevLK1WZeSI0ANpVef2CpbaWHepM,11493
+agent_profiler/visualizer.py,sha256=FUJgZPKLHshTZHfjcuXHAMgc6aCjxP4STKZqqs_FCGU,7686
+fableforge_agent_profiler-0.1.0.dist-info/licenses/LICENSE,sha256=w5aFYmJW6UW4AWlHHzPSfzaK9jMabxY0EPRzd12k7V0,1080
+fableforge_agent_profiler-0.1.0.dist-info/METADATA,sha256=_ED5zdnChqzIP8vStin4bm600jNcc8jXKQHtrh-uMI8,4446
+fableforge_agent_profiler-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fableforge_agent_profiler-0.1.0.dist-info/entry_points.txt,sha256=V0up_36o3l7wKOR3by_dFEDuWE6UVngpWjrNtLtfjEg,49
+fableforge_agent_profiler-0.1.0.dist-info/top_level.txt,sha256=GnHEbiXyleZptDgHmb5tZoxLyIaOQNfM0Y5pNvBbzNM,15
+fableforge_agent_profiler-0.1.0.dist-info/RECORD,,

fableforge_agent_profiler-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fableforge_agent_profiler-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aprof = agent_profiler.cli:cli

fableforge_agent_profiler-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FableForge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fableforge_agent_profiler-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_profiler