codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/services/analytics_aggregate.py

@@ -0,0 +1,837 @@
+"""Analytics Aggregation Script — JSONL → CSV 리포트 생성.
+
+analytics JSONL 파일들을 읽어 C레벨 보고용 CSV 리포트를 생성합니다.
+- A1_active_users.csv: Jupyter vs Agent DAU/MAU
+- A2_agent_frequency.csv: 사용자별 사용 빈도
+- A3_feature_preference.csv: 기능별 사용량
+- A4_errors.csv: 실패 유형 집계
+- A5_cell_attribution.csv: 일별/유저별 agent 셀 기여율
+- A6_codebuff_users.csv: Jupyter-only vs Code Buff 사용자 (MAU/DAU)
+- A7_codebuff_feature_mix.csv: Code Buff 기능별 비중 (softmax + 건수)
+- A8_codebuff_utilization.csv: Code Buff 활용률 (세션 단위 binary)
+
+Usage:
+    python scripts/analytics_aggregate.py \
+        --input extensions/logs/ \
+        --output /tmp/reports/ \
+        --date-from 2026-03-01 \
+        --date-to 2026-03-31
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+
+CODEBUFF_FEATURES = frozenset(
+    {
+        "code_insert_from_agent",
+        "code_copy_from_agent",
+        "code_paste_from_agent",
+    }
+)
+
+
+def _read_jsonl_files(input_dir: Path, prefix: str) -> list[dict]:
+    """Read all JSONL files matching prefix and return list of parsed dicts."""
+    records: list[dict] = []
+    for p in sorted(input_dir.glob(f"{prefix}*.jsonl")):
+        with open(p) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    records.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return records
+
+
+def _filter_by_date(
+    df: pd.DataFrame,
+    date_col: str,
+    date_from: Optional[str],
+    date_to: Optional[str],
+) -> pd.DataFrame:
+    """Filter DataFrame by date range (inclusive)."""
+    if df.empty:
+        return df
+    if date_from:
+        df = df[df[date_col] >= date_from]
+    if date_to:
+        df = df[df[date_col] <= date_to]
+    return df
+
+
+def aggregate_active_users(
+    impressions: list[dict],
+    clicks: list[dict],
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+) -> pd.DataFrame:
+    """A1: Jupyter vs Agent DAU/MAU."""
+    # Build per-user-per-date sets
+    imp_df = pd.DataFrame(impressions)
+    click_df = pd.DataFrame(clicks)
+
+    if imp_df.empty and click_df.empty:
+        return pd.DataFrame(
+            columns=[
+                "date",
+                "jupyter_dau",
+                "agent_dau",
+                "non_agent_dau",
+                "agent_adoption_rate",
+                "jupyter_mau",
+                "agent_mau",
+                "agent_mau_rate",
+            ]
+        )
+
+    # Extract date from datetime field
+    if not imp_df.empty:
+        imp_df["date"] = imp_df["datetime"].str[:10]
+        imp_df = _filter_by_date(imp_df, "date", date_from, date_to)
+
+    if not click_df.empty:
+        click_df["date"] = click_df["datetime"].str[:10]
+        click_df = _filter_by_date(click_df, "date", date_from, date_to)
+
+    # Jupyter DAU: users with session_start impression
+    if not imp_df.empty:
+        session_starts = imp_df[imp_df["feature"] == "session_start"]
+        if not session_starts.empty:
+            jupyter_daily_df = (
+                session_starts.groupby("date")["user_id"].apply(set).reset_index()
+            )
+            jupyter_daily_df.columns = ["date", "jupyter_users"]
+        else:
+            jupyter_daily_df = pd.DataFrame(columns=["date", "jupyter_users"])
+    else:
+        jupyter_daily_df = pd.DataFrame(columns=["date", "jupyter_users"])
+
+    # Agent DAU: users with at least 1 click event
+    if not click_df.empty:
+        agent_daily_df = click_df.groupby("date")["user_id"].apply(set).reset_index()
+        agent_daily_df.columns = ["date", "agent_users"]
+    else:
+        agent_daily_df = pd.DataFrame(columns=["date", "agent_users"])
+
+    # Merge daily
+    all_dates = set()
+    if not jupyter_daily_df.empty:
+        all_dates.update(jupyter_daily_df["date"].tolist())
+    if not agent_daily_df.empty:
+        all_dates.update(agent_daily_df["date"].tolist())
+
+    rows = []
+    jupyter_daily_map = {}
+    agent_daily_map = {}
+    if not jupyter_daily_df.empty:
+        jupyter_daily_map = dict(
+            zip(jupyter_daily_df["date"], jupyter_daily_df["jupyter_users"])
+        )
+    if not agent_daily_df.empty:
+        agent_daily_map = dict(
+            zip(agent_daily_df["date"], agent_daily_df["agent_users"])
+        )
+
+    for date in sorted(all_dates):
+        j_users = jupyter_daily_map.get(date, set())
+        a_users = agent_daily_map.get(date, set())
+        jupyter_dau = len(j_users)
+        agent_dau = len(a_users)
+        non_agent_dau = len(j_users - a_users)
+        adoption = round(agent_dau / jupyter_dau, 4) if jupyter_dau > 0 else 0.0
+        rows.append(
+            {
+                "date": date,
+                "jupyter_dau": jupyter_dau,
+                "agent_dau": agent_dau,
+                "non_agent_dau": non_agent_dau,
+                "agent_adoption_rate": adoption,
+            }
+        )
+
+    daily_df = pd.DataFrame(rows)
+
+    # MAU: same logic at month level
+    month_jupyter: dict[str, set] = {}
+    month_agent: dict[str, set] = {}
+
+    if not imp_df.empty:
+        session_starts = imp_df[imp_df["feature"] == "session_start"]
+        for _, row in session_starts.iterrows():
+            m = row["date"][:7]
+            month_jupyter.setdefault(m, set()).add(row["user_id"])
+
+    if not click_df.empty:
+        for _, row in click_df.iterrows():
+            m = row["date"][:7]
+            month_agent.setdefault(m, set()).add(row["user_id"])
+
+    all_months = sorted(set(list(month_jupyter.keys()) + list(month_agent.keys())))
+    mau_map: dict[str, dict] = {}
+    for m in all_months:
+        j_mau = len(month_jupyter.get(m, set()))
+        a_mau = len(month_agent.get(m, set()))
+        mau_rate = round(a_mau / j_mau, 4) if j_mau > 0 else 0.0
+        mau_map[m] = {
+            "jupyter_mau": j_mau,
+            "agent_mau": a_mau,
+            "agent_mau_rate": mau_rate,
+        }
+
+    # Attach MAU to daily rows by month
+    if not daily_df.empty:
+        daily_df["month"] = daily_df["date"].str[:7]
+        daily_df["jupyter_mau"] = daily_df["month"].map(
+            lambda m: mau_map.get(m, {}).get("jupyter_mau", 0)
+        )
+        daily_df["agent_mau"] = daily_df["month"].map(
+            lambda m: mau_map.get(m, {}).get("agent_mau", 0)
+        )
+        daily_df["agent_mau_rate"] = daily_df["month"].map(
+            lambda m: mau_map.get(m, {}).get("agent_mau_rate", 0.0)
+        )
+        daily_df = daily_df.drop(columns=["month"])
+
+    return daily_df
+
+
+def aggregate_agent_frequency(
+    clicks: list[dict],
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+) -> pd.DataFrame:
+    """A2: 사용자별 사용 빈도."""
+    if not clicks:
+        return pd.DataFrame(
+            columns=["team", "project", "user_id", "date", "click_count"]
+        )
+
+    df = pd.DataFrame(clicks)
+    df["date"] = df["datetime"].str[:10]
+    df = _filter_by_date(df, "date", date_from, date_to)
+
+    if df.empty:
+        return pd.DataFrame(
+            columns=["team", "project", "user_id", "date", "click_count"]
+        )
+
+    # Fill missing identity fields
+    for col in ("team", "project", "user_id"):
+        if col not in df.columns:
+            df[col] = ""
+        df[col] = df[col].fillna("")
+
+    result = (
+        df.groupby(["team", "project", "user_id", "date"])
+        .size()
+        .reset_index(name="click_count")
+        .sort_values(["date", "team", "project", "user_id"])
+    )
+    return result
+
+
+def aggregate_feature_preference(
+    clicks: list[dict],
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+) -> pd.DataFrame:
+    """A3: 기능별 사용량."""
+    if not clicks:
+        return pd.DataFrame(columns=["feature", "count", "percentage"])
+
+    df = pd.DataFrame(clicks)
+    df["date"] = df["datetime"].str[:10]
+    df = _filter_by_date(df, "date", date_from, date_to)
+
+    if df.empty:
+        return pd.DataFrame(columns=["feature", "count", "percentage"])
+
+    result = (
+        df.groupby("feature")
+        .size()
+        .reset_index(name="count")
+        .sort_values("count", ascending=False)
+    )
+    total = result["count"].sum()
+    result["percentage"] = (result["count"] / total * 100).round(2)
+    return result
+
+
+def aggregate_errors(
+    errors: list[dict],
+    structured_logs: list[dict],
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+) -> pd.DataFrame:
+    """A4: 실패 유형 집계 (프론트엔드 + 백엔드)."""
+    rows = []
+
+    # Frontend errors from analytics_error JSONL
+    if errors:
+        err_df = pd.DataFrame(errors)
+        err_df["date"] = err_df["datetime"].str[:10]
+        err_df = _filter_by_date(err_df, "date", date_from, date_to)
+        if not err_df.empty:
+            fe_counts = err_df.groupby("feature").size().reset_index(name="count")
+            for _, r in fe_counts.iterrows():
+                rows.append(
+                    {
+                        "source": "frontend",
+                        "feature_or_error_type": r["feature"],
+                        "count": r["count"],
+                    }
+                )
+
+    # Backend errors from agent_structured.jsonl (status starts with "error:")
+    if structured_logs:
+        for rec in structured_logs:
+            status = rec.get("status", "")
+            if isinstance(status, str) and status.startswith("error:"):
+                ts = rec.get("ts", "")
+                date = ts[:10] if ts else ""
+                if date_from and date < date_from:
+                    continue
+                if date_to and date > date_to:
+                    continue
+                error_type = status.replace("error:", "", 1)
+                rows.append(
+                    {
+                        "source": "backend",
+                        "feature_or_error_type": error_type,
+                        "count": 1,
+                    }
+                )
+
+    if not rows:
+        return pd.DataFrame(columns=["source", "feature_or_error_type", "count"])
+
+    result = (
+        pd.DataFrame(rows)
+        .groupby(["source", "feature_or_error_type"])["count"]
+        .sum()
+        .reset_index()
+        .sort_values(["source", "count"], ascending=[True, False])
+    )
+    return result
+
+
+def aggregate_cell_attribution(
+    impressions: list[dict],
+    clicks: list[dict],
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+) -> pd.DataFrame:
+    """A5: 노트북 저장 시점의 agent 셀 기여 비율 + 코드 복사 기여."""
+    cols = [
+        "team",
+        "project",
+        "user_id",
+        "date",
+        "total_code_cells",
+        "agent_created_code_cells",
+        "agent_modified_code_cells",
+        "agent_pasted_code_cells",
+        "agent_code_ratio_pct",
+        "total_markdown_cells",
+        "agent_markdown_cells",
+        "code_copy_count",
+        "code_copy_lines",
+    ]
+    if not impressions and not clicks:
+        return pd.DataFrame(columns=cols)
+
+    # --- Cell attribution from impressions ---
+    attr_rows = []
+    if impressions:
+        imp_df = pd.DataFrame(impressions)
+        attr = imp_df[imp_df["feature"] == "cell_attribution"].copy()
+        if not attr.empty:
+            attr["date"] = attr["datetime"].str[:10]
+            attr = _filter_by_date(attr, "date", date_from, date_to)
+            if not attr.empty:
+                for col in ("team", "project", "user_id"):
+                    if col not in attr.columns:
+                        attr[col] = ""
+                    attr[col] = attr[col].fillna("")
+
+                numeric_fields = cols[4:11]  # cell count fields
+                for field in numeric_fields:
+                    attr[field] = attr["context"].apply(
+                        lambda c, f=field: c.get(f, 0) if isinstance(c, dict) else 0
+                    )
+
+                # 유저별 일별 마지막 저장 스냅샷 기준
+                attr_rows_df = (
+                    attr.groupby(["team", "project", "user_id", "date"])
+                    .agg({f: "last" for f in numeric_fields})
+                    .reset_index()
+                )
+                attr_rows = attr_rows_df.to_dict("records")
+
+    # --- Code copy from clicks ---
+    copy_map: dict[tuple, dict] = {}  # (team, project, user_id, date) -> counts
+    if clicks:
+        click_df = pd.DataFrame(clicks)
+        copies = click_df[click_df["feature"] == "code_copy_from_agent"].copy()
+        if not copies.empty:
+            copies["date"] = copies["datetime"].str[:10]
+            copies = _filter_by_date(copies, "date", date_from, date_to)
+            if not copies.empty:
+                for col in ("team", "project", "user_id"):
+                    if col not in copies.columns:
+                        copies[col] = ""
+                    copies[col] = copies[col].fillna("")
+
+                copies["_lines"] = copies["context"].apply(
+                    lambda c: c.get("code_lines", 0) if isinstance(c, dict) else 0
+                )
+                grouped = (
+                    copies.groupby(["team", "project", "user_id", "date"])
+                    .agg(
+                        code_copy_count=("_lines", "count"),
+                        code_copy_lines=("_lines", "sum"),
+                    )
+                    .reset_index()
+                )
+                for _, r in grouped.iterrows():
+                    key = (r["team"], r["project"], r["user_id"], r["date"])
+                    copy_map[key] = {
+                        "code_copy_count": int(r["code_copy_count"]),
+                        "code_copy_lines": int(r["code_copy_lines"]),
+                    }
+
+    # --- Merge ---
+    if not attr_rows and not copy_map:
+        return pd.DataFrame(columns=cols)
+
+    # Start from attribution rows, then merge copy data
+    result_map: dict[tuple, dict] = {}
+    for row in attr_rows:
+        key = (row["team"], row["project"], row["user_id"], row["date"])
+        result_map[key] = row
+
+    # Add copy data (may create new rows if user only copied, no cell attribution)
+    for key, cdata in copy_map.items():
+        if key in result_map:
+            result_map[key].update(cdata)
+        else:
+            result_map[key] = {
+                "team": key[0],
+                "project": key[1],
+                "user_id": key[2],
+                "date": key[3],
+                "total_code_cells": 0,
+                "agent_created_code_cells": 0,
+                "agent_modified_code_cells": 0,
+                "agent_pasted_code_cells": 0,
+                "agent_code_ratio_pct": 0,
+                "total_markdown_cells": 0,
+                "agent_markdown_cells": 0,
+                **cdata,
+            }
+
+    # Fill missing copy fields
+    for row in result_map.values():
+        row.setdefault("code_copy_count", 0)
+        row.setdefault("code_copy_lines", 0)
+
+    result = (
+        pd.DataFrame(list(result_map.values()), columns=cols)
+        .sort_values(["date", "team", "project", "user_id"])
+        .reset_index(drop=True)
+    )
+    return result
+
+
+def aggregate_codebuff_users(
+    impressions: list[dict],
+    clicks: list[dict],
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+) -> pd.DataFrame:
+    """A6: Jupyter-only vs Code Buff DAU/MAU."""
+    empty_cols = [
+        "date",
+        "jupyter_dau",
+        "codebuff_dau",
+        "jupyter_only_dau",
+        "codebuff_adoption_rate",
+        "jupyter_mau",
+        "codebuff_mau",
+        "jupyter_only_mau",
+        "codebuff_mau_rate",
+    ]
+
+    imp_df = pd.DataFrame(impressions)
+    click_df = pd.DataFrame(clicks)
+
+    if imp_df.empty and click_df.empty:
+        return pd.DataFrame(columns=empty_cols)
+
+    if not imp_df.empty:
+        imp_df["date"] = imp_df["datetime"].str[:10]
+        imp_df = _filter_by_date(imp_df, "date", date_from, date_to)
+
+    if not click_df.empty:
+        click_df["date"] = click_df["datetime"].str[:10]
+        click_df = _filter_by_date(click_df, "date", date_from, date_to)
+
+    # Jupyter DAU: users with session_start impression
+    if not imp_df.empty:
+        session_starts = imp_df[imp_df["feature"] == "session_start"]
+        if not session_starts.empty:
+            jupyter_daily_df = (
+                session_starts.groupby("date")["user_id"].apply(set).reset_index()
+            )
+            jupyter_daily_df.columns = ["date", "jupyter_users"]
+        else:
+            jupyter_daily_df = pd.DataFrame(columns=["date", "jupyter_users"])
+    else:
+        jupyter_daily_df = pd.DataFrame(columns=["date", "jupyter_users"])
+
+    # Code Buff DAU: users with code buff click features only
+    if not click_df.empty:
+        cb_clicks = click_df[click_df["feature"].isin(CODEBUFF_FEATURES)]
+        if not cb_clicks.empty:
+            cb_daily_df = cb_clicks.groupby("date")["user_id"].apply(set).reset_index()
+            cb_daily_df.columns = ["date", "codebuff_users"]
+        else:
+            cb_daily_df = pd.DataFrame(columns=["date", "codebuff_users"])
+    else:
+        cb_daily_df = pd.DataFrame(columns=["date", "codebuff_users"])
+
+    # Merge daily
+    all_dates: set[str] = set()
+    if not jupyter_daily_df.empty:
+        all_dates.update(jupyter_daily_df["date"].tolist())
+    if not cb_daily_df.empty:
+        all_dates.update(cb_daily_df["date"].tolist())
+
+    jupyter_daily_map: dict[str, set] = {}
+    cb_daily_map: dict[str, set] = {}
+    if not jupyter_daily_df.empty:
+        jupyter_daily_map = dict(
+            zip(jupyter_daily_df["date"], jupyter_daily_df["jupyter_users"])
+        )
+    if not cb_daily_df.empty:
+        cb_daily_map = dict(zip(cb_daily_df["date"], cb_daily_df["codebuff_users"]))
+
+    rows = []
+    for date in sorted(all_dates):
+        j_users = jupyter_daily_map.get(date, set())
+        cb_users = cb_daily_map.get(date, set())
+        jupyter_dau = len(j_users)
+        codebuff_dau = len(cb_users)
+        jupyter_only_dau = len(j_users - cb_users)
+        adoption = round(codebuff_dau / jupyter_dau, 4) if jupyter_dau > 0 else 0.0
+        rows.append(
+            {
+                "date": date,
+                "jupyter_dau": jupyter_dau,
+                "codebuff_dau": codebuff_dau,
+                "jupyter_only_dau": jupyter_only_dau,
+                "codebuff_adoption_rate": adoption,
+            }
+        )
+
+    daily_df = pd.DataFrame(rows)
+
+    # MAU
+    month_jupyter: dict[str, set] = {}
+    month_cb: dict[str, set] = {}
+
+    if not imp_df.empty:
+        session_starts = imp_df[imp_df["feature"] == "session_start"]
+        for _, row in session_starts.iterrows():
+            m = row["date"][:7]
+            month_jupyter.setdefault(m, set()).add(row["user_id"])
+
+    if not click_df.empty:
+        cb_clicks = click_df[click_df["feature"].isin(CODEBUFF_FEATURES)]
+        for _, row in cb_clicks.iterrows():
+            m = row["date"][:7]
+            month_cb.setdefault(m, set()).add(row["user_id"])
+
+    all_months = sorted(set(list(month_jupyter.keys()) + list(month_cb.keys())))
+    mau_map: dict[str, dict] = {}
+    for m in all_months:
+        j_set = month_jupyter.get(m, set())
+        cb_set = month_cb.get(m, set())
+        j_mau = len(j_set)
+        cb_mau = len(cb_set)
+        mau_rate = round(cb_mau / j_mau, 4) if j_mau > 0 else 0.0
+        mau_map[m] = {
+            "jupyter_mau": j_mau,
+            "codebuff_mau": cb_mau,
+            "jupyter_only_mau": len(j_set - cb_set),
+            "codebuff_mau_rate": mau_rate,
+        }
+
+    if not daily_df.empty:
+        daily_df["month"] = daily_df["date"].str[:7]
+        daily_df["jupyter_mau"] = daily_df["month"].map(
+            lambda m: mau_map.get(m, {}).get("jupyter_mau", 0)
+        )
+        daily_df["codebuff_mau"] = daily_df["month"].map(
+            lambda m: mau_map.get(m, {}).get("codebuff_mau", 0)
+        )
+        daily_df["jupyter_only_mau"] = daily_df["month"].map(
+            lambda m: mau_map.get(m, {}).get("jupyter_only_mau", 0)
+        )
+        daily_df["codebuff_mau_rate"] = daily_df["month"].map(
+            lambda m: mau_map.get(m, {}).get("codebuff_mau_rate", 0.0)
+        )
+        daily_df = daily_df.drop(columns=["month"])
+
+    return daily_df
+
+
+def aggregate_codebuff_feature_mix(
+    clicks: list[dict],
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+) -> pd.DataFrame:
+    """A7: Code Buff 기능별 softmax 비중 + 건수."""
+    empty_cols = ["period", "period_type", "feature", "count", "softmax_weight"]
+    if not clicks:
+        return pd.DataFrame(columns=empty_cols)
+
+    df = pd.DataFrame(clicks)
+    df["date"] = df["datetime"].str[:10]
+    df = _filter_by_date(df, "date", date_from, date_to)
+    df = df[df["feature"].isin(CODEBUFF_FEATURES)]
+
+    if df.empty:
+        return pd.DataFrame(columns=empty_cols)
+
+    df["month"] = df["date"].str[:7]
+
+    rows = []
+
+    # Daily
+    daily_counts = df.groupby(["date", "feature"]).size().reset_index(name="count")
+    for date, grp in daily_counts.groupby("date"):
+        counts = grp["count"].values.astype(float)
+        shifted = counts - counts.max()
+        exp_vals = np.exp(shifted)
+        softmax = exp_vals / exp_vals.sum()
+        for i, (_, r) in enumerate(grp.iterrows()):
+            rows.append(
+                {
+                    "period": date,
+                    "period_type": "daily",
+                    "feature": r["feature"],
+                    "count": int(r["count"]),
+                    "softmax_weight": round(float(softmax[i]), 6),
+                }
+            )
+
+    # Monthly
+    monthly_counts = df.groupby(["month", "feature"]).size().reset_index(name="count")
+    for month, grp in monthly_counts.groupby("month"):
+        counts = grp["count"].values.astype(float)
+        shifted = counts - counts.max()
+        exp_vals = np.exp(shifted)
+        softmax = exp_vals / exp_vals.sum()
+        for i, (_, r) in enumerate(grp.iterrows()):
+            rows.append(
+                {
+                    "period": month,
+                    "period_type": "monthly",
+                    "feature": r["feature"],
+                    "count": int(r["count"]),
+                    "softmax_weight": round(float(softmax[i]), 6),
+                }
+            )
+
+    return pd.DataFrame(rows, columns=empty_cols)
+
+
+def aggregate_codebuff_utilization(
+    impressions: list[dict],
+    clicks: list[dict],
+    date_from: Optional[str] = None,
+    date_to: Optional[str] = None,
+) -> pd.DataFrame:
+    """A8: Code Buff 활용률 (세션 단위 binary)."""
+    empty_cols = [
+        "period",
+        "period_type",
+        "code_shown_sessions",
+        "code_action_sessions",
+        "utilization_rate",
+    ]
+
+    imp_df = pd.DataFrame(impressions)
+    click_df = pd.DataFrame(clicks)
+
+    if imp_df.empty and click_df.empty:
+        return pd.DataFrame(columns=empty_cols)
+
+    # Impression: code_block_shown → (session_id, date)
+    shown_pairs: set[tuple[str, str]] = set()
+    if not imp_df.empty:
+        imp_df["date"] = imp_df["datetime"].str[:10]
+        imp_df = _filter_by_date(imp_df, "date", date_from, date_to)
+        shown = imp_df[imp_df["feature"] == "code_block_shown"]
+        if not shown.empty:
+            for _, r in shown.iterrows():
+                shown_pairs.add((r["session_id"], r["date"]))
+
+    # Click: CODEBUFF_FEATURES → (session_id, date)
+    action_pairs: set[tuple[str, str]] = set()
+    if not click_df.empty:
+        click_df["date"] = click_df["datetime"].str[:10]
+        click_df = _filter_by_date(click_df, "date", date_from, date_to)
+        cb_clicks = click_df[click_df["feature"].isin(CODEBUFF_FEATURES)]
+        if not cb_clicks.empty:
+            for _, r in cb_clicks.iterrows():
+                action_pairs.add((r["session_id"], r["date"]))
+
+    if not shown_pairs and not action_pairs:
+        return pd.DataFrame(columns=empty_cols)
+
+    rows = []
+
+    # Daily
+    all_dates = sorted({d for _, d in shown_pairs} | {d for _, d in action_pairs})
+    for date in all_dates:
+        shown_sessions = {sid for sid, d in shown_pairs if d == date}
+        action_sessions = {sid for sid, d in action_pairs if d == date}
+        n_shown = len(shown_sessions)
+        n_action = len(action_sessions)
+        rate = round(n_action / n_shown, 4) if n_shown > 0 else 0.0
+        rows.append(
+            {
+                "period": date,
+                "period_type": "daily",
+                "code_shown_sessions": n_shown,
+                "code_action_sessions": n_action,
+                "utilization_rate": rate,
+            }
+        )
+
+    # Monthly
+    shown_monthly: dict[str, set] = {}
+    for sid, d in shown_pairs:
+        m = d[:7]
+        shown_monthly.setdefault(m, set()).add(sid)
+    action_monthly: dict[str, set] = {}
+    for sid, d in action_pairs:
+        m = d[:7]
+        action_monthly.setdefault(m, set()).add(sid)
+
+    all_months = sorted(set(shown_monthly.keys()) | set(action_monthly.keys()))
+    for month in all_months:
+        n_shown = len(shown_monthly.get(month, set()))
+        n_action = len(action_monthly.get(month, set()))
+        rate = round(n_action / n_shown, 4) if n_shown > 0 else 0.0
+        rows.append(
+            {
+                "period": month,
+                "period_type": "monthly",
+                "code_shown_sessions": n_shown,
+                "code_action_sessions": n_action,
+                "utilization_rate": rate,
+            }
+        )
+
+    return pd.DataFrame(rows, columns=empty_cols)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Analytics JSONL → CSV 집계 리포트 생성"
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        help="JSONL 로그 디렉토리 (예: extensions/logs/)",
+    )
+    parser.add_argument(
+        "--output",
+        required=True,
+        help="CSV 출력 디렉토리 (예: /tmp/reports/)",
+    )
+    parser.add_argument("--date-from", default=None, help="시작 날짜 (YYYY-MM-DD)")
+    parser.add_argument("--date-to", default=None, help="종료 날짜 (YYYY-MM-DD)")
+    args = parser.parse_args()
+
+    input_dir = Path(args.input)
+    output_dir = Path(args.output)
+
+    if not input_dir.is_dir():
+        print(f"Error: input directory not found: {input_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Read JSONL data
+    impressions = _read_jsonl_files(input_dir, "analytics_impression_")
+    clicks = _read_jsonl_files(input_dir, "analytics_click_")
+    errors = _read_jsonl_files(input_dir, "analytics_error_")
+    structured_logs = _read_jsonl_files(input_dir, "agent_structured")
+
+    print(
+        f"Read: {len(impressions)} impressions, {len(clicks)} clicks, "
+        f"{len(errors)} errors, {len(structured_logs)} structured logs"
+    )
+
+    # A1: Active Users
+    a1 = aggregate_active_users(impressions, clicks, args.date_from, args.date_to)
+    a1.to_csv(output_dir / "A1_active_users.csv", index=False)
+    print(f"A1_active_users.csv: {len(a1)} rows")
+
+    # A2: Agent Frequency
+    a2 = aggregate_agent_frequency(clicks, args.date_from, args.date_to)
+    a2.to_csv(output_dir / "A2_agent_frequency.csv", index=False)
+    print(f"A2_agent_frequency.csv: {len(a2)} rows")
+
+    # A3: Feature Preference
+    a3 = aggregate_feature_preference(clicks, args.date_from, args.date_to)
+    a3.to_csv(output_dir / "A3_feature_preference.csv", index=False)
+    print(f"A3_feature_preference.csv: {len(a3)} rows")
+
+    # A4: Errors
+    a4 = aggregate_errors(errors, structured_logs, args.date_from, args.date_to)
+    a4.to_csv(output_dir / "A4_errors.csv", index=False)
+    print(f"A4_errors.csv: {len(a4)} rows")
+
+    # A5: Cell Attribution
+    a5 = aggregate_cell_attribution(impressions, clicks, args.date_from, args.date_to)
+    a5.to_csv(output_dir / "A5_cell_attribution.csv", index=False)
+    print(f"A5_cell_attribution.csv  : {len(a5)} rows")
+
+    # A6: Code Buff Users
+    a6 = aggregate_codebuff_users(impressions, clicks, args.date_from, args.date_to)
+    a6.to_csv(output_dir / "A6_codebuff_users.csv", index=False)
+    print(f"A6_codebuff_users.csv   : {len(a6)} rows")
+
+    # A7: Code Buff Feature Mix
+    a7 = aggregate_codebuff_feature_mix(clicks, args.date_from, args.date_to)
+    a7.to_csv(output_dir / "A7_codebuff_feature_mix.csv", index=False)
+    print(f"A7_codebuff_feature_mix.csv: {len(a7)} rows")
+
+    # A8: Code Buff Utilization
+    a8 = aggregate_codebuff_utilization(
+        impressions, clicks, args.date_from, args.date_to
+    )
+    a8.to_csv(output_dir / "A8_codebuff_utilization.csv", index=False)
+    print(f"A8_codebuff_utilization.csv: {len(a8)} rows")
+
+    print(f"\nDone. Reports saved to {output_dir}/")
+
+
+if __name__ == "__main__":
+    main()