launching

backend/app/routers/topics.py

@@ -1,5 +1,10 @@
+"""Topic map: topics as stars, co-occurrence as constellation lines, plus the insight a writer needs:
+which topics are rising, which went dormant, which travel together, and how each one evolved."""
+
 import uuid
-from collections import Counter
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
 from itertools import combinations
 
 from fastapi import APIRouter, Depends, HTTPException
@@ -12,33 +17,174 @@ from app.services.jobs import create_job, serialize_job
 
 router = APIRouter(prefix="/api/topics", tags=["topics"])
 
+BUCKETS = 12  # timeline resolution across the archive's lifetime
+
+
+def _aware(dt: datetime | None) -> datetime | None:
+    return dt if dt is None or dt.tzinfo else dt.replace(tzinfo=UTC)
+
+
+@dataclass
+class TopicStats:
+    topic: Topic
+    dates: list[datetime] = field(default_factory=list)
+    docs: set[uuid.UUID] = field(default_factory=set)
+
+
+@dataclass
+class Archive:
+    start: datetime
+    end: datetime
+    recent_from: datetime
+    total_docs: int
+    recent_docs: int
+
+    def bucket(self, dt: datetime) -> int:
+        span = (self.end - self.start).total_seconds() or 1
+        return min(BUCKETS - 1, max(0, int((dt - self.start).total_seconds() / span * BUCKETS)))
+
+
+def _load(ctx: Ctx, topic_ids: set[uuid.UUID] | None = None):
+    """Topic -> dated posts, and the archive's time frame."""
+    q = (
+        select(DocumentTopic.topic_id, DocumentTopic.document_id, Document.published_at, Document.created_at)
+        .join(Document, Document.id == DocumentTopic.document_id)
+        .where(Document.workspace_id == ctx.workspace.id)
+    )
+    if topic_ids is not None:
+        q = q.where(DocumentTopic.topic_id.in_(topic_ids))
+    rows = ctx.db.execute(q).all()
+    all_dates = [
+        _aware(p or c)
+        for p, c in ctx.db.execute(
+            select(Document.published_at, Document.created_at).where(
+                Document.workspace_id == ctx.workspace.id, Document.path.is_not(None))
+        ).all()
+    ]
+    now = datetime.now(UTC)
+    start = min(all_dates, default=now)
+    end = max(all_dates, default=now)
+    span = end - start
+    # "Recent" is the last quarter of the writer's own publishing history (at least 60 days), so an archive
+    # that stopped in 2022 still shows what was rising at the end of it.
+    window = max(span / 4, timedelta(days=60))
+    recent_from = end - window
+    archive = Archive(start, end, recent_from, len(all_dates), sum(1 for d in all_dates if d >= recent_from))
+    return rows, archive
+
+
+def _status(count: int, recent: int, last: datetime | None, archive: Archive) -> tuple[str, float]:
+    """(status, momentum). Momentum compares the topic's share of recent posts to its share of all posts."""
+    overall = count / max(archive.total_docs, 1)
+    recent_share = recent / max(archive.recent_docs, 1)
+    momentum = round(recent_share / overall, 2) if overall else 0.0
+    if recent == 0 and last and last < archive.recent_from:
+        return "dormant", momentum
+    if momentum >= 1.4 and recent >= 2:
+        return "rising", momentum
+    return "steady", momentum
+
+
+def _galaxies(node_ids: list[str], edges: Counter) -> dict[str, int]:
+    """Weighted label propagation: topics that share posts settle into the same galaxy."""
+    label = {n: i for i, n in enumerate(node_ids)}
+    nbrs: dict[str, list[tuple[str, int]]] = defaultdict(list)
+    for (a, b), w in edges.items():
+        nbrs[a].append((b, w))
+        nbrs[b].append((a, w))
+    for _ in range(12):
+        changed = False
+        for n in node_ids:  # deterministic order: biggest topics first
+            if not nbrs[n]:
+                continue
+            score: Counter = Counter()
+            for m, w in nbrs[n]:
+                score[label[m]] += w
+            best = max(score.items(), key=lambda kv: (kv[1], -kv[0]))[0]
+            if score[best] > score.get(label[n], 0) and best != label[n]:
+                label[n] = best
+                changed = True
+        if not changed:
+            break
+    return label
+
 
 @router.get("")
 def topic_map(ctx: Ctx = Depends(get_ctx), min_posts: int = 1, limit: int = 80):
