agentfluent 0.1.0__py3-none-any.whl

agentfluent/analytics/tokens.py

@@ -0,0 +1,137 @@
+"""Token and cost analytics for session analysis.
+
+Computes token usage totals, dollar costs, and cache efficiency from
+parsed session messages. Handles mixed-model sessions with per-model
+cost breakdown.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from agentfluent.analytics.pricing import compute_cost, get_pricing
+from agentfluent.core.session import SessionMessage
+
+
+@dataclass
+class ModelTokenBreakdown:
+    """Token counts and cost for a single model within a session."""
+
+    model: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
+    cost: float = 0.0
+
+    @property
+    def total_tokens(self) -> int:
+        return (
+            self.input_tokens
+            + self.output_tokens
+            + self.cache_creation_input_tokens
+            + self.cache_read_input_tokens
+        )
+
+
+@dataclass
+class TokenMetrics:
+    """Aggregated token usage and cost metrics for a session."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
+    total_cost: float = 0.0
+    cache_efficiency: float = 0.0
+    """Cache efficiency as a percentage (0-100).
+    Formula: cache_read / (cache_read + input + cache_creation) * 100."""
+
+    api_call_count: int = 0
+    """Number of deduplicated assistant messages (API calls)."""
+
+    by_model: dict[str, ModelTokenBreakdown] = field(default_factory=dict)
+    """Per-model token breakdown, keyed by model name."""
+
+    @property
+    def total_tokens(self) -> int:
+        return (
+            self.input_tokens
+            + self.output_tokens
+            + self.cache_creation_input_tokens
+            + self.cache_read_input_tokens
+        )
+
+
+def compute_token_metrics(messages: list[SessionMessage]) -> TokenMetrics:
+    """Compute token usage totals and dollar costs from session messages.
+
+    Processes only assistant messages that have usage data. Messages should
+    already be deduplicated (streaming snapshots collapsed).
+
+    Handles mixed-model sessions by computing per-model breakdowns and
+    summing costs across models.
+
+    Args:
+        messages: Parsed and deduplicated session messages.
+
+    Returns:
+        TokenMetrics with totals, per-model breakdown, cost, and cache efficiency.
+    """
+    by_model: dict[str, ModelTokenBreakdown] = {}
+    api_call_count = 0
+
+    for msg in messages:
+        if msg.type != "assistant" or msg.usage is None:
+            continue
+
+        api_call_count += 1
+        model_name = msg.model or "unknown"
+        usage = msg.usage
+
+        breakdown = by_model.get(model_name)
+        if breakdown is None:
+            breakdown = ModelTokenBreakdown(model=model_name)
+            by_model[model_name] = breakdown
+
+        breakdown.input_tokens += usage.input_tokens
+        breakdown.output_tokens += usage.output_tokens
+        breakdown.cache_creation_input_tokens += usage.cache_creation_input_tokens
+        breakdown.cache_read_input_tokens += usage.cache_read_input_tokens
+
+    # Compute per-model costs
+    total_cost = 0.0
+    for breakdown in by_model.values():
+        pricing = get_pricing(breakdown.model)
+        if pricing:
+            breakdown.cost = compute_cost(
+                pricing,
+                breakdown.input_tokens,
+                breakdown.output_tokens,
+                breakdown.cache_creation_input_tokens,
+                breakdown.cache_read_input_tokens,
+            )
+            total_cost += breakdown.cost
+
+    # Aggregate totals
+    total_input = sum(b.input_tokens for b in by_model.values())
+    total_output = sum(b.output_tokens for b in by_model.values())
+    total_cache_creation = sum(b.cache_creation_input_tokens for b in by_model.values())
+    total_cache_read = sum(b.cache_read_input_tokens for b in by_model.values())
+
+    # Cache efficiency: cache_read / (cache_read + input + cache_creation)
+    cache_denominator = total_cache_read + total_input + total_cache_creation
+    cache_efficiency = (
+        round(total_cache_read / cache_denominator * 100, 1) if cache_denominator > 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=by_model,
+    )

agentfluent/analytics/tools.py

