skillpool 4.3.0__py3-none-any.whl

skillpool/cost/__init__.py

@@ -0,0 +1,111 @@
+"""CostManager — unified cost tracking, budgeting, and throttling."""
+
+from __future__ import annotations
+
+from skillpool.cost.models import (
+    BudgetStatus,
+    CostDashboardResponse,
+    CostQuery,
+    CostRecord,
+    ThrottleAction,
+)
+from skillpool.cost.token_governor import TokenGovernor
+from skillpool.cost.budget_tracker import BudgetTracker
+from skillpool.cost.trace_ceiling import TraceCeiling
+from skillpool.cost.audit_hash import AuditHashChain
+from skillpool.cost.dashboard import CostDashboard
+
+
+class CostManager:
+    """Central cost management: recording, throttling, budgeting, auditing.
+
+    Combines TokenGovernor, BudgetTracker, TraceCeiling, AuditHashChain/AuditLayer,
+    and CostDashboard into a single facade.
+
+    When an AuditLayer is provided via audit_layer parameter, it is used for
+    full 34-field OTel audit records. Otherwise the lightweight AuditHashChain
+    is used for basic hash chain integrity.
+    """
+
+    def __init__(
+        self,
+        monthly_budget_usd: float = 5000.0,
+        trace_ceiling_usd: float = 5.0,
+        audit_layer=None,
+    ) -> None:
+        self._governor = TokenGovernor()
+        self._budget = BudgetTracker(monthly_budget_usd=monthly_budget_usd)
+        self._trace_ceiling = TraceCeiling(ceiling_usd=trace_ceiling_usd)
+        # Use full AuditLayer if provided, otherwise lightweight AuditHashChain
+        if audit_layer is not None:
+            self._audit = audit_layer
+            self._audit_full = True
+        else:
+            self._audit = AuditHashChain()
+            self._audit_full = False
+        self._dashboard = CostDashboard(governor=self._governor, budget_tracker=self._budget)
+
+    def report_cost(self, record: CostRecord) -> bool:
+        """Process a cost record: validate, record, check throttles.
+
+        Returns True if the cost was accepted, False if rejected by
+        budget or trace ceiling.
+        """
+        total_tokens = record.tokens_input + record.tokens_output
+
+        # Check trace ceiling
+        allowed, reason = self._trace_ceiling.check(record.trace_id, record.cost_usd)
+        if not allowed:
+            return False
+
+        # Check budget threshold
+        threshold, action = self._budget.check_budget_threshold()
+        if action == "block":
+            return False
+
+        # Record usage
+        self._governor.record_usage(record.agent_id, total_tokens)
+        self._budget.record_cost(record.cost_usd)
+        self._trace_ceiling.record_trace_cost(record.trace_id, record.cost_usd)
+
+        # Audit record: full AuditLayer or lightweight AuditHashChain
+        if self._audit_full:
+            self._audit.append(
+                action="cost_record",
+                object_id=record.agent_id,
+                result="success",
+                metadata={
+                    "cost_usd": record.cost_usd,
+                    "tokens_input": record.tokens_input,
+                    "tokens_output": record.tokens_output,
+                    "trace_id": record.trace_id,
+                },
+                trace_id=record.trace_id,
+            )
+        else:
+            self._audit.append(record.model_dump(mode="json"))
+
+        self._dashboard.record(
+            agent_id=record.agent_id,
+            tokens_input=record.tokens_input,
+            tokens_output=record.tokens_output,
+            cost_usd=record.cost_usd,
+            model=record.model,
+            operation=record.operation,
+            skill_id=record.skill_id,
+        )
+
+        return True
+
+    def get_dashboard(self, query: CostQuery) -> CostDashboardResponse:
+        """Query the cost dashboard."""
+        return self._dashboard.query(query)
+
+    def get_budget(self) -> BudgetStatus:
+        """Return current monthly budget status."""
+        return self._dashboard.get_budget_status()
+
+    def check_throttle(self, agent_id: str, tokens: int) -> ThrottleAction:
+        """Check throttle status for an agent/token request."""
+        action, _ = self._governor.check(agent_id, tokens)
+        return action