-    """Nodes are topics sized by post count; edges join topics that share posts."""
     topics = ctx.db.scalars(
         select(Topic).where(Topic.workspace_id == ctx.workspace.id, Topic.post_count >= min_posts)
-        .order_by(Topic.post_count.desc()).limit(min(limit, 300))
+        .order_by(Topic.post_count.desc(), Topic.name).limit(min(limit, 300))
     ).all()
-    ids = {t.id for t in topics}
-    links = ctx.db.execute(
-        select(DocumentTopic.document_id, DocumentTopic.topic_id).where(DocumentTopic.topic_id.in_(ids))
-    ).all() if ids else []
-    by_doc: dict[uuid.UUID, list[uuid.UUID]] = {}
-    for doc_id, topic_id in links:
-        by_doc.setdefault(doc_id, []).append(topic_id)
+    by_id = {t.id: TopicStats(t) for t in topics}
+    rows, archive = _load(ctx, set(by_id)) if by_id else ([], None)
+
+    by_doc: dict[uuid.UUID, list[str]] = defaultdict(list)
+    for topic_id, doc_id, published, created in rows:
+        st = by_id[topic_id]
+        if doc_id not in st.docs:
+            st.docs.add(doc_id)
+            st.dates.append(_aware(published or created))
+            by_doc[doc_id].append(str(topic_id))
     edges: Counter[tuple[str, str]] = Counter()
     for tids in by_doc.values():
-        for a, b in combinations(sorted(str(t) for t in tids), 2):
+        for a, b in combinations(sorted(set(tids)), 2):
             edges[(a, b)] += 1
+
+    node_ids = [str(t.id) for t in topics]
+    galaxy_of = _galaxies(node_ids, edges)
+    nodes = []
+    for t in topics:
+        st = by_id[t.id]
+        dates = sorted(st.dates)
+        count = len(dates) or t.post_count
+        recent = sum(1 for d in dates if archive and d >= archive.recent_from)
+        first, last = (dates[0], dates[-1]) if dates else (None, None)
+        status, momentum = _status(count, recent, last, archive) if archive else ("steady", 1.0)
+        timeline = [0] * BUCKETS
+        for d in dates:
+            timeline[archive.bucket(d)] += 1
+        span = (archive.end - archive.start).total_seconds() if archive else 0
+        recency = round((last - archive.start).total_seconds() / span, 3) if last and span else 1.0
+        nodes.append({
+            "id": str(t.id), "name": t.name, "summary": t.summary, "post_count": count,
+            "first_at": first.isoformat() if first else None, "last_at": last.isoformat() if last else None,
+            "recent_posts": recent, "momentum": momentum, "status": status, "recency": recency,
+            "timeline": timeline, "galaxy": galaxy_of[str(t.id)],
+        })
+
+    # Galaxies: named after their brightest (most written about) star.
+    members: dict[int, list[dict]] = defaultdict(list)
+    for n in nodes:
+        members[n["galaxy"]].append(n)
+    galaxies = []
+    for gid, ns in sorted(members.items(), key=lambda kv: -sum(n["post_count"] for n in kv[1])):
+        lead = max(ns, key=lambda n: n["post_count"])
+        galaxies.append({"id": gid, "name": lead["name"], "topic_ids": [n["id"] for n in ns],
+                         "post_count": sum(n["post_count"] for n in ns), "size": len(ns)})
+    names = {n["id"]: n["name"] for n in nodes}
+    rising = sorted((n for n in nodes if n["status"] == "rising"), key=lambda n: -n["momentum"])[:5]
+    dormant = sorted((n for n in nodes if n["status"] == "dormant"), key=lambda n: -n["post_count"])[:5]
     untagged = ctx.db.scalar(
         select(Document.id).where(Document.workspace_id == ctx.workspace.id, Document.path.is_not(None),
                                   Document.id.not_in(select(DocumentTopic.document_id))).limit(1)
     )
     return {
-        "nodes": [{"id": str(t.id), "name": t.name, "summary": t.summary, "post_count": t.post_count}
-                  for t in topics],
+        "nodes": nodes,
         "edges": [{"source": a, "target": b, "weight": w} for (a, b), w in edges.most_common(400)],
+        "galaxies": galaxies,
+        "insights": {
+            "rising": [{"id": n["id"], "name": n["name"], "momentum": n["momentum"]} for n in rising],
+            "dormant": [{"id": n["id"], "name": n["name"], "last_at": n["last_at"], "post_count": n["post_count"]}
+                        for n in dormant],
+            "pairs": [{"a": names[a], "b": names[b], "a_id": a, "b_id": b, "posts": w}
+                      for (a, b), w in edges.most_common(5)],
+        },
+        "archive": {
+            "start": archive.start.isoformat() if archive else None,
+            "end": archive.end.isoformat() if archive else None,
+            "recent_from": archive.recent_from.isoformat() if archive else None,
+            "posts": archive.total_docs if archive else 0,
+        },
         "has_untagged_posts": untagged is not None,
     }
 
