insyte 0.1.0__py3-none-any.whl

insyte/__init__.py

@@ -0,0 +1,12 @@
+"""Insyte — local-first AI analytics over your database, safely.
+
+Insyte connects to a database using read-only credentials and lets you analyse it
+through Claude Code, Codex, other MCP clients, or its own terminal UI. AI models never
+receive database credentials and can never bypass the SQL validation pipeline.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

insyte/analytics/__init__.py

@@ -0,0 +1,21 @@
+"""Analytics: metric resolution, SQL generation, comparison, segmentation, and charts."""
+
+from insyte.analytics.engine import AnalyticsEngine
+from insyte.analytics.models import (
+    AnalysisKind,
+    AnalysisResult,
+    ChartType,
+    Period,
+    PeriodComparison,
+    TimeGrain,
+)
+
+__all__ = [
+    "AnalysisKind",
+    "AnalysisResult",
+    "AnalyticsEngine",
+    "ChartType",
+    "Period",
+    "PeriodComparison",
+    "TimeGrain",
+]

insyte/analytics/charts.py

@@ -0,0 +1,67 @@
+"""Chart recommendation and value formatting (spec §20).
+
+Chart selection is a pure function of the analysis kind and result shape; a chart is only
+recommended when it genuinely helps (never for a single aggregate value).
+"""
+
+from __future__ import annotations
+
+from insyte.analytics.models import AnalysisKind, ChartSpec, ChartType
+from insyte.semantic.models import MetricFormat
+
+# Above this many segments, a horizontal bar reads better than a vertical one.
+_HORIZONTAL_BAR_THRESHOLD = 6
+
+
+def recommend_chart(
+    kind: AnalysisKind, columns: list[str], row_count: int, label: str
+) -> ChartSpec:
+    """Recommend a chart type for a result."""
+
+    if kind is AnalysisKind.timeseries and row_count >= 2:
+        return ChartSpec(ChartType.line, title=label, x_label=_col(columns, 0), y_label=label)
+    if kind is AnalysisKind.segment and row_count >= 1:
+        chart = ChartType.horizontal_bar if row_count > _HORIZONTAL_BAR_THRESHOLD else ChartType.bar
+        return ChartSpec(chart, title=label, x_label=_col(columns, 0), y_label=label)
+    return ChartSpec(ChartType.none, title=label)
+
+
+def _col(columns: list[str], index: int) -> str | None:
+    return columns[index] if index < len(columns) else None
+
+
+def format_value(value: object, fmt: MetricFormat) -> str:
+    """Format a scalar metric value for display."""
+
+    if value is None:
+        return "—"
+    number = _as_float(value)
+    if number is None:
+        return str(value)
+    if fmt is MetricFormat.percent:
+        return f"{number * 100:.1f}%"
+    if fmt is MetricFormat.currency:
+        return _compact_number(number, prefix="₹")
+    return _compact_number(number)
+
+
+def _compact_number(number: float, prefix: str = "") -> str:
+    """Compact number in the Indian system: thousand (K), lakh (L), crore (Cr)."""
+
+    magnitude = abs(number)
+    if magnitude >= 10_000_000:  # 1 crore = 1,00,00,000
+        return f"{prefix}{number / 10_000_000:.2f} Cr"
+    if magnitude >= 100_000:  # 1 lakh = 1,00,000
+        return f"{prefix}{number / 100_000:.2f} L"
+    if magnitude >= 1_000:
+        return f"{prefix}{number / 1_000:.1f} K"
+    if number == int(number):
+        return f"{prefix}{int(number)}"
+    return f"{prefix}{number:.2f}"
+
+
+def _as_float(value: object) -> float | None:
+    try:
+        return float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None

insyte/analytics/comparison.py

@@ -0,0 +1,64 @@
+"""Period comparison: compute deltas between a current and a baseline value."""
+
+from __future__ import annotations
+
+from insyte.analytics.charts import format_value
+from insyte.analytics.models import Period, PeriodComparison
+from insyte.semantic.models import Metric
+
+
+def compute_comparison(
+    metric_name: str,
+    metric: Metric,
+    current: Period,
+    current_value: float | None,
+    baseline: Period,
+    baseline_value: float | None,
+    sql_current: str,
+    sql_baseline: str,
+) -> PeriodComparison:
+    """Assemble a :class:`PeriodComparison`, including absolute and percentage change."""
+
+    absolute: float | None = None
+    percent: float | None = None
+    if current_value is not None and baseline_value is not None:
+        absolute = current_value - baseline_value
+        percent = (absolute / baseline_value * 100.0) if baseline_value else None
+
+    return PeriodComparison(
+        metric=metric_name,
+        label=metric.label,
+        current=current,
+        baseline=baseline,
+        current_value=current_value,
+        baseline_value=baseline_value,
+        absolute_change=absolute,
+        percent_change=percent,
+        sql_current=sql_current,
+        sql_baseline=sql_baseline,
+        summary=_summarise(metric, current, baseline, current_value, baseline_value, percent),
+    )
+
+
+def _summarise(
+    metric: Metric,
+    current: Period,
+    baseline: Period,
+    current_value: float | None,
+    baseline_value: float | None,
+    percent: float | None,
+) -> str:
+    if current_value is None or baseline_value is None:
+        return f"{metric.label}: not enough data to compare."
+    cur = format_value(current_value, metric.format)
+    base = format_value(baseline_value, metric.format)
+    if percent is None:
+        direction = "changed"
+        pct = ""
+    else:
+        direction = "increased" if percent >= 0 else "decreased"
+        pct = f" by {abs(percent):.1f}%"
+    return (
+        f"{metric.label} {direction}{pct}, from {base} ({baseline.label}) "
+        f"to {cur} ({current.label})."
+    )

insyte/analytics/engine.py

@@ -0,0 +1,195 @@
+"""The analytics engine: turn a metric request into an executed, formatted result.
+
+The engine resolves a metric (and optional dimension) from the semantic layer, generates safe
+SQL, runs it through the Milestone 4 executor (validation + audit + read-only execution), then
+formats the rows and recommends a chart.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from insyte.analytics.charts import format_value, recommend_chart
+from insyte.analytics.comparison import compute_comparison
+from insyte.analytics.models import (
+    AnalysisKind,
+    AnalysisResult,
+    Period,
+    PeriodComparison,
+    TimeGrain,
+)
+from insyte.analytics.segmentation import rank_contributors
+from insyte.exceptions import DimensionNotFoundError, MetricNotFoundError
+from insyte.metadata.models import RelationshipInfo
+from insyte.query.executor import QueryExecutor
+from insyte.query.generator import aggregate_sql, segment_sql, timeseries_sql
+from insyte.query.models import ExecutionResult
+from insyte.semantic.models import Dimension, Metric, SemanticLayer
+
+_SOURCE = "analytics"
+
+
+class AnalyticsEngine:
+    """Answer structured analytical questions against a project."""
+
+    def __init__(
+        self,
+        executor: QueryExecutor,
+        layer: SemanticLayer,
+        relationships: list[RelationshipInfo],
+    ) -> None:
+        self._executor = executor
+        self._layer = layer
+        self._relationships = relationships
+
+    # -- resolution --------------------------------------------------------------------------
+
+    def _metric(self, name: str) -> Metric:
+        metric = self._layer.metrics.get(name)
+        if metric is None:
+            raise MetricNotFoundError(name)
+        return metric
+
+    def _dimension(self, name: str) -> Dimension:
+        dimension = self._layer.dimensions.get(name)
+        if dimension is None:
+            raise DimensionNotFoundError(name)
+        return dimension
+
+    # -- analyses ----------------------------------------------------------------------------
+
+    def aggregate(self, metric_name: str, period: Period | None = None) -> AnalysisResult:
+        metric = self._metric(metric_name)
+        start, end = _bounds(period)
+        sql = aggregate_sql(metric, start, end)
+        execution = self._executor.execute(sql, source=_SOURCE)
+        value = _scalar(execution)
+        formatted = format_value(value, metric.format)
+        suffix = f" ({period.label})" if period else ""
+        return AnalysisResult(
+            kind=AnalysisKind.aggregate,
+            metric=metric_name,
+            label=metric.label,
+            columns=execution.columns,
+            rows=execution.rows,
+            formatted_rows=[[formatted]],
+            sql=execution.normalized_sql,
+            chart=recommend_chart(AnalysisKind.aggregate, execution.columns, 1, metric.label),
+            summary=f"{metric.label}: {formatted}{suffix}.",
+            row_count=execution.row_count,
+            duration_ms=execution.duration_ms,
+        )
+
+    def timeseries(
+        self, metric_name: str, grain: TimeGrain, period: Period | None = None
+    ) -> AnalysisResult:
+        metric = self._metric(metric_name)
+        start, end = _bounds(period)
+        sql = timeseries_sql(metric, grain.value, start, end)
+        execution = self._executor.execute(sql, source=_SOURCE)
+        formatted = _format_rows(execution.rows, value_index=1, metric=metric)
+        latest = format_value(execution.rows[-1][1], metric.format) if execution.rows else "—"
+        return AnalysisResult(
+            kind=AnalysisKind.timeseries,
+            metric=metric_name,
+            label=metric.label,
+            columns=execution.columns,
+            rows=execution.rows,
+            formatted_rows=formatted,
+            sql=execution.normalized_sql,
+            chart=recommend_chart(
+                AnalysisKind.timeseries, execution.columns, execution.row_count, metric.label
+            ),
+            summary=(
+                f"{metric.label} by {grain.value}: {execution.row_count} buckets; latest {latest}."
+            ),
+            row_count=execution.row_count,
+            duration_ms=execution.duration_ms,
+        )
+
+    def segment(
+        self,
+        metric_name: str,
+        dimension_name: str,
+        period: Period | None = None,
+        limit: int = 20,
+    ) -> AnalysisResult:
+        metric = self._metric(metric_name)
+        dimension = self._dimension(dimension_name)
+        start, end = _bounds(period)
+        sql = segment_sql(metric, dimension, self._relationships, limit=limit, start=start, end=end)
+        execution = self._executor.execute(sql, source=_SOURCE)
+        contributors = rank_contributors(execution.rows)
+        formatted = _format_rows(execution.rows, value_index=1, metric=metric)
+        summary = _segment_summary(metric, dimension_name, contributors)
+        return AnalysisResult(
+            kind=AnalysisKind.segment,
+            metric=metric_name,
+            label=metric.label,
+            columns=execution.columns,
+            rows=execution.rows,
+            formatted_rows=formatted,
+            sql=execution.normalized_sql,
+            chart=recommend_chart(
+                AnalysisKind.segment, execution.columns, execution.row_count, metric.label
+            ),
+            summary=summary,
+            row_count=execution.row_count,
+            duration_ms=execution.duration_ms,
+            contributors=contributors,
+        )
+
+    def compare(self, metric_name: str, current: Period, baseline: Period) -> PeriodComparison:
+        metric = self._metric(metric_name)
+        sql_current = aggregate_sql(metric, current.start, current.end)
+        sql_baseline = aggregate_sql(metric, baseline.start, baseline.end)
+        current_value = _scalar(self._executor.execute(sql_current, source=_SOURCE))
+        baseline_value = _scalar(self._executor.execute(sql_baseline, source=_SOURCE))
+        return compute_comparison(
+            metric_name,
+            metric,
+            current,
+            current_value,
+            baseline,
+            baseline_value,
+            sql_current,
+            sql_baseline,
+        )
+
+
+def _bounds(period: Period | None) -> tuple[datetime | None, datetime | None]:
+    return (None, None) if period is None else (period.start, period.end)
+
+
+def _scalar(result: ExecutionResult) -> float | None:
+    if not result.rows or not result.rows[0]:
+        return None
+    try:
+        return float(result.rows[0][0])  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+def _format_rows(
+    rows: list[tuple[object, ...]], *, value_index: int, metric: Metric
+) -> list[list[str]]:
+    formatted: list[list[str]] = []
+    for row in rows:
+        cells = []
+        for index, cell in enumerate(row):
+            if index == value_index:
+                cells.append(format_value(cell, metric.format))
+            elif cell is None:
+                cells.append("—")
+            else:
+                cells.append(str(cell))
+        formatted.append(cells)
+    return formatted
+
+
+def _segment_summary(metric: Metric, dimension: str, contributors: list) -> str:
+    if not contributors:
+        return f"{metric.label} by {dimension}: no data."
+    top = contributors[0]
+    value = format_value(top.value, metric.format)
+    return f"{metric.label} by {dimension}: '{top.segment}' leads with {value} ({top.share:.0%})."

