@odla-ai/kg 0.3.2 → 0.4.0

package/dist/sources-nJyD0JUP.d.ts

@@ -1,256 +0,0 @@
-import { Value, Op, AdminDb, SerializedAttr, Cardinality, SerializedSchema } from '@odla-ai/db';
-import { Ai } from '@odla-ai/ai';
-
-/**
- * The output of a connector: one acquired item. Exactly one of `text` or
- * `fragment` is set — `text` goes through LLM extraction, `fragment` is already
- * ontology-typed and goes straight to the graph writer (structured feeds).
- */
-interface RawItem {
-    url: string;
-    title: string;
-    date?: string;
-    sourceName: string;
-    sourceKind: string;
-    watch?: string | null;
-    text?: string;
-    fragment?: GraphFragment;
-}
-/** A graph node = an odla-db entity in a namespace, keyed by a natural key. */
-interface GraphNode {
-    type: string;
-    key: string;
-    attrs: Record<string, Value>;
-}
-/** A graph edge = an odla-db `link` from one node to another by forward label. */
-interface GraphEdge {
-    from: {
-        type: string;
-        key: string;
-    };
-    to: {
-        type: string;
-        key: string;
-    };
-    label: string;
-}
-/** The single shape the graph writer consumes, whatever produced it. */
-interface GraphFragment {
-    nodes: GraphNode[];
-    edges: GraphEdge[];
-}
-/** What an extractor turns a text RawItem into: a fragment plus a prose summary. */
-interface ExtractResult {
-    fragment: GraphFragment;
-    summary: string;
-}
-/** Provider-agnostic LLM usage accounting. */
-interface Usage {
-    calls: number;
-    inputTokens: number;
-    outputTokens: number;
-}
-/** Create zeroed provider-agnostic usage totals for one pipeline run. */
-declare function emptyUsage(): Usage;
-/** Mutate an accumulator by adding call, input-token, and output-token totals. */
-declare function addUsage(into: Usage, more: Usage): void;
-
-/** 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;
-
-/**
- * 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;
-
-/** 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;
-}
-
-/**
- * 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[];
-
-export { type AttrSpec as A, type ConnectorContext as C, type ExtractResult as E, type GraphFragment as G, type LlmConfig as L, type MergeRule as M, type NaturalKeys as N, type Ontology as O, type Provider as P, type RawItem as R, type SourceConnector as S, type Usage as U, type WriteCall as W, type SourceEntry as a, type AttrType as b, type ConnectorJob as c, type EdgeSpec as d, type EntitySpec as e, type ExtractCall as f, type GraphEdge as g, type GraphNode as h, type LlmEnv as i, MODEL_TIERS as j, type ProviderFamily as k, type SearchCall as l, addUsage as m, allJobs as n, createProvider as o, emptyUsage as p, enabledSources as q, fragmentToOps as r, getProvider as s, humanAttrsOf as t, jobsForHour as u, mergeRulesOf as v, naturalKeysOf as w, toSerializedSchema as x, writeFragment as y };