@@ -54,18 +200,42 @@ def topic_detail(topic_id: uuid.UUID, ctx: Ctx = Depends(get_ctx)):
         .where(DocumentTopic.topic_id == topic.id)
         .order_by(DocumentTopic.weight.desc(), Document.published_at.desc())
     ).all()
-    return {"id": str(topic.id), "name": topic.name, "summary": topic.summary, "post_count": topic.post_count,
-            "posts": [{**serialize_document(d), "weight": w} for d, w in rows]}
+    doc_ids = [d.id for d, _ in rows]
+    _, archive = _load(ctx, {topic.id})
+    dates = sorted(_aware(d.published_at or d.created_at) for d, _ in rows)
+    recent = sum(1 for d in dates if d >= archive.recent_from)
+    status, momentum = _status(len(dates), recent, dates[-1] if dates else None, archive)
+    timeline = [0] * BUCKETS
+    for d in dates:
+        timeline[archive.bucket(d)] += 1
+    # Topics that share posts with this one, strongest first.
+    related = Counter()
+    if doc_ids:
+        for other_id, in ctx.db.execute(
+            select(DocumentTopic.topic_id).where(DocumentTopic.document_id.in_(doc_ids),
+                                                 DocumentTopic.topic_id != topic.id)
+        ).all():
+            related[other_id] += 1
+    related_topics = {t.id: t for t in ctx.db.scalars(select(Topic).where(Topic.id.in_(list(related))))} \
+        if related else {}
+    return {
+        "id": str(topic.id), "name": topic.name, "summary": topic.summary, "post_count": len(dates),
+        "first_at": dates[0].isoformat() if dates else None, "last_at": dates[-1].isoformat() if dates else None,
+        "recent_posts": recent, "momentum": momentum, "status": status, "timeline": timeline,
+        "timeline_start": archive.start.isoformat(), "timeline_end": archive.end.isoformat(),
+        "related": [{"id": str(tid), "name": related_topics[tid].name, "shared_posts": n}
+                    for tid, n in related.most_common(6) if tid in related_topics],
+        "posts": [{**serialize_document(d), "weight": w} for d, w in rows],
+    }
 
 
 @router.post("/rebuild")
 def rebuild(ctx: Ctx = Depends(get_ctx), full: bool = False):
-    params = {}
     if full:
         # Clear per post tags so every post is mapped again.
         for d in ctx.db.scalars(select(Document).where(Document.workspace_id == ctx.workspace.id)):
             if d.metadata_json and "topics" in d.metadata_json:
                 d.metadata_json = {k: v for k, v in d.metadata_json.items() if k != "topics"}
         ctx.db.commit()
-    job = create_job(ctx.db, ctx.workspace.id, "topics", params, max_attempts=2)
+    job = create_job(ctx.db, ctx.workspace.id, "topics", {}, max_attempts=2)
     return serialize_job(job)

backend/tests/test_buildout.py

@@ -263,6 +263,14 @@ def test_topic_map_and_notebook_from_topic(client, auth, run_jobs, feed, llm):
     assert len(graph["edges"]) == 2
     detail = client.get(f"/api/topics/{names['Writing Business']['id']}", headers=auth).json()
     assert len(detail["posts"]) == 2
