@odla-ai/kg 0.3.2 → 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,364 +99,6 @@ 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>;
-}
-/**
- * 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[];
-
-/**
- * One threshold rule over a region's static metrics. A rule matches when the
- * region has the metric and its value passes the comparison; regions or
- * metrics missing from the metric map never match (and never throw).
- */
-interface SpatialRule {
-    /** Stable identifier, reported on findings (e.g. `"capital-desert"`). */
-    id: string;
-    /** Metric name looked up in the region's metric record. */
-    metric: string;
-    /** Comparison direction against {@link threshold}. */
-    op: ">=" | "<=";
-    threshold: number;
-    /** Additive score boost when matched (finding score × (1 + Σ weights)). Default 1. */
-    weight?: number;
-}
-/** A bursting region, the rules it matched, and its boosted rank score. */
-interface SpatialFinding {
-    /** The series key — the region identifier the events were rolled up by. */
-    region: string;
-    /** The region's strongest burst (highest score) in the set. */
-    burst: Burst;
-    /** Ids of the rules that matched, in the rules' given order. */
-    matched: string[];
-    /** `burst.score × (1 + Σ matched weights)` — rule context amplifies heat. */
-    score: number;
-    /** The region's values for every rule metric it has (evidence for narration). */
-    metrics: Record<string, number>;
-}
-/** Ids of the rules a region's metric record matches, in rule order. */
-declare function matchRules(values: Record<string, number> | undefined, rules: readonly SpatialRule[]): string[];
-/**
- * Rank spatial anomalies: detect bursts in a geo-keyed SeriesSet (one series
- * per region — roll up with `by: "geo"`), keep each region's strongest burst,
- * then amplify by matched metric rules. Deterministic: score desc, then
- * region asc. `requireMatch` drops regions matching no rule (default keeps
- * them — a burst is a finding even without metric context).
- */
-declare function spatialFindings(set: SeriesSet, metrics: Record<string, Record<string, number> | undefined>, rules: readonly SpatialRule[], opts?: BurstOptions & {
-    top?: number;
-    requireMatch?: boolean;
-}): SpatialFinding[];
-
-/** One undirected weighted pair, with (capped) bridging node ids as evidence. */
-interface WeightedPair {
-    a: string;
-    b: string;
-    w: number;
-    via: string[];
-}
-/**
- * Bridge → target sets through a REIFIED relationship node (affiliation,
- * funding_round, record): every reified node with a `bridgeLabel` edge to the
- * bridge and a `targetLabel` edge to a target contributes that target to the
- * bridge's set. Ids are `type:key`.
- */
-declare function reifiedBridgeTargets(fragment: GraphFragment, opts: {
-    reified: string;
-    bridgeLabel: string;
-    targetLabel: string;
-}): Map<string, Set<string>>;
-/** Direct-edge targets: `from` node id → set of `to` node ids for one label. */
-declare function directTargets(fragment: GraphFragment, label: string): Map<string, Set<string>>;
-/** Compose A→B with B→C into A→C (e.g. person→companies ∘ company→counties). */
-declare function composeTargets(ab: Map<string, Set<string>>, bc: Map<string, Set<string>>): Map<string, Set<string>>;
-/**
- * The bipartite projection: targets sharing a bridge become pairs, weight =
- * number of distinct shared bridges. `maxPerBridge` skips promiscuous hubs
- * (a bridge touching 40 targets says little about any pair). Deterministic
- * pair order (a < b, then sorted).
- */
-declare function projectBridges(bridges: Map<string, Set<string>>, opts?: {
-    maxPerBridge?: number;
-    viaCap?: number;
-}): WeightedPair[];
-/**
- * Temporal cohort pairs: each node links to its k nearest neighbors in
- * arrival time, weight decaying with the gap (0.5 per halfLife). Nodes
- * without a date contribute nothing.
- */
-declare function timePairs(arrivals: Map<string, number>, opts?: {
-    k?: number;
-    halfLifeDays?: number;
-}): WeightedPair[];
-/**
- * Spatial proximity pairs: k nearest neighbors in normalized map space,
- * weight decaying with distance (0.5 per halfDist). Nodes without a
- * position contribute nothing. O(n²) — fine for the ≤1k-node universes
- * lenses operate on.
- */
-declare function geoPairs(positions: Map<string, XY>, opts?: {
-    k?: number;
-    halfDist?: number;
-}): WeightedPair[];
-/**
- * Blend lens edge sets: each set is normalized to a max weight of 1 (a lens
- * with big raw counts must not drown the others), scaled by its slider
- * weight, and summed per pair. Zero-weight lenses drop out entirely.
- */
-declare function blendPairs(sets: Array<{
-    pairs: WeightedPair[];
-    weight: number;
-}>): WeightedPair[];
-/**
- * Fabricate the Snapshot series a lens graph replays: at each bucket end,
- * nodes that have arrived and the blended edges among them. Slots straight
- * into labelPropagation/trackClusters/layoutSequence.
- */
-declare function lensSnapshots(arrivals: Map<string, number>, pairs: WeightedPair[], buckets: readonly TimeBucket[]): Snapshot[];
-
 /** One node's brokerage: normalized score + the communities it connects. */
 interface Bridging {
     /** 0..1, 1 = the frame's strongest connector. */
@@ -687,4 +126,4 @@ declare function topBridges(bridging: Map<NodeId, Bridging>, n?: number): Array<
     groups: string[];
 }>;
 
-export { type Bridging, 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 SpatialFinding, type SpatialRule, type TemporalConfig, type TemporalEvent, type TemporalReport, type TimeBucket, type TimeGrain, type Timeline, type TimelineEdge, type WeightedPair, type XY, blendPairs, bridgingScores, bucketFor, bucketKey, bucketRange, buildNarrationMaterials, buildTemporalReport, buildTimeline, burstScores, byNodeId, composeTargets, detectBursts, directTargets, extractEvents, flowFrames, forceLayout, geoPairs, hash32, indexGraph, labelPropagation, layoutSequence, leadScores, lensSnapshots, matchRules, mulberry32, nodeId, parseAmount, parseDateMs, projectBridges, rankEnrichmentCandidates, rankHotspots, reifiedBridgeTargets, resolvePath, rollup, seriesKeys, shouldNarrate, shuffle, snapshotAt, snapshotSeries, spatialFindings, splitTitleBody, synthesizeBurstSources, timePairs, topBridges, 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 };