agentfluent 0.1.0__py3-none-any.whl

agentfluent/cli/formatters/helpers.py

@@ -0,0 +1,59 @@
+"""Shared formatting utilities for CLI output."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from agentfluent.config.models import Severity
+
+if TYPE_CHECKING:
+    from agentfluent.config.models import ConfigScore
+
+SEVERITY_COLORS: dict[Severity, str] = {
+    Severity.CRITICAL: "red",
+    Severity.WARNING: "yellow",
+    Severity.INFO: "cyan",
+}
+
+
+def format_cost(cost: float) -> str:
+    """Format a dollar cost for display."""
+    if cost < 0.01:
+        return f"${cost:.4f}"
+    return f"${cost:.2f}"
+
+
+def format_tokens(tokens: int) -> str:
+    """Format token count with comma separator."""
+    return f"{tokens:,}"
+
+
+def format_size(size_bytes: int) -> str:
+    """Format bytes as human-readable size."""
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    if size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    return f"{size_bytes / (1024 * 1024):.1f} MB"
+
+
+def format_date(dt: datetime | None) -> str:
+    """Format a datetime for display."""
+    if dt is None:
+        return "—"
+    return dt.strftime("%Y-%m-%d %H:%M")
+
+
+def score_color(score: int) -> str:
+    """Return a Rich color based on score value."""
+    if score >= 80:
+        return "green"
+    if score >= 50:
+        return "yellow"
+    return "red"
+
+
+def average_score(scores: list[ConfigScore]) -> int:
+    """Integer average of overall_score across agents; 0 for an empty list."""
+    return sum(s.overall_score for s in scores) // len(scores) if scores else 0

agentfluent/cli/formatters/json_output.py

@@ -0,0 +1,60 @@
+"""JSON output envelope for CLI commands.
+
+All commands emit JSON in a stable envelope:
+
+    {
+      "version": "1",
+      "command": "<list|analyze|config-check>",
+      "data": { ... command-specific payload ... }
+    }
+
+`version` is a string and bumps independently of the package version when the
+schema changes. Consumers should check `command` before parsing `data`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Literal
+
+SCHEMA_VERSION = "1"
+
+CommandName = Literal["list-projects", "list-sessions", "analyze", "config-check"]
+
+
+def format_json_output(command: CommandName, data: Any) -> str:
+    """Wrap a command payload in the versioned JSON envelope."""
+    envelope = {
+        "version": SCHEMA_VERSION,
+        "command": command,
+        "data": data,
+    }
+    return json.dumps(envelope, indent=2, default=str)
+
+
+def parse_json_output(
+    text: str, *, expected_command: CommandName | None = None,
+) -> Any:
+    """Validate the envelope and return its `data` payload.
+
+    Raises ValueError on schema violation (missing keys, wrong version,
+    wrong command).
+    """
+    envelope = json.loads(text)
+    missing = {"version", "command", "data"} - envelope.keys()
+    if missing:
+        msg = f"JSON envelope missing keys: {sorted(missing)}"
+        raise ValueError(msg)
+    if envelope["version"] != SCHEMA_VERSION:
+        msg = (
+            f"JSON envelope version {envelope['version']!r} does not match "
+            f"SCHEMA_VERSION {SCHEMA_VERSION!r}"
+        )
+        raise ValueError(msg)
+    if expected_command is not None and envelope["command"] != expected_command:
+        msg = (
+            f"JSON envelope command {envelope['command']!r} does not match "
+            f"expected {expected_command!r}"
+        )
+        raise ValueError(msg)
+    return envelope["data"]

agentfluent/cli/formatters/table.py