+    # Insight: Habits was only written about in 2024, long before the archive's recent window.
+    assert names["Habits"]["status"] == "dormant" and names["Pricing"]["recent_posts"] == 1
+    assert len(names["Pricing"]["timeline"]) == 12 and sum(names["Writing Business"]["timeline"]) == 2
+    assert graph["galaxies"] and graph["galaxies"][0]["name"] == "Writing Business"
+    assert graph["insights"]["dormant"][0]["name"] == "Habits"
+    assert graph["insights"]["pairs"][0]["posts"] == 1
+    assert {r["name"] for r in detail["related"]} == {"Pricing", "Habits"}
+    assert detail["first_at"] < detail["last_at"]
     nb = client.post(f"/api/notebooks/from-topic/{names['Pricing']['id']}", headers=auth).json()
     assert nb["added"] == 1
 

frontend/src/api/types.ts

@@ -119,13 +119,54 @@ export type Artifact = {
   job: Job | null;
 };
 
-export type TopicNode = { id: string; name: string; summary: string | null; post_count: number };
+export type TopicStatus = "rising" | "steady" | "dormant";
+
+export type TopicNode = {
+  id: string;
+  name: string;
+  summary: string | null;
+  post_count: number;
+  first_at: string | null;
+  last_at: string | null;
+  recent_posts: number;
+  momentum: number;
+  status: TopicStatus;
+  recency: number; // 0 = only written about at the start of the archive, 1 = written about most recently
+  timeline: number[];
+  galaxy: number;
+};
+
+export type Galaxy = { id: number; name: string; topic_ids: string[]; post_count: number; size: number };
+
 export type TopicMap = {
   nodes: TopicNode[];
   edges: { source: string; target: string; weight: number }[];
+  galaxies: Galaxy[];
+  insights: {
+    rising: { id: string; name: string; momentum: number }[];
+    dormant: { id: string; name: string; last_at: string | null; post_count: number }[];
+    pairs: { a: string; b: string; a_id: string; b_id: string; posts: number }[];
+  };
+  archive: { start: string | null; end: string | null; recent_from: string | null; posts: number };
   has_untagged_posts: boolean;
 };
-export type TopicDetail = TopicNode & { posts: (Doc & { weight: number })[] };
+
+export type TopicDetail = {
+  id: string;
+  name: string;
+  summary: string | null;
+  post_count: number;
+  first_at: string | null;
+  last_at: string | null;
+  recent_posts: number;
+  momentum: number;
+  status: TopicStatus;
+  timeline: number[];
+  timeline_start: string;
+  timeline_end: string;
+  related: { id: string; name: string; shared_posts: number }[];
+  posts: (Doc & { weight: number })[];
+};
 
 export type VoiceProfileData = {
   tone: string[];

frontend/src/styles/showcase.css

@@ -584,3 +584,283 @@
   font-size: 0.72rem;
   margin-top: -4px;
 }
