@chainlesschain/personal-data-hub 0.1.0 → 0.2.0

package/lib/analysis-skills/spending.js

@@ -0,0 +1,216 @@
+/**
+ * Phase 11 — analysis.spending skill.
+ *
+ * Inputs:
+ *   - timeWindow:  { since, until } | { sinceDays N } | { sinceMonths N }
+ *   - dimension:   "merchant" | "category" | "counterparty" | "month"
+ *                  Default "merchant".
+ *   - merchantFilter:   optional substring (e.g. "美团" to scope to one
+ *                       merchant family)
+ *   - personId:         optional — scope to spending TO this person (uses
+ *                       merge-group expansion)
+ *   - topN:             default 10
+ *
+ * Output:
+ *   {
+ *     summary: {
+ *       totalSpend, totalIncome, netFlow, currency,
+ *       eventCount, uniqueCounterparties, period,
+ *     },
+ *     breakdown: [{ key, totalSpend, eventCount, percentOfTotal }, ...],
+ *     trend: [{ monthKey, totalSpend, eventCount }, ...],
+ *     citations: [eventId, ...],
+ *     llm_commentary: "..." | null,
+ *   }
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+const SUPPORTED_DIMENSIONS = new Set(["merchant", "category", "counterparty", "month"]);
+
+class SpendingSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.spending" });
+  }
+
+  async run(options = {}) {
+    const { since, until } = this.resolveTimeWindow(options);
+    const dimension = SUPPORTED_DIMENSIONS.has(options.dimension)
+      ? options.dimension
+      : "merchant";
+    const topN = Number.isFinite(options.topN) && options.topN > 0 ? options.topN : 10;
+
+    // Pull events with subtype = payment / transfer / refund / utility /
+    // redenvelope / investment / income. These are the ones with content.amount.
+    const events = this._fetchPaymentEvents({ since, until });
+    const filtered = this._applyFilters(events, options);
+
+    const summary = this._summarize(filtered, since, until);
+    const breakdown = this._breakdown(filtered, dimension, topN);
+    const trend = this._monthlyTrend(filtered);
+    const citations = filtered.slice(0, 50).map((e) => e.id);
+
+    let llmCommentary = null;
+    if (options.commentary !== false && this.llm) {
+      llmCommentary = await this._llmCommentary(summary, breakdown, dimension, options);
+    }
+
+    return {
+      skill: "analysis.spending",
+      summary,
+      breakdown,
+      trend,
+      citations,
+      llm_commentary: llmCommentary,
+    };
+  }
+
+  _fetchPaymentEvents({ since, until }) {
+    const events = [];
+    const subtypes = ["payment", "transfer", "refund", "utility", "redenvelope", "investment", "income"];
+    for (const subtype of subtypes) {
+      const q = { subtype, limit: 5000 };
+      if (since != null) q.since = since;
+      if (until != null) q.until = until;
+      const batch = this.vault.queryEvents(q) || [];
+      for (const e of batch) {
+        // queryEvents may strip extra; we already get full row from vault
+        if (e && e.content && e.content.amount && Number.isFinite(e.content.amount.value)) {
+          events.push(e);
+        }
+      }
+    }
+    return events;
+  }
+
+  _applyFilters(events, options) {
+    let out = events;
+    if (typeof options.merchantFilter === "string" && options.merchantFilter.length > 0) {
+      const needle = options.merchantFilter.toLowerCase();
+      out = out.filter((e) => {
+        const title = (e.content && e.content.title) || "";
+        const counterparty = (e.extra && e.extra.counterparty) || "";
+        return title.toLowerCase().includes(needle)
+          || counterparty.toLowerCase().includes(needle);
+      });
+    }
+    if (typeof options.personId === "string" && options.personId.length > 0) {
+      const memberSet = new Set(this.expandToMergeGroup(options.personId));
+      out = out.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;
+      });
+    }
+    if (options.direction === "out" || options.direction === "in") {
+      out = out.filter((e) => e.content.amount.direction === options.direction);
+    }
+    return out;
+  }
+
+  _summarize(events, since, until) {
+    let totalSpend = 0;
+    let totalIncome = 0;
+    const counterparties = new Set();
+    for (const e of events) {
+      const v = e.content.amount.value;
+      if (e.content.amount.direction === "in") totalIncome += v;
+      else if (e.content.amount.direction === "out") totalSpend += v;
+      // Identify counterparty for distinctness
+      const cp = (e.extra && e.extra.counterparty) || e.actor;
+      if (cp && cp !== "person-self") counterparties.add(cp);
+    }
+    return {
+      totalSpend: Math.round(totalSpend * 100) / 100,
+      totalIncome: Math.round(totalIncome * 100) / 100,
+      netFlow: Math.round((totalIncome - totalSpend) * 100) / 100,
+      currency: events[0]?.content?.amount?.currency || "CNY",
+      eventCount: events.length,
+      uniqueCounterparties: counterparties.size,
+      period: { since: since || null, until: until || null },
+    };
+  }
+
+  _breakdown(events, dimension, topN) {
+    const buckets = new Map();
+    for (const e of events) {
+      // Only count "out" for spending breakdown — income tracked separately
+      if (e.content.amount.direction !== "out") continue;
+      const key = this._keyFor(e, dimension);
+      if (!key) continue;
+      const cur = buckets.get(key) || { key, totalSpend: 0, eventCount: 0 };
+      cur.totalSpend += e.content.amount.value;
+      cur.eventCount += 1;
+      buckets.set(key, cur);
+    }
+    const totalOut = Array.from(buckets.values()).reduce((s, b) => s + b.totalSpend, 0);
+    const sorted = Array.from(buckets.values())
+      .map((b) => ({
+        ...b,
+        totalSpend: Math.round(b.totalSpend * 100) / 100,
+        percentOfTotal: totalOut > 0 ? Math.round((b.totalSpend / totalOut) * 1000) / 10 : 0,
+      }))
+      .sort((a, b) => b.totalSpend - a.totalSpend)
+      .slice(0, topN);
+    return sorted;
+  }
+
+  _monthlyTrend(events) {
+    const buckets = new Map();
+    for (const e of events) {
+      if (e.content.amount.direction !== "out") continue;
+      const d = new Date(e.occurredAt);
+      if (!Number.isFinite(d.getTime())) continue;
+      const monthKey = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+      const cur = buckets.get(monthKey) || { monthKey, totalSpend: 0, eventCount: 0 };
+      cur.totalSpend += e.content.amount.value;
+      cur.eventCount += 1;
+      buckets.set(monthKey, cur);
+    }
+    return Array.from(buckets.values())
+      .map((b) => ({ ...b, totalSpend: Math.round(b.totalSpend * 100) / 100 }))
+      .sort((a, b) => a.monthKey.localeCompare(b.monthKey));
+  }
+
+  _keyFor(event, dimension) {
+    if (dimension === "merchant" || dimension === "counterparty") {
+      return (event.extra && event.extra.counterparty)
+        || (event.content && event.content.title)
+        || "(unknown)";
+    }
+    if (dimension === "category") {
+      return (event.extra && event.extra.category)
+        || event.subtype
+        || "(uncategorized)";
+    }
+    if (dimension === "month") {
+      const d = new Date(event.occurredAt);
+      if (!Number.isFinite(d.getTime())) return "(unknown date)";
+      return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}`;
+    }
+    return null;
+  }
+
+  async _llmCommentary(summary, breakdown, dimension, options) {
+    if (summary.eventCount === 0) return "No spending events found in this period.";
+    const topItems = breakdown.slice(0, 5).map((b) => `${b.key} ¥${b.totalSpend} (${b.percentOfTotal}%)`).join(", ");
+    const periodStr = summary.period.since
+      ? `${new Date(summary.period.since).toISOString().slice(0, 10)} 至 ${new Date(summary.period.until).toISOString().slice(0, 10)}`
+      : "全部时间";
+    const userMsg = `用户的消费数据：
+- 期间：${periodStr}
+- 总支出 ¥${summary.totalSpend} (${summary.currency}), 总收入 ¥${summary.totalIncome}, 净流 ¥${summary.netFlow}
+- 共 ${summary.eventCount} 笔交易, ${summary.uniqueCounterparties} 个独特对方
+- 按 ${dimension} 排名 top 5：${topItems}
+
+请用 2-3 句话点评消费习惯，指出最大支出方向和异常（如有）。中文回答。`;
+    return await this.callLlmCommentary([
+      { role: "system", content: "你是一个理性、克制的财务分析助手。基于事实给出简短结论，不夸张、不臆断。" },
+      { role: "user", content: userMsg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+  }
+}
+
+module.exports = { SpendingSkill, SUPPORTED_DIMENSIONS };

package/lib/analysis-skills/timeline.js

@@ -0,0 +1,167 @@
+/**
+ * Phase 11 — analysis.timeline skill.
+ *
+ * Cross-source narrative timeline. Given a time window + optional topic
+ * keyword, weaves Events from all adapters into a chronological story
+ * with adapter-aware glyphs (so "邮件" / "支付" / "出行" are
+ * visually distinguishable in the UI).
+ *
+ * LLM (optional) produces a 1-paragraph synthesis: "你这周买过 X 也去过
+ * Y, 给妈妈转账过 Z" rather than just a list.
+ *
+ * Inputs:
+ *   - timeWindow:   required (default last 7 days)
+ *   - topicFilter:  optional substring match against title / counterparty
+ *   - personId:     optional — scope to events involving this person
+ *                   (merge-group expanded)
+ *   - limit:        default 100 events
+ *
+ * Output:
+ *   {
+ *     entries: [{ id, occurredAt, title, kind, amount?, adapter, snippet }],
+ *     summary: { totalEvents, byAdapter, byDay, period },
+ *     citations,
+ *     llm_narrative: "..." | null,
+ *   }
+ */
+
+"use strict";
+
+const { AnalysisSkill } = require("./base");
+
+class TimelineSkill extends AnalysisSkill {
+  constructor(opts) {
+    super({ ...opts, name: "analysis.timeline" });
+  }
+
+  async run(options = {}) {
+    const window = this.resolveTimeWindow({
+      sinceDays: options.sinceDays ?? (options.since ? null : 7), // default 7d
+      ...options,
+    });
+    const limit = Number.isFinite(options.limit) && options.limit > 0
+      ? Math.min(options.limit, 1000)
+      : 100;
+
+    let events = this._fetchEvents(window, limit);
+    events = this._applyFilters(events, options);
+    const entries = events.map((e) => this._toEntry(e));
+    const summary = this._summarize(entries, window);
+
+    let narrative = null;
+    if (options.narrative !== false && this.llm && entries.length > 0) {
+      narrative = await this._llmNarrative(entries, summary, options);
+    }
+
+    return {
+      skill: "analysis.timeline",
+      entries,
+      summary,
+      citations: entries.slice(0, 50).map((e) => e.id),
+      llm_narrative: narrative,
+    };
+  }
+
+  _fetchEvents({ since, until }, limit) {
+    const q = { limit };
+    if (since != null) q.since = since;
+    if (until != null) q.until = until;
+    const events = this.vault.queryEvents(q) || [];
+    // queryEvents orders DESC; reverse for narrative (oldest first)
+    return events.slice().sort((a, b) => (a.occurredAt || 0) - (b.occurredAt || 0));
+  }
+
+  _applyFilters(events, options) {
+    let out = events;
+    if (typeof options.topicFilter === "string" && options.topicFilter.length > 0) {
+      const needle = options.topicFilter.toLowerCase();
+      out = out.filter((e) => {
+        const title = (e.content && e.content.title) || "";
+        const counterparty = (e.extra && e.extra.counterparty) || "";
+        const text = (e.content && e.content.text) || "";
+        return title.toLowerCase().includes(needle)
+          || counterparty.toLowerCase().includes(needle)
+          || text.toLowerCase().includes(needle);
+      });
+    }
+    if (typeof options.personId === "string" && options.personId.length > 0) {
+      const memberSet = new Set(this.expandToMergeGroup(options.personId));
+      out = out.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;
+      });
+    }
+    return out;
+  }
+
+  _toEntry(event) {
+    const adapter = (event.source && event.source.adapter) || "unknown";
+    return {
+      id: event.id,
+      occurredAt: event.occurredAt,
+      title: (event.content && event.content.title) || "(无标题)",
+      kind: event.subtype || "event",
+      amount: event.content?.amount || null,
+      adapter,
+      snippet: this._buildSnippet(event),
+    };
+  }
+
+  _buildSnippet(event) {
+    const parts = [];
+    const text = (event.content && event.content.text) || "";
+    if (text) parts.push(text.slice(0, 100));
+    if (event.extra) {
+      if (event.extra.counterparty) parts.push(`@${event.extra.counterparty}`);
+      if (event.extra.from && event.extra.to) parts.push(`${event.extra.from} → ${event.extra.to}`);
+    }
+    return parts.join(" · ").slice(0, 200);
+  }
+
+  _summarize(entries, window) {
+    const byAdapter = {};
+    const byDay = {};
+    for (const e of entries) {
+      byAdapter[e.adapter] = (byAdapter[e.adapter] || 0) + 1;
+      const d = new Date(e.occurredAt);
+      if (Number.isFinite(d.getTime())) {
+        const day = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+        byDay[day] = (byDay[day] || 0) + 1;
+      }
+    }
+    return {
+      totalEvents: entries.length,
+      byAdapter,
+      byDay,
+      period: {
+        since: window.since || null,
+        until: window.until || null,
+      },
+    };
+  }
+
+  async _llmNarrative(entries, summary, options) {
+    if (entries.length === 0) return null;
+    // Cap to 30 entries for prompt size
+    const sampled = entries.slice(-30);
+    const lines = sampled.map((e) => {
+      const d = new Date(e.occurredAt).toISOString().slice(0, 10);
+      const amt = e.amount ? ` ¥${e.amount.value}(${e.amount.direction})` : "";
+      return `- ${d} [${e.adapter}/${e.kind}] ${e.title}${amt}`;
+    }).join("\n");
+
+    const userMsg = `用户的事件时间线（共 ${summary.totalEvents} 条, 显示最近 ${sampled.length}）:
+
+${lines}
+
+请用 3-5 句话讲清楚这段时间发生了什么、出现的人物 / 地点、有没有明显的主题或事件。中文回答，平实叙述，不评价。`;
+
+    return await this.callLlmCommentary([
+      { role: "system", content: "你是一个克制的时间线叙述助手。基于事实串联事件，不引申、不评价。" },
+      { role: "user", content: userMsg },
+    ], { acceptNonLocal: options.acceptNonLocal });
+  }
+}
+
+module.exports = { TimelineSkill };

