@chainlesschain/personal-data-hub 0.1.0 → 0.2.0

package/lib/analysis-skills/footprint.js

@@ -0,0 +1,167 @@
+/**
+ * Phase 11 — analysis.footprint skill.
+ *
+ * Travel + location patterns based on Place entities + Event records
+ * with location data. Phase 9 (Travel adapters) will substantially
+ * expand the source data; this v0 works with whatever Place rows
+ * adapters already produce (Phase 6 Alipay travel transactions /
+ * Phase 5 Email travel template).
+ *
+ * Inputs:
+ *   - timeWindow:  { since, until } | { sinceDays N } | { sinceMonths N }
+ *   - topN:        default 10
+ *   - groupBy:     "city" | "place" | "country"  (default "place")
+ *
+ * Output:
+ *   {
+ *     summary: {
+ *       totalTrips, uniquePlaces, period,
+ *     },
+ *     topPlaces: [{ name, visits, lastVisit, eventIds }, ...],
+ *     monthlyDistribution: [{ monthKey, trips }, ...],
+ *     citations,
+ *     llm_commentary,
+ *   }
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+const TRAVEL_SUBTYPES = new Set(["travel", "visit", "checkin"]);
+
+class FootprintSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.footprint" });
+  }
+
+  async run(options = {}) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const topN = Number.isFinite(options.topN) && options.topN > 0 ? options.topN : 10;
+    const groupBy = options.groupBy || "place";
+
+    const events = this._fetchTravelEvents({ since, until });
+    const visits = this._extractVisits(events);
+    const topPlaces = this._topPlaces(visits, groupBy, topN);
+    const monthly = this._monthlyDistribution(visits);
+
+    const summary = {
+      totalTrips: visits.length,
+      uniquePlaces: new Set(visits.map((v) => v.key)).size,
+      period: { since: since || null, until: until || null },
+    };
+
+    let llmCommentary = null;
+    if (options.commentary !== false && this.llm && visits.length > 0) {
+      llmCommentary = await this._llmCommentary(summary, topPlaces, options);
+    }
+
+    return {
+      skill: "analysis.footprint",
+      summary,
+      topPlaces,
+      monthlyDistribution: monthly,
+      citations: events.slice(0, 50).map((e) => e.id),
+      llm_commentary: llmCommentary,
+    };
+  }
+
+  _fetchTravelEvents({ since, until }) {
+    const events = [];
+    for (const subtype of TRAVEL_SUBTYPES) {
+      const q = { subtype, limit: 5000 };
+      if (since != null) q.since = since;
+      if (until != null) q.until = until;
+      const batch = this.vault.queryEvents(q) || [];
+      events.push(...batch);
+    }
+    // Also include events with explicit Place participants
+    const general = this.vault.queryEvents({
+      limit: 10_000,
+      ...(since != null ? { since } : {}),
+      ...(until != null ? { until } : {}),
+    }) || [];
+    for (const e of general) {
+      if (e.extra && (e.extra.placeId || e.extra.from || e.extra.to)) events.push(e);
+    }
+    // Dedup by id
+    const seen = new Set();
+    return events.filter((e) => {
+      if (seen.has(e.id)) return false;
+      seen.add(e.id);
+      return true;
+    });
+  }
+
+  _extractVisits(events) {
+    const visits = [];
+    for (const e of events) {
+      const places = [];
+      // Travel adapters typically store from/to in extra
+      if (e.extra) {
+        if (typeof e.extra.from === "string") places.push({ key: e.extra.from, role: "from" });
+        if (typeof e.extra.to === "string") places.push({ key: e.extra.to, role: "to" });
+        if (typeof e.extra.placeId === "string") places.push({ key: e.extra.placeId, role: "visit" });
+        if (typeof e.extra.city === "string") places.push({ key: e.extra.city, role: "city" });
+      }
+      // Event with location in content
+      if (e.content && typeof e.content.location === "string") {
+        places.push({ key: e.content.location, role: "location" });
+      }
+      for (const p of places) {
+        if (!p.key || p.key === "(unknown)") continue;
+        visits.push({
+          key: p.key,
+          role: p.role,
+          eventId: e.id,
+          occurredAt: e.occurredAt,
+        });
+      }
+    }
+    return visits;
+  }
+
+  _topPlaces(visits, _groupBy, topN) {
+    const buckets = new Map();
+    for (const v of visits) {
+      const cur = buckets.get(v.key) || { name: v.key, visits: 0, lastVisit: 0, eventIds: [] };
+      cur.visits += 1;
+      if (v.occurredAt > cur.lastVisit) cur.lastVisit = v.occurredAt;
+      if (cur.eventIds.length < 5) cur.eventIds.push(v.eventId);
+      buckets.set(v.key, cur);
+    }
+    return Array.from(buckets.values())
+      .sort((a, b) => b.visits - a.visits)
+      .slice(0, topN);
+  }
+
+  _monthlyDistribution(visits) {
+    const buckets = new Map();
+    for (const v of visits) {
+      const d = new Date(v.occurredAt);
+      if (!Number.isFinite(d.getTime())) continue;
+      const m = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+      buckets.set(m, (buckets.get(m) || 0) + 1);
+    }
+    return Array.from(buckets.entries())
+      .map(([monthKey, trips]) => ({ monthKey, trips }))
+      .sort((a, b) => a.monthKey.localeCompare(b.monthKey));
+  }
+
+  async _llmCommentary(summary, topPlaces, options) {
+    if (summary.totalTrips === 0) return "No travel events in this period.";
+    const topList = topPlaces.slice(0, 5).map((p) => `${p.name}(${p.visits}次)`).join(", ");
+    const userMsg = `用户的出行数据：
+- 期间: ${summary.period.since ? new Date(summary.period.since).toISOString().slice(0,10) : "全部"} 至 ${summary.period.until ? new Date(summary.period.until).toISOString().slice(0,10) : "现在"}
+- 共 ${summary.totalTrips} 次足迹, ${summary.uniquePlaces} 个独特地点
+- Top 5: ${topList}
+
+请用 2-3 句话总结出行模式（常去、稀去、季节性 etc.）。中文回答。`;
+    return await this.callLlmCommentary([
+      { role: "system", content: "你是一个克制的足迹分析助手。基于事实简短描述出行模式。" },
+      { role: "user", content: userMsg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+  }
+}
+
+module.exports = { FootprintSkill };

package/lib/analysis-skills/index.js

@@ -0,0 +1,58 @@
+/**
+ * Phase 11 — internal analysis skills entry point.
+ *
+ * Each skill is a small focused class that the hub dispatches to via
+ * `runAnalysisSkill(name, options)`. Skills work over the vault +
+ * optional LLM and respect the same privacy gate as AnalysisEngine.
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+const { SpendingSkill, SUPPORTED_DIMENSIONS: SPENDING_DIMENSIONS } = require("./spending");
+const { RelationsSkill } = require("./relations");
+const { FootprintSkill } = require("./footprint");
+const { InterestsSkill } = require("./interests");
+const { TimelineSkill } = require("./timeline");
+
+const SKILL_REGISTRY = Object.freeze({
+  "analysis.spending": SpendingSkill,
+  "analysis.relations": RelationsSkill,
+  "analysis.footprint": FootprintSkill,
+  "analysis.interests": InterestsSkill,
+  "analysis.timeline": TimelineSkill,
+});
+
+const SKILL_NAMES = Object.freeze(Object.keys(SKILL_REGISTRY));
+
+/**
+ * Run a single skill by name. Convenience over instantiating Skill
+ * classes directly — the same {vault, llm} pair gets reused.
+ *
+ * @param {{vault, llm?}} deps
+ * @param {string} skillName
+ * @param {object} options
+ */
+async function runAnalysisSkill(deps, skillName, options = {}) {
+  if (!deps || !deps.vault) throw new Error("runAnalysisSkill: deps.vault required");
+  const Cls = SKILL_REGISTRY[skillName];
+  if (!Cls) {
+    throw new Error(`unknown analysis skill: ${skillName}. Known: ${SKILL_NAMES.join(", ")}`);
+  }
+  const skill = new Cls({ vault: deps.vault, llm: deps.llm });
+  return await skill.run(options);
+}
+
+module.exports = {
+  AnalysisSkill,
+  SpendingSkill,
+  RelationsSkill,
+  FootprintSkill,
+  InterestsSkill,
+  TimelineSkill,
+  SKILL_REGISTRY,
+  SKILL_NAMES,
+  ANALYSIS_SKILL_NAMES: SKILL_NAMES,
+  SPENDING_DIMENSIONS,
+  runAnalysisSkill,
+};

