@odla-ai/kg 0.3.0 → 0.4.0

package/dist/temporal/index.d.cts

@@ -1,6 +1,6 @@
-import { h as GraphNode, G as GraphFragment, a as SourceEntry } from '../sources-nJyD0JUP.cjs';
-import { Value } from '@odla-ai/db';
-import '@odla-ai/ai';
+import { b as GraphNode, G as GraphFragment } from '../lenses-C7Q7Gvnx.cjs';
+export { W as WeightedPair, X as XY, d as blendPairs, f as composeTargets, g as directTargets, h as geoPairs, p as projectBridges, r as reifiedBridgeTargets, t as timePairs } from '../lenses-C7Q7Gvnx.cjs';
+import '@odla-ai/db';
 
 /**
  * FNV-1a 32-bit hash of a string. Used to derive a per-identity PRNG seed
@@ -76,209 +76,6 @@ declare function indexGraph(fragment: GraphFragment): GraphIndex;
  */
 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;
@@ -302,252 +99,31 @@ declare function labelPropagation(nodes: readonly NodeId[], edges: ReadonlyArray
     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>;
+/** One node's brokerage: normalized score + the communities it connects. */
+interface Bridging {
+    /** 0..1, 1 = the frame's strongest connector. */
+    score: number;
+    /** Communities this node touches through its edges (own community first). */
+    groups: string[];
 }
 /**
- * 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]².
+ * Score every node's brokerage against a community partition. Edges inside a
+ * community contribute nothing; an edge to a foreign community contributes
+ * its weight, and the total is multiplied by the number of DISTINCT foreign
+ * communities — a node wiring three groups together outranks one with the
+ * same raw weight into a single neighbor group. Scores are normalized to
+ * the frame's max (empty/one-community frames → all zeros).
  */
-declare function forceLayout(nodes: readonly NodeId[], edges: ReadonlyArray<{
+declare function bridgingScores(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;
+}>, labels: Map<NodeId, string>): Map<NodeId, Bridging>;
+/** The frame's strongest connectors, ranked (ties: id order). */
+declare function topBridges(bridging: Map<NodeId, Bridging>, n?: number): Array<{
+    id: NodeId;
     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[];
+    groups: string[];
+}>;
 
-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 };
+export { type Bridging, type GraphIndex, type NodeId, type NodeRef, type TimeBucket, type TimeGrain, bridgingScores, bucketFor, bucketKey, bucketRange, byNodeId, hash32, indexGraph, labelPropagation, mulberry32, nodeId, parseDateMs, resolvePath, shuffle, topBridges };