insyte/analytics/forecast.py

@@ -0,0 +1,58 @@
+"""Deterministic year-end projection from real monthly actuals.
+
+This is *not* a model guess — it is arithmetic on the metric's own history: completed months of
+the current year plus a trailing run-rate for the months not yet elapsed. The result is always
+labelled an estimate. No AI is involved; the LLM only recognises that the user asked for a
+forecast and routes here, Insyte computes it from queried rows.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+_RUN_RATE_MONTHS = 3
+
+
+@dataclass
+class YearProjection:
+    """A projected full-year total for a metric, with the inputs that produced it."""
+
+    year: int
+    ytd_actual: float  # sum of completed months in the current year
+    projected_total: float  # ytd_actual + run_rate * remaining months
+    run_rate: float  # average of the last N completed months (any year)
+    complete_months: int  # completed months of the current year
+    remaining_months: int  # months not yet complete (incl. the current partial month)
+    basis_months: int  # how many months the run-rate averaged over
+
+
+def project_current_year(
+    points: list[tuple[datetime, float]], now: datetime
+) -> YearProjection | None:
+    """Project the current calendar year from monthly ``(period_start, value)`` actuals."""
+
+    monthly = sorted((d, v) for d, v in points if v is not None)
+    if not monthly:
+        return None
+
+    # "Completed" = months strictly before the current month (the current month is partial).
+    completed = [(d, v) for d, v in monthly if (d.year, d.month) < (now.year, now.month)]
+    ytd_actual = sum(v for d, v in completed if d.year == now.year)
+
+    basis = completed[-_RUN_RATE_MONTHS:]
+    run_rate = sum(v for _, v in basis) / len(basis) if basis else 0.0
+
+    complete_months = now.month - 1
+    remaining_months = 12 - complete_months  # includes the current, still-incomplete month
+    projected_total = ytd_actual + run_rate * remaining_months
+
+    return YearProjection(
+        year=now.year,
+        ytd_actual=ytd_actual,
+        projected_total=projected_total,
+        run_rate=run_rate,
+        complete_months=complete_months,
+        remaining_months=remaining_months,
+        basis_months=len(basis),
+    )

insyte/analytics/models.py

@@ -0,0 +1,90 @@
+"""Data structures for analytical requests and results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+
+
+class TimeGrain(StrEnum):
+    day = "day"
+    week = "week"
+    month = "month"
+    quarter = "quarter"
+    year = "year"
+
+
+class AnalysisKind(StrEnum):
+    aggregate = "aggregate"
+    timeseries = "timeseries"
+    segment = "segment"
+    comparison = "comparison"
+
+
+class ChartType(StrEnum):
+    line = "line"
+    bar = "bar"
+    horizontal_bar = "horizontal_bar"
+    pie = "pie"
+    scatter = "scatter"
+    none = "none"
+
+
+@dataclass
+class ChartSpec:
+    """A recommendation for how to chart a result (spec §20)."""
+
+    type: ChartType
+    title: str
+    x_label: str | None = None
+    y_label: str | None = None
+
+
+@dataclass
+class Period:
+    """A named, half-open time range [start, end)."""
+
+    label: str
+    start: datetime
+    end: datetime
+
+
+@dataclass
+class Contributor:
+    """A single segment's contribution to a metric."""
+
+    segment: str
+    value: float
+    share: float  # fraction of the total, 0..1
+
+
+@dataclass
+class AnalysisResult:
+    kind: AnalysisKind
+    metric: str
+    label: str
+    columns: list[str]
+    rows: list[tuple[object, ...]]
+    formatted_rows: list[list[str]]
+    sql: str
+    chart: ChartSpec
+    summary: str
+    row_count: int
+    duration_ms: float
+    contributors: list[Contributor] = field(default_factory=list)
+
+
+@dataclass
+class PeriodComparison:
+    metric: str
+    label: str
+    current: Period
+    baseline: Period
+    current_value: float | None
+    baseline_value: float | None
+    absolute_change: float | None
+    percent_change: float | None
+    sql_current: str
+    sql_baseline: str
+    summary: str