+
+/* ---------- Topic map: space chart ---------- */
+.map-canvas {
+  background:
+    radial-gradient(60% 50% at 50% 45%, rgba(33, 124, 255, 0.07), transparent 70%),
+    #000;
+}
+
+.survey-ring {
+  fill: none;
+  stroke: rgba(255, 255, 255, 0.05);
+  stroke-dasharray: 2 6;
+}
+
+.survey-axis {
+  stroke: rgba(255, 255, 255, 0.04);
+}
+
+.nebula {
+  cursor: zoom-in;
+}
+
+.galaxy-label {
+  fill: rgba(156, 196, 255, 0.75);
+  font-family: var(--font-mono);
+  pointer-events: none;
+}
+
+.constellation {
+  transition: stroke-opacity 0.25s ease;
+}
+
+.map-count {
+  fill: var(--blue);
+  font-family: var(--font-mono);
+}
+
+.orbit-ring {
+  fill: none;
+  stroke: var(--blue);
+  stroke-dasharray: 4 5;
+  transform-box: fill-box;
+  transform-origin: center;
+  animation: orbit-spin 12s linear infinite;
+}
+
+@keyframes orbit-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.spikes {
+  pointer-events: none;
+}
+
+.map-hud {
+  position: absolute;
+  left: 14px;
+  top: 12px;
+  z-index: 1;
+  display: grid;
+  gap: 4px;
+  max-width: min(360px, 60%);
+  padding: 10px 12px;
+  border: 1px solid var(--blue-20);
+  border-radius: 10px;
+  background: rgba(0, 0, 0, 0.72);
+  backdrop-filter: blur(6px);
+  font-size: 0.72rem;
+  pointer-events: none;
+}
+
+.hud-title {
+  font-family: var(--font-display);
+  font-size: 0.95rem;
+  letter-spacing: 0;
+  color: var(--white);
+}
+
+.map-hud .sparkline {
+  width: 160px;
+  height: 18px;
+}
+
+.map-legend {
+  position: absolute;
+  right: 12px;
+  bottom: 10px;
+  z-index: 1;
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 6px 14px;
+  max-width: 70%;
+  padding: 6px 10px;
+  border-radius: 10px;
+  background: rgba(0, 0, 0, 0.6);
+  font-size: 0.66rem;
+  color: var(--text-2);
+  pointer-events: none;
+}
+
+.map-legend span {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.map-legend i {
+  display: inline-block;
+}
+
+.lg-size {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  background: var(--white);
+  box-shadow: 0 0 8px var(--blue), -8px 0 0 -3px var(--white);
+  margin-left: 6px;
+}
+
+.lg-bright {
+  width: 26px;
+  height: 6px;
+  border-radius: 3px;
+  background: linear-gradient(90deg, var(--blue), #ffffff);
+}
+
+.lg-tail {
+  width: 22px;
+  height: 4px;
+  border-radius: 3px;
+  background: linear-gradient(90deg, #ffffff, transparent);
+}
+
+.lg-dormant {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  border: 1px dashed rgba(255, 255, 255, 0.6);
+}
+
+.lg-line {
+  width: 22px;
+  height: 0;
+  border-top: 2px solid rgba(255, 255, 255, 0.4);
+}
+
+.map-hint {
+  display: none;
+}
+
+/* Side panel: briefing and star detail */
+.brief {
+  display: grid;
+  gap: 6px;
+  padding-top: 10px;
+  border-top: 1px solid var(--line);
+}
+
+.brief h3 {
+  font-size: 0.8rem;
+  font-family: var(--font-mono);
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--blue);
+}
+
+.brief-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: 6px;
+}
+
+.brief-list li {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 10px;
+  font-size: 0.875rem;
+}
+
+.brief-list .mono {
+  font-size: 0.7rem;
+  white-space: nowrap;
+}
+
+.brief-up {
+  color: var(--white);
+  text-shadow: 0 0 8px var(--blue);
+}
+
+.star-stats {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 8px;
+  margin: 0;
+}
+
+.star-stats div {
+  display: grid;
+  gap: 2px;
+  padding: 8px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+}
+
+.star-stats dt {
+  font: 0.62rem var(--font-mono);
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--text-3);
+}
+
+.star-stats dd {
+  margin: 0;
+  font-size: 0.82rem;
+}
+
+.timeline {
+  display: grid;
+  gap: 4px;
+}
+
+.sparkline {
+  width: 100%;
+  height: 44px;
+}
+
+.sparkline rect {
+  fill: rgba(33, 124, 255, 0.55);
+}
+
+.sparkline rect.recent {
+  fill: #ffffff;
+}
+
+.status-rising {
+  border: 1px solid var(--white);
+  color: var(--white);
+  box-shadow: 0 0 10px var(--blue-60);
+}
+
+.status-steady {
+  border: 1px solid var(--blue-60);
+  color: var(--white);
+}
+
+.status-dormant {
+  border: 1px dashed var(--line-strong);
+  color: var(--text-2);
+}
+
+.chip-btn {
+  background: transparent;
+  color: var(--white);
+  font: inherit;
+  font-size: 0.75rem;
+  cursor: pointer;
+}
+
+.chip-btn:hover {
+  border-color: var(--blue);
+  background: var(--blue-10);
+}
+
+.chip-btn .mono {
+  font-size: 0.65rem;
+  color: var(--blue);
+  margin-left: 4px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .orbit-ring {
+    animation: none;
+  }
+}