package/lib/analysis-skills/interests.js

@@ -0,0 +1,161 @@
+/**
+ * Phase 11 — analysis.interests skill.
+ *
+ * Extracts the user's interest profile from:
+ *   - Topic entities (already-categorized by adapter)
+ *   - Item entities (product / content names)
+ *   - Event content.title from order/payment/visit events
+ *
+ * LLM is used to cluster + name interest categories. Without LLM,
+ * falls back to topic-frequency + most-purchased-item ranking (no
+ * generalization).
+ *
+ * Inputs:
+ *   - timeWindow:  optional; default all-time
+ *   - topN:        default 15
+ *
+ * Output:
+ *   {
+ *     topTopics: [{ name, eventCount, lastSeen }, ...],
+ *     topItems:  [{ name, occurrences, totalSpend }, ...],
+ *     llmInterests?: [{ category, evidenceCount, examples }, ...],
+ *     citations,
+ *     llm_commentary,
+ *   }
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+class InterestsSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.interests" });
+  }
+
+  async run(options = {}) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const topN = Number.isFinite(options.topN) && options.topN > 0 ? options.topN : 15;
+
+    const topTopics = this._topTopics(since, until, topN);
+    const topItems = this._topItems(since, until, topN);
+    const events = this._sampleEvents(since, until, 200);
+    const llmInterests = (options.commentary !== false && this.llm)
+      ? await this._clusterInterests(topTopics, topItems, events, options)
+      : null;
+
+    return {
+      skill: "analysis.interests",
+      topTopics,
+      topItems,
+      llmInterests,
+      citations: events.slice(0, 50).map((e) => e.id),
+      llm_commentary: null,
+    };
+  }
+
+  _topTopics(since, until, topN) {
+    // Topics are stored in their own table — eventCount is derived from
+    // the JSON `derived_from_events` array length; lastSeen is the
+    // topic's ingested_at (proxy until we add a real last_seen column).
+    let topics = [];
+    try {
+      const db = this.vault._requireOpen();
+      topics = db.prepare(
+        "SELECT id, name, derived_from_events, ingested_at FROM topics ORDER BY ingested_at DESC LIMIT ?"
+      ).all(topN * 3);
+    } catch (_e) {
+      // Older vaults may not have topics; non-fatal.
+    }
+    const mapped = topics.map((t) => {
+      let eventCount = 0;
+      try {
+        const arr = t.derived_from_events ? JSON.parse(t.derived_from_events) : [];
+        if (Array.isArray(arr)) eventCount = arr.length;
+      } catch (_e) {}
+      return {
+        id: t.id,
+        name: t.name,
+        eventCount,
+        lastSeen: t.ingested_at || null,
+      };
+    });
+    return mapped
+      .sort((a, b) => (b.eventCount - a.eventCount) || ((b.lastSeen || 0) - (a.lastSeen || 0)))
+      .slice(0, topN);
+  }
+
+  _topItems(since, until, topN) {
+    let items = [];
+    try {
+      const db = this.vault._requireOpen();
+      items = db.prepare(
+        "SELECT id, name FROM items ORDER BY ingested_at DESC LIMIT ?"
+      ).all(topN * 3);
+    } catch (_e) {}
+    // Re-bucket by name (multiple Item rows often share the same product
+    // name across adapters). Phase 8 EntityResolver doesn't dedup items
+    // yet — that's Phase 9+.
+    const buckets = new Map();
+    for (const row of items) {
+      const item = this.vault.getItem ? this.vault.getItem(row.id) : null;
+      if (!item) continue;
+      const key = item.name || "(unknown)";
+      const cur = buckets.get(key) || { name: key, occurrences: 0, totalSpend: 0 };
+      cur.occurrences += 1;
+      if (item.price && Number.isFinite(item.price.value)) cur.totalSpend += item.price.value;
+      buckets.set(key, cur);
+    }
+    return Array.from(buckets.values())
+      .sort((a, b) => b.occurrences - a.occurrences)
+      .slice(0, topN)
+      .map((b) => ({ ...b, totalSpend: Math.round(b.totalSpend * 100) / 100 }));
+  }
+
+  _sampleEvents(since, until, limit) {
+    const q = { limit };
+    if (since != null) q.since = since;
+    if (until != null) q.until = until;
+    return this.vault.queryEvents(q) || [];
+  }
+
+  async _clusterInterests(topTopics, topItems, events, options) {
+    if (topTopics.length === 0 && topItems.length === 0) return null;
+    const userMsg = `用户的互动数据样本：
+
+Topics (按出现频次):
+${topTopics.slice(0, 10).map((t) => `- ${t.name} (${t.eventCount}次)`).join("\n") || "(无)"}
+
+Items (购买/收到):
+${topItems.slice(0, 10).map((i) => `- ${i.name} (${i.occurrences}次, ¥${i.totalSpend})`).join("\n") || "(无)"}
+
+最近事件 titles (抽样):
+${events.slice(0, 20).map((e) => `- ${e.content?.title || "(无标题)"}`).join("\n")}
+
+请将以上抽 3-5 个兴趣类别（如"咖啡"、"科技阅读"、"户外旅行"），每个给出 1-2 个 evidence 引用。
+输出 JSON 数组：[{"category": "类别名", "evidenceCount": N, "examples": ["..."]}, ...]
+只输出 JSON，不要其它文字。`;
+
+    const resp = await this.callLlmCommentary([
+      { role: "system", content: "你是一个克制的兴趣画像分析助手。基于明示数据归纳类别，不臆造。" },
+      { role: "user", content: userMsg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+
+    if (!resp) return null;
+    // Parse JSON array (strict → fenced → regex)
+    try {
+      return JSON.parse(resp.trim());
+    } catch (_e) {}
+    const fence = resp.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
+    if (fence) {
+      try { return JSON.parse(fence[1].trim()); } catch (_e) {}
+    }
+    const arrMatch = resp.match(/\[\s*\{[\s\S]*?\}\s*\]/);
+    if (arrMatch) {
+      try { return JSON.parse(arrMatch[0]); } catch (_e) {}
+    }
+    return null;
+  }
+}
+
+module.exports = { InterestsSkill };

package/lib/analysis-skills/relations.js

@@ -0,0 +1,226 @@
+/**
+ * Phase 11 — analysis.relations skill.
+ *
+ * Per-Person interaction profile. Either:
+ *   - `personId`: scope to one specific Person (uses merge-group expansion
+ *     so cross-source identities count together) — returns single
+ *     person's interaction profile vs self.
+ *   - no `personId`: ranks ALL Persons by total interaction count and
+ *     returns the top-N.
+ *
+ * "Interaction" = any Event where the Person is actor or participant.
+ * Counts include payments, messages, emails — adapter-agnostic.
+ *
+ * Output:
+ *   {
+ *     mode: "single" | "ranked",
+ *     personId: ...,
+ *     profile?: {                   // single mode
+ *       personId, names,
+ *       totalInteractions, byAdapter, byMonth,
+ *       outboundCount, inboundCount, outboundShare,
+ *       totalSpend, totalIncome,
+ *       firstInteraction, lastInteraction,
+ *     },
+ *     ranked?: [...],               // ranked mode
+ *     citations,
+ *     llm_commentary,
+ *   }
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+class RelationsSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.relations" });
+  }
+
+  async run(options = {}) {
+    if (typeof options.personId === "string" && options.personId.length > 0) {
+      return await this._runSingle(options);
+    }
+    return await this._runRanked(options);
+  }
+
+  async _runSingle(options) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const members = this.expandToMergeGroup(options.personId);
+    const memberSet = new Set(members);
+
+    const events = this._fetchAllRelevant({ since, until, memberSet });
+    const profile = this._buildProfile(options.personId, members, events);
+    const citations = events.slice(0, 50).map((e) => e.id);
+
+    let llmCommentary = null;
+    if (options.commentary !== false && this.llm) {
+      llmCommentary = await this._llmCommentary(profile, options);
+    }
+
+    return {
+      skill: "analysis.relations",
+      mode: "single",
+      personId: options.personId,
+      profile,
+      citations,
+      llm_commentary: llmCommentary,
+    };
+  }
+
+  async _runRanked(options) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const topN = Number.isFinite(options.topN) && options.topN > 0 ? options.topN : 20;
+
+    // Pull all events in window then bucket by counterparty
+    const allEvents = this._fetchAllRelevant({ since, until, memberSet: null });
+    const buckets = new Map();
+    for (const e of allEvents) {
+      const ids = (e.participants || []).concat(e.actor ? [e.actor] : []);
+      for (const pid of new Set(ids)) {
+        if (pid === "person-self" || !pid) continue;
+        const cur = buckets.get(pid) || {
+          personId: pid, totalInteractions: 0, totalSpend: 0, totalIncome: 0,
+          byAdapter: {}, firstSeen: e.occurredAt, lastSeen: e.occurredAt,
+        };
+        cur.totalInteractions += 1;
+        if (e.content?.amount?.direction === "out") cur.totalSpend += e.content.amount.value;
+        if (e.content?.amount?.direction === "in") cur.totalIncome += e.content.amount.value;
+        const adapter = (e.source && e.source.adapter) || "unknown";
+        cur.byAdapter[adapter] = (cur.byAdapter[adapter] || 0) + 1;
+        if (e.occurredAt < cur.firstSeen) cur.firstSeen = e.occurredAt;
+        if (e.occurredAt > cur.lastSeen) cur.lastSeen = e.occurredAt;
+        buckets.set(pid, cur);
+      }
+    }
+    // Resolve display names per top bucket; ignore self if it sneaks in
+    const ranked = Array.from(buckets.values())
+      .sort((a, b) => b.totalInteractions - a.totalInteractions)
+      .slice(0, topN)
+      .map((b) => ({
+        ...b,
+        totalSpend: Math.round(b.totalSpend * 100) / 100,
+        totalIncome: Math.round(b.totalIncome * 100) / 100,
+        name: this._lookupName(b.personId),
+      }));
+
+    return {
+      skill: "analysis.relations",
+      mode: "ranked",
+      ranked,
+      citations: allEvents.slice(0, 50).map((e) => e.id),
+      llm_commentary: null,
+    };
+  }
+
+  _fetchAllRelevant({ since, until, memberSet }) {
+    // No subtype filter — relations cares about ALL events. Limit guards
+    // memory for big vaults.
+    const q = { limit: 10_000 };
+    if (since != null) q.since = since;
+    if (until != null) q.until = until;
+    const events = this.vault.queryEvents(q) || [];
+    if (!memberSet) return events;
+    return events.filter((e) => {
+      if (memberSet.has(e.actor)) return true;
+      if (Array.isArray(e.participants) && e.participants.some((p) => memberSet.has(p))) return true;
+      return false;
+    });
+  }
+
+  _buildProfile(personId, members, events) {
+    let outboundCount = 0;
+    let inboundCount = 0;
+    let totalSpend = 0;
+    let totalIncome = 0;
+    let firstInteraction = Infinity;
+    let lastInteraction = -Infinity;
+    const byAdapter = {};
+    const byMonth = {};
+    const memberSet = new Set(members);
+
+    for (const e of events) {
+      const t = e.occurredAt || 0;
+      if (t < firstInteraction) firstInteraction = t;
+      if (t > lastInteraction) lastInteraction = t;
+      // Outbound = self → them (actor=self, target=them); inbound = them → self
+      if (e.actor === "person-self" || memberSet.has(e.actor)) {
+        if (e.actor === "person-self") outboundCount += 1;
+        else inboundCount += 1;
+      } else {
+        // Participant-only event; counts as both? Most adapters keep
+        // actor+participants consistent so this branch is rare.
+        outboundCount += 1;
+      }
+      if (e.content?.amount) {
+        if (e.content.amount.direction === "out") totalSpend += e.content.amount.value;
+        else if (e.content.amount.direction === "in") totalIncome += e.content.amount.value;
+      }
+      const adapter = (e.source && e.source.adapter) || "unknown";
+      byAdapter[adapter] = (byAdapter[adapter] || 0) + 1;
+      const d = new Date(t);
+      if (Number.isFinite(d.getTime())) {
+        const m = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+        byMonth[m] = (byMonth[m] || 0) + 1;
+      }
+    }
+    const total = outboundCount + inboundCount;
+
+    return {
+      personId,
+      members,
+      names: this._lookupNames(members),
+      totalInteractions: total,
+      byAdapter,
+      byMonth,
+      outboundCount,
+      inboundCount,
+      outboundShare: total > 0 ? Math.round((outboundCount / total) * 100) / 100 : 0,
+      totalSpend: Math.round(totalSpend * 100) / 100,
+      totalIncome: Math.round(totalIncome * 100) / 100,
+      firstInteraction: firstInteraction === Infinity ? null : firstInteraction,
+      lastInteraction: lastInteraction === -Infinity ? null : lastInteraction,
+    };
+  }
+
+  _lookupName(personId) {
+    try {
+      const p = this.vault.getPerson ? this.vault.getPerson(personId) : null;
+      return (p && p.names && p.names[0]) || personId;
+    } catch (_e) {
+      return personId;
+    }
+  }
+
+  _lookupNames(personIds) {
+    const set = new Set();
+    for (const id of personIds) {
+      try {
+        const p = this.vault.getPerson ? this.vault.getPerson(id) : null;
+        if (p && Array.isArray(p.names)) {
+          for (const n of p.names) if (n) set.add(n);
+        }
+      } catch (_e) {}
+    }
+    return Array.from(set);
+  }
+
+  async _llmCommentary(profile, options) {
+    if (!profile.totalInteractions) return "No interactions found in this period.";
+    const userMsg = `分析与某人的关系：
+- 姓名/别名: ${profile.names.join(", ") || profile.personId}
+- 互动总数: ${profile.totalInteractions}
+- 主动占比: ${(profile.outboundShare * 100).toFixed(0)}% (${profile.outboundCount} 主动 vs ${profile.inboundCount} 收到)
+- 钱款来往: 支出 ¥${profile.totalSpend} / 收入 ¥${profile.totalIncome}
+- 跨源: ${Object.keys(profile.byAdapter).join(", ")}
+- 时间跨度: ${profile.firstInteraction ? new Date(profile.firstInteraction).toISOString().slice(0,10) : "?"} 到 ${profile.lastInteraction ? new Date(profile.lastInteraction).toISOString().slice(0,10) : "?"}
+
+请用 2-3 句话总结关系特征（亲密 / 疏远 / 单向 / 平等）。中文回答。`;
+    return await this.callLlmCommentary([
+      { role: "system", content: "你是一个克制的人际分析助手。仅基于提供的数据给出温和的描述性总结，不评价、不臆断情感。" },
+      { role: "user", content: userMsg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+  }
+}
+
+module.exports = { RelationsSkill };