insyte/analytics/periods.py

@@ -0,0 +1,46 @@
+"""Compute current/previous period pairs for a time grain (for comparisons)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from insyte.analytics.models import Period, TimeGrain
+
+
+def periods_for_grain(grain: TimeGrain, *, now: datetime | None = None) -> tuple[Period, Period]:
+    """Return ``(current, previous)`` periods for the grain, relative to ``now`` (or UTC now)."""
+
+    now = now or datetime.now(UTC)
+    if grain is TimeGrain.day:
+        start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        return _pair(start, timedelta(days=1), "%Y-%m-%d")
+    if grain is TimeGrain.week:
+        midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
+        start = midnight - timedelta(days=midnight.weekday())
+        return _pair(start, timedelta(weeks=1), "%Y-%m-%d")
+    if grain is TimeGrain.year:
+        start = datetime(now.year, 1, 1, tzinfo=UTC)
+        return (
+            Period(str(now.year), start, datetime(now.year + 1, 1, 1, tzinfo=UTC)),
+            Period(str(now.year - 1), datetime(now.year - 1, 1, 1, tzinfo=UTC), start),
+        )
+    months = 3 if grain is TimeGrain.quarter else 1
+    start = datetime(now.year, now.month, 1, tzinfo=UTC)
+    end = _add_months(start, months)
+    previous = _add_months(start, -months)
+    return (
+        Period(start.strftime("%b %Y"), start, end),
+        Period(previous.strftime("%b %Y"), previous, start),
+    )
+
+
+def _pair(start: datetime, span: timedelta, fmt: str) -> tuple[Period, Period]:
+    return (
+        Period(start.strftime(fmt), start, start + span),
+        Period((start - span).strftime(fmt), start - span, start),
+    )
+
+
+def _add_months(value: datetime, months: int) -> datetime:
+    index = value.month - 1 + months
+    return datetime(value.year + index // 12, index % 12 + 1, 1, tzinfo=UTC)

insyte/analytics/segmentation.py

@@ -0,0 +1,40 @@
+"""Segmentation helpers: rank a metric's breakdown by contribution."""
+
+from __future__ import annotations
+
+from insyte.analytics.models import Contributor
+
+
+def rank_contributors(rows: list[tuple[object, ...]]) -> list[Contributor]:
+    """Turn ``(segment, value)`` rows into contributors ranked by absolute value.
+
+    ``share`` is each segment's fraction of the total of positive values.
+    """
+
+    pairs: list[tuple[str, float]] = []
+    for row in rows:
+        if len(row) < 2:
+            continue
+        value = _as_float(row[1])
+        if value is None:
+            continue
+        pairs.append((_as_str(row[0]), value))
+
+    total = sum(v for _, v in pairs if v > 0)
+    contributors = [
+        Contributor(segment=segment, value=value, share=(value / total if total else 0.0))
+        for segment, value in pairs
+    ]
+    contributors.sort(key=lambda c: abs(c.value), reverse=True)
+    return contributors
+
+
+def _as_float(value: object) -> float | None:
+    try:
+        return float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_str(value: object) -> str:
+    return "—" if value is None else str(value)

