agentlinter 0.1.1__py3-none-any.whl

agent_lint/__init__.py

@@ -0,0 +1,4 @@
+"""agent-lint -- Estimate costs and lint agent workflow YAML files."""
+
+__version__ = "0.1.1"
+__all__ = ["__version__"]

agent_lint/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running as ``python -m agent_lint``."""
+
+from __future__ import annotations
+
+from agent_lint.cli import app
+
+if __name__ == "__main__":
+    app()

agent_lint/cli.py

@@ -0,0 +1,215 @@
+"""CLI entry point for agent-lint."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from agent_lint import __version__
+from agent_lint.exceptions import AgentAuditError
+from agent_lint.formatters import (
+    format_compare_json,
+    format_compare_table,
+    format_estimate_json,
+    format_estimate_markdown,
+    format_estimate_table,
+    format_lint_json,
+    format_lint_markdown,
+    format_lint_table,
+)
+from agent_lint.licensing import get_upgrade_message, has_feature
+
+app = typer.Typer(
+    name="agent-lint",
+    help="Analyze agent workflow configs for cost estimation and anti-patterns.",
+)
+console = Console()
+
+
+# ---------------------------------------------------------------------------
+# Root callback
+# ---------------------------------------------------------------------------
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Analyze agent workflow configs for cost estimation and anti-patterns."""
+    if version:
+        console.print(f"agent-lint {__version__}")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        console.print(ctx.get_help())
+        raise typer.Exit()
+
+
+# ---------------------------------------------------------------------------
+# estimate
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def estimate(
+    workflow_file: Path = typer.Argument(..., help="Workflow YAML file to analyze."),
+    provider: str | None = typer.Option(
+        None, "--provider", "-p", help="Provider (anthropic, openai, ollama)."
+    ),
+    model: str | None = typer.Option(None, "--model", "-m", help="Model name."),
+    json: bool = typer.Option(False, "--json", help="Output as JSON."),
+    fmt: str = typer.Option("table", "--format", "-f", help="Output format (table|json|markdown)."),
+) -> None:
+    """Estimate token usage and cost for a workflow."""
+    from agent_lint.estimator import estimate_workflow
+    from agent_lint.parsers import parse_workflow
+
+    try:
+        wf = parse_workflow(workflow_file)
+        result = estimate_workflow(wf, provider=provider, model=model)
+    except AgentAuditError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    if json or fmt == "json":
+        format_estimate_json(result, console)
+    elif fmt == "markdown":
+        format_estimate_markdown(result, console)
+    else:
+        format_estimate_table(result, console)
+
+
+# ---------------------------------------------------------------------------
+# lint
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def lint(
+    workflow_file: Path = typer.Argument(..., help="Workflow YAML file to lint."),
+    category: str | None = typer.Option(
+        None,
+        "--category",
+        "-c",
+        help="Filter by category (budget|resilience|efficiency|security).",
+    ),
+    severity: str | None = typer.Option(
+        None,
+        "--severity",
+        "-s",
+        help="Filter by severity (error|warning|info).",
+    ),
+    fail_under: int | None = typer.Option(
+        None, "--fail-under", help="Exit 1 if score is below this threshold."
+    ),
+    json: bool = typer.Option(False, "--json", help="Output as JSON."),
+    fmt: str = typer.Option("table", "--format", "-f", help="Output format (table|json|markdown)."),
+) -> None:
+    """Lint a workflow for anti-patterns and best practice violations."""
+    from agent_lint.linter import run_lint
+    from agent_lint.models import RuleCategory, Severity
+    from agent_lint.parsers import parse_workflow
+
+    try:
+        wf = parse_workflow(workflow_file)
+    except AgentAuditError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    cat = None
+    if category:
+        try:
+            cat = RuleCategory(category.lower())
+        except ValueError:
+            console.print(f"[red]Unknown category:[/red] {category}")
+            raise typer.Exit(1) from None
+
+    sev = None
+    if severity:
+        try:
+            sev = Severity(severity.lower())
+        except ValueError:
+            console.print(f"[red]Unknown severity:[/red] {severity}")
+            raise typer.Exit(1) from None
+
+    report = run_lint(wf, category=cat, severity=sev)
+
+    if json or fmt == "json":
+        format_lint_json(report, console)
+    elif fmt == "markdown":
+        format_lint_markdown(report, console)
+    else:
+        format_lint_table(report, console)
+
+    if fail_under is not None and report.score < fail_under:
+        console.print(f"[red]Score {report.score} is below threshold {fail_under}.[/red]")
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def status() -> None:
+    """Show license status and available features."""
+    from agent_lint.licensing import TIER_DEFINITIONS, get_license_info
+
+    info = get_license_info()
+    tier_config = TIER_DEFINITIONS[info.tier]
+
+    console.print(f"\n[bold]agent-lint {__version__}[/bold]")
+    console.print(f"[bold]Tier:[/bold] {tier_config.name} ({tier_config.price_label})")
+
+    if info.license_key:
+        masked = info.license_key[:9] + "****-****"
+        console.print(f"[bold]Key:[/bold] {masked}")
+        valid_str = "[green]valid[/green]" if info.valid else "[red]invalid[/red]"
+        console.print(f"[bold]Valid:[/bold] {valid_str}")
+
+    console.print(f"\n[bold]Features:[/bold] {', '.join(tier_config.features)}")
+    console.print()
+
+
+# ---------------------------------------------------------------------------
+# compare (Pro)
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def compare(
+    workflow_file: Path = typer.Argument(..., help="Workflow YAML file to analyze."),
+    providers: list[str] | None = typer.Option(
+        None, "--provider", "-p", help="Providers to compare (repeat for each)."
+    ),
+    json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Compare workflow costs across providers (Pro feature)."""
+    from agent_lint.comparator import compare_providers
+    from agent_lint.parsers import parse_workflow
+
+    # Gate check.
+    if not has_feature("compare"):
+        console.print(f"[yellow]{get_upgrade_message('compare')}[/yellow]")
+        raise typer.Exit(1)
+
+    try:
+        wf = parse_workflow(workflow_file)
+        result = compare_providers(wf, providers=providers)
+    except AgentAuditError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+    if json:
+        format_compare_json(result, console)
+    else:
+        format_compare_table(result, console)

