@odla-ai/kg 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,71 @@
-import { O as Ontology, G as GraphFragment, M as MergeRule, P as Provider, S as SourceConnector, C as ConnectorContext, R as RawItem, a as SourceEntry, E as ExtractResult } from './sources-nJyD0JUP.cjs';
-export { A as AttrSpec, b as AttrType, c as ConnectorJob, d as EdgeSpec, e as EntitySpec, f as ExtractCall, g as GraphEdge, h as GraphNode, L as LlmConfig, i as LlmEnv, j as MODEL_TIERS, N as NaturalKeys, k as ProviderFamily, l as SearchCall, U as Usage, W as WriteCall, m as addUsage, n as allJobs, o as createProvider, p as emptyUsage, q as enabledSources, r as fragmentToOps, s as getProvider, t as humanAttrsOf, u as jobsForHour, v as mergeRulesOf, w as naturalKeysOf, x as toSerializedSchema, y as writeFragment } from './sources-nJyD0JUP.cjs';
-import { AdminDb, Value, Entity } from '@odla-ai/db';
-import '@odla-ai/ai';
+import { G as GraphFragment, W as WeightedPair, U as Usage, R as RawItem, E as ExtractResult } from './lenses-C7Q7Gvnx.cjs';
+export { a as GraphEdge, b as GraphNode, c as addUsage, e as emptyUsage } from './lenses-C7Q7Gvnx.cjs';
+import { Op, AdminDb, SerializedAttr, Cardinality, SerializedSchema, Value, Entity } from '@odla-ai/db';
+import { ExtractTool, Ai } from '@odla-ai/ai';
+
+/** node type → unique natural-key attribute name. */
+type NaturalKeys = Record<string, string>;
+/**
+ * Pure fragment → ops mapping (no read/merge). Node upserts by Lookup natural
+ * key, then links — nodes always before links so `link` targets resolve.
+ * Used by tests and as the building block for the provenance path below.
+ */
+declare function fragmentToOps(fragment: GraphFragment, keys: NaturalKeys): Op[];
+/**
+ * Provenance-preserving write. Reads existing nodes by natural key (one batched
+ * query), merges scalar attrs per the ontology's rules, drops human-owned
+ * attrs, then writes merged node updates + all links in one atomic, idempotent
+ * transaction. `mutationId` must be deterministic so odla-db can deduplicate
+ * the write on retry; this does not make preceding reads or external effects
+ * exactly-once.
+ */
+declare function writeFragment(db: AdminDb, fragment: GraphFragment, ontology: Ontology, mutationId: string): Promise<{
+    txId: number;
+    ops: number;
+}>;
+
+/** How a scalar attribute is reconciled when a node is re-discovered. */
+type MergeRule = "replace" | "prefer" | "earliest" | "latest";
+type AttrType = SerializedAttr["type"];
+interface AttrSpec {
+    type: AttrType;
+    unique?: boolean;
+    indexed?: boolean;
+    optional?: boolean;
+    /** The pipeline NEVER writes this attr (hand-edited in a UI); omitted from every update. */
+    human?: boolean;
+    /** Provenance rule for re-discovery. Default "replace". */
+    merge?: MergeRule;
+    /** Shown to the LLM when this attr appears in an extraction schema. */
+    desc?: string;
+}
+interface EntitySpec {
+    /** Unique attr used for Lookup upsert (MERGE key). Must be `unique` in attrs. */
+    naturalKey: string;
+    attrs: Record<string, AttrSpec>;
+    /** FTS fields for fuzzy resolution (P5). */
+    searchable?: string[];
+}
+interface EdgeSpec {
+    from: string;
+    to: string;
+    forwardLabel: string;
+    reverseLabel: string;
+    forwardHas?: Cardinality;
+    reverseHas?: Cardinality;
+}
+interface Ontology {
+    entities: Record<string, EntitySpec>;
+    edges: Record<string, EdgeSpec>;
+}
+/** node type → natural-key attr name (for the graph writer's Lookup refs). */
+declare function naturalKeysOf(o: Ontology): NaturalKeys;
+/** Attr name → merge rule, for every entity type (used by the provenance writer). */
+declare function mergeRulesOf(o: Ontology): Record<string, Record<string, MergeRule>>;
+/** Attr names the pipeline must never write, per entity type. */
+declare function humanAttrsOf(o: Ontology): Record<string, Set<string>>;
+/** Compile the ontology to an odla-db SerializedSchema to POST at /app/:id/schema. */
+declare function toSerializedSchema(o: Ontology): SerializedSchema;
 
 /** One entity type to export. */
 interface ExportEntitySpec {
@@ -71,6 +135,210 @@ declare function resolveName(db: AdminDb, type: string, keyAttr: string, name: s
  */
 declare function canonicalizeFragment(db: AdminDb, fragment: GraphFragment, ontology: Ontology): Promise<GraphFragment>;
 
+/** One relatedness lens over the universe nodes. */
+interface ConnectorLens {
+    /** Reified relationship node type carrying both edges (e.g. `"affiliation"`). */
+    reified: string;
+    /** Edge label to the SHARED entity that bridges (e.g. `"of_person"`). */
+    bridge: string;
+    /** Edge label to the UNIVERSE node the shared entity connects (e.g. `"of_company"`). */
+    of: string;
+    /** Blend weight (each lens is normalized to max 1 first). Default 1. */
+    weight?: number;
+}
+/** How to find connectors: the lenses to blend, plus limits. */
+interface ConnectorConfig {
+    lenses: ConnectorLens[];
+    /** Extra precomputed pairs to fold in (e.g. geo/time affinity). */
+    extraPairs?: Array<{
+        pairs: WeightedPair[];
+        weight: number;
+    }>;
+    /** How many connectors to return. Default 12. */
+    top?: number;
+    /** Skip promiscuous shared entities touching more than this many nodes. Default 12. */
+    maxPerBridge?: number;
+}
+/** One bridging node: the groups it joins and the shared entities that link it out. */
+interface Connector {
+    /** `type:key` of the connector node. */
+    ref: string;
+    name: string;
+    /** 0..1 brokerage — 1 is the strongest connector found. */
+    score: number;
+    /** Representative names of the distinct groups it bridges. */
+    groups: string[];
+    /** Names of the shared entities (people/investors/…) linking it to other groups. */
+    via: string[];
+}
+/** The ranked connectors plus the size of the graph they were found in. */
+interface ConnectorReport {
+    connectors: Connector[];
+    /** Distinct communities in the blended graph. */
+    communities: number;
+    /** Universe nodes with at least one relationship. */
+    nodes: number;
+}
+/**
+ * Rank the connectors of a graph. Builds the blended relationship graph from
+ * the lenses, detects communities, scores each node's cross-community
+ * brokerage, and returns the top bridges with the groups they join and the
+ * shared entities behind each link. Empty/relationshipless input → empty report.
+ */
+declare function findConnectors(fragment: GraphFragment, config: ConnectorConfig): ConnectorReport;
+
+/** The minimal company row enrichment reads (attrs only — never hydrates). */
+interface CompanyRow {
+    slug: string;
+    name: string;
+    city?: string;
+    region?: string;
+    first_seen?: string;
+    founded?: string;
+    fips?: string;
+}
+/** System prompt for the county-resolution extraction. */
+declare const LOCATE_SYSTEM = "You resolve US business locations to counties. For each company you are given a city and/or a free-text region. Name the US county containing that city (for independent cities, use the city's own county-equivalent name) plus its 2-letter state. Use nulls when the location is ambiguous, outside the US, or unknown.";
+/** Forced-tool schema pairing each company slug with a county name + state. */
+declare const LOCATE_TOOL: ExtractTool;
+/** The user prompt for a LOCATE batch. */
+declare function locatePrompt(batch: CompanyRow[]): string;
+/** System prompt for the grounded web-search research pass. */
+declare const FACTS_SEARCH_SYSTEM = "You are a research assistant with web search. Find concrete facts about the company: founding year/date, headquarters city and state, founders and key executives (names, roles), and funding (rounds, dates, amounts, investor names). Prefer official/reputable sources. Report dense factual notes; say 'not found' for anything you cannot establish. Do not speculate.";
+/** System prompt for structuring the research notes into {@link FactsDraft}. */
+declare const FACTS_EXTRACT_SYSTEM = "Extract structured facts from the research notes. Use null for anything the notes do not establish.";
+/** Forced-tool schema for the structured company facts (founding, HQ, people, funding). */
+declare const FACTS_EXTRACT_TOOL: ExtractTool;
+/** The model's structured company facts, before validation into a fragment. */
+interface FactsDraft {
+    founded?: string | null;
+    city?: string | null;
+    state?: string | null;
+    people: Array<{
+        name: string;
+        role: string;
+    }>;
+    rounds: Array<{
+        round?: string | null;
+        date?: string | null;
+        amount?: string | null;
+        investors: string[];
+    }>;
+}
+/** Loose county-name key for joining model output ("Santa Clara","CA") to a gazetteer. */
+declare const countyKey: (name: string, st: string) => string;
+/**
+ * Turn one company's structured facts into an idempotent fragment: founded/
+ * city attrs, person + dated affiliation nodes, funding_round nodes (keyed
+ * `slug~e<i>` so they never collide with seed rounds), and investors. Capped
+ * and validated — the draft is a proposal, not a command.
+ */
+declare function factsToFragment(company: CompanyRow, draft: FactsDraft): GraphFragment;
+/** The `located_in` write linking a company to its resolved county. */
+declare function locationFragment(slug: string, name: string, fips: string): GraphFragment;
+
+/** Which model serves each verb (search must be a web-grounded model). */
+interface EnrichModels {
+    /** Web-search-grounded research model. */
+    search: string;
+    /** Structured-extraction (forced tool-call) model. */
+    extract: string;
+}
+/**
+ * Enrich one company: a grounded web search for its facts, then a structured
+ * extraction into a validated {@link factsToFragment}. Retries the extraction
+ * once (reasoning models sometimes skip a forced tool call). Returns the
+ * fragment (possibly empty — nothing established); the caller writes it.
+ */
+declare function enrichCompany(ai: Ai, models: EnrichModels, company: CompanyRow): Promise<GraphFragment>;
+/**
+ * Resolve a batch of companies' free-text locations to county FIPS codes via a
+ * single structured extraction, joined against a caller-supplied gazetteer
+ * (`countyKey(name, state)` → FIPS). Only confident, gazetteer-matched
+ * resolutions are returned.
+ */
+declare function resolveCounties(ai: Ai, model: string, rows: CompanyRow[], gazetteer: Map<string, string>): Promise<Array<{
+    slug: string;
+    fips: string;
+}>>;
+
+/**
+ * The LLM seam, now a thin adapter over @odla-ai/ai (which was itself
+ * generalized from this package's original Provider). Three verbs stay:
+ * extract (forced structured tool call), search (web-search-enabled text),
+ * write (plain generation). Callers never see vendor or oracle types.
+ */
+type ProviderFamily = "claude" | "openai";
+/** Role → model tiers per family — config as data. `cheap` is for gate-style
+ * calls, `extract` for structured extraction (and prose writing), `search`
+ * for web-search-enabled calls. */
+declare const MODEL_TIERS: Record<ProviderFamily, {
+    cheap: string;
+    extract: string;
+    search: string;
+}>;
+/** A forced structured tool call: schema in, validated object out. */
+interface ExtractCall {
+    system: string;
+    user: string;
+    tool: {
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+    };
+    model?: string;
+    maxTokens?: number;
+}
+/** A web-search-enabled call: the model searches and returns text (caller tolerant-parses). */
+interface SearchCall {
+    system: string;
+    user: string;
+    model?: string;
+    maxTokens?: number;
+}
+/** A plain text-generation call (no tools, no search) — e.g. digest prose. */
+interface WriteCall {
+    system: string;
+    user: string;
+    model?: string;
+    maxTokens?: number;
+}
+interface Provider {
+    id: ProviderFamily;
+    /** The underlying @odla-ai/ai client — escape hatch for advanced use. */
+    ai: Ai;
+    extract<T = unknown>(c: ExtractCall): Promise<{
+        value: T;
+        usage: Usage;
+    }>;
+    search(c: SearchCall): Promise<{
+        text: string;
+        usage: Usage;
+    }>;
+    write(c: WriteCall): Promise<{
+        text: string;
+        usage: Usage;
+    }>;
+}
+interface LlmConfig {
+    provider: ProviderFamily;
+    anthropicKey?: string;
+    openaiKey?: string;
+    /** Inject a pre-built Ai (tests, custom catalog); keys are ignored when set. */
+    ai?: Ai;
+}
+/** The library primitive: an explicit config in, the three-verb seam out. */
+declare function createProvider(cfg: LlmConfig): Provider;
+/** The env vars the provider factory reads — a structural slice, not the
+ * worker Env, so any host (worker, script, test) can supply plain strings. */
+interface LlmEnv {
+    LLM_PROVIDER?: string;
+    ANTHROPIC_API_KEY?: string;
+    OPENAI_API_KEY?: string;
+}
+/** Build the configured provider from host env, failing before use when its key is missing. */
+declare function getProvider(env: LlmEnv): Provider;
+
 /**
  * Tolerant JSON extraction from LLM prose — web-search models return JSON inside
  * explanatory text. Ported from agnacl services/enrichment.ts.
@@ -79,6 +347,41 @@ declare function extractJson<T = unknown>(text: string): T | null;
 /** Tolerantly parse the first JSON-array-shaped span in model prose, or return an empty array. */
 declare function extractJsonArray<T = unknown>(text: string): T[];
 
+/** Ambient services a connector may use. Host-agnostic: secrets come through
+ * secret(), never a worker Env, so the library runs anywhere. */
+interface ConnectorContext {
+    now: Date;
+    fetchText(url: string): Promise<string>;
+    secret(name: string): string | undefined;
+    ontology: Ontology;
+    /** The configured LLM provider (lazy — only web-search/discovery connectors need it). */
+    provider(): Provider;
+}
+/**
+ * The extensibility seam. A connector emits normalized RawItems — text-bearing
+ * (→ LLM extraction) or fragment-bearing (structured → straight to the writer).
+ * Adding a source = a new module implementing this + one registry line.
+ */
+interface SourceConnector<Cfg = unknown> {
+    id: string;
+    capabilities: {
+        fetch: boolean;
+        discover?: boolean;
+        structured: boolean;
+    };
+    parseConfig(raw: unknown): Cfg;
+    fetch(cfg: Cfg, ctx: ConnectorContext): Promise<RawItem[]>;
+    /** Web-search-style net-new discovery (P4). */
+    discover?(cfg: Cfg, ctx: ConnectorContext): Promise<RawItem[]>;
+}
+/** One unit of work for the ingest workflow: which connector + its config. */
+interface ConnectorJob {
+    kind: string;
+    name: string;
+    watch?: string | null;
+    cfg: unknown;
+}
+
 /** Resolve a built-in source connector by its stable registry id. */
 declare function getConnector(id: string): SourceConnector | undefined;
 /** List registered connector ids in deterministic insertion order. */
@@ -97,6 +400,28 @@ declare function makeContext(cfg: ContextConfig): ConnectorContext;
 /** Fetch one URL → a text-bearing RawItem. Used both directly (/trigger) and as a connector. */
 declare function fetchUrl(url: string): Promise<RawItem>;
 
+/**
+ * Sources are DATA, not code. Each entry names a connector (`kind`) + its config
+ * + scheduling. Add a feed → add an entry; no redeploy of the pipeline. P5 moves
+ * this into KV behind a /config admin endpoint so edits don't need a deploy at all.
+ */
+interface SourceEntry {
+    kind: string;
+    name: string;
+    enabled?: boolean;
+    cadenceHours?: number;
+    watch?: string | null;
+    url?: string;
+    query?: string;
+    [key: string]: unknown;
+}
+/** Return source entries not explicitly disabled, preserving configured order. */
+declare function enabledSources(sources: SourceEntry[]): SourceEntry[];
+/** Enabled sources whose cadence lands on this UTC hour. */
+declare function jobsForHour(sources: SourceEntry[], hour: number): ConnectorJob[];
+/** Every enabled source, ignoring cadence (manual /trigger?kind=sources). */
+declare function allJobs(sources: SourceEntry[]): ConnectorJob[];
+
 /**
  * The slice of a KV store the pipeline needs. Cloudflare's KVNamespace
  * satisfies it structurally; tests pass an in-memory map. Keeping the library
@@ -236,4 +561,4 @@ declare function htmlToText(html: string, maxChars?: number): string;
 /** Fetch a URL and return readable text. Best-effort: returns "" on any failure. */
 declare function fetchText(url: string, maxChars?: number): Promise<string>;
 
-export { COMMIT_STEP_CONFIG, ConnectorContext, type ContextConfig, type ExportEntitySpec, type ExportSpec, ExtractResult, GraphFragment, IO_STEP_CONFIG, type KVLike, LLM_STEP_CONFIG, MergeRule, Ontology, type PipelineDeps, Provider, RawItem, SourceConnector, SourceEntry, type StepConfig, type StepLike, Store, asStepLike, canonicalizeFragment, connectorIds, exportFragment, extractJson, extractJsonArray, fetchText, fetchUrl, getConnector, htmlToText, ingestFresh, isLikelyPersonName, makeContext, mergeAttrs, mergeScalar, normalizeUrl, resilientStep, resolveName, searchEntities, slugify, urlHash };
+export { type AttrSpec, type AttrType, COMMIT_STEP_CONFIG, type CompanyRow, type Connector, type ConnectorConfig, type ConnectorContext, type ConnectorJob, type ConnectorLens, type ConnectorReport, type ContextConfig, type EdgeSpec, type EnrichModels, type EntitySpec, type ExportEntitySpec, type ExportSpec, type ExtractCall, ExtractResult, FACTS_EXTRACT_SYSTEM, FACTS_EXTRACT_TOOL, FACTS_SEARCH_SYSTEM, type FactsDraft, GraphFragment, IO_STEP_CONFIG, type KVLike, LLM_STEP_CONFIG, LOCATE_SYSTEM, LOCATE_TOOL, type LlmConfig, type LlmEnv, MODEL_TIERS, type MergeRule, type NaturalKeys, type Ontology, type PipelineDeps, type Provider, type ProviderFamily, RawItem, type SearchCall, type SourceConnector, type SourceEntry, type StepConfig, type StepLike, Store, Usage, type WriteCall, allJobs, asStepLike, canonicalizeFragment, connectorIds, countyKey, createProvider, enabledSources, enrichCompany, exportFragment, extractJson, extractJsonArray, factsToFragment, fetchText, fetchUrl, findConnectors, fragmentToOps, getConnector, getProvider, htmlToText, humanAttrsOf, ingestFresh, isLikelyPersonName, jobsForHour, locatePrompt, locationFragment, makeContext, mergeAttrs, mergeRulesOf, mergeScalar, naturalKeysOf, normalizeUrl, resilientStep, resolveCounties, resolveName, searchEntities, slugify, toSerializedSchema, urlHash, writeFragment };