insyte/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface package."""

insyte/cli/_project.py

@@ -0,0 +1,43 @@
+"""Shared helpers for commands that operate on a project."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from insyte.config import loader, paths
+from insyte.config.models import InsyteConfig
+from insyte.exceptions import InsyteError
+
+console = Console()
+
+
+def resolve_config(project: str | None) -> InsyteConfig:
+    """Load the requested project's config, or the active/only one.
+
+    Prints a friendly message and raises ``typer.Exit(1)`` when no project can be resolved.
+    """
+
+    projects = loader.list_projects()
+    if not projects:
+        console.print(
+            "[yellow]No Insyte projects found.[/yellow] Run [bold]insyte init[/bold] first."
+        )
+        raise typer.Exit(1)
+
+    name = project or paths.get_active_project() or projects[0]
+    if name not in projects:
+        # On case-insensitive filesystems (macOS default) the on-disk folder and the stored
+        # active-project name can differ only by case — match case-insensitively before failing.
+        matches = [p for p in projects if p.lower() == name.lower()]
+        if matches:
+            name = matches[0]
+        else:
+            console.print(f"[red]Error:[/red] project {name!r} does not exist.")
+            raise typer.Exit(1)
+
+    try:
+        return loader.load_config(name)
+    except InsyteError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc

