agentfluent 0.1.0__py3-none-any.whl

agentfluent/__init__.py

@@ -0,0 +1,8 @@
+"""AgentFluent: Local-first agent analytics with prompt diagnostics."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("agentfluent")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

agentfluent/agents/extractor.py

@@ -0,0 +1,78 @@
+"""Extract agent invocations from parsed session messages.
+
+Identifies Agent tool_use blocks in assistant messages and matches them
+to their corresponding tool_result blocks to build AgentInvocation objects.
+"""
+
+from __future__ import annotations
+
+from agentfluent.agents.models import AgentInvocation, is_builtin_agent
+from agentfluent.core.session import SessionMessage
+
+
+def extract_agent_invocations(messages: list[SessionMessage]) -> list[AgentInvocation]:
+    """Extract agent invocations from a list of parsed session messages.
+
+    Scans for assistant messages containing Agent tool_use blocks (name == "Agent"),
+    then matches each to its corresponding tool_result by tool_use_id.
+
+    Args:
+        messages: Parsed session messages from the JSONL parser.
+
+    Returns:
+        List of AgentInvocation objects in session order.
+    """
+    # Build a lookup of tool_result messages by tool_use_id
+    tool_results: dict[str, SessionMessage] = {}
+    for msg in messages:
+        if msg.type == "tool_result" and msg.tool_use_id:
+            tool_results[msg.tool_use_id] = msg
+
+    invocations: list[AgentInvocation] = []
+
+    for msg in messages:
+        if msg.type != "assistant":
+            continue
+
+        for tool_use in msg.tool_use_blocks:
+            if tool_use.name != "Agent":
+                continue
+
+            agent_type = tool_use.input.get("subagent_type", "unknown")
+            description = tool_use.input.get("description", "")
+            prompt = tool_use.input.get("prompt", "")
+
+            # Match to tool_result
+            result = tool_results.get(tool_use.id)
+
+            total_tokens = None
+            tool_uses_count = None
+            duration_ms = None
+            agent_id = None
+            output_text = ""
+
+            if result is not None:
+                output_text = result.text
+
+                if result.metadata is not None:
+                    total_tokens = result.metadata.total_tokens
+                    tool_uses_count = result.metadata.tool_uses
+                    duration_ms = result.metadata.duration_ms
+                    agent_id = result.metadata.agent_id
+
+            invocations.append(
+                AgentInvocation(
+                    agent_type=agent_type,
+                    is_builtin=is_builtin_agent(agent_type),
+                    description=description,
+                    prompt=prompt,
+                    tool_use_id=tool_use.id,
+                    total_tokens=total_tokens,
+                    tool_uses=tool_uses_count,
+                    duration_ms=duration_ms,
+                    agent_id=agent_id,
+                    output_text=output_text,
+                )
+            )
+
+    return invocations

agentfluent/agents/models.py

@@ -0,0 +1,71 @@
+"""Data models for agent invocations extracted from session data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Built-in agent types (case-insensitive matching).
+# Update this set as Anthropic adds new built-in agents.
+BUILTIN_AGENT_TYPES: frozenset[str] = frozenset(
+    {
+        "explore",
+        "plan",
+        "general-purpose",
+        "code-reviewer",
+        "statusline-setup",
+        "claude-code-guide",
+    }
+)
+
+
+def is_builtin_agent(agent_type: str) -> bool:
+    """Check if an agent type is a built-in Claude Code agent."""
+    return agent_type.lower() in BUILTIN_AGENT_TYPES
+
+
+@dataclass
+class AgentInvocation:
+    """A single agent invocation extracted from a session.
+
+    Combines data from the Agent tool_use block (in the assistant message)
+    with the corresponding tool_result (including metadata).
+    """
+
+    agent_type: str
+    """Agent type (e.g., 'pm', 'Explore', 'Plan')."""
+
+    is_builtin: bool
+    """Whether this is a built-in Claude Code agent."""
+
+    description: str
+    """The description passed to the Agent tool."""
+
+    prompt: str
+    """The delegation prompt sent to the agent."""
+
+    tool_use_id: str
+    """The tool_use ID linking this invocation to its tool_result."""
+
+    # From tool_result metadata (may be None if no metadata or agent was interrupted)
+    total_tokens: int | None = None
+    tool_uses: int | None = None
+    duration_ms: int | None = None
+    agent_id: str | None = None
+
+    # From tool_result content
+    output_text: str = ""
+    """The agent's final summary/output text."""
+
+    @property
+    def tokens_per_tool_use(self) -> float | None:
+        """Average tokens per tool call. None if data unavailable."""
+        if self.total_tokens is not None and self.tool_uses and self.tool_uses > 0:
+            return self.total_tokens / self.tool_uses
+        return None
+
+    @property
+    def duration_per_tool_use(self) -> float | None:
+        """Average duration (ms) per tool call. None if data unavailable."""
+        if self.duration_ms is not None and self.tool_uses and self.tool_uses > 0:
+            return self.duration_ms / self.tool_uses
+        return None