@@ -0,0 +1,358 @@
+"""Rich table formatters for CLI output.
+
+Each command gets its own `format_*_table` function -- no shared Formatter
+base class, since the three commands produce different data shapes that
+would not benefit from unification. Functions render already-computed data
+to a Rich Console; I/O stays in the command callbacks.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+from rich.table import Table
+
+from agentfluent.cli.formatters.helpers import (
+    SEVERITY_COLORS,
+    average_score,
+    format_cost,
+    format_date,
+    format_size,
+    format_tokens,
+    score_color,
+)
+
+if TYPE_CHECKING:
+    from agentfluent.analytics.pipeline import AnalysisResult
+    from agentfluent.config.models import ConfigScore
+    from agentfluent.core.discovery import ProjectInfo, SessionInfo
+    from agentfluent.diagnostics.models import DiagnosticsResult
+
+
+def format_projects_table(
+    console: Console,
+    projects: list[ProjectInfo],
+    *,
+    verbose: bool = False,
+) -> None:
+    """Render discovered projects as a Rich table."""
+    if not projects:
+        console.print("No projects found in ~/.claude/projects/")
+        return
+
+    table = Table(title="Projects")
+    table.add_column("Name", style="cyan")
+    table.add_column("Sessions", justify="right")
+    table.add_column("Size", justify="right")
+    table.add_column("Latest", style="dim")
+    if verbose:
+        table.add_column("Slug", style="dim")
+
+    for p in projects:
+        row = [
+            p.display_name,
+            str(p.session_count),
+            format_size(p.total_size_bytes),
+            format_date(p.latest_session),
+        ]
+        if verbose:
+            row.append(p.slug)
+        table.add_row(*row)
+
+    console.print(table)
+
+
+def format_sessions_table(
+    console: Console,
+    project_name: str,
+    sessions: list[tuple[SessionInfo, int]],
+    *,
+    verbose: bool = False,
+) -> None:
+    """Render per-session stats as a Rich table.
+
+    `sessions` is a list of (SessionInfo, message_count) tuples. The caller
+    owns session parsing so this function stays pure rendering.
+    """
+    if not sessions:
+        console.print(f"No sessions in project '{project_name}'")
+        return
+
+    table = Table(title=f"Sessions — {project_name}")
+    file_label = "Path" if verbose else "File"
+    table.add_column(file_label, style="cyan")
+    table.add_column("Size", justify="right")
+    table.add_column("Modified", style="dim")
+    table.add_column("Messages", justify="right")
+    table.add_column("Subagents", justify="right", style="dim")
+
+    for info, message_count in sessions:
+        table.add_row(
+            str(info.path) if verbose else info.filename,
+            format_size(info.size_bytes),
+            format_date(info.modified),
+            str(message_count),
+            str(info.subagent_count) if info.subagent_count > 0 else "—",
+        )
+
+    console.print(table)
+
+
+def format_analysis_table(
+    console: Console,
+    result: AnalysisResult,
+    *,
+    verbose: bool = False,
+    show_diagnostics: bool = False,
+) -> None:
+    """Render analyze output: token, cost, tool, agent, and diagnostics tables."""
+    tm = result.token_metrics
+    am = result.agent_metrics
+    tlm = result.tool_metrics
+
+    token_table = Table(title="Token Usage", show_header=True)
+    token_table.add_column("Metric", style="cyan")
+    token_table.add_column("Value", justify="right")
+    token_table.add_row("Input tokens", format_tokens(tm.input_tokens))
+    token_table.add_row("Output tokens", format_tokens(tm.output_tokens))
+    token_table.add_row("Cache creation tokens", format_tokens(tm.cache_creation_input_tokens))
+    token_table.add_row("Cache read tokens", format_tokens(tm.cache_read_input_tokens))
+    token_table.add_row("Total tokens", format_tokens(tm.total_tokens))
+    token_table.add_row("Total cost", format_cost(tm.total_cost))
+    token_table.add_row("Cache efficiency", f"{tm.cache_efficiency}%")
+    token_table.add_row("API calls", str(tm.api_call_count))
+    console.print(token_table)
+
+    if tm.by_model and (verbose or len(tm.by_model) > 1):
+        model_table = Table(title="Cost by Model", show_header=True)
+        model_table.add_column("Model", style="cyan")
+        model_table.add_column("Tokens", justify="right")
+        model_table.add_column("Cost", justify="right")
+        for model_name, breakdown in sorted(tm.by_model.items()):
+            model_table.add_row(
+                model_name,
+                format_tokens(breakdown.total_tokens),
+                format_cost(breakdown.cost),
+            )
+        console.print(model_table)
+
+    if tlm.total_tool_calls > 0:
+        tool_table = Table(title="Tool Usage", show_header=True)
+        tool_table.add_column("Tool", style="cyan")
+        tool_table.add_column("Calls", justify="right")
+        tool_table.add_column("% of Total", justify="right")
+        for name, count in tlm.tool_frequency.items():
+            pct = round(count / tlm.total_tool_calls * 100, 1)
+            tool_table.add_row(name, str(count), f"{pct}%")
+        tool_table.add_row("", "", "")
+        tool_table.add_row("Total", str(tlm.total_tool_calls), "")
+        tool_table.add_row("Unique tools", str(tlm.unique_tool_count), "")
+        console.print(tool_table)
+
+    if am.total_invocations > 0:
+        agent_table = Table(title="Agent Invocations", show_header=True)
+        agent_table.add_column("Agent Type", style="cyan")
+        agent_table.add_column("Count", justify="right")
+        agent_table.add_column("Tokens", justify="right")
+        agent_table.add_column("Avg Tokens/Call", justify="right")
+        agent_table.add_column("Duration", justify="right")
+        for _key, m in sorted(am.by_agent_type.items()):
+            label = f"{m.agent_type} {'(builtin)' if m.is_builtin else ''}"
+            avg_tok = (
+                format_tokens(int(m.avg_tokens_per_invocation))
+                if m.avg_tokens_per_invocation
+                else "-"
+            )
+            duration = f"{m.total_duration_ms / 1000:.1f}s" if m.total_duration_ms else "-"
+            agent_table.add_row(
+                label.strip(),
+                str(m.invocation_count),
+                format_tokens(m.total_tokens),
+                avg_tok,
+                duration,
+            )
+        agent_table.add_row("", "", "", "", "")
+        agent_table.add_row("Total", str(am.total_invocations), "", "", "")
+        agent_table.add_row(
+            "Agent token %",
+            f"{am.agent_token_percentage}%",
+            "",
+            "",
+            "",
+        )
+        console.print(agent_table)
+
+    if verbose and len(result.sessions) > 1:
+        session_table = Table(title="Per-Session Breakdown", show_header=True)
+        session_table.add_column("Session", style="cyan")
+        session_table.add_column("Tokens", justify="right")
+        session_table.add_column("Cost", justify="right")
+        session_table.add_column("Tool calls", justify="right")
+        session_table.add_column("Invocations", justify="right")
+        for s in result.sessions:
+            session_table.add_row(
+                s.session_path.name,
+                format_tokens(s.token_metrics.total_tokens),
+                format_cost(s.token_metrics.total_cost),
+                str(s.tool_metrics.total_tool_calls),
+                str(s.agent_metrics.total_invocations),
+            )
+        console.print(session_table)
+
+    if verbose and am.total_invocations > 0:
+        inv_table = Table(title="Per-Invocation Detail", show_header=True)
+        inv_table.add_column("Agent", style="cyan")
+        inv_table.add_column("Description")
+        inv_table.add_column("Tokens", justify="right")
+        inv_table.add_column("Tool uses", justify="right")
+        inv_table.add_column("Duration", justify="right")
+        for s in result.sessions:
+            for inv in s.invocations:
+                tokens = format_tokens(inv.total_tokens) if inv.total_tokens else "-"
+                tools = str(inv.tool_uses) if inv.tool_uses else "-"
+                duration = f"{inv.duration_ms / 1000:.1f}s" if inv.duration_ms else "-"
+                desc = (
+                    inv.description
+                    if len(inv.description) <= 60
+                    else inv.description[:57] + "..."
+                )
+                inv_table.add_row(inv.agent_type, desc, tokens, tools, duration)
+        console.print(inv_table)
+
+    diag = result.diagnostics
+    if diag:
+        if show_diagnostics:
+            _format_diagnostics_table(console, diag, verbose=verbose)
+        else:
+            _format_diagnostics_summary(console, diag)
+
+    console.print(f"\n[bold]Sessions analyzed:[/bold] {result.session_count}")
+
+
+def _format_diagnostics_table(
+    console: Console,
+    diag: DiagnosticsResult,
+    *,
+    verbose: bool = False,
+) -> None:
+    """Render diagnostic signals and recommendations tables."""
+    if diag.signals:
+        sig_table = Table(title="Diagnostic Signals", show_header=True)
+        sig_table.add_column("Agent", style="cyan")
+        sig_table.add_column("Type")
+        sig_table.add_column("Severity")
+        sig_table.add_column("Message")
+
+        for sig in diag.signals:
+            color = SEVERITY_COLORS.get(sig.severity, "white")
+            sig_table.add_row(
+                sig.agent_type,
+                sig.signal_type.value,
+                f"[{color}]{sig.severity.value}[/{color}]",
+                sig.message,
+            )
+        console.print(sig_table)
+
+    if diag.recommendations:
+        rec_table = Table(title="Recommendations", show_header=True)
+        rec_table.add_column("Agent", style="cyan")
+        rec_table.add_column("Target")
+        rec_table.add_column("Severity")
+        if verbose:
+            rec_table.add_column("Observation")
+            rec_table.add_column("Action")
+        else:
+            rec_table.add_column("Recommendation")
+
+        for rec in diag.recommendations:
+            color = SEVERITY_COLORS.get(rec.severity, "white")
+            if verbose:
+                rec_table.add_row(
+                    rec.agent_type,
+                    rec.target,
+                    f"[{color}]{rec.severity.value}[/{color}]",
+                    rec.observation,
+                    rec.action,
+                )
+            else:
+                rec_table.add_row(
+                    rec.agent_type,
+                    rec.target,
+                    f"[{color}]{rec.severity.value}[/{color}]",
+                    rec.message,
+                )
+        console.print(rec_table)
+
+    if diag.subagent_trace_count > 0:
+        console.print(
+            f"\n[dim]{diag.subagent_trace_count} subagent trace files available. "
+            "Deep diagnostics (per-tool-call analysis) coming in v1.1.[/dim]"
+        )
+
+
+def _format_diagnostics_summary(console: Console, diag: DiagnosticsResult) -> None:
+    """Print a brief diagnostics summary when --diagnostics is not passed."""
+    signal_count = len(diag.signals)
+    if signal_count > 0:
+        console.print(
+            f"\n[yellow]{signal_count} diagnostic signal(s) detected.[/yellow] "
+            "Run with [bold]--diagnostics[/bold] for details."
+        )
+
+
+def format_config_check_table(
+    console: Console,
+    scores: list[ConfigScore],
+    *,
+    verbose: bool = False,
+) -> None:
+    """Render agent configuration scores and recommendations."""
+    summary = Table(title="Agent Configuration Scores", show_header=True)
+    summary.add_column("Agent", style="cyan")
+    summary.add_column("Score", justify="right")
+    summary.add_column("Description", justify="right")
+    summary.add_column("Tools", justify="right")
+    summary.add_column("Model", justify="right")
+    summary.add_column("Prompt", justify="right")
+    summary.add_column("Recs", justify="right")
+
+    for s in scores:
+        color = score_color(s.overall_score)
+        summary.add_row(
+            s.agent_name,
+            f"[{color}]{s.overall_score}/100[/{color}]",
+            f"{s.dimension_scores.get('description', 0)}/25",
+            f"{s.dimension_scores.get('tool_restrictions', 0)}/25",
+            f"{s.dimension_scores.get('model_selection', 0)}/25",
+            f"{s.dimension_scores.get('prompt_body', 0)}/25",
+            str(len(s.recommendations)),
+        )
+    console.print(summary)
+
+    all_recs = [(s.agent_name, r) for s in scores for r in s.recommendations]
+    if all_recs:
+        rec_table = Table(title="Recommendations", show_header=True)
+        rec_table.add_column("Agent", style="cyan")
+        rec_table.add_column("Severity")
+        rec_table.add_column("Recommendation")
+        if verbose:
+            rec_table.add_column("Action")
+
+        for agent_name, rec in all_recs:
+            color = SEVERITY_COLORS.get(rec.severity, "white")
+            row = [
+                agent_name,
+                f"[{color}]{rec.severity.value}[/{color}]",
+                rec.message,
+            ]
+            if verbose:
+                row.append(rec.suggested_action)
+            rec_table.add_row(*row)
+        console.print(rec_table)
+
+    console.print(
+        f"\n[bold]Agents scanned:[/bold] {len(scores)}, "
+        f"[bold]average score:[/bold] {average_score(scores)}/100, "
+        f"[bold]recommendations:[/bold] {len(all_recs)}"
+    )

agentfluent/cli/main.py

@@ -0,0 +1,63 @@
+"""AgentFluent CLI application."""
+
+from typing import Optional
+
+import typer
+
+from agentfluent import __version__
+from agentfluent.cli.commands import analyze, config_check, list_cmd
+
+TOP_LEVEL_HELP = """\
+Local-first agent analytics for the Claude Agent SDK and Claude Code subagents.
+
+AgentFluent analyzes session JSONL files in ~/.claude/projects/ to diagnose
+agent quality -- token usage, tool patterns, behavior signals, and config
+health -- and produces specific recommendations for improving agent prompts,
+tool access, model selection, and other configuration surfaces.
+"""
+
+TOP_LEVEL_EPILOG = """\
+Common workflows:
+
+  agentfluent list
+      Discover which projects have session data.
+
+  agentfluent analyze --project <slug> --diagnostics
+      Full analytics with behavior diagnostics.
+
+  agentfluent config-check
+      Score agent definitions against best practices.
+
+Run any command with --help for command-specific options and examples.
+"""
+
+app = typer.Typer(
+    name="agentfluent",
+    help=TOP_LEVEL_HELP,
+    epilog=TOP_LEVEL_EPILOG,
+    no_args_is_help=True,
+)
+
+app.add_typer(list_cmd.app, name="list")
+app.add_typer(analyze.app, name="analyze")
+app.add_typer(config_check.app, name="config-check")
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"agentfluent {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(  # noqa: UP007, UP045
+        None,
+        "--version",
+        "-V",
+        help="Show version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Local-first agent analytics with prompt diagnostics."""