insyte/cli/_stubs.py

@@ -0,0 +1,42 @@
+"""Registration of not-yet-implemented commands.
+
+Every command from the product spec is registered so ``insyte --help`` shows the full
+roadmap. Unimplemented commands print a clean notice pointing at the milestone that will
+deliver them, and exit successfully.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# command name -> (milestone, help text)
+_STUBS: dict[str, tuple[int, str]] = {
+    "serve": (7, "Run the Insyte HTTP API"),
+}
+
+
+def _coming_soon(command: str, milestone: int) -> None:
+    console.print(
+        f"[yellow]🚧 [bold]insyte {command}[/bold] is coming in Milestone {milestone}.[/yellow]"
+    )
+    console.print("[dim]This command is registered but not yet implemented.[/dim]")
+
+
+def _make_stub(command: str, milestone: int) -> Callable[[], None]:
+    def _stub() -> None:
+        _coming_soon(command, milestone)
+
+    _stub.__name__ = f"stub_{command.replace(' ', '_')}"
+    return _stub
+
+
+def register_stub_commands(app: typer.Typer) -> None:
+    """Register all stubbed commands (and the ``mcp`` sub-app) on the given Typer app."""
+
+    for name, (milestone, help_text) in _STUBS.items():
+        app.command(name, help=f"{help_text} (Milestone {milestone})")(_make_stub(name, milestone))