package/lib/entity-resolver/embedding-stage.js

@@ -0,0 +1,198 @@
+/**
+ * Phase 8.3 — embedding stage.
+ *
+ * Pluggable function that takes two Person rows + returns
+ * `{ sim, profileA, profileB }` where `sim` is a cosine similarity in
+ * [0, 1]. Caller (EntityResolver.drain) uses thresholds to decide
+ * auto-same / auto-different / "send to LLM stage".
+ *
+ * Profile encoding (per design doc §4.2):
+ *   "{type}: {primary_name} | aliases: {a1, a2} | identifiers: {phone,
+ *    email} | recent: {top-3 event titles}"
+ *
+ * Embedding backend: Ollama HTTP API by default (compatible with
+ * `nomic-embed-text` / `bge-m3` / `bge-large-zh`). Caller can inject any
+ * `embedFn: async (text) => Float32Array | number[]` via opts.
+ *
+ * Privacy: same gate as AnalysisEngine — local Ollama default, accept-
+ * NonLocal flag required for hosted. Phase 8.4 LLM stage carries the
+ * same invariant; this module is dumb to that and trusts caller.
+ */
+
+"use strict";
+
+const DEFAULT_OLLAMA_URL = "http://localhost:11434";
+const DEFAULT_MODEL = "nomic-embed-text";
+
+class EmbeddingStage {
+  constructor(opts = {}) {
+    if (!opts || typeof opts !== "object") {
+      throw new Error("EmbeddingStage: opts required");
+    }
+    this._embedFn = typeof opts.embedFn === "function" ? opts.embedFn : null;
+    this._ollamaUrl = typeof opts.ollamaUrl === "string" && opts.ollamaUrl.length > 0
+      ? opts.ollamaUrl
+      : DEFAULT_OLLAMA_URL;
+    this._model = typeof opts.model === "string" && opts.model.length > 0
+      ? opts.model
+      : DEFAULT_MODEL;
+    // Caller-supplied vault lets us pull recent events for richer profiles
+    // (per design doc §4.2 — "recent: top-3 event titles"). Optional.
+    this._vault = opts.vault || null;
+    // LRU-ish in-memory cache: personId → embedding. Cheap perf win for
+    // re-using the same person across many pair comparisons in one drain.
+    this._cache = new Map();
+    this._cacheMaxSize = Number.isFinite(opts.cacheMaxSize) ? opts.cacheMaxSize : 1000;
+  }
+
+  /**
+   * The function EntityResolver.drain expects.
+   * Signature: `async (a, b) => { sim, profileA, profileB }`
+   */
+  async compare(a, b) {
+    const [vecA, profileA] = await this._embedPerson(a);
+    const [vecB, profileB] = await this._embedPerson(b);
+    const sim = cosineSimilarity(vecA, vecB);
+    return { sim, profileA, profileB };
+  }
+
+  /**
+   * Returns a stage function bound to this instance, suitable for passing
+   * as `opts.embeddingStage` to EntityResolver.
+   */
+  asStageFn() {
+    return (a, b) => this.compare(a, b);
+  }
+
+  async _embedPerson(person) {
+    if (!person || !person.id) throw new Error("EmbeddingStage: person required");
+    const profile = this.buildProfile(person);
+    if (this._cache.has(person.id)) {
+      return [this._cache.get(person.id), profile];
+    }
+    const vec = await this._embed(profile);
+    if (!Array.isArray(vec) && !(vec instanceof Float32Array)) {
+      throw new Error("EmbeddingStage: embedFn must return Array<number> or Float32Array");
+    }
+    if (this._cache.size >= this._cacheMaxSize) {
+      // FIFO eviction
+      const first = this._cache.keys().next().value;
+      if (first !== undefined) this._cache.delete(first);
+    }
+    this._cache.set(person.id, vec);
+    return [vec, profile];
+  }
+
+  /**
+   * Build the textual profile that gets embedded. Public for tests +
+   * for callers that want to feed the same string to LLM stage.
+   */
+  buildProfile(person) {
+    const parts = [];
+    parts.push(`${person.type || "person"}: ${(person.names && person.names[0]) || "(unknown)"}`);
+    if (person.names && person.names.length > 1) {
+      parts.push(`aliases: ${person.names.slice(1).join(", ")}`);
+    }
+    const ids = person.identifiers || {};
+    const idStrs = [];
+    for (const key of Object.keys(ids)) {
+      const v = ids[key];
+      if (Array.isArray(v)) {
+        for (const x of v) idStrs.push(`${key}:${x}`);
+      } else if (typeof v === "string") {
+        idStrs.push(`${key}:${v}`);
+      }
+    }
+    if (idStrs.length > 0) {
+      parts.push(`identifiers: ${idStrs.join(", ")}`);
+    }
+    if (this._vault) {
+      try {
+        const recent = this._recentEvents(person.id, 3);
+        if (recent.length > 0) {
+          parts.push(`recent: ${recent.map((e) => e.content?.title || "(no title)").join("; ")}`);
+        }
+      } catch (_e) {
+        // Vault read failure is non-fatal — embedding still works without events
+      }
+    }
+    return parts.join(" | ");
+  }
+
+  _recentEvents(personId, limit) {
+    if (!this._vault || typeof this._vault.queryEvents !== "function") return [];
+    // Pull events where this person is actor or participant
+    const events = this._vault.queryEvents({ actor: personId, limit });
+    return Array.isArray(events) ? events : [];
+  }
+
+  async _embed(text) {
+    if (this._embedFn) return this._embedFn(text);
+    // Default backend: Ollama HTTP API
+    return await ollamaEmbed(this._ollamaUrl, this._model, text);
+  }
+
+  /** Clear the embedding cache (e.g. after batch). */
+  clearCache() {
+    this._cache.clear();
+  }
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Cosine similarity ∈ [-1, 1], clamped to [0, 1] for embeddings (they
+ * tend to live in non-negative space but we don't trust that).
+ */
+function cosineSimilarity(a, b) {
+  if (!a || !b) return 0;
+  const len = Math.min(a.length, b.length);
+  if (len === 0) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < len; i += 1) {
+    const x = Number(a[i]) || 0;
+    const y = Number(b[i]) || 0;
+    dot += x * y;
+    normA += x * x;
+    normB += y * y;
+  }
+  if (normA === 0 || normB === 0) return 0;
+  const sim = dot / (Math.sqrt(normA) * Math.sqrt(normB));
+  // Clamp to [0, 1] for the threshold-comparison call site
+  return Math.max(0, Math.min(1, sim));
+}
+
+/**
+ * Call Ollama's /api/embeddings endpoint. Throws on failure; caller
+ * (EntityResolver.drain → errorResolve) handles retry-vs-fatal.
+ */
+async function ollamaEmbed(baseUrl, model, text) {
+  const url = `${baseUrl.replace(/\/$/, "")}/api/embeddings`;
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model, prompt: text }),
+    });
+  } catch (err) {
+    throw new Error(`Ollama embed call failed (${url}): ${err && err.message ? err.message : err}`);
+  }
+  if (!resp.ok) {
+    const body = await resp.text().catch(() => "");
+    throw new Error(`Ollama embed returned ${resp.status}: ${body.slice(0, 200)}`);
+  }
+  const data = await resp.json();
+  if (!data || !Array.isArray(data.embedding)) {
+    throw new Error(`Ollama embed response missing 'embedding' array`);
+  }
+  return data.embedding;
+}
+
+module.exports = {
+  EmbeddingStage,
+  cosineSimilarity,
+  ollamaEmbed,
+};