agent_lint/comparator.py

@@ -0,0 +1,47 @@
+"""Multi-provider cost comparison engine."""
+
+from __future__ import annotations
+
+from agent_lint.estimator import estimate_workflow
+from agent_lint.models import CompareResult, ParsedWorkflow, WorkflowEstimate
+from agent_lint.pricing import list_providers, load_providers
+
+
+def compare_providers(
+    workflow: ParsedWorkflow,
+    providers: list[str] | None = None,
+) -> CompareResult:
+    """Estimate workflow cost across multiple providers and compare."""
+    all_providers = load_providers()
+
+    if providers is None:
+        providers = list_providers(providers=all_providers)
+
+    estimates: list[WorkflowEstimate] = []
+    for provider in providers:
+        est = estimate_workflow(workflow, provider=provider)
+        estimates.append(est)
+
+    if not estimates:
+        return CompareResult(
+            workflow_name=workflow.name,
+            estimates=[],
+            cheapest="",
+            most_expensive="",
+            savings_pct=0.0,
+        )
+
+    cheapest = min(estimates, key=lambda e: e.total_cost_usd)
+    most_expensive = max(estimates, key=lambda e: e.total_cost_usd)
+
+    savings = 0.0
+    if most_expensive.total_cost_usd > 0:
+        savings = round((1 - cheapest.total_cost_usd / most_expensive.total_cost_usd) * 100, 1)
+
+    return CompareResult(
+        workflow_name=workflow.name,
+        estimates=estimates,
+        cheapest=cheapest.provider,
+        most_expensive=most_expensive.provider,
+        savings_pct=savings,
+    )

agent_lint/config.py

