specsmith 0.1.4.dev33__tar.gz → 0.1.4.dev34__tar.gz

{specsmith-0.1.4.dev33/src/specsmith.egg-info → specsmith-0.1.4.dev34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.1.4.dev33
+Version: 0.1.4.dev34
 Summary: Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
 Author: BitConcepts
 License: MIT

{specsmith-0.1.4.dev33 → specsmith-0.1.4.dev34}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.1.4.dev33"
+version = "0.1.4.dev34"
 description = "Forge governed project scaffolds from the Agentic AI Development Workflow Specification."
 readme = "README.md"
 license = {text = "MIT"}

{specsmith-0.1.4.dev33 → specsmith-0.1.4.dev34}/src/specsmith/cli.py

@@ -1357,6 +1357,141 @@ def session_end_cmd(project_dir: str) -> None:
         console.print("[bold green]Session clean. Ready to end.[/bold green]")
 
 
+# ---------------------------------------------------------------------------
+# Credits
+# ---------------------------------------------------------------------------
+
+
+@main.group()
+def credits() -> None:
+    """AI credit/token spend tracking and analysis."""
+
+
+@credits.command(name="summary")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--month", default="", help="Filter by month (YYYY-MM).")
+def credits_summary(project_dir: str, month: str) -> None:
+    """Show credit spend summary."""
+    from specsmith.credits import get_summary
+
+    root = Path(project_dir).resolve()
+    s = get_summary(root, month=month)
+    console.print(f"  Tokens in:  {s.total_tokens_in:,}")
+    console.print(f"  Tokens out: {s.total_tokens_out:,}")
+    console.print(f"  Cost:       ${s.total_cost_usd:.4f}")
+    console.print(f"  Sessions:   {s.session_count}")
+    console.print(f"  Entries:    {s.entry_count}")
+    if s.by_model:
+        console.print("\n  By model:")
+        for model, cost in sorted(s.by_model.items(), key=lambda x: -x[1]):
+            console.print(f"    {model}: ${cost:.4f}")
+    if s.alerts:
+        console.print()
+        for alert in s.alerts:
+            console.print(f"  [yellow]\u26a0[/yellow] {alert}")
+
+
+@credits.command(name="record")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--model", default="unknown", help="AI model used.")
+@click.option("--provider", default="unknown", help="AI provider (openai, anthropic, etc.).")
+@click.option("--tokens-in", type=int, default=0, help="Input tokens.")
+@click.option("--tokens-out", type=int, default=0, help="Output tokens.")
+@click.option("--task", default="", help="Task description.")
+@click.option("--cost", type=float, default=None, help="Actual cost in USD (overrides estimate).")
+def credits_record(
+    project_dir: str,
+    model: str,
+    provider: str,
+    tokens_in: int,
+    tokens_out: int,
+    task: str,
+    cost: float | None,
+) -> None:
+    """Record a credit usage entry."""
+    from specsmith.credits import record_usage
+
+    root = Path(project_dir).resolve()
+    entry = record_usage(
+        root,
+        model=model,
+        provider=provider,
+        tokens_in=tokens_in,
+        tokens_out=tokens_out,
+        task=task,
+        cost_usd=cost,
+    )
+    console.print(
+        f"[green]\u2713[/green] Recorded: {entry.model} "
+        f"{entry.tokens_in:,}+{entry.tokens_out:,} tokens "
+        f"(${entry.estimated_cost_usd:.4f})"
+    )
+
+
+@credits.command(name="report")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--output", default="", help="Write to file instead of stdout.")
+def credits_report(project_dir: str, output: str) -> None:
+    """Generate credit spend report."""
+    from specsmith.credits import generate_report
+
+    root = Path(project_dir).resolve()
+    report = generate_report(root)
+    if output:
+        Path(output).write_text(report, encoding="utf-8")
+        console.print(f"[green]\u2713[/green] Report written to {output}")
+    else:
+        console.print(report)
+
+
+@credits.command(name="analyze")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def credits_analyze(project_dir: str) -> None:
+    """Analyze spend patterns and get optimization recommendations."""
+    from specsmith.credit_analyzer import generate_analysis_report
+
+    root = Path(project_dir).resolve()
+    report = generate_analysis_report(root)
+    console.print(report)
+
+
+@credits.command(name="budget")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--cap", type=float, default=None, help="Monthly cap in USD (0=unlimited).")
+@click.option("--alert-pct", type=int, default=None, help="Alert at this % of cap.")
+@click.option(
+    "--watermarks", default=None, help="Comma-separated USD watermark alerts (e.g. 5,10,25,50)."
+)
+def credits_budget(
+    project_dir: str, cap: float | None, alert_pct: int | None, watermarks: str | None,
+) -> None:
+    """View or set credit budget and alert thresholds."""
+    from specsmith.credits import load_budget, save_budget
+
+    root = Path(project_dir).resolve()
+    budget = load_budget(root)
+
+    if cap is not None:
+        budget.monthly_cap_usd = cap
+    if alert_pct is not None:
+        budget.alert_threshold_pct = alert_pct
+    if watermarks is not None:
+        budget.alert_watermarks_usd = [float(w.strip()) for w in watermarks.split(",") if w.strip()]
+
+    if any(x is not None for x in (cap, alert_pct, watermarks)):
+        save_budget(root, budget)
+        console.print("[green]\u2713[/green] Budget updated.")
+
+    cap_note = " (unlimited)" if budget.monthly_cap_usd == 0 else ""
+    console.print(f"  Monthly cap:   ${budget.monthly_cap_usd:.2f}{cap_note}")
+    console.print(f"  Alert at:      {budget.alert_threshold_pct}%")
+    console.print(f"  Watermarks:    {', '.join(f'${w:.2f}' for w in budget.alert_watermarks_usd)}")
+    console.print(f"  Enabled:       {budget.enabled}")
+
+
+main.add_command(credits)
+
+
 # ---------------------------------------------------------------------------
 # Plugin system
 # ---------------------------------------------------------------------------

specsmith-0.1.4.dev34/src/specsmith/credit_analyzer.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Credit analyzer — spend analysis and closed-loop optimization."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class CreditInsight:
+    """Single optimization insight."""
+
+    category: str  # "waste", "model", "governance", "batch"
+    severity: str  # "info", "warn", "critical"
+    message: str
+    recommendation: str
+    estimated_savings_pct: float = 0.0
+
+
+@dataclass
+class AnalysisReport:
+    """Full credit analysis report."""
+
+    insights: list[CreditInsight] = field(default_factory=list)
+    total_cost: float = 0.0
+    estimated_optimized_cost: float = 0.0
+    cost_trend: str = ""  # "increasing", "decreasing", "stable"
+
+
+def analyze_spend(root: Path) -> AnalysisReport:
+    """Analyze credit spend and generate optimization insights."""
+    from specsmith.credits import _load_entries
+
+    entries = _load_entries(root)
+    report = AnalysisReport()
+
+    if not entries:
+        report.insights.append(
+            CreditInsight(
+                category="info",
+                severity="info",
+                message="No credit data yet.",
+                recommendation=(
+                    "Record usage with `specsmith credits record` "
+                    "or integrate with your AI agent."
+                ),
+            )
+        )
+        return report
+
+    report.total_cost = sum(e.estimated_cost_usd for e in entries)
+
+    # --- Analysis 1: Model efficiency ---
+    model_costs: dict[str, list[float]] = {}
+    for e in entries:
+        model_costs.setdefault(e.model, []).append(e.estimated_cost_usd)
+
+    if len(model_costs) > 1:
+        avg_by_model = {m: sum(c) / len(c) for m, c in model_costs.items() if c}
+        most_expensive = max(avg_by_model, key=avg_by_model.get)  # type: ignore[arg-type]
+        cheapest = min(avg_by_model, key=avg_by_model.get)  # type: ignore[arg-type]
+        if avg_by_model[most_expensive] > avg_by_model[cheapest] * 3:
+            report.insights.append(
+                CreditInsight(
+                    category="model",
+                    severity="warn",
+                    message=(
+                        f"{most_expensive} costs {avg_by_model[most_expensive]:.4f}/task avg "
+                        f"vs {cheapest} at {avg_by_model[cheapest]:.4f}/task"
+                    ),
+                    recommendation=(
+                        f"Use {cheapest} for routine tasks (audit, lint, simple edits). "
+                        f"Reserve {most_expensive} for complex architecture/design work."
+                    ),
+                    estimated_savings_pct=30.0,
+                )
+            )
+
+    # --- Analysis 2: Token waste (high input, low output) ---
+    high_input_sessions = [e for e in entries if e.tokens_in > 0 and e.tokens_out > 0]
+    for e in high_input_sessions:
+        ratio = e.tokens_in / max(e.tokens_out, 1)
+        if ratio > 10 and e.tokens_in > 5000:
+            report.insights.append(
+                CreditInsight(
+                    category="waste",
+                    severity="warn",
+                    message=(
+                        f"Task '{e.task or 'unknown'}': {e.tokens_in:,} tokens in, "
+                        f"only {e.tokens_out:,} out (ratio {ratio:.0f}:1)"
+                    ),
+                    recommendation=(
+                        "High input/output ratio suggests large file reads for small changes. "
+                        "Use targeted reads (line ranges) and grep over full file reads."
+                    ),
+                    estimated_savings_pct=20.0,
+                )
+            )
+            break  # One example is enough
+
+    # --- Analysis 3: Governance file size vs cost ---
+    gov_dir = root / "docs" / "governance"
+    gov_files = list(gov_dir.glob("*.md")) if gov_dir.is_dir() else []
+    total_gov_lines = 0
+    for gf in gov_files:
+        total_gov_lines += len(gf.read_text(encoding="utf-8").splitlines())
+    if total_gov_lines > 500:
+        report.insights.append(
+            CreditInsight(
+                category="governance",
+                severity="info",
+                message=(
+                    f"Governance files total {total_gov_lines} lines "
+                    f"across {len(gov_files)} files."
+                ),
+                recommendation=(
+                    "Ensure agents lazy-load governance files. Only rules.md + workflow.md "
+                    "should load at session start. Others on demand."
+                ),
+                estimated_savings_pct=15.0,
+            )
+        )
+
+    # --- Analysis 4: Cost trend ---
+    if len(entries) >= 5:
+        first_half = entries[: len(entries) // 2]
+        second_half = entries[len(entries) // 2 :]
+        avg_first = sum(e.estimated_cost_usd for e in first_half) / len(first_half)
+        avg_second = sum(e.estimated_cost_usd for e in second_half) / len(second_half)
+        if avg_second > avg_first * 1.2:
+            report.cost_trend = "increasing"
+            report.insights.append(
+                CreditInsight(
+                    category="batch",
+                    severity="warn",
+                    message="Cost per task is trending upward.",
+                    recommendation=(
+                        "Review recent tasks for scope creep. Consider batching "
+                        "related changes into fewer sessions."
+                    ),
+                    estimated_savings_pct=10.0,
+                )
+            )
+        elif avg_second < avg_first * 0.8:
+            report.cost_trend = "decreasing"
+        else:
+            report.cost_trend = "stable"
+
+    # Estimate optimized cost
+    total_savings_pct = sum(i.estimated_savings_pct for i in report.insights) / max(
+        len(report.insights), 1
+    )
+    report.estimated_optimized_cost = report.total_cost * (1 - total_savings_pct / 100)
+
+    return report
+
+
+def generate_analysis_report(root: Path) -> str:
+    """Generate a markdown analysis report."""
+    report = analyze_spend(root)
+
+    md = "# Credit Analysis Report\n\n"
+    md += f"- **Total spend**: ${report.total_cost:.4f}\n"
+    if report.estimated_optimized_cost < report.total_cost:
+        savings = report.total_cost - report.estimated_optimized_cost
+        md += (
+            f"- **Estimated optimized**: ${report.estimated_optimized_cost:.4f}"
+            f" (save ${savings:.4f})\n"
+        )
+    if report.cost_trend:
+        md += f"- **Trend**: {report.cost_trend}\n"
+    md += "\n"
+
+    if report.insights:
+        md += "## Insights\n\n"
+        for i, insight in enumerate(report.insights, 1):
+            icon = {"info": "ℹ️", "warn": "⚠️", "critical": "🔴"}.get(insight.severity, "•")
+            md += f"### {i}. {icon} {insight.message}\n\n"
+            md += f"**Recommendation**: {insight.recommendation}\n"
+            if insight.estimated_savings_pct > 0:
+                md += f"**Estimated savings**: {insight.estimated_savings_pct:.0f}%\n"
+            md += "\n"
+
+    return md

specsmith-0.1.4.dev34/src/specsmith/credits.py

@@ -0,0 +1,284 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Credits — AI token/cost spend tracking per project and session."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+
+@dataclass
+class CreditEntry:
+    """Single credit usage record."""
+
+    timestamp: str = ""
+    session_id: str = ""
+    model: str = ""
+    provider: str = ""  # openai, anthropic, google, warp, local
+    tokens_in: int = 0
+    tokens_out: int = 0
+    estimated_cost_usd: float = 0.0
+    task: str = ""  # what was being done
+    duration_seconds: float = 0.0
+
+
+@dataclass
+class CreditBudget:
+    """Budget/alert configuration for a project."""
+
+    monthly_cap_usd: float = 0.0  # 0 = unlimited
+    alert_threshold_pct: int = 80  # warn at this % of cap
+    alert_watermarks_usd: list[float] = field(default_factory=lambda: [5.0, 10.0, 25.0, 50.0])
+    enabled: bool = True
+
+
+@dataclass
+class CreditSummary:
+    """Aggregate credit summary."""
+
+    total_tokens_in: int = 0
+    total_tokens_out: int = 0
+    total_cost_usd: float = 0.0
+    session_count: int = 0
+    entry_count: int = 0
+    by_model: dict[str, float] = field(default_factory=dict)
+    by_provider: dict[str, float] = field(default_factory=dict)
+    by_task: dict[str, float] = field(default_factory=dict)
+    budget: CreditBudget | None = None
+    alerts: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Cost estimation (per 1M tokens, approximate 2026 pricing)
+# ---------------------------------------------------------------------------
+
+_COST_PER_1M: dict[str, tuple[float, float]] = {
+    # (input $/1M, output $/1M)
+    "gpt-4o": (2.50, 10.00),
+    "gpt-4o-mini": (0.15, 0.60),
+    "gpt-4-turbo": (10.00, 30.00),
+    "claude-sonnet": (3.00, 15.00),
+    "claude-haiku": (0.25, 1.25),
+    "claude-opus": (15.00, 75.00),
+    "gemini-pro": (1.25, 5.00),
+    "gemini-flash": (0.075, 0.30),
+    "local": (0.0, 0.0),
+    "unknown": (3.00, 15.00),  # conservative default
+}
+
+
+def estimate_cost(model: str, tokens_in: int, tokens_out: int) -> float:
+    """Estimate USD cost for a token usage."""
+    key = model.lower()
+    # Fuzzy match: find the best matching model key
+    for k in _COST_PER_1M:
+        if k in key:
+            rates = _COST_PER_1M[k]
+            return (tokens_in * rates[0] + tokens_out * rates[1]) / 1_000_000
+    rates = _COST_PER_1M["unknown"]
+    return (tokens_in * rates[0] + tokens_out * rates[1]) / 1_000_000
+
+
+# ---------------------------------------------------------------------------
+# Storage — JSON file at .specsmith/credits.json
+# ---------------------------------------------------------------------------
+
+_CREDITS_DIR = ".specsmith"
+_CREDITS_FILE = "credits.json"
+_BUDGET_FILE = "credit-budget.json"
+
+
+def _get_credits_path(root: Path) -> Path:
+    """Get path to credits JSON file, creating dir if needed."""
+    path = root / _CREDITS_DIR / _CREDITS_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _get_budget_path(root: Path) -> Path:
+    return root / _CREDITS_DIR / _BUDGET_FILE
+
+
+def _load_entries(root: Path) -> list[CreditEntry]:
+    """Load all credit entries from storage."""
+    path = _get_credits_path(root)
+    if not path.exists():
+        return []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return [CreditEntry(**e) for e in data]
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def _save_entries(root: Path, entries: list[CreditEntry]) -> None:
+    """Save credit entries to storage."""
+    path = _get_credits_path(root)
+    path.write_text(
+        json.dumps([asdict(e) for e in entries], indent=2),
+        encoding="utf-8",
+    )
+
+
+def load_budget(root: Path) -> CreditBudget:
+    """Load budget configuration."""
+    path = _get_budget_path(root)
+    if not path.exists():
+        return CreditBudget()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return CreditBudget(**data)
+    except Exception:  # noqa: BLE001
+        return CreditBudget()
+
+
+def save_budget(root: Path, budget: CreditBudget) -> None:
+    """Save budget configuration."""
+    path = _get_budget_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(asdict(budget), indent=2), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def record_usage(
+    root: Path,
+    *,
+    model: str = "unknown",
+    provider: str = "unknown",
+    tokens_in: int = 0,
+    tokens_out: int = 0,
+    task: str = "",
+    session_id: str = "",
+    duration_seconds: float = 0.0,
+    cost_usd: float | None = None,
+) -> CreditEntry:
+    """Record a credit usage entry."""
+    entry = CreditEntry(
+        timestamp=datetime.now().isoformat(),
+        session_id=session_id or datetime.now().strftime("%Y%m%d-%H%M"),
+        model=model,
+        provider=provider,
+        tokens_in=tokens_in,
+        tokens_out=tokens_out,
+        estimated_cost_usd=cost_usd if cost_usd is not None else estimate_cost(
+            model, tokens_in, tokens_out
+        ),
+        task=task,
+        duration_seconds=duration_seconds,
+    )
+    entries = _load_entries(root)
+    entries.append(entry)
+    _save_entries(root, entries)
+    return entry
+
+
+def get_summary(
+    root: Path, *, since: str = "", month: str = "",
+) -> CreditSummary:
+    """Get aggregate credit summary with budget alerts."""
+    entries = _load_entries(root)
+
+    if since:
+        entries = [e for e in entries if e.timestamp >= since]
+    if month:
+        entries = [e for e in entries if e.timestamp[:7] == month]
+
+    summary = CreditSummary(entry_count=len(entries))
+    sessions: set[str] = set()
+
+    for e in entries:
+        summary.total_tokens_in += e.tokens_in
+        summary.total_tokens_out += e.tokens_out
+        summary.total_cost_usd += e.estimated_cost_usd
+        sessions.add(e.session_id)
+
+        # By model
+        summary.by_model[e.model] = summary.by_model.get(e.model, 0.0) + e.estimated_cost_usd
+        # By provider
+        summary.by_provider[e.provider] = (
+            summary.by_provider.get(e.provider, 0.0) + e.estimated_cost_usd
+        )
+        # By task
+        if e.task:
+            summary.by_task[e.task] = summary.by_task.get(e.task, 0.0) + e.estimated_cost_usd
+
+    summary.session_count = len(sessions)
+
+    # Budget alerts
+    budget = load_budget(root)
+    summary.budget = budget
+    if budget.enabled and budget.monthly_cap_usd > 0:
+        current_month = datetime.now().strftime("%Y-%m")
+        month_entries = [e for e in _load_entries(root) if e.timestamp[:7] == current_month]
+        month_cost = sum(e.estimated_cost_usd for e in month_entries)
+
+        pct = (month_cost / budget.monthly_cap_usd) * 100 if budget.monthly_cap_usd else 0
+        if pct >= 100:
+            summary.alerts.append(
+                f"BUDGET EXCEEDED: ${month_cost:.2f} / ${budget.monthly_cap_usd:.2f} "
+                f"({pct:.0f}%)"
+            )
+        elif pct >= budget.alert_threshold_pct:
+            summary.alerts.append(
+                f"Budget warning: ${month_cost:.2f} / ${budget.monthly_cap_usd:.2f} "
+                f"({pct:.0f}%) — approaching cap"
+            )
+
+        # Watermark alerts
+        for watermark in sorted(budget.alert_watermarks_usd):
+            if month_cost >= watermark:
+                summary.alerts.append(f"Watermark: ${watermark:.2f} spend reached this month")
+
+    return summary
+
+
+def generate_report(root: Path, *, since: str = "") -> str:
+    """Generate a markdown credit report."""
+    summary = get_summary(root, since=since)
+
+    report = "# AI Credit Report\n\n"
+    report += f"- **Total tokens in**: {summary.total_tokens_in:,}\n"
+    report += f"- **Total tokens out**: {summary.total_tokens_out:,}\n"
+    report += f"- **Estimated cost**: ${summary.total_cost_usd:.4f}\n"
+    report += f"- **Sessions**: {summary.session_count}\n"
+    report += f"- **Entries**: {summary.entry_count}\n\n"
+
+    if summary.alerts:
+        report += "## Alerts\n\n"
+        for alert in summary.alerts:
+            report += f"- ⚠️ {alert}\n"
+        report += "\n"
+
+    if summary.by_model:
+        report += "## Cost by Model\n\n"
+        for model, cost in sorted(summary.by_model.items(), key=lambda x: -x[1]):
+            report += f"- {model}: ${cost:.4f}\n"
+        report += "\n"
+
+    if summary.by_provider:
+        report += "## Cost by Provider\n\n"
+        for provider, cost in sorted(summary.by_provider.items(), key=lambda x: -x[1]):
+            report += f"- {provider}: ${cost:.4f}\n"
+        report += "\n"
+
+    if summary.by_task:
+        report += "## Cost by Task\n\n"
+        for task, cost in sorted(summary.by_task.items(), key=lambda x: -x[1]):
+            report += f"- {task}: ${cost:.4f}\n"
+        report += "\n"
+
+    if summary.budget and summary.budget.monthly_cap_usd > 0:
+        report += "## Budget\n\n"
+        report += f"- Monthly cap: ${summary.budget.monthly_cap_usd:.2f}\n"
+        report += f"- Alert at: {summary.budget.alert_threshold_pct}%\n"
+        wm = ", ".join(f"${w:.2f}" for w in summary.budget.alert_watermarks_usd)
+        report += f"- Watermarks: {wm}\n"
+
+    return report

{specsmith-0.1.4.dev33 → specsmith-0.1.4.dev34/src/specsmith.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.1.4.dev33
+Version: 0.1.4.dev34
 Summary: Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
 Author: BitConcepts
 License: MIT

{specsmith-0.1.4.dev33 → specsmith-0.1.4.dev34}/src/specsmith.egg-info/SOURCES.txt

@@ -8,6 +8,8 @@ src/specsmith/auditor.py
 src/specsmith/cli.py
 src/specsmith/compressor.py
 src/specsmith/config.py
+src/specsmith/credit_analyzer.py
+src/specsmith/credits.py
 src/specsmith/differ.py
 src/specsmith/doctor.py
 src/specsmith/exporter.py