agentfluent/config/__init__.py

@@ -0,0 +1,31 @@
+"""Agent configuration assessment package."""
+
+from __future__ import annotations
+
+from agentfluent.config.models import ConfigScore
+from agentfluent.config.scanner import scan_agents
+from agentfluent.config.scoring import score_agent
+
+
+def assess_agents(
+    scope: str = "all",
+    *,
+    agent_filter: str | None = None,
+) -> list[ConfigScore]:
+    """Scan and score agent definitions.
+
+    Reusable orchestration function for CLI, diagnostics, and tests.
+
+    Args:
+        scope: Which locations to scan -- "user", "project", or "all".
+        agent_filter: If set, only score this agent name (case-insensitive).
+
+    Returns:
+        List of ConfigScore results.
+    """
+    agents = scan_agents(scope)
+
+    if agent_filter:
+        agents = [a for a in agents if a.name.lower() == agent_filter.lower()]
+
+    return [score_agent(a) for a in agents]

agentfluent/config/models.py

@@ -0,0 +1,118 @@
+"""Data models for agent configuration assessment.
+
+These models represent parsed agent definition files and their scoring results.
+They cross module boundaries (scanner -> scorer -> CLI -> diagnostics), so
+Pydantic is used for validation and serialization.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Scope(StrEnum):
+    """Where an agent definition was discovered."""
+
+    USER = "user"
+    PROJECT = "project"
+
+
+class Severity(StrEnum):
+    """Recommendation severity level."""
+
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+class AgentConfig(BaseModel):
+    """Parsed agent definition from a `.md` file.
+
+    Captures both explicitly-modeled fields and raw frontmatter for
+    forward compatibility with new agent config fields.
+    """
+
+    name: str
+    """Agent name from frontmatter or filename."""
+
+    file_path: Path
+    """Absolute path to the `.md` file."""
+
+    scope: Scope
+    """Whether this came from user or project agents directory."""
+
+    # Core fields
+    description: str = ""
+    """Agent description from frontmatter."""
+
+    model: str | None = None
+    """Model name (e.g., 'claude-opus-4-6')."""
+
+    prompt_body: str = ""
+    """Everything after the YAML frontmatter closing `---`."""
+
+    # Tool access
+    tools: list[str] = Field(default_factory=list)
+    """Allowed tools list."""
+
+    disallowed_tools: list[str] = Field(default_factory=list)
+    """Disallowed tools list."""
+
+    # Additional config fields
+    mcp_servers: list[str] = Field(default_factory=list)
+    """MCP server names."""
+
+    hooks: dict[str, Any] = Field(default_factory=dict)
+    """Hook configuration (complex nested structure)."""
+
+    skills: list[str] = Field(default_factory=list)
+    """Skill names."""
+
+    memory: str | None = None
+    """Memory scope (e.g., 'user')."""
+
+    isolation: str | None = None
+    """Isolation mode (e.g., 'worktree')."""
+
+    color: str | None = None
+    """Agent color for display."""
+
+    raw_frontmatter: dict[str, Any] = Field(default_factory=dict)
+    """Complete raw frontmatter dict for fields not explicitly modeled."""
+
+
+class ConfigRecommendation(BaseModel):
+    """A specific, actionable recommendation from config scoring."""
+
+    dimension: str
+    """Which scoring dimension produced this recommendation."""
+
+    severity: Severity
+    """How important this recommendation is."""
+
+    message: str
+    """Human-readable recommendation text."""
+
+    current_value: str = ""
+    """What was found in the config (for context)."""
+
+    suggested_action: str = ""
+    """What the user should change."""
+
+
+class ConfigScore(BaseModel):
+    """Scoring results for a single agent configuration."""
+
+    agent_name: str
+    overall_score: int = 0
+    """Overall score (0-100), sum of dimension scores."""
+
+    dimension_scores: dict[str, int] = Field(default_factory=dict)
+    """Per-dimension scores, keyed by dimension name."""
+
+    recommendations: list[ConfigRecommendation] = Field(default_factory=list)
+    """Actionable recommendations for improving the config."""