@odla-ai/kg 0.2.3 → 0.3.0

package/dist/temporal/index.d.ts

@@ -0,0 +1,553 @@
+import { h as GraphNode, G as GraphFragment, a as SourceEntry } from '../sources-nJyD0JUP.js';
+import { Value } from '@odla-ai/db';
+import '@odla-ai/ai';
+
+/**
+ * FNV-1a 32-bit hash of a string. Used to derive a per-identity PRNG seed
+ * (`mulberry32(hash32(id) ^ seed)`), which makes node placement independent
+ * of the order nodes arrive in.
+ */
+declare function hash32(s: string): number;
+/**
+ * mulberry32: a tiny, fast, seedable PRNG returning floats in [0, 1).
+ * The same seed always yields the same sequence — replayable layouts and
+ * community assignments depend on this.
+ */
+declare function mulberry32(seed: number): () => number;
+/**
+ * Fisher–Yates shuffle into a NEW array, driven by the supplied random source
+ * (pass a seeded `mulberry32` for a deterministic permutation).
+ */
+declare function shuffle<T>(items: readonly T[], rand: () => number): T[];
+
+/** Supported bucketing granularities. */
+type TimeGrain = "week" | "month" | "quarter";
+/** One half-open time bucket: `start` inclusive, `end` exclusive (epoch ms). */
+interface TimeBucket {
+    key: string;
+    start: number;
+    end: number;
+}
+/**
+ * Parse a date-ish value to epoch ms, or null if unparseable. Accepts
+ * `"YYYY-MM-DD"` (UTC midnight, with real calendar validation — `2026-02-31`
+ * is null), full ISO strings, and finite numbers (already epoch ms).
+ */
+declare function parseDateMs(v: unknown): number | null;
+/** The bucket key containing epoch-ms `t`: `"2026-07"`, `"2026-Q3"`, or `"2026-W29"`. */
+declare function bucketKey(t: number, grain: TimeGrain): string;
+/**
+ * Expand a bucket key back to its half-open [start, end) range. Throws on a
+ * key that matches no known grain format.
+ */
+declare function bucketFor(key: string): TimeBucket;
+/**
+ * Every bucket from the one containing `from` through the one containing `to`,
+ * in order. Returns [] when from > to.
+ */
+declare function bucketRange(from: number, to: number, grain: TimeGrain): TimeBucket[];
+
+/** A node reference: the `{type, key}` pair used by fragment edges. */
+interface NodeRef {
+    type: string;
+    key: string;
+}
+/** Canonical string id for a node reference: `"type:key"`. */
+type NodeId = string;
+/** Make the canonical `"type:key"` id for a node reference. */
+declare function nodeId(ref: NodeRef): NodeId;
+/** Compare two refs by canonical id (stable orderings everywhere). */
+declare function byNodeId(a: NodeRef, b: NodeRef): number;
+/** Indexed view of one GraphFragment. */
+interface GraphIndex {
+    /** The node for an id, if present in the fragment. */
+    node(id: NodeId): GraphNode | undefined;
+    /** Forward-label adjacency: targets of `label` edges out of `id`. */
+    out(id: NodeId, label: string): NodeRef[];
+    /** Every node of one entity type. */
+    nodesOf(type: string): GraphNode[];
+}
+/** Build the index (one pass over nodes + edges). */
+declare function indexGraph(fragment: GraphFragment): GraphIndex;
+/**
+ * Walk a sequence of forward edge labels from `start`, breadth-first, and
+ * return the deduplicated frontier after the last hop, sorted by id.
+ * An empty label list returns just `start`.
+ */
+declare function resolvePath(g: GraphIndex, start: NodeRef, labels: readonly string[]): NodeRef[];
+
+/**
+ * Where an event's geography lives: walk `path` (forward edge labels) from the
+ * event node, then read `attr` off the landing node — or, with no `attr`, use
+ * the landing node's key (e.g. a `region` entity slug). With no `path`, the
+ * event node itself is the landing node.
+ */
+interface GeoSpec {
+    path?: readonly string[];
+    attr?: string;
+}
+/** How to turn one entity type into temporal events. */
+interface EventSpec {
+    /** Event entity type, e.g. `"funding_round"` or `"signal"`. */
+    type: string;
+    /** Attr holding the event date (parsed with `parseDateMs`; undated nodes are skipped). */
+    dateAttr: string;
+    /** Attr holding a magnitude, parsed with `parseAmount`; unparseable → weight 1. */
+    weightAttr?: string;
+    /** Override hook for weights the attr grammar can't express. */
+    weightOf?: (attrs: Record<string, Value>) => number | undefined;
+    /** Edge-label paths from the event node to its participant entities. */
+    attach?: readonly (readonly string[])[];
+    /** Geography of the event (choropleth/hotspot keying). */
+    geo?: GeoSpec;
+    /** Destination geography — only for flow-shaped events (money moving A→B). */
+    geoTo?: GeoSpec;
+}
+/** The extraction contract: one spec per event entity type. */
+interface TemporalConfig {
+    events: EventSpec[];
+}
+/** One timestamped event extracted from the graph. */
+interface TemporalEvent {
+    /** Epoch ms (UTC). */
+    t: number;
+    /** The spec's entity type. */
+    kind: string;
+    /** The event node itself. */
+    node: NodeRef;
+    /** Attached participant entities, deduped, sorted by id. */
+    refs: NodeRef[];
+    /** Magnitude (defaults to 1). */
+    weight: number;
+    /** Source geography key, when resolvable. */
+    geo?: string;
+    /** Destination geography key, when resolvable (flow events). */
+    geoTo?: string;
+}
+/**
+ * Parse a human money/quantity string to a number: `"$12.5M"` → 12500000,
+ * `"12,500,000"` → 12500000, `"500k"` → 500000, numbers pass through.
+ * Returns undefined for anything else (never NaN).
+ */
+declare function parseAmount(v: unknown): number | undefined;
+/**
+ * Extract the event stream: for every spec, every node of that type with a
+ * parseable date becomes one event. Sorted by time, tie-broken by node id —
+ * the ordering is total and reproducible.
+ */
+declare function extractEvents(fragment: GraphFragment, config: TemporalConfig): TemporalEvent[];
+
+/** One named series, index-aligned with its SeriesSet's buckets. */
+interface Series {
+    key: string;
+    values: number[];
+}
+/** A grain, its buckets, and every series over them (sorted by key). */
+interface SeriesSet {
+    grain: TimeGrain;
+    buckets: TimeBucket[];
+    series: Series[];
+}
+/**
+ * How to key events into series: `"kind"` (event type), `"geo"` (source
+ * geography; geo-less events are dropped), `"ref"` (fan one event into one
+ * increment per attached participant, keyed by node id), or a custom function
+ * returning zero or more keys per event.
+ */
+type SeriesKeyer = "kind" | "geo" | "ref" | ((e: TemporalEvent) => string | readonly string[] | undefined);
+/** The series keys one event contributes to under a keyer (used by rollup and by hotspot contributor attachment). */
+declare function seriesKeys(e: TemporalEvent, by: SeriesKeyer): readonly string[];
+/**
+ * Roll events up into bucketed series. The bucket range spans `from`..`to`
+ * when given (zero-padded even where nothing happened — burst baselines need
+ * the quiet buckets), else the events' own time span. Events outside the
+ * range are ignored.
+ */
+declare function rollup(events: readonly TemporalEvent[], opts: {
+    grain: TimeGrain;
+    by?: SeriesKeyer;
+    measure?: "count" | "weight";
+    from?: number;
+    to?: number;
+}): SeriesSet;
+/** Per-bucket sum across every series in the set (the "all" line). */
+declare function totals(set: SeriesSet): Series;
+
+/** Tuning for {@link burstScores}/{@link detectBursts}. */
+interface BurstOptions {
+    /** Trailing buckets forming the baseline (excluding the scored bucket). Default 6. */
+    window?: number;
+    /** z needed to OPEN a burst run. Default 2. */
+    zEnter?: number;
+    /** z needed to EXTEND an open run (hysteresis). Default 1. */
+    zExit?: number;
+    /** Minimum trailing buckets before scoring (cold start → z 0). Default 3. */
+    minBaseline?: number;
+    /**
+     * Floor on the baseline sigma. sqrt(mean) is always applied (Poisson-
+     * consistent for counts); this guards the all-zero baseline. Default 1.
+     */
+    minSigma?: number;
+}
+/**
+ * Per-bucket burst z-scores for one series: (value − trailing mean) /
+ * max(trailing stdev, sqrt(mean), minSigma). Cold-start buckets score 0.
+ */
+declare function burstScores(values: readonly number[], opts?: BurstOptions): number[];
+/** One detected burst: a maximal hysteresis run within one series. */
+interface Burst {
+    seriesKey: string;
+    /** Bucket indexes, inclusive. */
+    start: number;
+    end: number;
+    /** Highest z in the run. */
+    peak: number;
+    /** Σ max(0, z) over the run — rewards both height and duration. */
+    score: number;
+}
+/**
+ * All bursts across a SeriesSet, ranked score desc (ties: earlier start,
+ * then series key). A run opens at z ≥ zEnter and extends while z ≥ zExit.
+ */
+declare function detectBursts(set: SeriesSet, opts?: BurstOptions): Burst[];
+/** A burst plus its bucket keys and top contributing events — a ranked lead. */
+interface Hotspot extends Burst {
+    bucketKeys: string[];
+    contributors: TemporalEvent[];
+}
+/**
+ * Detect, rank, and enrich bursts into explorable leads. `by` must be the
+ * same keyer the SeriesSet was rolled up with — it re-derives each event's
+ * series keys to attach contributors (top per-lead by weight, then time).
+ */
+declare function rankHotspots(set: SeriesSet, events: readonly TemporalEvent[], opts?: BurstOptions & {
+    by?: SeriesKeyer;
+    top?: number;
+    contributorsPer?: number;
+}): Hotspot[];
+
+/** One dated undirected edge (canonical order: a < b). */
+interface TimelineEdge {
+    a: NodeId;
+    b: NodeId;
+    t: number;
+    kind: string;
+    weight: number;
+}
+/** The replayable structure built once from the event stream. */
+interface Timeline {
+    events: TemporalEvent[];
+    /** Every node ever seen, sorted by id. */
+    nodes: NodeId[];
+    /** Dated edges, time-ordered. */
+    edges: TimelineEdge[];
+    /** Node id → first time it appeared. */
+    firstSeen: Map<NodeId, number>;
+}
+/**
+ * Build the timeline. `"entities"` (default) projects each event onto its
+ * participants — every ref pair co-occurring in one event becomes an edge
+ * (companies↔investors↔people), and event nodes vanish. `"full"` keeps the
+ * event node and links it to each ref (bipartite).
+ */
+declare function buildTimeline(events: readonly TemporalEvent[], opts?: {
+    mode?: "entities" | "full";
+}): Timeline;
+/** The graph as it stood at time `t`. */
+interface Snapshot {
+    t: number;
+    /** Nodes first seen at or before t, sorted. */
+    nodes: NodeId[];
+    /** Aggregated undirected edges (weight = co-occurrence count). */
+    edges: Array<{
+        a: NodeId;
+        b: NodeId;
+        weight: number;
+    }>;
+    /** Node id → its latest event time ≤ t (drives recency glow). */
+    activity: Map<NodeId, number>;
+}
+/**
+ * Materialize the graph at `t`: cumulative by default, or only edges within
+ * the trailing `window` ms when given (rolling co-activity).
+ */
+declare function snapshotAt(timeline: Timeline, t: number, opts?: {
+    window?: number;
+}): Snapshot;
+/** One snapshot per bucket, each taken at the bucket's inclusive end. */
+declare function snapshotSeries(timeline: Timeline, buckets: readonly TimeBucket[], opts?: {
+    window?: number;
+}): Snapshot[];
+
+/**
+ * Asynchronous label propagation with deterministic (seeded) tie-breaking:
+ * - labels start as each node's own id;
+ * - each round visits nodes in a seeded-shuffled order (one PRNG stream
+ *   reused across rounds) and adopts the label with the greatest total
+ *   incident edge weight; if the node's CURRENT label ties for the max it is
+ *   kept, otherwise a tied max is picked via the same seeded stream (a
+ *   lexicographic tie-break would systematically bleed communities toward
+ *   alphabetically small ids — verified on the two-triangles fixture);
+ * - stops on a round with no change, or after `maxRounds`;
+ * - finally each community's label is canonicalized to its smallest member
+ *   id, so the output is independent of propagation history.
+ * Isolated nodes keep their own label (singleton communities).
+ */
+declare function labelPropagation(nodes: readonly NodeId[], edges: ReadonlyArray<{
+    a: NodeId;
+    b: NodeId;
+    weight?: number;
+}>, opts?: {
+    seed?: number;
+    maxRounds?: number;
+}): Map<NodeId, string>;
+
+/** One cluster in one frame (members sorted). */
+interface Cluster {
+    id: string;
+    members: NodeId[];
+}
+/** All clusters at one instant, id-sorted. */
+interface ClusterFrame {
+    t: number;
+    clusters: Cluster[];
+}
+/** A structural change between consecutive frames. */
+type ClusterChange = {
+    kind: "birth";
+    t: number;
+    id: string;
+} | {
+    kind: "death";
+    t: number;
+    id: string;
+} | {
+    kind: "merge";
+    t: number;
+    into: string;
+    from: string[];
+} | {
+    kind: "split";
+    t: number;
+    from: string;
+    into: string[];
+};
+/**
+ * Thread stable cluster ids through per-frame label maps. A current cluster
+ * inherits the id of its best-Jaccard predecessor at ≥ minJaccard (ties:
+ * more shared members, then smaller id); when several current clusters claim
+ * one predecessor the best keeps the id and the rest record a split; a
+ * current cluster absorbing ≥2 predecessors records a merge. Unmatched
+ * current clusters are births (id = "c:" + smallest member); vanished ids
+ * are deaths.
+ */
+declare function trackClusters(frames: ReadonlyArray<{
+    t: number;
+    labels: Map<NodeId, string>;
+}>, opts?: {
+    minJaccard?: number;
+}): {
+    frames: ClusterFrame[];
+    changes: ClusterChange[];
+};
+
+/** A unit-square position (scale to pixels at draw time). */
+interface XY {
+    x: number;
+    y: number;
+}
+/** Tuning for {@link forceLayout}. */
+interface LayoutOptions {
+    /** Force iterations. Default 300 (cold); use fewer for warm refinement. */
+    iterations?: number;
+    /** Seed mixed into every node's hash-derived initial position. Default 1. */
+    seed?: number;
+    /**
+     * Repulsion multiplier. Default 0.1 — measured on a real ~800-node OSINT
+     * graph as the point where nothing pins to the clamped boundary.
+     */
+    repulsion?: number;
+    /** Pull toward the center, proportional to distance. Default 0.5. */
+    gravity?: number;
+    /** Warm-start positions (nodes present here start where they were). */
+    positions?: ReadonlyMap<NodeId, XY>;
+}
+/**
+ * Lay out one graph. Init priority per node: warm `positions` entry →
+ * hash-disc from (id, seed). Forces per iteration (accumulated over
+ * sorted-id order, applied synchronously): pairwise repulsion k²/d, edge
+ * attraction d²/k scaled by min(weight, 4), center gravity. Linear cooling
+ * caps displacement; results clamp to [0,1]².
+ */
+declare function forceLayout(nodes: readonly NodeId[], edges: ReadonlyArray<{
+    a: NodeId;
+    b: NodeId;
+    weight?: number;
+}>, opts?: LayoutOptions): Map<NodeId, XY>;
+/**
+ * Lay out a snapshot sequence: frame 0 runs cold (`iterations`), each later
+ * frame warm-starts from the previous frame's positions and refines for
+ * `warmIterations` — existing nodes drift instead of re-scrambling, so
+ * inter-frame motion means something.
+ */
+declare function layoutSequence(snapshots: readonly Snapshot[], opts?: LayoutOptions & {
+    warmIterations?: number;
+}): Map<NodeId, XY>[];
+
+/** Tuning for {@link buildTemporalReport}. */
+interface ReportOptions {
+    /** Analysis anchor (epoch ms). Default: the latest event time. Inject for determinism. */
+    now?: number;
+    /** Weekly cluster/lead window. Default 155 days (~22 frames). */
+    windowDays?: number;
+    /** Monthly density-series span. Default 12 months. */
+    monthlyMonths?: number;
+    /** Ranked leads kept. Default 8. */
+    topLeads?: number;
+    /** Contributing events per lead. Default 3. */
+    contributorsPer?: number;
+    /** Trailing weeks of cluster changes kept. Default 4. */
+    changeWeeks?: number;
+    /** Burst detector tuning. Default `{ window: 6 }`. */
+    burst?: BurstOptions;
+}
+/** One ranked hotspot lead: a bursting entity plus its evidence. */
+interface ReportLead {
+    key: string;
+    type: string;
+    name: string;
+    city?: string;
+    sector?: string;
+    score: number;
+    peak: number;
+    window: string[];
+    contributors: Array<{
+        kind: string;
+        key: string;
+        title: string;
+        date: string;
+    }>;
+}
+/** One cluster-evolution change, name-resolved for display. */
+interface ReportClusterChange {
+    week: string;
+    kind: "birth" | "death" | "merge" | "split";
+    ids: string[];
+    names: string[];
+}
+/** The cached/served analysis product — everything JSON-native and bounded (≲20KB). */
+interface TemporalReport {
+    generatedAt: string;
+    window: {
+        from: string;
+        to: string;
+        weeks: string[];
+    };
+    totals: {
+        events: number;
+        nodes: number;
+        edges: number;
+    };
+    series: Array<{
+        kind: string;
+        months: string[];
+        values: number[];
+    }>;
+    leads: ReportLead[];
+    clusters: {
+        frames: Array<{
+            week: string;
+            count: number;
+            top: Array<{
+                id: string;
+                size: number;
+                label: string;
+            }>;
+        }>;
+        changes: ReportClusterChange[];
+    };
+}
+/** Build the full temporal report for a graph fragment. Empty input → zeroed report. */
+declare function buildTemporalReport(fragment: GraphFragment, config: TemporalConfig, opts?: ReportOptions): TemporalReport;
+
+/** True when the report has anything worth narrating (any lead or recent cluster change). */
+declare function shouldNarrate(report: TemporalReport): boolean;
+/**
+ * The deterministic materials block handed to the narrative LLM call:
+ * window/totals header, top leads with evidence, cluster changes, and
+ * per-kind monthly density lines. No prose, no interpretation.
+ */
+declare function buildNarrationMaterials(report: TemporalReport, opts?: {
+    topLeads?: number;
+}): string;
+/** First-line `# title` heuristic shared with the digest workflow. */
+declare function splitTitleBody(text: string, fallbackTitle: string): {
+    title: string;
+    body: string;
+};
+
+/**
+ * Burst score per natural key for one entity type, from a report's leads:
+ * `{ leads: [{key: "company:acme", score: 7.3}] }` → `{ acme: 7.3 }`.
+ */
+declare function leadScores(report: Pick<TemporalReport, "leads">, type?: string): Record<string, number>;
+/** One selected enrichment target. */
+interface EnrichmentCandidate {
+    slug: string;
+    name: string;
+    score: number;
+}
+/**
+ * Rank enrichment candidates: burst score descending, ties keep the input
+ * (creation) order. Cooling rows are skipped at selection. Complete rows are
+ * skipped UNLESS they carry a burst score — a bursting complete company
+ * deserves a re-check. With no scores this reproduces the legacy behavior
+ * exactly (input order, incomplete rows only).
+ */
+declare function rankEnrichmentCandidates(rows: ReadonlyArray<Record<string, unknown>>, opts: {
+    limit: number;
+    scores?: Record<string, number>;
+    cooling?: ReadonlySet<string>;
+    isComplete?: (row: Record<string, unknown>) => boolean;
+}): EnrichmentCandidate[];
+/**
+ * Replace the synthesized burst-sweep source with a fresh one derived from
+ * the report's top company leads (or remove it when there are none).
+ * Hand-authored entries — anything without `origin: "burst"` — are returned
+ * untouched, in order. Queries follow
+ * `"<name>" <city|sector|startup> funding OR expansion OR hiring news`.
+ */
+declare function synthesizeBurstSources(existing: readonly SourceEntry[], report: Pick<TemporalReport, "leads">, opts?: {
+    max?: number;
+    cadenceHours?: number;
+}): SourceEntry[];
+
+/** One aggregated movement between two geography keys within a bucket. */
+interface Flow {
+    from: string;
+    to: string;
+    /** Summed event weights (e.g. dollars). */
+    weight: number;
+    /** Number of contributing events. */
+    count: number;
+}
+/** All flows for one time bucket, sorted weight-desc then from/to. */
+interface FlowFrame {
+    bucket: TimeBucket;
+    flows: Flow[];
+}
+/**
+ * Aggregate flow events into per-bucket frames over `from`..`to` (default:
+ * the events' span). With `cumulative`, each frame includes everything up to
+ * and including its bucket — replay-style accumulation.
+ */
+declare function flowFrames(events: readonly TemporalEvent[], opts: {
+    grain: TimeGrain;
+    from?: number;
+    to?: number;
+    cumulative?: boolean;
+}): FlowFrame[];
+/** The frame's top-n flows by weight (already the frame's sort order). */
+declare function topFlows(frame: FlowFrame, n: number): Flow[];
+
+export { type Burst, type BurstOptions, type Cluster, type ClusterChange, type ClusterFrame, type EnrichmentCandidate, type EventSpec, type Flow, type FlowFrame, type GeoSpec, type GraphIndex, type Hotspot, type LayoutOptions, type NodeId, type NodeRef, type ReportClusterChange, type ReportLead, type ReportOptions, type Series, type SeriesKeyer, type SeriesSet, type Snapshot, type TemporalConfig, type TemporalEvent, type TemporalReport, type TimeBucket, type TimeGrain, type Timeline, type TimelineEdge, type XY, bucketFor, bucketKey, bucketRange, buildNarrationMaterials, buildTemporalReport, buildTimeline, burstScores, byNodeId, detectBursts, extractEvents, flowFrames, forceLayout, hash32, indexGraph, labelPropagation, layoutSequence, leadScores, mulberry32, nodeId, parseAmount, parseDateMs, rankEnrichmentCandidates, rankHotspots, resolvePath, rollup, seriesKeys, shouldNarrate, shuffle, snapshotAt, snapshotSeries, splitTitleBody, synthesizeBurstSources, topFlows, totals, trackClusters };