ccusage-viz 0.1.0__py3-none-any.whl

ccusage_viz/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

ccusage_viz/__main__.py

@@ -0,0 +1,3 @@
+from ccusage_viz.cli import main
+
+raise SystemExit(main())

ccusage_viz/acquisition.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from datetime import date, timedelta
+
+from ccusage_viz.core.time import today_for_timezone
+from ccusage_viz.coverage import DateCoverage, DateInterval
+from ccusage_viz.options import MonitorConfig, StandaloneLaunch
+from ccusage_viz.query.models import (
+    DataResolution,
+    DataScope,
+    ExecutionContext,
+    QueryIntent,
+    QueryTrigger,
+)
+from ccusage_viz.query.provider import ProviderDefinition
+
+
+def historical_provider_id(options: StandaloneLaunch) -> str:
+    """Resolve the configured historical data mode to its Provider ID."""
+    return "demo" if options.host.demo_size else options.host.provider
+
+
+def monitor_query_intent(
+    options: StandaloneLaunch,
+    definition: ProviderDefinition,
+    *,
+    owner_id: str,
+    generation: int,
+    trigger: QueryTrigger,
+    sample_ordinal: int = 0,
+    today: date | None = None,
+) -> QueryIntent:
+    """Compose one complete cumulative Monitor sample request."""
+    chart = options.chart
+    if not isinstance(chart, MonitorConfig):
+        raise TypeError("monitor query planning requires a monitor configuration")
+    provider = definition.provider
+    current_day = today_for_timezone(options.host.timezone, today)
+    scope_interval = DateInterval(current_day - timedelta(days=1), current_day)
+    project_required = bool(chart.filters.projects) or chart.by == "project"
+    available_options = {
+        "chart_kind": chart.kind,
+        "demo_size": options.host.demo_size,
+        "sample_ordinal": sample_ordinal,
+    }
+    execution_options = tuple(
+        (key, available_options[key])
+        for key in sorted(provider.capabilities.execution_options)
+        if available_options.get(key) is not None
+    )
+    execution_context = (
+        None
+        if provider.capabilities.in_process
+        else ExecutionContext(
+            options.process.ccusage_bin,
+            options.process.query_timeout,
+            options.process.output_limit,
+            options.process.environment,
+        )
+    )
+    return QueryIntent(
+        owner_id=owner_id,
+        generation=generation,
+        trigger=trigger,
+        provider=provider.provider,
+        scope=DataScope((scope_interval,), options.host.timezone),
+        missing_intervals=(scope_interval,),
+        resolution=DataResolution.DATE,
+        dimensions=("project",) if project_required else ("agent",),
+        execution_options=execution_options,
+        execution_context=execution_context,
+    )
+
+
+def historical_query_intent(
+    options: StandaloneLaunch,
+    definition: ProviderDefinition,
+    *,
+    owner_id: str,
+    generation: int,
+    trigger: QueryTrigger,
+    coverage: DateCoverage | None = None,
+    required_coverage: DateCoverage | None = None,
+) -> QueryIntent:
+    """Compose one historical Host request into provider-neutral query intent."""
+    chart = options.chart
+    if isinstance(chart, MonitorConfig):
+        raise TypeError("historical query planning does not support monitor configurations")
+    provider = definition.provider
+    scope_interval = DateInterval(chart.date_range.since, chart.date_range.until)
+    required_coverage = (
+        required_coverage if required_coverage is not None else DateCoverage((scope_interval,))
+    )
+    coverage = coverage or DateCoverage()
+    project_required = bool(chart.filters.projects) or getattr(chart, "by", None) == "project"
+    available_options = {
+        "chart_kind": chart.kind,
+        "demo_size": options.host.demo_size,
+    }
+    execution_options = tuple(
+        (key, available_options[key])
+        for key in sorted(provider.capabilities.execution_options)
+        if available_options.get(key) is not None
+    )
+    execution_context = (
+        None
+        if provider.capabilities.in_process
+        else ExecutionContext(
+            options.process.ccusage_bin,
+            options.process.query_timeout,
+            options.process.output_limit,
+            options.process.environment,
+        )
+    )
+    return QueryIntent(
+        owner_id=owner_id,
+        generation=generation,
+        trigger=trigger,
+        provider=provider.provider,
+        scope=DataScope(required_coverage.intervals, chart.date_range.timezone),
+        missing_intervals=coverage.missing_coverage(required_coverage).intervals,
+        resolution=DataResolution.DATE,
+        dimensions=("project",) if project_required else ("agent",),
+        execution_options=execution_options,
+        execution_context=execution_context,
+    )

