openanchor 0.1.0__py3-none-any.whl

openanchor/__init__.py

@@ -0,0 +1,56 @@
+"""
+OpenAnchor: Token Consumption Intelligence Platform
+
+OpenAnchor provides observability, attribution, pattern detection, and
+optimization intelligence for AI token consumption.
+
+Built on PyTokenCalc (token accounting foundation).
+
+Quick Start:
+    from openanchor import TokenCollector, Analytics
+
+    collector = TokenCollector()
+    event = collector.capture_event(
+        call_id="call_1",
+        model="gpt-4",
+        provider="openai",
+        input_tokens=100,
+        output_tokens=50
+    )
+
+    # Analyze
+    from openanchor import AttributionModel
+    attribution = AttributionModel(collector.store)
+    breakdown = attribution.analyze_call("call_1")
+"""
+
+from .models import (
+    TokenEvent,
+    TokenConsumption,
+    Attribution,
+    SessionStats,
+    OperationType,
+    RequestPhase,
+)
+from .collector import TokenCollector
+from .storage import EventStore, SqliteEventStore
+from .attribution import AttributionModel
+from .analytics import Analytics
+
+__version__ = "0.1.0"
+__author__ = "Georgi Mammen Mullassery"
+__license__ = "MIT"
+
+__all__ = [
+    "TokenEvent",
+    "TokenConsumption",
+    "Attribution",
+    "SessionStats",
+    "OperationType",
+    "RequestPhase",
+    "TokenCollector",
+    "EventStore",
+    "SqliteEventStore",
+    "AttributionModel",
+    "Analytics",
+]

openanchor/analytics.py

