context-forge-cli 0.1.0__py3-none-any.whl

contextforge/core/analytics.py

@@ -0,0 +1,226 @@
+"""Analytics aggregations for the ContextForge TUI dashboard."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import sqlite_utils
+
+
+# ── Data classes ─────────────────────────────────────────────────────────────
+
+
+@dataclass
+class OverviewStats:
+    total_sessions: int
+    total_tokens: int
+    active_tools: list[str]
+    date_range: tuple[datetime, datetime] | None
+    session_count_by_tool: dict[str, int]
+    token_sum_by_tool: dict[str, int]
+
+
+@dataclass
+class ActivityBucket:
+    label: str
+    count: int
+    tokens: int
+
+
+@dataclass
+class ProjectStats:
+    project: str
+    count: int
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+
+
+def _window_start_ms(window: str) -> int:
+    """Return epoch-ms for the start of *window* relative to now."""
+    now = datetime.now(timezone.utc)
+    if window == "7d":
+        delta = timedelta(days=7)
+    elif window == "30d":
+        delta = timedelta(days=30)
+    elif window == "6m":
+        # Approximate 6 months as 183 days
+        delta = timedelta(days=183)
+    elif window == "1y":
+        delta = timedelta(days=365)
+    else:
+        delta = timedelta(days=30)
+    start = now - delta
+    return int(start.timestamp() * 1000)
+
+
+def _bucket_key(updated_at_ms: int, window: str) -> str:
+    """Return the period label for a given ms timestamp and window."""
+    try:
+        dt = datetime.fromtimestamp(updated_at_ms / 1000, tz=timezone.utc)
+    except Exception:
+        return "?"
+    if window in ("7d", "30d"):
+        return dt.strftime("%Y-%m-%d")
+    elif window == "6m":
+        return dt.strftime("%Y-W%W")
+    else:  # 1y
+        return dt.strftime("%Y-%m")
+
+
+def _all_bucket_labels(window: str) -> list[str]:
+    """Return the ordered list of all period labels for the window (including zeros)."""
+    now = datetime.now(timezone.utc)
+    labels: list[str] = []
+
+    if window == "7d":
+        for i in range(6, -1, -1):
+            d = now - timedelta(days=i)
+            labels.append(d.strftime("%Y-%m-%d"))
+    elif window == "30d":
+        for i in range(29, -1, -1):
+            d = now - timedelta(days=i)
+            labels.append(d.strftime("%Y-%m-%d"))
+    elif window == "6m":
+        # ~26 ISO weeks
+        for i in range(25, -1, -1):
+            d = now - timedelta(weeks=i)
+            labels.append(d.strftime("%Y-W%W"))
+        # Deduplicate while preserving order
+        seen: set[str] = set()
+        unique: list[str] = []
+        for lbl in labels:
+            if lbl not in seen:
+                seen.add(lbl)
+                unique.append(lbl)
+        labels = unique
+    else:  # 1y
+        # 12 months backwards
+        for i in range(11, -1, -1):
+            # Subtract i months
+            month = now.month - i
+            year = now.year
+            while month <= 0:
+                month += 12
+                year -= 1
+            labels.append(f"{year:04d}-{month:02d}")
+
+    return labels
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def get_overview(
+    db: "sqlite_utils.Database",
+    window: str = "30d",
+) -> OverviewStats:
+    """Return high-level aggregates for the given time window."""
+    start_ms = _window_start_ms(window)
+
+    rows = list(db.execute(
+        "SELECT tool, COUNT(*) as cnt, COALESCE(SUM(token_count), 0) as tok "
+        "FROM sessions WHERE updated_at >= ? GROUP BY tool",
+        [start_ms],
+    ).fetchall())
+
+    session_count_by_tool: dict[str, int] = {}
+    token_sum_by_tool: dict[str, int] = {}
+    total_sessions = 0
+    total_tokens = 0
+
+    for tool, cnt, tok in rows:
+        session_count_by_tool[tool] = cnt
+        token_sum_by_tool[tool] = tok
+        total_sessions += cnt
+        total_tokens += tok
+
+    active_tools = [t for t, c in session_count_by_tool.items() if c > 0]
+
+    # Date range
+    range_row = db.execute(
+        "SELECT MIN(updated_at), MAX(updated_at) FROM sessions WHERE updated_at >= ?",
+        [start_ms],
+    ).fetchone()
+    date_range: tuple[datetime, datetime] | None = None
+    if range_row and range_row[0] and range_row[1]:
+        try:
+            earliest = datetime.fromtimestamp(range_row[0] / 1000, tz=timezone.utc)
+            latest = datetime.fromtimestamp(range_row[1] / 1000, tz=timezone.utc)
+            date_range = (earliest, latest)
+        except Exception:
+            pass
+
+    return OverviewStats(
+        total_sessions=total_sessions,
+        total_tokens=total_tokens,
+        active_tools=active_tools,
+        date_range=date_range,
+        session_count_by_tool=session_count_by_tool,
+        token_sum_by_tool=token_sum_by_tool,
+    )
+
+
+def get_activity_over_time(
+    db: "sqlite_utils.Database",
+    window: str = "30d",
+) -> list[ActivityBucket]:
+    """Return ordered activity buckets for the sparkline. Zero-count buckets included."""
+    start_ms = _window_start_ms(window)
+
+    data_rows = list(db.execute(
+        "SELECT updated_at, COALESCE(token_count, 0) FROM sessions WHERE updated_at >= ?",
+        [start_ms],
+    ).fetchall())
+
+    # Aggregate into buckets
+    bucket_counts: dict[str, int] = {}
+    bucket_tokens: dict[str, int] = {}
+    for updated_ms, tok in data_rows:
+        key = _bucket_key(updated_ms, window)
+        bucket_counts[key] = bucket_counts.get(key, 0) + 1
+        bucket_tokens[key] = bucket_tokens.get(key, 0) + tok
+
+    # Fill all period labels (including zeros)
+    labels = _all_bucket_labels(window)
+    return [
+        ActivityBucket(
+            label=lbl,
+            count=bucket_counts.get(lbl, 0),
+            tokens=bucket_tokens.get(lbl, 0),
+        )
+        for lbl in labels
+    ]
+
+
+def get_top_projects(
+    db: "sqlite_utils.Database",
+    window: str = "30d",
+    top_n: int = 5,
+) -> list[ProjectStats]:
+    """Return top N projects by session count within the window."""
+    start_ms = _window_start_ms(window)
+
+    rows = list(db.execute(
+        "SELECT cwd, COUNT(*) as cnt FROM sessions "
+        "WHERE updated_at >= ? AND cwd IS NOT NULL AND cwd != '' "
+        "GROUP BY cwd ORDER BY cnt DESC LIMIT ?",
+        [start_ms, top_n],
+    ).fetchall())
+
+    result: list[ProjectStats] = []
+    for cwd, cnt in rows:
+        # Use last 2 path components as display name
+        parts = [p for p in cwd.replace("\\", "/").split("/") if p]
+        if len(parts) >= 2:
+            project = "/".join(parts[-2:])
+        elif parts:
+            project = parts[-1]
+        else:
+            project = cwd
+        result.append(ProjectStats(project=project, count=cnt))
+
+    return result

contextforge/core/compactor.py

@@ -0,0 +1,182 @@
+"""Context compaction: convert one or more sessions into a token-efficient ContextBundle."""
+from __future__ import annotations
+
+import time
+from typing import Literal
+
+import sqlite_utils
+
+from contextforge.adapters.registry import get_adapter
+from contextforge.core.db import get_session
+from contextforge.models.session import ContextBundle, Message
+from contextforge.utils.tokens import count_tokens, truncate_to_budget
+
+Strategy = Literal["summary_only", "key_messages", "full_recent"]
+
+
+def _message_importance(msg: Message, index: int, total: int) -> float:
+    score = 0.0
+    content = msg.content
+
+    # Recency bonus (later messages score higher)
+    score += (index / max(total, 1)) * 2.0
+
+    # Length is a rough proxy for information density
+    score += min(len(content) / 500, 3.0)
+
+    # Code blocks, file paths, decisions
+    if "```" in content:
+        score += 2.0
+    if any(kw in content.lower() for kw in ("decided", "solution", "fixed", "implemented", "created")):
+        score += 1.5
+    if "/" in content and any(ext in content for ext in (".py", ".ts", ".js", ".go", ".rs", ".md")):
+        score += 1.0
+    if msg.role == "user":
+        score += 0.5
+
+    return score
+
+
+def _compact_summary_only(
+    db: sqlite_utils.Database,
+    session_ids: list[str],
+    token_budget: int,
+) -> str:
+    parts = []
+    for sid in session_ids:
+        row = get_session(db, sid)
+        if row is None:
+            continue
+        tool = row.get("tool", "?")
+        title = row.get("title") or sid[:12]
+        summary = row.get("summary") or row.get("first_message") or "(no summary)"
+        parts.append(f"## Session: {title} [{tool}]\n{summary}")
+    return "\n\n---\n\n".join(parts)
+
+
+def _compact_key_messages(
+    db: sqlite_utils.Database,
+    session_ids: list[str],
+    token_budget: int,
+) -> str:
+    parts = []
+    per_session_budget = token_budget // max(len(session_ids), 1)
+
+    for sid in session_ids:
+        row = get_session(db, sid)
+        if row is None:
+            continue
+        tool = row.get("tool", "?")
+        title = row.get("title") or sid[:12]
+
+        try:
+            adapter = get_adapter(tool)
+            messages = adapter.load_messages(sid)
+        except Exception:
+            messages = []
+
+        if not messages:
+            summary = row.get("summary") or row.get("first_message") or ""
+            parts.append(f"## Session: {title} [{tool}]\n{summary}")
+            continue
+
+        # Score and select
+        scored = [
+            (msg, _message_importance(msg, i, len(messages)))
+            for i, msg in enumerate(messages)
+        ]
+        scored.sort(key=lambda x: x[1], reverse=True)
+
+        selected: list[Message] = []
+        used_tokens = 0
+        header_tokens = count_tokens(f"## Session: {title} [{tool}]\n")
+        remaining = per_session_budget - header_tokens
+
+        for msg, _ in scored:
+            t = count_tokens(f"{msg.role.capitalize()}: {msg.content}\n\n")
+            if used_tokens + t > remaining:
+                break
+            selected.append(msg)
+            used_tokens += t
+
+        # Restore chronological order
+        original_order = {id(m): i for i, m in enumerate(messages)}
+        selected.sort(key=lambda m: original_order.get(id(m), 0))
+
+        lines = [f"## Session: {title} [{tool}]"]
+        for msg in selected:
+            lines.append(f"{msg.role.capitalize()}: {msg.content}")
+        parts.append("\n\n".join(lines))
+
+    return "\n\n---\n\n".join(parts)
+
+
+def _compact_full_recent(
+    db: sqlite_utils.Database,
+    session_ids: list[str],
+    token_budget: int,
+) -> str:
+    parts = []
+    per_session_budget = token_budget // max(len(session_ids), 1)
+
+    for sid in session_ids:
+        row = get_session(db, sid)
+        if row is None:
+            continue
+        tool = row.get("tool", "?")
+        title = row.get("title") or sid[:12]
+
+        try:
+            adapter = get_adapter(tool)
+            messages = adapter.load_messages(sid)
+        except Exception:
+            messages = []
+
+        lines = [f"## Session: {title} [{tool}]"]
+        used = count_tokens(lines[0])
+
+        for msg in reversed(messages):
+            chunk = f"{msg.role.capitalize()}: {msg.content}"
+            t = count_tokens(chunk)
+            if used + t > per_session_budget:
+                break
+            lines.insert(1, chunk)
+            used += t
+
+        parts.append("\n\n".join(lines))
+
+    return "\n\n---\n\n".join(parts)
+
+
+def compact(
+    db: sqlite_utils.Database,
+    session_ids: list[str],
+    strategy: Strategy = "summary_only",
+    token_budget: int = 4096,
+    name: str | None = None,
+    target_tool: str | None = None,
+) -> ContextBundle:
+    if not name:
+        name = f"bundle-{int(time.time())}"
+
+    if strategy == "summary_only":
+        text = _compact_summary_only(db, session_ids, token_budget)
+    elif strategy == "key_messages":
+        text = _compact_key_messages(db, session_ids, token_budget)
+    elif strategy == "full_recent":
+        text = _compact_full_recent(db, session_ids, token_budget)
+    else:
+        raise ValueError(f"Unknown strategy: {strategy!r}")
+
+    # Hard cap: never exceed budget
+    text = truncate_to_budget(text, token_budget)
+    actual_tokens = count_tokens(text)
+
+    return ContextBundle(
+        name=name,
+        source_sessions=session_ids,
+        compacted_text=text,
+        token_count=actual_tokens,
+        strategy=strategy,
+        target_tool=target_tool,
+    )

contextforge/core/db.py

@@ -0,0 +1,181 @@
+"""SQLite schema, migrations, and CRUD helpers for ContextForge."""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import sqlite_utils
+
+from contextforge.models.session import ContextBundle, Session
+
+_SCHEMA_VERSION = 1
+
+
+def get_db(db_path: Path) -> sqlite_utils.Database:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    db = sqlite_utils.Database(db_path)
+    _migrate(db)
+    return db
+
+
+def _migrate(db: sqlite_utils.Database) -> None:
+    if "schema_version" not in db.table_names():
+        db["schema_version"].insert({"version": 0})
+
+    row = next(db["schema_version"].rows)
+    version = row["version"]
+
+    if version < 1:
+        db["sessions"].create(
+            {
+                "id": str,
+                "tool": str,
+                "title": str,
+                "cwd": str,
+                "created_at": int,
+                "updated_at": int,
+                "first_message": str,
+                "token_count": int,
+                "raw_path": str,
+                "status": str,
+                "summary": str,
+                "summary_updated_at": int,
+                "tags": str,
+            },
+            pk="id",
+            if_not_exists=True,
+        )
+        db["context_bundles"].create(
+            {
+                "id": int,
+                "name": str,
+                "created_at": int,
+                "source_sessions": str,
+                "compacted_text": str,
+                "token_count": int,
+                "strategy": str,
+                "target_tool": str,
+            },
+            pk="id",
+            if_not_exists=True,
+        )
+        db["transfers"].create(
+            {
+                "id": int,
+                "bundle_id": int,
+                "target_tool": str,
+                "target_session_id": str,
+                "injected_at": int,
+                "method": str,
+                "command_used": str,
+            },
+            pk="id",
+            if_not_exists=True,
+        )
+        db["schema_version"].update(1, {"version": 1})
+
+
+def upsert_session(db: sqlite_utils.Database, session: Session) -> None:
+    existing = list(db["sessions"].rows_where("id = ?", [session.id]))
+    if existing:
+        existing_updated = existing[0]["updated_at"]
+        new_updated = int(session.updated_at.timestamp() * 1000)
+        if existing_updated >= new_updated:
+            return
+
+    first_msg = ""
+    if session.messages:
+        for m in session.messages:
+            if m.role == "user":
+                first_msg = m.content[:200]
+                break
+
+    db["sessions"].upsert(
+        {
+            "id": session.id,
+            "tool": session.tool,
+            "title": session.title,
+            "cwd": session.cwd,
+            "created_at": int(session.created_at.timestamp() * 1000),
+            "updated_at": int(session.updated_at.timestamp() * 1000),
+            "first_message": first_msg,
+            "token_count": session.token_count,
+            "raw_path": session.raw_path,
+            "status": session.status,
+            "summary": session.summary,
+            "summary_updated_at": None,
+            "tags": json.dumps(session.tags),
+        },
+        pk="id",
+    )
+
+
+def get_sessions(
+    db: sqlite_utils.Database,
+    tool: str | None = None,
+    limit: int = 200,
+) -> list[dict]:
+    where = "tool = ?" if tool else None
+    params = [tool] if tool else []
+    rows = db["sessions"].rows_where(
+        where,
+        params,
+        order_by="updated_at desc",
+        limit=limit,
+    )
+    return list(rows)
+
+
+def get_session(db: sqlite_utils.Database, session_id: str) -> dict | None:
+    rows = list(db["sessions"].rows_where("id = ?", [session_id]))
+    return rows[0] if rows else None
+
+
+def save_bundle(db: sqlite_utils.Database, bundle: ContextBundle) -> int:
+    result = db["context_bundles"].insert(
+        {
+            "name": bundle.name,
+            "created_at": int(time.time() * 1000),
+            "source_sessions": json.dumps(bundle.source_sessions),
+            "compacted_text": bundle.compacted_text,
+            "token_count": bundle.token_count,
+            "strategy": bundle.strategy,
+            "target_tool": bundle.target_tool,
+        }
+    )
+    return db.execute("SELECT last_insert_rowid()").fetchone()[0]
+
+
+def get_bundle(db: sqlite_utils.Database, bundle_id: int) -> dict | None:
+    rows = list(db["context_bundles"].rows_where("id = ?", [bundle_id]))
+    return rows[0] if rows else None
+
+
+def save_transfer(
+    db: sqlite_utils.Database,
+    bundle_id: int,
+    target_tool: str,
+    method: str,
+    command_used: str,
+    target_session_id: str | None = None,
+) -> None:
+    db["transfers"].insert(
+        {
+            "bundle_id": bundle_id,
+            "target_tool": target_tool,
+            "target_session_id": target_session_id,
+            "injected_at": int(time.time() * 1000),
+            "method": method,
+            "command_used": command_used,
+        }
+    )
+
+
+def update_summary(
+    db: sqlite_utils.Database, session_id: str, summary: str
+) -> None:
+    db["sessions"].update(
+        session_id,
+        {"summary": summary, "summary_updated_at": int(time.time() * 1000)},
+    )

contextforge/core/injector.py

@@ -0,0 +1,94 @@
+"""Build and optionally execute context injection commands."""
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import tempfile
+from pathlib import Path
+
+import sqlite_utils
+
+from contextforge.adapters.registry import get_adapter
+from contextforge.core.db import save_transfer
+from contextforge.models.session import ContextBundle
+
+# If compacted text exceeds this, write to a file instead of inline system prompt
+_INLINE_TOKEN_LIMIT = 4096
+
+
+def build_inject_command(
+    bundle: ContextBundle,
+    target_tool: str,
+    target_session_id: str | None = None,
+    cwd: str | None = None,
+    method: str | None = None,
+) -> tuple[str, str]:
+    """Return (shell_command, method_used)."""
+    adapter = get_adapter(target_tool)
+
+    # Choose injection method based on token count
+    if method is None:
+        if bundle.token_count > _INLINE_TOKEN_LIMIT:
+            method = "file"
+        elif target_session_id:
+            method = "resume"
+        else:
+            method = "system_prompt"
+
+    if method == "file":
+        # Context goes into a temp CONTEXT.md; system prompt references it
+        ctx_summary = (
+            f"Prior session context has been written to CONTEXT.md in this directory. "
+            f"Read it before proceeding. Summary: {bundle.compacted_text[:300]}..."
+        )
+        cmd = adapter.build_inject_command(
+            context=ctx_summary,
+            target_session_id=None,
+            cwd=cwd,
+            method="system_prompt",
+        )
+    else:
+        cmd = adapter.build_inject_command(
+            context=bundle.compacted_text,
+            target_session_id=target_session_id,
+            cwd=cwd,
+            method=method,
+        )
+
+    return cmd, method
+
+
+def execute_transfer(
+    db: sqlite_utils.Database,
+    bundle: ContextBundle,
+    bundle_id: int,
+    target_tool: str,
+    target_session_id: str | None = None,
+    cwd: str | None = None,
+    method: str | None = None,
+) -> str:
+    """Build the command, write CONTEXT.md if needed, record transfer, and execute."""
+    cmd, actual_method = build_inject_command(
+        bundle, target_tool, target_session_id, cwd, method
+    )
+
+    context_file: Path | None = None
+
+    if actual_method == "file":
+        work_dir = Path(cwd) if cwd else Path.cwd()
+        context_file = work_dir / "CONTEXT.md"
+        context_file.write_text(bundle.compacted_text, encoding="utf-8")
+
+    save_transfer(
+        db=db,
+        bundle_id=bundle_id,
+        target_tool=target_tool,
+        method=actual_method,
+        command_used=cmd,
+    )
+
+    # Execute via shell
+    subprocess.run(cmd, shell=True, cwd=cwd or None)
+
+    return cmd