agentfluent/analytics/agent_metrics.py

@@ -0,0 +1,127 @@
+"""Per-agent execution metrics.
+
+Computes invocation counts, token usage, and efficiency metrics
+grouped by agent type. Reports token counts and percentages rather
+than dollar costs, since tool_result metadata only provides aggregate
+total_tokens without the per-category breakdown needed for accurate
+cost estimation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from agentfluent.agents.models import AgentInvocation
+
+
+@dataclass
+class AgentTypeMetrics:
+    """Execution metrics for a single agent type."""
+
+    agent_type: str
+    is_builtin: bool
+    invocation_count: int = 0
+    total_tokens: int = 0
+    total_tool_uses: int = 0
+    total_duration_ms: int = 0
+    avg_tokens_per_tool_use: float | None = None
+    avg_duration_per_tool_use: float | None = None
+
+    @property
+    def avg_tokens_per_invocation(self) -> float | None:
+        if self.invocation_count > 0 and self.total_tokens > 0:
+            return self.total_tokens / self.invocation_count
+        return None
+
+    @property
+    def avg_duration_per_invocation(self) -> float | None:
+        if self.invocation_count > 0 and self.total_duration_ms > 0:
+            return self.total_duration_ms / self.invocation_count
+        return None
+
+
+@dataclass
+class AgentMetrics:
+    """Aggregated agent execution metrics for a session."""
+
+    by_agent_type: dict[str, AgentTypeMetrics] = field(default_factory=dict)
+    """Per-agent-type metrics, keyed by agent_type."""
+
+    total_invocations: int = 0
+    total_agent_tokens: int = 0
+    total_agent_duration_ms: int = 0
+
+    builtin_invocations: int = 0
+    custom_invocations: int = 0
+
+    agent_token_percentage: float = 0.0
+    """Agent tokens as percentage of session total tokens (0-100).
+    Set by the caller who has session-level token data."""
+
+
+def compute_agent_metrics(
+    invocations: list[AgentInvocation],
+    session_total_tokens: int = 0,
+) -> AgentMetrics:
+    """Compute per-agent-type execution metrics from extracted invocations.
+
+    Groups invocations by agent_type and computes counts, totals, and averages.
+    Invocations with missing metadata are counted but excluded from averages.
+
+    Args:
+        invocations: Extracted agent invocations from a session.
+        session_total_tokens: Total session tokens for computing agent percentage.
+
+    Returns:
+        AgentMetrics with per-type breakdowns and summary totals.
+    """
+    by_type: dict[str, AgentTypeMetrics] = {}
+
+    for inv in invocations:
+        key = inv.agent_type.lower()
+        metrics = by_type.get(key)
+        if metrics is None:
+            metrics = AgentTypeMetrics(agent_type=inv.agent_type, is_builtin=inv.is_builtin)
+            by_type[key] = metrics
+
+        metrics.invocation_count += 1
+
+        if inv.total_tokens is not None:
+            metrics.total_tokens += inv.total_tokens
+        if inv.tool_uses is not None:
+            metrics.total_tool_uses += inv.tool_uses
+        if inv.duration_ms is not None:
+            metrics.total_duration_ms += inv.duration_ms
+
+    # Compute averages
+    for metrics in by_type.values():
+        if metrics.total_tool_uses > 0:
+            if metrics.total_tokens > 0:
+                metrics.avg_tokens_per_tool_use = metrics.total_tokens / metrics.total_tool_uses
+            if metrics.total_duration_ms > 0:
+                metrics.avg_duration_per_tool_use = (
+                    metrics.total_duration_ms / metrics.total_tool_uses
+                )
+
+    # Aggregate totals
+    total_invocations = sum(m.invocation_count for m in by_type.values())
+    total_agent_tokens = sum(m.total_tokens for m in by_type.values())
+    total_agent_duration = sum(m.total_duration_ms for m in by_type.values())
+    builtin_count = sum(m.invocation_count for m in by_type.values() if m.is_builtin)
+    custom_count = sum(m.invocation_count for m in by_type.values() if not m.is_builtin)
+
+    agent_token_pct = (
+        round(total_agent_tokens / session_total_tokens * 100, 1)
+        if session_total_tokens > 0 and total_agent_tokens > 0
+        else 0.0
+    )
+
+    return AgentMetrics(
+        by_agent_type=by_type,
+        total_invocations=total_invocations,
+        total_agent_tokens=total_agent_tokens,
+        total_agent_duration_ms=total_agent_duration,
+        builtin_invocations=builtin_count,
+        custom_invocations=custom_count,
+        agent_token_percentage=agent_token_pct,
+    )

agentfluent/analytics/pipeline.py

@@ -0,0 +1,278 @@
+"""Analytics pipeline orchestration.
+
+Connects parser, extractor, and analytics modules into a single
+analysis pipeline. Reusable by the CLI, future webapp, and tests.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from agentfluent.agents.extractor import extract_agent_invocations
+from agentfluent.agents.models import AgentInvocation
+from agentfluent.analytics.agent_metrics import (
+    AgentMetrics,
+    AgentTypeMetrics,
+    compute_agent_metrics,
+)
+from agentfluent.analytics.tokens import (
+    ModelTokenBreakdown,
+    TokenMetrics,
+    compute_token_metrics,
+)
+from agentfluent.analytics.tools import (
+    ConcentrationEntry,
+    ToolMetrics,
+    compute_tool_metrics,
+)
+from agentfluent.core.parser import parse_session
+from agentfluent.core.session import SessionMessage
+from agentfluent.diagnostics.models import DiagnosticsResult
+
+
+class SessionAnalysis(BaseModel):
+    """Complete analysis results for a single session."""
+
+    session_path: Path
+    token_metrics: TokenMetrics
+    tool_metrics: ToolMetrics
+    agent_metrics: AgentMetrics
+    invocations: list[AgentInvocation] = Field(default_factory=list)
+    message_count: int = 0
+    user_message_count: int = 0
+    assistant_message_count: int = 0
+
+
+class AnalysisResult(BaseModel):
+    """Aggregated analysis results across one or more sessions."""
+
+    sessions: list[SessionAnalysis] = Field(default_factory=list)
+    token_metrics: TokenMetrics = Field(default_factory=TokenMetrics)
+    tool_metrics: ToolMetrics = Field(default_factory=ToolMetrics)
+    agent_metrics: AgentMetrics = Field(default_factory=AgentMetrics)
+    session_count: int = 0
+    diagnostics: DiagnosticsResult | None = None
+
+
+def analyze_session(
+    path: Path,
+    *,
+    agent_filter: str | None = None,
+) -> SessionAnalysis:
+    """Run the full analytics pipeline on a single session file.
+
+    Args:
+        path: Path to the .jsonl session file.
+        agent_filter: If set, only include this agent type in agent metrics.
+
+    Returns:
+        SessionAnalysis with token, tool, and agent metrics.
+    """
+    messages = parse_session(path)
+
+    token_metrics = compute_token_metrics(messages)
+    tool_metrics = compute_tool_metrics(messages)
+
+    invocations = extract_agent_invocations(messages)
+    if agent_filter:
+        invocations = [
+            inv for inv in invocations if inv.agent_type.lower() == agent_filter.lower()
+        ]
+
+    agent_metrics = compute_agent_metrics(
+        invocations, session_total_tokens=token_metrics.total_tokens
+    )
+
+    return SessionAnalysis(
+        session_path=path,
+        token_metrics=token_metrics,
+        tool_metrics=tool_metrics,
+        agent_metrics=agent_metrics,
+        invocations=invocations,
+        message_count=len(messages),
+        user_message_count=_count_type(messages, "user"),
+        assistant_message_count=_count_type(messages, "assistant"),
+    )
+
+
+def analyze_sessions(
+    paths: list[Path],
+    *,
+    agent_filter: str | None = None,
+) -> AnalysisResult:
+    """Run analytics across multiple session files and aggregate results.
+
+    Calls analyze_session per file, then merges results mathematically
+    rather than re-processing raw messages.
+
+    Args:
+        paths: List of .jsonl session file paths.
+        agent_filter: If set, only include this agent type in agent metrics.
+
+    Returns:
+        AnalysisResult with per-session and aggregated metrics.
+    """
+    session_analyses = [analyze_session(p, agent_filter=agent_filter) for p in paths]
+
+    if not session_analyses:
+        return AnalysisResult()
+
+    agg_token = _merge_token_metrics([s.token_metrics for s in session_analyses])
+    agg_tool = _merge_tool_metrics([s.tool_metrics for s in session_analyses])
+    agg_agent = _merge_agent_metrics(
+        [s.agent_metrics for s in session_analyses],
+        session_total_tokens=agg_token.total_tokens,
+    )
+
+    return AnalysisResult(
+        sessions=session_analyses,
+        token_metrics=agg_token,
+        tool_metrics=agg_tool,
+        agent_metrics=agg_agent,
+        session_count=len(session_analyses),
+    )
+
+
+def _merge_token_metrics(metrics_list: list[TokenMetrics]) -> TokenMetrics:
+    """Merge multiple TokenMetrics by summing per-model breakdowns."""
+    merged_models: dict[str, ModelTokenBreakdown] = {}
+    api_call_count = 0
+
+    for tm in metrics_list:
+        api_call_count += tm.api_call_count
+        for model_name, breakdown in tm.by_model.items():
+            existing = merged_models.get(model_name)
+            if existing is None:
+                merged_models[model_name] = ModelTokenBreakdown(
+                    model=model_name,
+                    input_tokens=breakdown.input_tokens,
+                    output_tokens=breakdown.output_tokens,
+                    cache_creation_input_tokens=breakdown.cache_creation_input_tokens,
+                    cache_read_input_tokens=breakdown.cache_read_input_tokens,
+                    cost=breakdown.cost,
+                )
+            else:
+                existing.input_tokens += breakdown.input_tokens
+                existing.output_tokens += breakdown.output_tokens
+                existing.cache_creation_input_tokens += breakdown.cache_creation_input_tokens
+                existing.cache_read_input_tokens += breakdown.cache_read_input_tokens
+                existing.cost += breakdown.cost
+
+    total_input = sum(b.input_tokens for b in merged_models.values())
+    total_output = sum(b.output_tokens for b in merged_models.values())
+    total_cache_creation = sum(b.cache_creation_input_tokens for b in merged_models.values())
+    total_cache_read = sum(b.cache_read_input_tokens for b in merged_models.values())
+    total_cost = sum(b.cost for b in merged_models.values())
+
+    cache_denom = total_cache_read + total_input + total_cache_creation
+    cache_efficiency = (
+        round(total_cache_read / cache_denom * 100, 1) if cache_denom > 0 else 0.0
+    )
+
+    return TokenMetrics(
+        input_tokens=total_input,
+        output_tokens=total_output,
+        cache_creation_input_tokens=total_cache_creation,
+        cache_read_input_tokens=total_cache_read,
+        total_cost=total_cost,
+        cache_efficiency=cache_efficiency,
+        api_call_count=api_call_count,
+        by_model=merged_models,
+    )
+
+
+def _merge_tool_metrics(metrics_list: list[ToolMetrics]) -> ToolMetrics:
+    """Merge multiple ToolMetrics by summing frequency dicts."""
+    merged_counts: dict[str, int] = {}
+    for tm in metrics_list:
+        for name, count in tm.tool_frequency.items():
+            merged_counts[name] = merged_counts.get(name, 0) + count
+
+    if not merged_counts:
+        return ToolMetrics()
+
+    sorted_tools = sorted(merged_counts.items(), key=lambda x: (-x[1], x[0]))
+    sorted_freq = dict(sorted_tools)
+    total = sum(merged_counts.values())
+
+    concentration: list[ConcentrationEntry] = []
+    cumulative = 0
+    for i, (_name, count) in enumerate(sorted_tools, start=1):
+        cumulative += count
+        concentration.append(
+            ConcentrationEntry(
+                top_n=i,
+                call_count=cumulative,
+                percentage=round(cumulative / total * 100, 1),
+            )
+        )
+
+    return ToolMetrics(
+        tool_frequency=sorted_freq,
+        unique_tool_count=len(merged_counts),
+        total_tool_calls=total,
+        concentration=concentration,
+    )
+
+
+def _merge_agent_metrics(
+    metrics_list: list[AgentMetrics],
+    session_total_tokens: int = 0,
+) -> AgentMetrics:
+    """Merge multiple AgentMetrics by summing per-type breakdowns."""
+    merged: dict[str, AgentTypeMetrics] = {}
+
+    for am in metrics_list:
+        for key, m in am.by_agent_type.items():
+            existing = merged.get(key)
+            if existing is None:
+                merged[key] = AgentTypeMetrics(
+                    agent_type=m.agent_type,
+                    is_builtin=m.is_builtin,
+                    invocation_count=m.invocation_count,
+                    total_tokens=m.total_tokens,
+                    total_tool_uses=m.total_tool_uses,
+                    total_duration_ms=m.total_duration_ms,
+                )
+            else:
+                existing.invocation_count += m.invocation_count
+                existing.total_tokens += m.total_tokens
+                existing.total_tool_uses += m.total_tool_uses
+                existing.total_duration_ms += m.total_duration_ms
+
+    # Recompute averages on merged data
+    for m in merged.values():
+        if m.total_tool_uses > 0:
+            if m.total_tokens > 0:
+                m.avg_tokens_per_tool_use = m.total_tokens / m.total_tool_uses
+            if m.total_duration_ms > 0:
+                m.avg_duration_per_tool_use = m.total_duration_ms / m.total_tool_uses
+
+    total_invocations = sum(m.invocation_count for m in merged.values())
+    total_agent_tokens = sum(m.total_tokens for m in merged.values())
+    total_agent_duration = sum(m.total_duration_ms for m in merged.values())
+    builtin_count = sum(m.invocation_count for m in merged.values() if m.is_builtin)
+    custom_count = sum(m.invocation_count for m in merged.values() if not m.is_builtin)
+
+    agent_token_pct = (
+        round(total_agent_tokens / session_total_tokens * 100, 1)
+        if session_total_tokens > 0 and total_agent_tokens > 0
+        else 0.0
+    )
+
+    return AgentMetrics(
+        by_agent_type=merged,
+        total_invocations=total_invocations,
+        total_agent_tokens=total_agent_tokens,
+        total_agent_duration_ms=total_agent_duration,
+        builtin_invocations=builtin_count,
+        custom_invocations=custom_count,
+        agent_token_percentage=agent_token_pct,
+    )
+
+
+def _count_type(messages: list[SessionMessage], msg_type: str) -> int:
+    """Count messages of a given type."""
+    return sum(1 for m in messages if m.type == msg_type)