@@ -0,0 +1,252 @@
+"""Analytics and query APIs for token insights."""
+
+from datetime import datetime, timedelta
+from typing import Dict, List, Any, Optional
+from collections import defaultdict
+import logging
+
+from .collector import TokenCollector
+from .attribution import AttributionModel
+from .models import TokenEvent, SessionStats
+from .storage import EventStore
+
+logger = logging.getLogger(__name__)
+
+
+class Analytics:
+    """High-level analytics and query API."""
+
+    def __init__(self, collector: TokenCollector, attribution: AttributionModel):
+        """
+        Initialize analytics engine.
+
+        Args:
+            collector: Token collector
+            attribution: Attribution model
+        """
+        self.collector = collector
+        self.attribution = attribution
+        self.store = collector.store
+
+    # Session-level queries
+
+    def get_session_stats(self, session_id: str) -> SessionStats:
+        """Get overall statistics for a session."""
+        return self.collector.compute_session_stats(session_id)
+
+    def get_all_sessions(self) -> List[str]:
+        """Get all session IDs."""
+        events = self.store.all_events()
+        sessions = set()
+        for event in events:
+            if event.session_id:
+                sessions.add(event.session_id)
+        return sorted(sessions)
+
+    # Call-level queries
+
+    def get_call_stats(self, call_id: str) -> Dict[str, Any]:
+        """Get statistics for a single call."""
+        return self.collector.compute_call_stats(call_id)
+
+    # Token breakdown queries
+
+    def get_tokens_by_operation(self, session_id: str) -> Dict[str, int]:
+        """Get token consumption by operation type."""
+        return self.attribution.get_operation_breakdown(session_id)
+
+    def get_tokens_by_phase(self, session_id: str) -> Dict[str, int]:
+        """Get token consumption by request/response phase."""
+        return self.attribution.get_phase_breakdown(session_id)
+
+    def get_tokens_by_model(self, session_id: str) -> Dict[str, int]:
+        """Get token consumption by model."""
+        return self.attribution.get_model_distribution(session_id)
+
+    def get_tokens_by_prompt_template(self, session_id: str) -> Dict[str, int]:
+        """Get token consumption by prompt template."""
+        events = self.store.get_events_by_session(session_id)
+        breakdown: Dict[str, int] = defaultdict(int)
+
+        for event in events:
+            template = event.prompt_template or "untagged"
+            breakdown[template] += event.tokens.total_tokens
+
+        return dict(breakdown)
+
+    # Efficiency queries
+
+    def rank_prompts_by_efficiency(
+        self, session_id: str, top_n: int = 10
+    ) -> List[tuple]:
+        """Rank prompt templates by efficiency (quality per token)."""
+        return self.attribution.rank_prompts_by_efficiency(session_id, top_n)
+
+    def get_prompt_stats(self, session_id: str) -> Dict[str, Dict[str, float]]:
+        """Get efficiency stats for all prompts in a session."""
+        return self.attribution.get_prompt_efficiency(session_id)
+
+    # Time-based queries
+
+    def get_tokens_by_hour(self, session_id: str) -> Dict[str, int]:
+        """Get token consumption by hour."""
+        events = self.store.get_events_by_session(session_id)
+
+        breakdown: Dict[str, int] = defaultdict(int)
+        for event in events:
+            hour_key = event.timestamp.strftime("%Y-%m-%d %H:00")
+            breakdown[hour_key] += event.tokens.total_tokens
+
+        return dict(sorted(breakdown.items()))
+
+    def get_tokens_by_day(self, session_id: str) -> Dict[str, int]:
+        """Get token consumption by day."""
+        events = self.store.get_events_by_session(session_id)
+
+        breakdown: Dict[str, int] = defaultdict(int)
+        for event in events:
+            day_key = event.timestamp.strftime("%Y-%m-%d")
+            breakdown[day_key] += event.tokens.total_tokens
+
+        return dict(sorted(breakdown.items()))
+
+    # Performance queries
+
+    def get_latency_stats(self, session_id: str) -> Dict[str, float]:
+        """Get latency statistics for a session."""
+        events = self.store.get_events_by_session(session_id)
+
+        latencies = [e.latency_ms for e in events if e.latency_ms]
+        if not latencies:
+            return {"count": 0}
+
+        latencies.sort()
+        total = sum(latencies)
+
+        return {
+            "count": len(latencies),
+            "avg_ms": total / len(latencies),
+            "median_ms": latencies[len(latencies) // 2],
+            "min_ms": min(latencies),
+            "max_ms": max(latencies),
+            "p95_ms": latencies[int(len(latencies) * 0.95)],
+            "p99_ms": latencies[int(len(latencies) * 0.99)],
+        }
+
+    def get_quality_stats(self, session_id: str) -> Dict[str, float]:
+        """Get quality score statistics for a session."""
+        events = self.store.get_events_by_session(session_id)
+
+        scores = [e.quality_score for e in events if e.quality_score is not None]
+        if not scores:
+            return {"count": 0}
+
+        scores.sort()
+        total = sum(scores)
+
+        return {
+            "count": len(scores),
+            "avg": total / len(scores),
+            "median": scores[len(scores) // 2],
+            "min": min(scores),
+            "max": max(scores),
+        }
+
+    # Comparison queries
+
+    def compare_sessions(self, session_ids: List[str]) -> Dict[str, Dict[str, Any]]:
+        """Compare statistics across sessions."""
+        comparison: Dict[str, Dict[str, Any]] = {}
+
+        for session_id in session_ids:
+            stats = self.get_session_stats(session_id)
+            comparison[session_id] = {
+                "total_tokens": stats.total_tokens,
+                "total_calls": stats.total_calls,
+                "avg_latency_ms": stats.avg_latency_ms,
+                "avg_quality": stats.avg_quality_score,
+                "tokens_per_call": (
+                    stats.total_tokens / stats.total_calls if stats.total_calls > 0 else 0
+                ),
+            }
+
+        return comparison
+
+    # Diagnostic queries
+
+    def get_problematic_calls(
+        self, session_id: str, min_tokens: int = 5000, max_quality: float = 0.8
+    ) -> List[Dict[str, Any]]:
+        """
+        Find calls that consumed many tokens but had low quality.
+
+        Args:
+            session_id: Session to analyze
+            min_tokens: Minimum tokens to consider problematic
+            max_quality: Maximum quality score to flag
+
+        Returns:
+            List of problematic calls
+        """
+        events = self.store.get_events_by_session(session_id)
+
+        problematic = []
+        call_stats: Dict[str, Dict[str, Any]] = defaultdict(lambda: {"tokens": 0})
+
+        for event in events:
+            call_id = event.call_id
+            call_stats[call_id]["tokens"] += event.tokens.total_tokens
+
+            if event.quality_score is not None:
+                if "quality_scores" not in call_stats[call_id]:
+                    call_stats[call_id]["quality_scores"] = []
+                call_stats[call_id]["quality_scores"].append(event.quality_score)
+
+        for call_id, stats in call_stats.items():
+            if stats["tokens"] < min_tokens:
+                continue
+
+            avg_quality = (
+                sum(stats["quality_scores"]) / len(stats["quality_scores"])
+                if "quality_scores" in stats and stats["quality_scores"]
+                else 1.0
+            )
+
+            if avg_quality <= max_quality:
+                problematic.append(
+                    {
+                        "call_id": call_id,
+                        "total_tokens": stats["tokens"],
+                        "avg_quality": avg_quality,
+                        "quality_ratio": (
+                            avg_quality / stats["tokens"] if stats["tokens"] > 0 else 0
+                        ),
+                    }
+                )
+
+        return sorted(
+            problematic,
+            key=lambda x: x["quality_ratio"],
+        )
+
+    def get_summary(self, session_id: str) -> Dict[str, Any]:
+        """Get a comprehensive summary of session activity."""
+        stats = self.get_session_stats(session_id)
+        op_breakdown = self.get_tokens_by_operation(session_id)
+        phase_breakdown = self.get_tokens_by_phase(session_id)
+        latency_stats = self.get_latency_stats(session_id)
+        quality_stats = self.get_quality_stats(session_id)
+
+        return {
+            "session_id": session_id,
+            "total_tokens": stats.total_tokens,
+            "total_calls": stats.total_calls,
+            "duration_seconds": stats.duration_seconds,
+            "by_operation": op_breakdown,
+            "by_phase": phase_breakdown,
+            "latency_stats": latency_stats,
+            "quality_stats": quality_stats,
+            "tokens_per_call": (
+                stats.total_tokens / stats.total_calls if stats.total_calls > 0 else 0
+            ),
+        }

openanchor/attribution.py

@@ -0,0 +1,265 @@
+"""Token attribution analysis (6D breakdown)."""
+
+from datetime import datetime
+from typing import Dict, List, Optional
+from collections import defaultdict
+import logging
+
+from .models import Attribution, OperationType, RequestPhase, TokenEvent
+from .storage import EventStore
+
+logger = logging.getLogger(__name__)
+
+
+class AttributionModel:
+    """Performs 6-dimensional token attribution analysis."""
+
+    def __init__(self, store: EventStore):
+        """
+        Initialize attribution model.
+
+        Args:
+            store: Event store to analyze
+        """
+        self.store = store
+
+    def analyze_call(self, call_id: str) -> Attribution:
+        """
+        Analyze token attribution for a single call.
+
+        Breaks down tokens across 6 dimensions:
+        1. WHEN: Request vs response phase
+        2. WHERE: Operation type (GitHub, PDF, reasoning, etc.)
+        3. HOW: Sub-operation (GitHub read/write/search)
+        4. WHICH: Prompt template used
+        5. SESSION/PHASE: Temporal grouping
+        6. WHY: Patterns and recommendations (v0.2+)
+
+        Args:
+            call_id: Call to analyze
+
+        Returns:
+            Attribution breakdown
+        """
+        events = self.store.get_events_by_call(call_id)
+
+        if not events:
+            return Attribution(call_id=call_id)
+
+        # Check cache first
+        cached = self.store.get_attribution(call_id)
+        if cached:
+            return cached
+
+        # Breakdown by phase
+        by_phase: Dict[RequestPhase, int] = defaultdict(int)
+        # Breakdown by operation type
+        by_operation: Dict[OperationType, int] = defaultdict(int)
+        # Breakdown by prompt template
+        by_prompt_template: Dict[str, int] = defaultdict(int)
+
+        total_tokens = 0
+
+        for event in events:
+            tokens = event.tokens.total_tokens
+            total_tokens += tokens
+
+            # WHEN: Request vs response
+            by_phase[event.phase] += tokens
+
+            # WHERE & HOW: Operation type
+            by_operation[event.operation_type] += tokens
+
+            # WHICH: Prompt template
+            if event.prompt_template:
+                by_prompt_template[event.prompt_template] += tokens
+            else:
+                by_prompt_template["untagged"] += tokens
+
+        attribution = Attribution(
+            call_id=call_id,
+            by_phase=dict(by_phase),
+            by_operation=dict(by_operation),
+            by_prompt_template=dict(by_prompt_template),
+            total_tokens=total_tokens,
+        )
+
+        # Cache the result
+        self.store.add_attribution(attribution)
+
+        return attribution
+
+    def get_operation_breakdown(self, session_id: str) -> Dict[str, int]:
+        """
+        Get token breakdown by operation type for a session.
+
+        Returns:
+            Dict mapping operation names to token counts
+        """
+        events = self.store.get_events_by_session(session_id)
+
+        breakdown: Dict[str, int] = defaultdict(int)
+        for event in events:
+            op_name = event.operation_type.value
+            breakdown[op_name] += event.tokens.total_tokens
+
+        return dict(breakdown)
+
+    def get_phase_breakdown(self, session_id: str) -> Dict[str, int]:
+        """
+        Get token breakdown by request/response phase.
+
+        Returns:
+            Dict with 'request' and 'response' token counts
+        """
+        events = self.store.get_events_by_session(session_id)
+
+        breakdown: Dict[str, int] = {"request": 0, "response": 0}
+        for event in events:
+            phase_name = event.phase.value
+            breakdown[phase_name] += event.tokens.total_tokens
+
+        return breakdown
+
+    def get_prompt_efficiency(self, session_id: str) -> Dict[str, Dict[str, float]]:
+        """
+        Rank prompts by efficiency (tokens per quality point).
+
+        Returns:
+            Dict mapping prompt templates to efficiency metrics
+        """
+        events = self.store.get_events_by_session(session_id)
+
+        prompt_stats: Dict[str, Dict[str, List[float]]] = defaultdict(
+            lambda: {"tokens": [], "quality": []}
+        )
+
+        for event in events:
+            if event.prompt_template:
+                prompt_stats[event.prompt_template]["tokens"].append(
+                    event.tokens.total_tokens
+                )
+                if event.quality_score is not None:
+                    prompt_stats[event.prompt_template]["quality"].append(
+                        event.quality_score
+                    )
+
+        # Calculate efficiency
+        efficiency: Dict[str, Dict[str, float]] = {}
+        for prompt, stats in prompt_stats.items():
+            if not stats["tokens"]:
+                continue
+
+            avg_tokens = sum(stats["tokens"]) / len(stats["tokens"])
+            avg_quality = (
+                sum(stats["quality"]) / len(stats["quality"])
+                if stats["quality"]
+                else 0.0
+            )
+
+            efficiency[prompt] = {
+                "avg_tokens": avg_tokens,
+                "avg_quality": avg_quality,
+                "efficiency_score": (
+                    avg_quality / avg_tokens if avg_tokens > 0 else 0.0
+                ),
+                "usage_count": len(stats["tokens"]),
+            }
+
+        return efficiency
+
+    def get_model_distribution(self, session_id: str) -> Dict[str, int]:
+        """
+        Get token distribution across models.
+
+        Returns:
+            Dict mapping model names to token counts
+        """
+        events = self.store.get_events_by_session(session_id)
+
+        distribution: Dict[str, int] = defaultdict(int)
+        for event in events:
+            distribution[event.model] += event.tokens.total_tokens
+
+        return dict(distribution)
+
+    def rank_prompts_by_efficiency(
+        self, session_id: str, top_n: int = 10
+    ) -> List[tuple]:
+        """
+        Rank prompts by efficiency (quality per token).
+
+        Args:
+            session_id: Session to analyze
+            top_n: Number of top prompts to return
+
+        Returns:
+            List of (prompt_name, efficiency_score) tuples, sorted by efficiency
+        """
+        efficiency = self.get_prompt_efficiency(session_id)
+
+        if not efficiency:
+            return []
+
+        # Sort by efficiency score (descending)
+        sorted_prompts = sorted(
+            efficiency.items(), key=lambda x: x[1]["efficiency_score"], reverse=True
+        )
+
+        return [(prompt, data["efficiency_score"]) for prompt, data in sorted_prompts][
+            :top_n
+        ]
+
+    def get_attribution_summary(self, call_id: str) -> Dict[str, str]:
+        """
+        Get a human-readable summary of token attribution.
+
+        Args:
+            call_id: Call to summarize
+
+        Returns:
+            Dict with readable breakdown
+        """
+        attr = self.analyze_call(call_id)
+
+        summary: Dict[str, str] = {
+            "total_tokens": str(attr.total_tokens),
+        }
+
+        # Phase breakdown
+        if attr.by_phase:
+            phase_strs = [
+                f"{phase.value}: {tokens} ({100 * tokens / attr.total_tokens:.1f}%)"
+                for phase, tokens in sorted(
+                    attr.by_phase.items(),
+                    key=lambda x: x[1],
+                    reverse=True,
+                )
+            ]
+            summary["by_phase"] = " | ".join(phase_strs)
+
+        # Operation breakdown
+        if attr.by_operation:
+            op_strs = [
+                f"{op.value}: {tokens} ({100 * tokens / attr.total_tokens:.1f}%)"
+                for op, tokens in sorted(
+                    attr.by_operation.items(),
+                    key=lambda x: x[1],
+                    reverse=True,
+                )
+            ]
+            summary["by_operation"] = " | ".join(op_strs)
+
+        # Prompt breakdown
+        if attr.by_prompt_template:
+            prompt_strs = [
+                f"{prompt}: {tokens} ({100 * tokens / attr.total_tokens:.1f}%)"
+                for prompt, tokens in sorted(
+                    attr.by_prompt_template.items(),
+                    key=lambda x: x[1],
+                    reverse=True,
+                )
+            ]
+            summary["by_prompt"] = " | ".join(prompt_strs)
+
+        return summary