@@ -0,0 +1,93 @@
+"""Tool pattern analytics for session analysis.
+
+Counts tool call frequency, computes unique tool count, and measures
+tool concentration across a session.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from agentfluent.core.session import SessionMessage
+
+
+@dataclass
+class ToolMetrics:
+    """Tool usage metrics for a session."""
+
+    tool_frequency: dict[str, int] = field(default_factory=dict)
+    """Tool call counts sorted by frequency (descending)."""
+
+    unique_tool_count: int = 0
+    """Number of distinct tools used."""
+
+    total_tool_calls: int = 0
+    """Total number of tool calls across all tools."""
+
+    concentration: list[ConcentrationEntry] = field(default_factory=list)
+    """Cumulative concentration: each entry shows how many top tools
+    account for what percentage of total calls."""
+
+
+@dataclass
+class ConcentrationEntry:
+    """A single point in the tool concentration curve."""
+
+    top_n: int
+    """Number of top tools."""
+
+    call_count: int
+    """Total calls from those top_n tools."""
+
+    percentage: float
+    """Percentage of total calls (0-100)."""
+
+
+def compute_tool_metrics(messages: list[SessionMessage]) -> ToolMetrics:
+    """Compute tool usage metrics from parsed session messages.
+
+    Scans assistant messages for tool_use content blocks and aggregates
+    call counts by tool name.
+
+    Args:
+        messages: Parsed (and deduplicated) session messages.
+
+    Returns:
+        ToolMetrics with frequency, unique count, and concentration data.
+    """
+    counts: dict[str, int] = {}
+
+    for msg in messages:
+        if msg.type != "assistant":
+            continue
+        for block in msg.tool_use_blocks:
+            counts[block.name] = counts.get(block.name, 0) + 1
+
+    if not counts:
+        return ToolMetrics()
+
+    # Sort by frequency descending, then alphabetically for ties
+    sorted_tools = sorted(counts.items(), key=lambda x: (-x[1], x[0]))
+    sorted_freq = dict(sorted_tools)
+
+    total = sum(counts.values())
+
+    # Build concentration curve
+    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(counts),
+        total_tool_calls=total,
+        concentration=concentration,
+    )

agentfluent/cli/commands/analyze.py

@@ -0,0 +1,162 @@
+"""agentfluent analyze -- compute execution analytics and diagnostics."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from agentfluent.analytics.pipeline import AnalysisResult, analyze_sessions
+from agentfluent.cli.exit_codes import EXIT_NO_DATA, EXIT_USER_ERROR
+from agentfluent.cli.formatters.helpers import format_cost, format_tokens
+from agentfluent.cli.formatters.json_output import format_json_output
+from agentfluent.cli.formatters.table import format_analysis_table
+from agentfluent.core.discovery import find_project
+from agentfluent.diagnostics import run_diagnostics
+
+ANALYZE_EPILOG = """\
+Examples:
+
+  agentfluent analyze --project codefluent
+      Analyze all sessions in the codefluent project.
+
+  agentfluent analyze --project codefluent --agent pm
+      Analyze only PM agent invocations.
+
+  agentfluent analyze --project codefluent --latest 5 --diagnostics
+      Analyze the 5 most recent sessions with behavior diagnostics.
+
+  agentfluent analyze --project codefluent --format json | jq '.data.token_metrics.total_cost'
+      Extract total cost programmatically.
+"""
+
+app = typer.Typer(help="Analyze agent sessions.")
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _print_quiet(result: AnalysisResult, project_name: str) -> None:
+    """Print a one-line summary."""
+    tm = result.token_metrics
+    am = result.agent_metrics
+    signal_count = len(result.diagnostics.signals) if result.diagnostics else 0
+    console.print(
+        f"Project {project_name}: "
+        f"{format_cost(tm.total_cost)} cost, "
+        f"{format_tokens(tm.total_tokens)} tokens, "
+        f"{am.total_invocations} agent invocations, "
+        f"{signal_count} diagnostic signals"
+    )
+
+
+def _print_json(result: AnalysisResult, *, quiet: bool, project_name: str) -> None:
+    """Print JSON output. Quiet emits a minimal summary; default emits the full tree."""
+    if quiet:
+        tm = result.token_metrics
+        am = result.agent_metrics
+        signal_count = len(result.diagnostics.signals) if result.diagnostics else 0
+        payload: dict[str, object] = {
+            "project": project_name,
+            "session_count": result.session_count,
+            "total_cost": tm.total_cost,
+            "total_tokens": tm.total_tokens,
+            "total_invocations": am.total_invocations,
+            "diagnostic_signal_count": signal_count,
+        }
+    else:
+        payload = result.model_dump(mode="json")
+    print(format_json_output("analyze", payload))
+
+
+@app.callback(invoke_without_command=True, epilog=ANALYZE_EPILOG)
+def analyze(
+    project: str = typer.Option(
+        ...,
+        "--project",
+        "-p",
+        help="Project slug or display name.",
+    ),
+    session: Optional[str] = typer.Option(  # noqa: UP007, UP045
+        None,
+        "--session",
+        "-s",
+        help="Specific session filename to analyze.",
+    ),
+    agent: Optional[str] = typer.Option(  # noqa: UP007, UP045
+        None,
+        "--agent",
+        "-a",
+        help="Filter to a specific agent type (e.g., 'pm').",
+    ),
+    latest: Optional[int] = typer.Option(  # noqa: UP007, UP045
+        None,
+        "--latest",
+        "-n",
+        help="Analyze only the N most recent sessions.",
+    ),
+    diagnostics: bool = typer.Option(
+        False,
+        "--diagnostics",
+        "-d",
+        help="Show detailed behavior diagnostics.",
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format: table or json.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Show summary only."),
+) -> None:
+    """Analyze agent sessions for token usage, cost, and behavior diagnostics."""
+    if verbose and quiet:
+        raise typer.BadParameter("--verbose and --quiet are mutually exclusive")
+
+    project_info = find_project(project)
+    if project_info is None:
+        err_console.print(f"[red]Project not found:[/red] {project}")
+        err_console.print("Use [bold]agentfluent list[/bold] to see available projects.")
+        raise typer.Exit(code=EXIT_USER_ERROR)
+
+    session_infos = project_info.sessions
+    if not session_infos:
+        name = project_info.display_name
+        err_console.print(f"[yellow]No sessions found for project:[/yellow] {name}")
+        raise typer.Exit(code=EXIT_NO_DATA)
+
+    if session:
+        session_infos = [s for s in session_infos if s.filename == session]
+        if not session_infos:
+            err_console.print(f"[red]Session not found:[/red] {session}")
+            raise typer.Exit(code=EXIT_USER_ERROR)
+
+    if latest is not None and latest > 0:
+        session_infos = session_infos[:latest]
+
+    paths = [s.path for s in session_infos]
+
+    result = analyze_sessions(paths, agent_filter=agent)
+
+    all_invocations = [inv for s in result.sessions for inv in s.invocations]
+    total_subagent_traces = sum(si.subagent_count for si in session_infos)
+
+    if all_invocations:
+        result.diagnostics = run_diagnostics(
+            all_invocations, subagent_trace_count=total_subagent_traces,
+        )
+    elif result.agent_metrics.total_invocations == 0 and diagnostics:
+        console.print(
+            "[dim]No agent invocations found -- "
+            "diagnostics require agent activity.[/dim]"
+        )
+
+    if format == "json":
+        _print_json(result, quiet=quiet, project_name=project_info.display_name)
+    elif quiet:
+        _print_quiet(result, project_info.display_name)
+    else:
+        format_analysis_table(
+            console, result, verbose=verbose, show_diagnostics=diagnostics,
+        )

agentfluent/cli/commands/config_check.py

@@ -0,0 +1,110 @@
+"""agentfluent config-check -- assess agent configuration quality."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from agentfluent.cli.exit_codes import EXIT_NO_DATA, EXIT_USER_ERROR
+from agentfluent.cli.formatters.helpers import average_score
+from agentfluent.cli.formatters.json_output import format_json_output
+from agentfluent.cli.formatters.table import format_config_check_table
+from agentfluent.config import assess_agents
+from agentfluent.config.models import ConfigScore
+
+CONFIG_CHECK_EPILOG = """\
+Examples:
+
+  agentfluent config-check
+      Score all user and project agent definitions.
+
+  agentfluent config-check --scope user
+      Check only user-level agents in ~/.claude/agents/.
+
+  agentfluent config-check --agent pm --verbose
+      Score a specific agent with detailed recommendations.
+
+  agentfluent config-check --format json | jq '.data.scores[] | select(.overall_score < 60)'
+      Find agents that need improvement.
+"""
+
+app = typer.Typer(help="Check agent configuration quality.")
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _print_quiet(scores: list[ConfigScore]) -> None:
+    """Print a one-line summary."""
+    total_recs = sum(len(s.recommendations) for s in scores)
+    console.print(
+        f"Agents: {len(scores)} | "
+        f"Avg score: {average_score(scores)}/100 | "
+        f"Recommendations: {total_recs}"
+    )
+
+
+def _print_json(scores: list[ConfigScore], *, quiet: bool) -> None:
+    """Print JSON output. Quiet emits a minimal summary; default emits all scores."""
+    if quiet:
+        payload: dict[str, object] = {
+            "agent_count": len(scores),
+            "average_score": average_score(scores),
+            "recommendation_count": sum(len(s.recommendations) for s in scores),
+        }
+    else:
+        payload = {"scores": [s.model_dump(mode="json") for s in scores]}
+    print(format_json_output("config-check", payload))
+
+
+@app.callback(invoke_without_command=True, epilog=CONFIG_CHECK_EPILOG)
+def config_check(
+    scope: str = typer.Option(
+        "all",
+        "--scope",
+        help="Scanning scope: 'user', 'project', or 'all'.",
+    ),
+    agent: Optional[str] = typer.Option(  # noqa: UP007, UP045
+        None,
+        "--agent",
+        "-a",
+        help="Score a specific agent by name.",
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format: table or json.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Show summary only."),
+) -> None:
+    """Scan agent definitions and score them against best practices."""
+    if verbose and quiet:
+        raise typer.BadParameter("--verbose and --quiet are mutually exclusive")
+
+    if scope not in ("user", "project", "all"):
+        err_console.print(f"[red]Invalid scope:[/red] {scope}")
+        err_console.print("Valid scopes: user, project, all")
+        raise typer.Exit(code=EXIT_USER_ERROR)
+
+    scores = assess_agents(scope, agent_filter=agent)
+
+    if not scores:
+        if agent:
+            err_console.print(f"[yellow]No agent found named:[/yellow] {agent}")
+            raise typer.Exit(code=EXIT_USER_ERROR)
+        err_console.print("[yellow]No agent definition files found.[/yellow]")
+        err_console.print(
+            "Agent definitions are `.md` files in "
+            "`~/.claude/agents/` (user) or `.claude/agents/` (project)."
+        )
+        raise typer.Exit(code=EXIT_NO_DATA)
+
+    if format == "json":
+        _print_json(scores, quiet=quiet)
+    elif quiet:
+        _print_quiet(scores)
+    else:
+        format_config_check_table(console, scores, verbose=verbose)

agentfluent/cli/commands/list_cmd.py

@@ -0,0 +1,165 @@
+"""agentfluent list -- discover projects and sessions."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from agentfluent.cli.exit_codes import EXIT_NO_DATA, EXIT_USER_ERROR
+from agentfluent.cli.formatters.json_output import format_json_output
+from agentfluent.cli.formatters.table import (
+    format_projects_table,
+    format_sessions_table,
+)
+from agentfluent.core.discovery import (
+    ProjectInfo,
+    discover_projects,
+    find_project,
+)
+from agentfluent.core.parser import parse_session
+
+LIST_EPILOG = """\
+Examples:
+
+  agentfluent list
+      List all projects in ~/.claude/projects/.
+
+  agentfluent list --project codefluent
+      List sessions in the codefluent project.
+
+  agentfluent list --format json | jq '.data.projects[].name'
+      Extract project names (command is "list-projects").
+
+  agentfluent list --project codefluent --format json | jq '.data.sessions[].filename'
+      Extract session filenames (command is "list-sessions").
+"""
+
+app = typer.Typer(help="List projects and sessions.")
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _discover_or_exit() -> list[ProjectInfo]:
+    """Discover projects; print error and exit on failure."""
+    try:
+        return discover_projects()
+    except FileNotFoundError as e:
+        err_console.print(f"[red]{e}[/red]")
+        raise typer.Exit(code=EXIT_NO_DATA) from None
+
+
+def _list_projects_table(*, verbose: bool, quiet: bool) -> None:
+    """Display all projects as a Rich table."""
+    projects = _discover_or_exit()
+    if quiet:
+        total_sessions = sum(p.session_count for p in projects)
+        console.print(f"{len(projects)} projects, {total_sessions} total sessions")
+        return
+    format_projects_table(console, projects, verbose=verbose)
+
+
+def _list_projects_json(*, quiet: bool) -> None:
+    """Output all projects as JSON."""
+    projects = _discover_or_exit()
+    if quiet:
+        payload: dict[str, object] = {
+            "project_count": len(projects),
+            "total_sessions": sum(p.session_count for p in projects),
+        }
+    else:
+        payload = {
+            "projects": [
+                {
+                    "name": p.display_name,
+                    "slug": p.slug,
+                    "session_count": p.session_count,
+                    "total_size_bytes": p.total_size_bytes,
+                    "earliest_session": (
+                        p.earliest_session.isoformat() if p.earliest_session else None
+                    ),
+                    "latest_session": (
+                        p.latest_session.isoformat() if p.latest_session else None
+                    ),
+                }
+                for p in projects
+            ]
+        }
+    print(format_json_output("list-projects", payload))
+
+
+def _find_or_exit(project_slug: str) -> ProjectInfo:
+    """Look up a project by slug; print error and exit if not found."""
+    project = find_project(project_slug)
+    if project is None:
+        err_console.print(f"[red]Project not found: {project_slug}[/red]")
+        raise typer.Exit(code=EXIT_USER_ERROR)
+    return project
+
+
+def _list_sessions_table(project_slug: str, *, verbose: bool, quiet: bool) -> None:
+    """Display sessions for a project as a Rich table."""
+    project = _find_or_exit(project_slug)
+    if quiet:
+        console.print(f"Project {project.display_name}: {len(project.sessions)} sessions")
+        return
+    sessions = [(s, len(parse_session(s.path))) for s in project.sessions]
+    format_sessions_table(console, project.display_name, sessions, verbose=verbose)
+
+
+def _list_sessions_json(project_slug: str, *, quiet: bool) -> None:
+    """Output sessions for a project as JSON."""
+    project = _find_or_exit(project_slug)
+    if quiet:
+        payload: dict[str, object] = {
+            "project": project.display_name,
+            "session_count": len(project.sessions),
+        }
+    else:
+        sessions = []
+        for s in project.sessions:
+            messages = parse_session(s.path)
+            sessions.append(
+                {
+                    "filename": s.filename,
+                    "size_bytes": s.size_bytes,
+                    "modified": s.modified.isoformat(),
+                    "message_count": len(messages),
+                    "subagent_count": s.subagent_count,
+                }
+            )
+        payload = {"project": project.display_name, "sessions": sessions}
+    print(format_json_output("list-sessions", payload))
+
+
+@app.callback(invoke_without_command=True, epilog=LIST_EPILOG)
+def list_cmd(
+    project: Optional[str] = typer.Option(  # noqa: UP007, UP045
+        None,
+        "--project",
+        "-p",
+        help="Project slug or name to list sessions for.",
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        "-f",
+        help="Output format: 'table' or 'json'.",
+    ),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Show summary only."),
+) -> None:
+    """List available projects, or sessions within a project."""
+    if verbose and quiet:
+        raise typer.BadParameter("--verbose and --quiet are mutually exclusive")
+    if project:
+        if format == "json":
+            _list_sessions_json(project, quiet=quiet)
+        else:
+            _list_sessions_table(project, verbose=verbose, quiet=quiet)
+    else:
+        if format == "json":
+            _list_projects_json(quiet=quiet)
+        else:
+            _list_projects_table(verbose=verbose, quiet=quiet)

agentfluent/cli/exit_codes.py

@@ -0,0 +1,18 @@
+"""Exit code invariant for AgentFluent commands.
+
+0 = success.
+1 = user named something specific and it's wrong (bad project slug, unknown
+    session, unknown agent name, invalid scope value).
+2 = system searched and found nothing (no projects dir, project has no
+    sessions, no agent definitions found).
+
+`typer.BadParameter` exits 2 by Click convention for argument-level usage
+errors (e.g., `--verbose --quiet` together). That's a framework-handled
+separate category and does not fold into the invariant above.
+"""
+
+from __future__ import annotations
+
+EXIT_OK = 0
+EXIT_USER_ERROR = 1
+EXIT_NO_DATA = 2