agentfluent/analytics/pricing.py

@@ -0,0 +1,96 @@
+"""Model pricing lookup for token cost estimation.
+
+Maps Anthropic model names to per-token costs (USD per 1M tokens) for
+input, output, cache_creation, and cache_read token categories.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ModelPricing:
+    """Per-token pricing for a single model (USD per 1M tokens)."""
+
+    input: float
+    output: float
+    cache_creation: float
+    cache_read: float
+
+
+# Pricing data: USD per 1M tokens.
+# Update this dict when Anthropic changes pricing.
+_PRICING: dict[str, ModelPricing] = {
+    "claude-opus-4-6": ModelPricing(
+        input=15.0, output=75.0, cache_creation=18.75, cache_read=1.875,
+    ),
+    "claude-opus-4-5-20251101": ModelPricing(
+        input=15.0, output=75.0, cache_creation=18.75, cache_read=1.875,
+    ),
+    "claude-sonnet-4-6": ModelPricing(
+        input=3.0, output=15.0, cache_creation=3.75, cache_read=0.30,
+    ),
+    "claude-sonnet-4-5-20250929": ModelPricing(
+        input=3.0, output=15.0, cache_creation=3.75, cache_read=0.30,
+    ),
+    "claude-sonnet-4-20250514": ModelPricing(
+        input=3.0, output=15.0, cache_creation=3.75, cache_read=0.30,
+    ),
+    "claude-haiku-4-5-20251001": ModelPricing(
+        input=0.80, output=4.0, cache_creation=1.0, cache_read=0.08,
+    ),
+}
+
+# Aliases map short names and variant identifiers to canonical model names.
+_ALIASES: dict[str, str] = {
+    "opus": "claude-opus-4-6",
+    "sonnet": "claude-sonnet-4-6",
+    "haiku": "claude-haiku-4-5-20251001",
+    "claude-opus-4-6[1m]": "claude-opus-4-6",
+    "claude-sonnet-4-6[1m]": "claude-sonnet-4-6",
+}
+
+DEFAULT_MODEL = "claude-sonnet-4-6"
+
+
+def get_pricing(model: str) -> ModelPricing | None:
+    """Look up pricing for a model name.
+
+    Checks exact match first, then aliases. Returns None with a warning
+    if the model is unknown.
+    """
+    pricing = _PRICING.get(model)
+    if pricing:
+        return pricing
+
+    canonical = _ALIASES.get(model)
+    if canonical:
+        return _PRICING.get(canonical)
+
+    logger.warning("Unknown model '%s' -- no pricing available", model)
+    return None
+
+
+def compute_cost(
+    pricing: ModelPricing,
+    input_tokens: int,
+    output_tokens: int,
+    cache_creation_input_tokens: int = 0,
+    cache_read_input_tokens: int = 0,
+) -> float:
+    """Compute dollar cost in USD from token counts and pricing rates."""
+    return (
+        input_tokens * pricing.input
+        + output_tokens * pricing.output
+        + cache_creation_input_tokens * pricing.cache_creation
+        + cache_read_input_tokens * pricing.cache_read
+    ) / 1_000_000
+
+
+def get_known_models() -> list[str]:
+    """Return sorted list of all known model names (excluding aliases)."""
+    return sorted(_PRICING.keys())