agentfluent 0.1.0__tar.gz

agentfluent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fred Pearce
+
+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.

agentfluent-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: agentfluent
+Version: 0.1.0
+Summary: Local-first agent analytics with prompt diagnostics
+Keywords: claude,agent,analytics,cli,llm,diagnostics
+Author: Fred Pearce
+Author-email: Fred Pearce <fpearce@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=14.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/frederick-douglas-pearce/agentfluent
+Project-URL: Repository, https://github.com/frederick-douglas-pearce/agentfluent
+Project-URL: Issues, https://github.com/frederick-douglas-pearce/agentfluent/issues
+Project-URL: Changelog, https://github.com/frederick-douglas-pearce/agentfluent/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# AgentFluent
+
+Local-first agent analytics with prompt diagnostics. The tools that exist tell you what your agent did. This tool tells you what to change.
+
+## What Is This?
+
+AgentFluent analyzes AI agent session data (Claude Code subagents + Agent SDK) to provide:
+
+- **Agent execution analytics** -- token usage, cost tracking, tool call patterns, error rates
+- **Agent prompt diagnostics** -- score system prompts against best practices, correlate agent behavior to prompt quality issues, generate specific improvement recommendations
+- **Prompt regression detection** -- compare agent behavior across prompt versions
+- **Agent configuration assessment** -- tool access audit, model selection analysis, hook coverage
+
+## Background
+
+Born from [CodeFluent](https://github.com/frederick-douglas-pearce/codefluent) research identifying a gap in the agent observability market: existing tools monitor agent execution (traces, latency, cost) but none evaluate agent *quality* or diagnose *prompt-level issues* from local session data.
+
+See `docs/AGENT_ANALYTICS_RESEARCH.md` for the full market analysis and technical feasibility study.
+
+## Status
+
+Early stage -- defining scope, architecture, and initial backlog.

agentfluent-0.1.0/README.md

@@ -0,0 +1,22 @@
+# AgentFluent
+
+Local-first agent analytics with prompt diagnostics. The tools that exist tell you what your agent did. This tool tells you what to change.
+
+## What Is This?
+
+AgentFluent analyzes AI agent session data (Claude Code subagents + Agent SDK) to provide:
+
+- **Agent execution analytics** -- token usage, cost tracking, tool call patterns, error rates
+- **Agent prompt diagnostics** -- score system prompts against best practices, correlate agent behavior to prompt quality issues, generate specific improvement recommendations
+- **Prompt regression detection** -- compare agent behavior across prompt versions
+- **Agent configuration assessment** -- tool access audit, model selection analysis, hook coverage
+
+## Background
+
+Born from [CodeFluent](https://github.com/frederick-douglas-pearce/codefluent) research identifying a gap in the agent observability market: existing tools monitor agent execution (traces, latency, cost) but none evaluate agent *quality* or diagnose *prompt-level issues* from local session data.
+
+See `docs/AGENT_ANALYTICS_RESEARCH.md` for the full market analysis and technical feasibility study.
+
+## Status
+
+Early stage -- defining scope, architecture, and initial backlog.

agentfluent-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "agentfluent"
+version = "0.1.0" # x-release-please-version
+description = "Local-first agent analytics with prompt diagnostics"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Fred Pearce", email = "fpearce@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = ["claude", "agent", "analytics", "cli", "llm", "diagnostics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.15",
+    "rich>=14.0",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/frederick-douglas-pearce/agentfluent"
+Repository = "https://github.com/frederick-douglas-pearce/agentfluent"
+Issues = "https://github.com/frederick-douglas-pearce/agentfluent/issues"
+Changelog = "https://github.com/frederick-douglas-pearce/agentfluent/blob/main/CHANGELOG.md"
+
+[project.scripts]
+agentfluent = "agentfluent.cli.main:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "ruff>=0.11",
+    "mypy>=1.15",
+    "types-pyyaml>=6.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: tests that require real session data (deselect with '-m \"not integration\"')",
+]
+
+[tool.coverage.run]
+source = ["agentfluent"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

agentfluent-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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,
+    )