@@ -0,0 +1,83 @@
+"""Configuration constants and defaults for agent-lint."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Token defaults by agent role (when estimated_tokens not declared).
+# ---------------------------------------------------------------------------
+ROLE_TOKEN_DEFAULTS: dict[str, int] = {
+    "planner": 5000,
+    "builder": 20000,
+    "tester": 10000,
+    "reviewer": 5000,
+    "architect": 8000,
+    "documenter": 6000,
+    "analyst": 8000,
+    "reporter": 4000,
+    "visualizer": 5000,
+    "security_auditor": 12000,
+}
+
+# Default tokens by step type when no role is specified.
+STEP_TYPE_TOKEN_DEFAULTS: dict[str, int] = {
+    "llm": 8000,
+    "shell": 0,
+    "checkpoint": 0,
+    "mcp_tool": 0,
+    "fan_in": 0,
+    "branch": 0,
+}
+
+# Input/output token ratio (30% input, 70% output).
+INPUT_OUTPUT_RATIO: float = 0.3
+
+# ---------------------------------------------------------------------------
+# Gorgon step type → provider mapping.
+# ---------------------------------------------------------------------------
+STEP_TYPE_PROVIDER_MAP: dict[str, str] = {
+    "claude_code": "anthropic",
+    "openai": "openai",
+}
+
+# ---------------------------------------------------------------------------
+# Gorgon step types that are LLM-based (cost tokens).
+# ---------------------------------------------------------------------------
+LLM_STEP_TYPES: frozenset[str] = frozenset({"claude_code", "openai"})
+
+# Non-LLM step types (zero token cost).
+ZERO_COST_STEP_TYPES: frozenset[str] = frozenset(
+    {
+        "shell",
+        "checkpoint",
+        "mcp_tool",
+        "fan_in",
+        "branch",
+    }
+)
+
+# Container step types (sum nested steps).
+CONTAINER_STEP_TYPES: frozenset[str] = frozenset(
+    {
+        "parallel",
+        "fan_out",
+        "map_reduce",
+        "loop",
+    }
+)
+
+# ---------------------------------------------------------------------------
+# Lint scoring weights.
+# ---------------------------------------------------------------------------
+SEVERITY_DEDUCTIONS: dict[str, int] = {
+    "error": 10,
+    "warning": 5,
+    "info": 2,
+}
+
+# ---------------------------------------------------------------------------
+# Paths.
+# ---------------------------------------------------------------------------
+DATA_DIR: Path = Path(__file__).parent / "data"
+PROVIDERS_FILE: Path = DATA_DIR / "providers.yaml"

agent_lint/data/providers.yaml

@@ -0,0 +1,54 @@
+# Provider pricing database for agent-lint.
+# Prices in USD per 1K tokens. Updated 2025-Q4.
+
+providers:
+  anthropic:
+    default_model: claude-sonnet-4
+    models:
+      claude-opus-4:
+        input: 0.015
+        output: 0.075
+        context: 200000
+      claude-sonnet-4:
+        input: 0.003
+        output: 0.015
+        context: 200000
+      claude-haiku-3.5:
+        input: 0.0008
+        output: 0.004
+        context: 200000
+
+  openai:
+    default_model: gpt-4o
+    models:
+      gpt-4o:
+        input: 0.0025
+        output: 0.01
+        context: 128000
+      gpt-4o-mini:
+        input: 0.00015
+        output: 0.0006
+        context: 128000
+      o1:
+        input: 0.015
+        output: 0.06
+        context: 200000
+
+  ollama:
+    default_model: llama3.3-70b
+    models:
+      llama3.3-70b:
+        input: 0.0
+        output: 0.0
+        context: 131072
+        notes: "Self-hosted, hardware cost not included"
+      deepseek-r1:
+        input: 0.0
+        output: 0.0
+        context: 65536
+        notes: "Self-hosted"
+
+# Map Gorgon step types to providers.
+step_type_mapping:
+  claude_code: anthropic
+  openai: openai

agent_lint/estimator.py

@@ -0,0 +1,130 @@
+"""Token estimation engine."""
+
+from __future__ import annotations
+
+from agent_lint.config import (
+    INPUT_OUTPUT_RATIO,
+    ROLE_TOKEN_DEFAULTS,
+    STEP_TYPE_TOKEN_DEFAULTS,
+)
+from agent_lint.models import (
+    ParsedStep,
+    ParsedWorkflow,
+    StepEstimate,
+    StepType,
+    WorkflowEstimate,
+)
+from agent_lint.pricing import calculate_cost, get_model_pricing, load_providers
+
+
+def _resolve_tokens(step: ParsedStep) -> tuple[int, str]:
+    """Resolve token estimate for a step. Returns (tokens, source)."""
+    # 1. Declared in YAML.
+    if step.estimated_tokens is not None:
+        return step.estimated_tokens, "declared"
+
+    # 2. Archetype default by role.
+    if step.role and step.role in ROLE_TOKEN_DEFAULTS:
+        return ROLE_TOKEN_DEFAULTS[step.role], "archetype"
+
+    # 3. Step type default.
+    default = STEP_TYPE_TOKEN_DEFAULTS.get(step.step_type.value, 0)
+    if step.step_type == StepType.LLM and default == 0:
+        default = STEP_TYPE_TOKEN_DEFAULTS.get("llm", 8000)
+    return default, "default"
+
+
+def _split_tokens(total: int) -> tuple[int, int]:
+    """Split total tokens into input/output based on ratio."""
+    input_tokens = int(total * INPUT_OUTPUT_RATIO)
+    output_tokens = total - input_tokens
+    return input_tokens, output_tokens
+
+
+def estimate_step(
+    step: ParsedStep,
+    provider: str,
+    model: str,
+) -> StepEstimate:
+    """Estimate tokens and cost for a single step."""
+    total_tokens, source = _resolve_tokens(step)
+
+    # Container steps: sum nested step tokens.
+    if step.nested_steps:
+        nested_total = sum(_resolve_tokens(ns)[0] for ns in step.nested_steps)
+        if nested_total > total_tokens:
+            total_tokens = nested_total
+            source = "declared" if step.estimated_tokens else "archetype"
+
+    input_tokens, output_tokens = _split_tokens(total_tokens)
+
+    # Non-LLM steps have zero cost regardless.
+    if step.step_type != StepType.LLM:
+        cost = 0.0
+    else:
+        pricing = get_model_pricing(provider, model)
+        cost = calculate_cost(input_tokens, output_tokens, pricing)
+
+    return StepEstimate(
+        step_id=step.id,
+        step_type=step.step_type,
+        provider=provider,
+        model=model,
+        role=step.role,
+        estimated_tokens=total_tokens,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cost_usd=cost,
+        source=source,
+    )
+
+
+def estimate_workflow(
+    workflow: ParsedWorkflow,
+    provider: str | None = None,
+    model: str | None = None,
+) -> WorkflowEstimate:
+    """Estimate total tokens and cost for a workflow."""
+    providers = load_providers()
+
+    # Track whether the user explicitly set the provider.
+    explicit_provider = provider is not None
+
+    # Determine default provider from first LLM step.
+    if provider is None:
+        for step in workflow.steps:
+            if step.provider:
+                provider = step.provider
+                break
+        if provider is None:
+            provider = "anthropic"
+
+    # Determine model.
+    if model is None:
+        config = providers.get(provider)
+        model = config.default_model if config else "unknown"
+
+    step_estimates: list[StepEstimate] = []
+    for step in workflow.steps:
+        # Explicit CLI provider overrides step-level providers.
+        step_provider = provider if explicit_provider else step.provider or provider
+        step_model = step.model or model
+        step_estimates.append(estimate_step(step, step_provider, step_model))
+
+    total_tokens = sum(e.estimated_tokens for e in step_estimates)
+    total_cost = sum(e.cost_usd for e in step_estimates)
+
+    budget_util: float | None = None
+    if workflow.token_budget and workflow.token_budget > 0:
+        budget_util = round((total_tokens / workflow.token_budget) * 100, 1)
+
+    return WorkflowEstimate(
+        workflow_name=workflow.name,
+        total_tokens=total_tokens,
+        total_cost_usd=round(total_cost, 6),
+        budget_declared=workflow.token_budget,
+        budget_utilization=budget_util,
+        steps=step_estimates,
+        provider=provider,
+        model=model,
+    )

agent_lint/exceptions.py

@@ -0,0 +1,27 @@
+"""Custom exceptions for agent-lint."""
+
+from __future__ import annotations
+
+
+class AgentAuditError(Exception):
+    """Base exception for all agent-lint errors."""
+
+
+class ParseError(AgentAuditError):
+    """Workflow YAML parsing failed."""
+
+
+class EstimateError(AgentAuditError):
+    """Cost estimation failed."""
+
+
+class LintError(AgentAuditError):
+    """Linting failed unexpectedly."""
+
+
+class PricingError(AgentAuditError):
+    """Pricing data load or calculation failed."""
+
+
+class LicenseError(AgentAuditError):
+    """Feature requires a higher license tier."""