ccusage_viz/application.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import os
+import sys
+
+from ccusage_viz.bootstrap import build_provider_registry
+from ccusage_viz.dependency import ensure_provider_dependencies
+from ccusage_viz.errors import UsageError
+from ccusage_viz.i18n import Translator
+from ccusage_viz.options import DashboardLaunch, LaunchConfig
+
+
+def _preflight_runtime(options: LaunchConfig) -> None:
+    if not interactive_streams():
+        raise UsageError("error.tty")
+    if options.was_explicit("interval") and isinstance(options, DashboardLaunch):
+        raise UsageError("error.arguments", detail="dashboard does not support --interval")
+    if os.environ.get("TERM") == "dumb" and not options.host.ascii:
+        raise UsageError("error.arguments", detail="TERM=dumb requires explicit --ascii")
+
+
+def run(options: LaunchConfig, translator: Translator) -> int:
+    _preflight_runtime(options)
+    ensure_provider_dependencies(options, build_provider_registry(), translator)
+    if isinstance(options, DashboardLaunch):
+        from ccusage_viz.tui import run_tui
+
+        return run_tui(options, translator)
+    if options.chart.kind == "monitor":
+        from ccusage_viz.monitor import run_monitor
+
+        return run_monitor(options, translator)
+
+    from ccusage_viz.watch import run_watch
+
+    return run_watch(options, translator)
+
+
+def interactive_streams() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()

ccusage_viz/bootstrap.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from ccusage_viz.charts.builtins import (
+    CALENDAR_DEFINITION,
+    RANKING_DEFINITION,
+    STACK_DEFINITION,
+    TIMELINE_DEFINITION,
+)
+from ccusage_viz.charts.registry import ChartRegistry
+from ccusage_viz.providers.ccusage import CCUSAGE_DEFINITION
+from ccusage_viz.providers.demo import DEMO_DEFINITION
+from ccusage_viz.query.coordinator import QueryCoordinator
+from ccusage_viz.query.registry import ProviderRegistry
+from ccusage_viz.query.runtime import QueryRuntime
+
+
+def build_chart_registry() -> ChartRegistry:
+    registry = ChartRegistry()
+    registry.register(TIMELINE_DEFINITION)
+    registry.register(CALENDAR_DEFINITION)
+    registry.register(STACK_DEFINITION)
+    registry.register(RANKING_DEFINITION)
+    registry.freeze()
+    return registry
+
+
+def build_provider_registry() -> ProviderRegistry:
+    registry = ProviderRegistry()
+    registry.register(CCUSAGE_DEFINITION)
+    registry.register(DEMO_DEFINITION)
+    registry.freeze()
+    return registry
+
+
+def build_query_runtime(*, max_parallel: int = 2) -> QueryRuntime:
+    return QueryRuntime(build_provider_registry(), QueryCoordinator(max_parallel=max_parallel))