skillpool/cost/audit_hash.py

@@ -0,0 +1,51 @@
+"""AuditHashChain — SHA-256 hash chain for cost record integrity."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+
+class AuditHashChain:
+    """Maintain a tamper-evident hash chain over cost records.
+
+    Each record's hash is computed from the previous hash + current record data,
+    creating a linked chain where any modification to a prior record invalidates
+    all subsequent hashes.
+    """
+
+    def __init__(self) -> None:
+        self._hashes: list[str] = []
+        self._records: list[dict] = []
+
+    @staticmethod
+    def compute_hash(previous_hash: str, record_data: dict) -> str:
+        """Compute SHA-256 hash from previous hash and record data."""
+        payload = previous_hash + json.dumps(record_data, sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+    def append(self, record_data: dict) -> str:
+        """Append a record to the chain and return its hash."""
+        previous = self._hashes[-1] if self._hashes else "0" * 64
+        new_hash = self.compute_hash(previous, record_data)
+        self._hashes.append(new_hash)
+        self._records.append(record_data)
+        return new_hash
+
+    def verify_chain(self) -> bool:
+        """Verify the entire hash chain is consistent.
+
+        Recomputes every hash from scratch and checks against stored values.
+        Returns True if the chain is intact.
+        """
+        previous = "0" * 64
+        for i, record in enumerate(self._records):
+            expected = self.compute_hash(previous, record)
+            if self._hashes[i] != expected:
+                return False
+            previous = expected
+        return True
+
+    def get_chain(self) -> list[str]:
+        """Return a copy of the hash chain."""
+        return list(self._hashes)

skillpool/cost/budget_tracker.py

@@ -0,0 +1,66 @@
+"""BudgetTracker — monthly budget enforcement with threshold alerts."""
+
+from __future__ import annotations
+
+from skillpool.cost.models import AgentConfig, BudgetStatus
+
+
+class BudgetTracker:
+    """Track monthly cost against a budget with threshold actions.
+
+    Thresholds:
+      - >=50% remaining: normal
+      - >=25% remaining: caution
+      - >=10% remaining: warning
+      - 0% remaining: critical (all spending blocked)
+    """
+
+    def __init__(self, monthly_budget_usd: float = 5000.0) -> None:
+        self.monthly_budget_usd = monthly_budget_usd
+        self._consumed_usd: float = 0.0
+
+    def record_cost(self, cost_usd: float) -> None:
+        """Record a cost event against the monthly budget."""
+        self._consumed_usd += cost_usd
+
+    def get_status(self, agent_configs: list[AgentConfig] | None = None) -> BudgetStatus:
+        """Return current monthly budget status."""
+        remaining = self.monthly_budget_usd - self._consumed_usd
+        consumed_pct = self.get_consumed_pct()
+        # Project: if we've used X% so far, assume linear burn to month end
+        projected = self._consumed_usd  # simplified; real impl would use day-of-month
+        if consumed_pct > 0:
+            # Approximate projection assuming mid-month
+            projected = self._consumed_usd * 2.0
+        return BudgetStatus(
+            monthly_budget_usd=self.monthly_budget_usd,
+            consumed_usd=round(self._consumed_usd, 4),
+            remaining_usd=round(max(0.0, remaining), 4),
+            consumed_pct=round(consumed_pct, 4),
+            projected_month_end_usd=round(projected, 4),
+            per_agent_limits=agent_configs or [],
+        )
+
+    def get_consumed_pct(self) -> float:
+        """Return percentage of monthly budget consumed (0.0 - 1.0+)."""
+        if self.monthly_budget_usd <= 0:
+            return 1.0
+        return self._consumed_usd / self.monthly_budget_usd
+
+    def check_budget_threshold(self) -> tuple[str, str]:
+        """Check budget threshold and return (threshold_name, action).
+
+        Returns:
+            - ("normal", "continue") when >50% budget remaining
+            - ("caution", "monitor") when 25-50% remaining
+            - ("warning", "throttle") when 10-25% remaining
+            - ("critical", "block") when <10% remaining
+        """
+        remaining_pct = 1.0 - self.get_consumed_pct()
+        if remaining_pct < 0.10:
+            return "critical", "block"
+        if remaining_pct < 0.25:
+            return "warning", "throttle"
+        if remaining_pct < 0.50:
+            return "caution", "monitor"
+        return "normal", "continue"

skillpool/cost/dashboard.py

@@ -0,0 +1,189 @@
+"""CostDashboard — aggregated cost query and reporting."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from skillpool.cost.models import (
+    AgentCost,
+    CostDashboardResponse,
+    CostQuery,
+    BudgetStatus,
+)
+from skillpool.cost.token_governor import TokenGovernor
+from skillpool.cost.budget_tracker import BudgetTracker
+from skillpool.utils.time_utils import utc_now
+
+
+class CostDashboard:
+    """Aggregate cost data across agents for dashboard queries.
+
+    Uses TokenGovernor for per-agent budget/throttle state and
+    BudgetTracker for monthly budget status.
+    """
+
+    def __init__(
+        self,
+        governor: TokenGovernor,
+        budget_tracker: BudgetTracker,
+    ) -> None:
+        self._governor = governor
+        self._budget = budget_tracker
+        # In-memory cost records for aggregation
+        self._records: list[dict] = []
+
+    def record(
+        self,
+        agent_id: str,
+        tokens_input: int,
+        tokens_output: int,
+        cost_usd: float,
+        model: str = "",
+        operation: str = "",
+        skill_id: str = "",
+    ) -> None:
+        """Store a cost record for later querying."""
+        self._records.append(
+            {
+                "agent_id": agent_id,
+                "tokens_input": tokens_input,
+                "tokens_output": tokens_output,
+                "cost_usd": cost_usd,
+                "model": model,
+                "operation": operation,
+                "skill_id": skill_id,
+                "timestamp": utc_now().isoformat(),
+            }
+        )
+
+    def query(self, request: CostQuery) -> CostDashboardResponse:
+        """Query aggregated cost data.
+
+        Supports multi-dimension grouping: agent_id, model, skill_id, operation.
+        """
+        # Filter by agent_id if specified
+        records = self._records
+        if request.agent_id:
+            records = [r for r in records if r["agent_id"] == request.agent_id]
+
+        # Aggregate by agent
+        agent_data: dict[str, dict] = {}
+        model_data: dict[str, dict] = {}
+        skill_data: dict[str, dict] = {}
+        op_data: dict[str, dict] = {}
+        total_cost = 0.0
+        total_tokens = 0
+
+        for r in records:
+            aid = r["agent_id"]
+            if aid not in agent_data:
+                agent_data[aid] = {"tokens": 0, "cost_usd": 0.0}
+            agent_data[aid]["tokens"] += r["tokens_input"] + r["tokens_output"]
+            agent_data[aid]["cost_usd"] += r["cost_usd"]
+
+            # Group by model
+            model = r.get("model", "")
+            if model:
+                if model not in model_data:
+                    model_data[model] = {"tokens": 0, "cost_usd": 0.0}
+                model_data[model]["tokens"] += r["tokens_input"] + r["tokens_output"]
+                model_data[model]["cost_usd"] += r["cost_usd"]
+
+            # Group by skill_id
+            skill = r.get("skill_id", "")
+            if skill:
+                if skill not in skill_data:
+                    skill_data[skill] = {"tokens": 0, "cost_usd": 0.0}
+                skill_data[skill]["tokens"] += r["tokens_input"] + r["tokens_output"]
+                skill_data[skill]["cost_usd"] += r["cost_usd"]
+
+            # Group by operation
+            op = r.get("operation", "")
+            if op:
+                if op not in op_data:
+                    op_data[op] = {"tokens": 0, "cost_usd": 0.0}
+                op_data[op]["tokens"] += r["tokens_input"] + r["tokens_output"]
+                op_data[op]["cost_usd"] += r["cost_usd"]
+
+            total_cost += r["cost_usd"]
+            total_tokens += r["tokens_input"] + r["tokens_output"]
+
+        # Build per-agent summaries
+        by_agent: list[AgentCost] = []
+        for aid, data in agent_data.items():
+            cfg = self._governor.get_config(aid)
+            pct_of_total = (data["cost_usd"] / total_cost * 100) if total_cost > 0 else 0.0
+            budget_limit = cfg.daily_limit_tokens if cfg else 0
+            daily_usage = self._governor.get_daily_usage(aid)
+            budget_consumed_pct = (daily_usage / budget_limit) if budget_limit > 0 else 0.0
+
+            by_agent.append(
+                AgentCost(
+                    agent_id=aid,
+                    agent_type=cfg.agent_type if cfg else "",
+                    tokens=data["tokens"],
+                    cost_usd=round(data["cost_usd"], 4),
+                    pct_of_total=round(pct_of_total, 2),
+                    budget_limit=budget_limit,
+                    budget_consumed_pct=round(budget_consumed_pct, 4),
+                    throttled=self._governor.is_throttled(aid),
+                )
+            )
+
+        budget_pct = self._budget.get_consumed_pct() * 100
+
+        # Projected overspend
+        consumed_pct = self._budget.get_consumed_pct()
+        projected_overspend = max(0.0, (consumed_pct * 2.0 - 1.0) * 100) if consumed_pct > 0.5 else 0.0
+
+        # Time series generation
+        series = self._build_time_series(records, request.granularity)
+
+        return CostDashboardResponse(
+            window=request.window,
+            total_cost_usd=round(total_cost, 4),
+            total_tokens=total_tokens,
+            monthly_budget_usd=self._budget.monthly_budget_usd,
+            monthly_budget_consumed_pct=round(budget_pct, 2),
+            by_agent=by_agent,
+            by_model=model_data,
+            by_skill=skill_data,
+            by_operation=op_data,
+            series=series,
+            projected_overspend_pct=round(projected_overspend, 2),
+        )
+
+    @staticmethod
+    def _build_time_series(records: list[dict], granularity: str) -> list[dict]:
+        """Build time series buckets from cost records.
+
+        granularity: "5m" → 5-minute buckets, "1h" → hourly, "1d" → daily.
+        """
+        if not records:
+            return []
+
+        delta_map = {"5m": timedelta(minutes=5), "1h": timedelta(hours=1), "1d": timedelta(days=1)}
+        _delta = delta_map.get(granularity, timedelta(hours=1))
+
+        buckets: dict[str, dict] = {}
+        for r in records:
+            ts = datetime.fromisoformat(r["timestamp"])
+            # Floor to bucket boundary
+            if granularity == "5m":
+                bucket_key = ts.replace(minute=(ts.minute // 5) * 5, second=0, microsecond=0).isoformat()
+            elif granularity == "1d":
+                bucket_key = ts.replace(hour=0, minute=0, second=0, microsecond=0).isoformat()
+            else:  # 1h
+                bucket_key = ts.replace(minute=0, second=0, microsecond=0).isoformat()
+
+            if bucket_key not in buckets:
+                buckets[bucket_key] = {"timestamp": bucket_key, "tokens": 0, "cost_usd": 0.0}
+            buckets[bucket_key]["tokens"] += r["tokens_input"] + r["tokens_output"]
+            buckets[bucket_key]["cost_usd"] += r["cost_usd"]
+
+        return sorted(buckets.values(), key=lambda b: b["timestamp"])
+
+    def get_budget_status(self) -> BudgetStatus:
+        """Return current monthly budget status."""
+        configs = list(self._governor._configs.values())
+        return self._budget.get_status(agent_configs=configs)

skillpool/cost/models.py

@@ -0,0 +1,129 @@
+"""Cost models — Pydantic schemas for cost tracking and budgeting."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from skillpool.utils.time_utils import utc_now
+
+
+class ThrottleAction(StrEnum):
+    ALLOW = "allow"
+    THROTTLE = "throttle"
+    REJECT = "reject"
+
+
+class AgentConfig(BaseModel):
+    """Per-agent token budget configuration."""
+
+    agent_id: str
+    agent_type: str = "worker"
+    daily_limit_tokens: int = Field(default=0, description="0 means unlimited")
+    throttle_at_pct: float = Field(default=0.8, ge=0.0, le=1.0)
+    throttle_to_pct: float = Field(default=0.25, ge=0.0, le=1.0)
+    is_critical: bool = False
+
+
+class CostRecord(BaseModel):
+    """A single cost event record."""
+
+    agent_id: str
+    tokens_input: int = 0
+    tokens_output: int = 0
+    cost_usd: float = Field(default=0.0, ge=0.0)
+    model: str = ""
+    operation: str = ""
+    trace_id: str = ""
+    skill_id: str = ""  # V4.1: per-skill cost attribution
+    timestamp: datetime = Field(default_factory=utc_now)
+
+
+class CostQuery(BaseModel):
+    """Query parameters for cost dashboard.
+
+    V4.1: Supports multi-dimension grouping and granularity.
+    """
+
+    window: str = Field(default="24h", pattern=r"^(1h|6h|24h|7d|30d)$")
+    group_by: list[str] = Field(default_factory=lambda: ["agent_id"])
+    agent_id: Optional[str] = None
+    granularity: str = Field(default="1d", pattern=r"^(5m|1h|1d)$", description="Time series granularity")
+
+
+class AgentCost(BaseModel):
+    """Cost summary for a single agent."""
+
+    agent_id: str
+    agent_type: str = ""
+    tokens: int = 0
+    cost_usd: float = 0.0
+    pct_of_total: float = 0.0
+    budget_limit: int = 0
+    budget_consumed_pct: float = 0.0
+    throttled: bool = False
+
+
+class CostDashboardResponse(BaseModel):
+    """Response from cost dashboard query.
+
+    V4.1: Multi-dimension grouping (by_agent, by_model, by_skill, by_operation)
+    and time series data.
+    """
+
+    window: str
+    total_cost_usd: float = 0.0
+    total_tokens: int = 0
+    monthly_budget_usd: float = 0.0
+    monthly_budget_consumed_pct: float = 0.0
+    by_agent: list[AgentCost] = Field(default_factory=list)
+    by_model: dict[str, dict] = Field(
+        default_factory=dict, description="Cost grouped by model: {model: {tokens, cost_usd}}"
+    )
+    by_skill: dict[str, dict] = Field(
+        default_factory=dict, description="Cost grouped by skill_id: {skill_id: {tokens, cost_usd}}"
+    )
+    by_operation: dict[str, dict] = Field(
+        default_factory=dict, description="Cost grouped by operation: {op: {tokens, cost_usd}}"
+    )
+    series: list[dict] = Field(
+        default_factory=list, description="Time series data [{timestamp, agent_id, tokens, cost_usd}]"
+    )
+    projected_overspend_pct: float = Field(
+        default=0.0, description="Projected overspend percentage if current burn rate continues"
+    )
+
+
+class BudgetStatus(BaseModel):
+    """Monthly budget status."""
+
+    monthly_budget_usd: float
+    consumed_usd: float = 0.0
+    remaining_usd: float = 0.0
+    consumed_pct: float = 0.0
+    projected_month_end_usd: float = 0.0
+    per_agent_limits: list[AgentConfig] = Field(default_factory=list)
+
+
+class CostEstimate(BaseModel):
+    """Session cost estimation result.
+
+    V4.2: P50 conservative pricing model for cost estimation.
+    Combines skill execution cost + review overhead + checkpoint overhead.
+    """
+
+    skill_id: str
+    skill_length: int = Field(description="Character count of skill definition")
+    token_count: int = Field(description="Estimated token count")
+    base_cost_usd: float = Field(description="Skill execution cost (P50 pricing)")
+    l2_review_overhead_usd: float = Field(default=0.0, description="L2 checkpoint review overhead")
+    l3_review_overhead_usd: float = Field(default=0.0, description="L3+L2+ checkpoint review overhead")
+    review_checkpoint_overhead_usd: float = Field(default=0.0, description="Review checkpoint overhead")
+    total_cost_usd: float = Field(description="Total estimated cost")
+    price_per_1k_tokens: float = Field(default=0.003, description="P50 pricing: $0.003/1K tokens")
+    gate_passed: bool = Field(default=True, description="Gate validation result")
+    gate_block_reason: str | None = Field(default=None, description="Gate block reason if failed")
+    emergency_bypass_active: bool = Field(default=False, description="Emergency bypass status")