ccusage_viz/chart_models.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from collections.abc import Hashable
+from dataclasses import KW_ONLY, dataclass, field
+from datetime import date, datetime
+from enum import StrEnum
+from typing import Literal
+
+from ccusage_viz.core.time import DateRange
+from ccusage_viz.domain import Notice, TokenUsage
+
+GroupKey = Hashable
+ChartValue = int | float
+MetricUnit = Literal["tokens", "tpm"]
+
+
+@dataclass(frozen=True, slots=True)
+class MetricDescriptor:
+    unit: MetricUnit = "tokens"
+
+
+@dataclass(frozen=True, slots=True)
+class ObservedScope:
+    window_seconds: int
+    mode: Literal["total", "agent", "model", "project"]
+    state: Literal["ready", "baseline", "sampling"] = "ready"
+    agents: tuple[str, ...] = ()
+
+
+class ChangeDirection(StrEnum):
+    INCREASE = "increase"
+    DECREASE = "decrease"
+    UNCHANGED = "unchanged"
+    FROM_ZERO = "from_zero"
+
+
+class ComparisonState(StrEnum):
+    READY = "ready"
+    PENDING = "pending"
+    UNAVAILABLE = "unavailable"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True, slots=True)
+class PercentChange:
+    direction: ChangeDirection
+    percent: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PeriodSummary:
+    period: str
+    day: date
+    total: int
+    sequential: PercentChange | None
+    year_over_year: PercentChange | None = None
+    previous_week_day: date | None = None
+    all_agents: bool = False
+    _: KW_ONLY
+    filter_count: int = 0
+    sequential_state: ComparisonState = ComparisonState.READY
+    year_over_year_state: ComparisonState = ComparisonState.READY
+
+    @property
+    def day_over_day(self) -> PercentChange | None:
+        return self.sequential
+
+    @property
+    def week_over_week(self) -> PercentChange | None:
+        return self.year_over_year
+
+
+@dataclass(frozen=True, slots=True)
+class Series:
+    key: GroupKey
+    label: str
+    values: tuple[TokenUsage, ...]
+    is_other: bool = False
+
+    @property
+    def total(self) -> TokenUsage:
+        return sum(self.values, start=TokenUsage.zero())
+
+
+@dataclass(frozen=True, slots=True)
+class ScalarSeries:
+    key: GroupKey
+    label: str
+    values: tuple[ChartValue | None, ...]
+    is_other: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class TimelineModel:
+    days: tuple[date, ...]
+    series: tuple[Series, ...]
+    notices: tuple[Notice, ...] = field(default_factory=tuple)
+    summary: PeriodSummary | None = None
+    aggregation: str = "day"
+    observed_at: tuple[datetime, ...] = field(default_factory=tuple)
+    observed_series: tuple[ScalarSeries, ...] = field(default_factory=tuple)
+    metric: MetricDescriptor = field(default_factory=MetricDescriptor)
+    observed_scope: ObservedScope | None = None
+    y_axis_max: float | None = None
+    observed_current: tuple[ScalarRankingEntry, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        if (
+            not self.observed_at
+            and not self.observed_series
+            and not self.observed_current
+            and self.observed_scope is None
+        ):
+            return
+        if self.days or self.series or self.observed_scope is None:
+            raise ValueError("observed timelines require only observed axis and series data")
+        if any(len(series.values) != len(self.observed_at) for series in self.observed_series):
+            raise ValueError("observed timeline values must align with observed timestamps")
+
+    @property
+    def is_observed(self) -> bool:
+        return self.observed_scope is not None
+
+    @property
+    def total(self) -> TokenUsage:
+        return sum((item.total for item in self.series), start=TokenUsage.zero())
+
+
+@dataclass(frozen=True, slots=True)
+class CalendarDay:
+    day: date
+    usage: TokenUsage
+
+
+@dataclass(frozen=True, slots=True)
+class CalendarModel:
+    days: tuple[CalendarDay, ...]
+    notices: tuple[Notice, ...] = field(default_factory=tuple)
+    summary: PeriodSummary | None = None
+
+    @property
+    def total(self) -> TokenUsage:
+        return sum((item.usage for item in self.days), start=TokenUsage.zero())
+
+    @property
+    def active_days(self) -> int:
+        return sum(item.usage.total > 0 for item in self.days)
+
+    @property
+    def peak(self) -> CalendarDay | None:
+        active = [item for item in self.days if item.usage.total > 0]
+        return (
+            max(active, key=lambda item: (item.usage.total, -item.day.toordinal()))
+            if active
+            else None
+        )
+
+    @property
+    def average(self) -> float:
+        return self.total.total / len(self.days) if self.days else 0.0
+
+    @property
+    def longest_streak(self) -> int:
+        longest = current = 0
+        for item in self.days:
+            current = current + 1 if item.usage.total > 0 else 0
+            longest = max(longest, current)
+        return longest
+
+    @property
+    def current_streak(self) -> int:
+        current = 0
+        for item in reversed(self.days):
+            if item.usage.total <= 0:
+                break
+            current += 1
+        return current
+
+
+@dataclass(frozen=True, slots=True)
+class StackModel:
+    days: tuple[date, ...]
+    components: tuple[Series, ...]
+    notices: tuple[Notice, ...] = field(default_factory=tuple)
+    summary: PeriodSummary | None = None
+    aggregation: str = "day"
+
+    @property
+    def total(self) -> TokenUsage:
+        # Every component series stores a usage with only its represented amount in total.
+        total = sum((item.total.total for item in self.components), start=0)
+        return TokenUsage(total, 0, 0, 0, 0, total)
+
+
+@dataclass(frozen=True, slots=True)
+class RankingEntry:
+    key: GroupKey
+    label: str
+    usage: TokenUsage
+    is_other: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ScalarRankingEntry:
+    key: GroupKey
+    label: str
+    value: ChartValue
+    is_other: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class RankingModel:
+    entries: tuple[RankingEntry, ...]
+    date_range: DateRange | None
+    notices: tuple[Notice, ...] = field(default_factory=tuple)
+    denominator: TokenUsage | None = None
+    summary: PeriodSummary | None = None
+    top: int | None = None
+    top_share: float | None = None
+    observed_entries: tuple[ScalarRankingEntry, ...] = field(default_factory=tuple)
+    metric: MetricDescriptor = field(default_factory=MetricDescriptor)
+    observed_scope: ObservedScope | None = None
+    summary_notices: tuple[Notice, ...] = field(default_factory=tuple)
+
+    def __post_init__(self) -> None:
+        if not self.observed_entries and self.observed_scope is None:
+            if self.date_range is None:
+                raise ValueError("historical rankings require a date range")
+            if self.top_share is not None:
+                if self.top is None or not 0 <= self.top_share <= 1:
+                    raise ValueError("ranking coverage requires Top and a valid share")
+                if self.denominator is None or self.denominator.total <= 0:
+                    raise ValueError("ranking coverage requires a positive denominator")
+            elif self.top is not None:
+                raise ValueError("ranking Top metadata requires coverage")
+            return
+        if self.entries or self.observed_scope is None or self.date_range is not None:
+            raise ValueError("observed rankings require only observed entries and scope")
+        if (
+            self.denominator is not None
+            or self.summary is not None
+            or self.top is not None
+            or self.top_share is not None
+        ):
+            raise ValueError("observed rankings do not support historical percentages or summaries")
+
+    @property
+    def is_observed(self) -> bool:
+        return self.observed_scope is not None
+
+    @property
+    def total(self) -> TokenUsage:
+        return sum((item.usage for item in self.entries), start=TokenUsage.zero())
+
+    @property
+    def percentage_total(self) -> TokenUsage:
+        """Return the full filtered total used for historical entry percentages."""
+        return self.denominator if self.denominator is not None else self.total

ccusage_viz/charts/__init__.py

@@ -0,0 +1,4 @@
+from ccusage_viz.charts.definition import ChartDefinition
+from ccusage_viz.charts.registry import ChartRegistry
+
+__all__ = ("ChartDefinition", "ChartRegistry")

ccusage_viz/charts/builtins.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import cast
+
+from ccusage_viz.chart_models import CalendarModel, RankingModel, StackModel, TimelineModel
+from ccusage_viz.charts.definition import ChartDefinition, HistoricalRenderer
+from ccusage_viz.options import CalendarConfig, RankingConfig, StackConfig, TimelineConfig
+from ccusage_viz.processing import process_historical
+from ccusage_viz.render import render_calendar, render_ranking, render_stack, render_timeline
+
+TIMELINE_DEFINITION = ChartDefinition(
+    "timeline",
+    TimelineConfig,
+    TimelineModel,
+    process_historical,
+    cast(HistoricalRenderer, render_timeline),
+)
+CALENDAR_DEFINITION = ChartDefinition(
+    "calendar",
+    CalendarConfig,
+    CalendarModel,
+    process_historical,
+    cast(HistoricalRenderer, render_calendar),
+)
+STACK_DEFINITION = ChartDefinition(
+    "stack",
+    StackConfig,
+    StackModel,
+    process_historical,
+    cast(HistoricalRenderer, render_stack),
+)
+RANKING_DEFINITION = ChartDefinition(
+    "ranking",
+    RankingConfig,
+    RankingModel,
+    process_historical,
+    cast(HistoricalRenderer, render_ranking),
+)

ccusage_viz/charts/definition.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from ccusage_viz.chart_models import CalendarModel, RankingModel, StackModel, TimelineModel
+from ccusage_viz.options import CalendarConfig, RankingConfig, StackConfig, TimelineConfig
+from ccusage_viz.processing.historical import HistoricalModel, process_historical
+from ccusage_viz.render.base import RenderContext
+
+HistoricalConfigType = (
+    type[TimelineConfig] | type[CalendarConfig] | type[StackConfig] | type[RankingConfig]
+)
+HistoricalModelType = (
+    type[TimelineModel] | type[CalendarModel] | type[StackModel] | type[RankingModel]
+)
+HistoricalRenderer = Callable[[HistoricalModel, RenderContext], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ChartDefinition:
+    """Stateless collaborators registered for one built-in chart kind."""
+
+    chart_id: str
+    config_type: HistoricalConfigType
+    model_type: HistoricalModelType
+    processor: Callable[..., HistoricalModel]
+    renderer: HistoricalRenderer
+
+
+__all__ = ("ChartDefinition", "HistoricalRenderer", "process_historical")

ccusage_viz/charts/registry.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from ccusage_viz.charts.definition import ChartDefinition
+
+
+class ChartRegistry:
+    """Private deterministic registry populated only by application bootstrap."""
+
+    __slots__ = ("_definitions", "_frozen")
+
+    def __init__(self) -> None:
+        self._definitions: dict[str, ChartDefinition] = {}
+        self._frozen = False
+
+    @property
+    def frozen(self) -> bool:
+        return self._frozen
+
+    def register(self, definition: ChartDefinition) -> None:
+        if self._frozen:
+            raise RuntimeError("chart registry is frozen")
+        if definition.chart_id in self._definitions:
+            raise ValueError(f"duplicate chart ID: {definition.chart_id}")
+        self._definitions[definition.chart_id] = definition
+
+    def freeze(self) -> None:
+        self._frozen = True
+
+    def get(self, chart_id: str) -> ChartDefinition:
+        try:
+            return self._definitions[chart_id]
+        except KeyError as exc:
+            raise KeyError(f"unknown chart ID: {chart_id}") from exc
+
+    def __iter__(self) -> Iterator[ChartDefinition]:
+        return iter(self._definitions.values())
+
+    def __len__(self) -> int:
+        return len(self._definitions)