@odla-ai/kg 0.5.0 → 0.6.1

package/dist/index.d.cts

@@ -287,6 +287,8 @@ interface PersonRow {
     /** Natural key of a company the person is already linked to — the strongest disambiguator. */
     companySlug?: string;
     companyName?: string;
+    /** The employer's website. What makes first-party evidence reachable at all. */
+    companyWebsite?: string;
     role?: string;
     city?: string;
     region?: string;
@@ -351,6 +353,96 @@ declare function validateLinks(raw: PersonDraft["links"], limit?: number): Perso
  */
 declare function personToFragment(person: PersonRow, draft: PersonDraft, retrievedAt?: string): PersonResult;
 
+/** Where a source sits on the scale that decides how much it counts. */
+type SourceClass = 
+/** The organization's own site: team page, staff directory, press release.
+ *  The subject cannot assert this about themselves, which is what makes it
+ *  the strongest ordinary evidence. */
+"first-party"
+/** A registry that assigns identifiers: ORCID, SEC EDGAR, a licensing board. */
+ | "authoritative"
+/** The person's own profile or site. Real, but self-asserted. */
+ | "self-asserted"
+/** Press, directories, anything else. */
+ | "third-party";
+/** What reading a source established about the subject. */
+type Corroboration = 
+/** Named the subject and tied them to their organization. */
+"confirmed"
+/** Named the subject, but nothing tied it to their work. */
+ | "name-only"
+/** Loaded, and mentioned neither. */
+ | "absent"
+/** Could not be read: blocked, gone, or refused. */
+ | "unreachable"
+/** Not checked yet. */
+ | "unchecked";
+/** One dated, classified source and what it corroborated. */
+interface VerifiedSource {
+    sourceUrl: string;
+    sourceClass: SourceClass;
+    /** Which facts this source supported: "employer", "title", "location", … */
+    facts: string[];
+    /** When it was read. Every fact is a fact *as of* a date. */
+    verifiedOn: string;
+    corroboration: Corroboration;
+}
+/** How well an identity is established. */
+type Grade = 
+/** Enough independent sources, anchored, agreeing, with no contradiction. */
+"high"
+/** Corroborated, but thinly or only by sources the subject controls. */
+ | "medium"
+/** One source, or a contradiction, or nothing that settles it. */
+ | "unresolved"
+/**
+ * Nothing could be read at all.
+ *
+ * Deliberately distinct from `unresolved`. In a real run 60 of 93 claimed
+ * URLs came back unreachable, almost all login walls. Scoring those as "not
+ * established" blames a lane for a wall it cannot walk through; scoring them
+ * as established would be a lie. Neither is true, so this says so.
+ */
+ | "unverifiable";
+/** The bar a `high` grade has to clear. */
+interface GradeStandard {
+    /** Distinct hosts that must corroborate. */
+    minimumSources: number;
+    /** Distinct facts that must be corroborated across them. */
+    minimumFacts: number;
+    /** Classes that can anchor a `high` grade. */
+    anchors: readonly SourceClass[];
+    /** Whether `medium` also requires an anchor. Measured: two third-party
+     *  sources agreeing about someone who does not exist is a thing that
+     *  happens, so anything acted on should usually require one. */
+    anchorRequiredForMedium: boolean;
+}
+/** Two independent sources, one first-party or authoritative, three facts. */
+declare const DEFAULT_STANDARD: GradeStandard;
+/** What the grade was based on, so a reviewer can disagree with it. */
+interface GradeReport {
+    grade: Grade;
+    independentSources: number;
+    factsCorroborated: string[];
+    hasAnchor: boolean;
+    contradictions: string[];
+    reason: string;
+}
+/** Two sources are independent when they are not the same site. */
+declare function independentHosts(sources: readonly VerifiedSource[]): string[];
+/**
+ * Grade an identity from the sources that were checked.
+ *
+ * Only sources that corroborated something count toward the grade. One that was
+ * read and did NOT name the subject is a contradiction; one that could not be
+ * read is neither, which is the whole reason `unverifiable` exists.
+ */
+declare function gradeSources(sources: readonly VerifiedSource[], standard?: GradeStandard): GradeReport;
+/** Grades that justify acting on the identity. */
+declare const ACTIONABLE: readonly Grade[];
+/** Whether a grade is good enough to act on. */
+declare function isActionable(value: Grade): boolean;
+
 /** Which model serves each verb (search must be a web-grounded model). */
 interface EnrichModels {
     /** Web-search-grounded research model. */
@@ -393,6 +485,325 @@ declare function resolveCounties(ai: Ai, model: string, rows: CompanyRow[], gaze
     fips: string;
 }>>;
 
+/** Normalize for containment testing: fold case, accents, and punctuation. */
+declare function fold(value: string): string;
+/**
+ * Whether a folded haystack names a person.
+ *
+ * Requires every name token, and requires them to sit within a couple of words
+ * of each other, which is how names are actually written: "Abbey Chrystal",
+ * "Chrystal, Abbey", and "Abbey R. Chrystal" all qualify.
+ *
+ * Proximity is the load-bearing part, and it was added because of a measured
+ * failure rather than in anticipation of one. Requiring only that the tokens
+ * appear somewhere on the page matched "Abbey Chrystal" against a staff
+ * directory that listed "Abbey Fornier" and "Dale Chrystal" — on a team page
+ * most name tokens appear somewhere, so a document-wide match corroborates
+ * almost anybody.
+ *
+ * Single-token names are rejected outright: matching "Deere" against arbitrary
+ * page text would corroborate almost anything.
+ *
+ * @param haystack Page text, already passed through {@link fold}.
+ * @param name The person's name, in any casing or accenting.
+ */
+declare function mentionsName(haystack: string, name: string): boolean;
+/**
+ * Pull a window of text around the person's name, as evidence a reviewer can
+ * read without re-fetching the page.
+ */
+declare function snippetAround(text: string, name: string, width?: number): string;
+/**
+ * Reduce HTML to readable text.
+ *
+ * Script and style bodies are dropped first: a page's inline JSON often repeats
+ * unrelated names, and matching against it corroborates the wrong person.
+ */
+declare function stripMarkup(html: string): string;
+
+/**
+ * Read a URL and return its body, or null if it could not be read.
+ *
+ * Supplied by the caller rather than implemented here, and deliberately so.
+ * Fetched pages are attacker-influenced: a strategy reads whatever a third
+ * party chose to serve. Making the reader an explicit dependency means the
+ * caller decides what boundary it crosses — in odla that is
+ * `@odla-ai/camel`'s artifact ingress, which caps bytes, screens redirects for
+ * SSRF, and labels the body Unsafe. kg does not reach for the network itself,
+ * so it can never quietly bypass that.
+ */
+type PageReader = (url: string) => Promise<string | null>;
+/** What a strategy is given to work with. */
+interface StrategyContext {
+    person: PersonRow;
+    /** The date this evidence is being gathered on. Every fact is a fact *as of* a date. */
+    retrievedAt: string;
+    /** Present for strategies that call a model. */
+    ai?: Ai;
+    models?: EnrichModels;
+    /** Present for strategies that read pages. */
+    readPage?: PageReader;
+}
+/** What one strategy established. */
+interface Finding {
+    strategy: string;
+    /** Dated, classified sources — the input the grade is computed from. */
+    sources: VerifiedSource[];
+    /** Profile and site URLs this strategy proposes. */
+    links: PersonLink[];
+    /** Human-readable account of what happened, for adjudication. */
+    notes: string;
+    /** Set when the strategy failed outright, which is not the same as finding nothing. */
+    error?: string;
+}
+/**
+ * One way of gathering evidence about a person.
+ *
+ * A strategy never decides whether the person was found. It reports what it
+ * saw and how strong the sources were; {@link investigatePerson} grades. That
+ * split is the point — it means adding a strategy cannot inflate a verdict, and
+ * it means the standard can be raised later and re-applied to stored evidence
+ * without paying for the inference again.
+ */
+interface Strategy {
+    /** Stable identifier, recorded on findings so results stay attributable. */
+    name: string;
+    /** Whether this strategy can run at all for this subject and context. */
+    applicable(context: StrategyContext): boolean;
+    run(context: StrategyContext): Promise<Finding>;
+}
+/** The result of investigating one person with a set of strategies. */
+interface Investigation {
+    person: PersonRow;
+    /** How well the identity is established, per the standard used. */
+    grade: Grade;
+    /** Why, in enough detail to disagree with. */
+    report: GradeReport;
+    /** Every source gathered, deduplicated by URL. */
+    sources: VerifiedSource[];
+    /** Every link proposed, deduplicated by URL. */
+    links: PersonLink[];
+    /** Per-strategy detail, including strategies that ran and found nothing. */
+    findings: Finding[];
+    /** Strategies skipped because they were not applicable. */
+    skipped: string[];
+}
+/**
+ * Run every applicable strategy and grade what they found together.
+ *
+ * Strategies run concurrently and are isolated from each other: one that throws
+ * becomes a `Finding` carrying its error rather than failing the investigation.
+ * A search provider being down should cost you that strategy's evidence, not
+ * the first-party page another strategy already read.
+ *
+ * @param context The person, the date, and whichever capabilities are available.
+ * @param strategies Which strategies to attempt, in any order.
+ * @param standard The bar a `high` grade must clear. Defaults to
+ *   {@link DEFAULT_STANDARD}: two independent sources, one anchoring, three facts.
+ */
+declare function investigatePerson(context: StrategyContext, strategies: readonly Strategy[], standard?: GradeStandard): Promise<Investigation>;
+
+/** Paths an organization is most likely to describe its people on. */
+declare const TEAM_PATHS: readonly string[];
+/** The site root, which is the only URL on a domain guaranteed to exist. */
+declare function rootOf(website: string): string | null;
+/**
+ * Guessed people-page paths. A fallback only.
+ *
+ * Guessing produced 67 refusals against 23 successful reads in a real run: most
+ * sites do not use these paths, and a 404 teaches nothing about whether the
+ * person works there. Following the site's own links is the primary route; this
+ * is what remains when a homepage offers no usable navigation.
+ */
+declare function candidatePages(website: string, limit?: number): string[];
+/**
+ * Extract the links a homepage itself offers toward its people pages.
+ *
+ * Reading the site's own navigation beats guessing at it on both counts: it is
+ * far more likely to resolve, and it lands on the page the organization
+ * actually maintains. Same-origin only — an off-site link is not first-party
+ * evidence, which is the entire reason this strategy carries weight.
+ */
+declare function peopleLinks(html: string, origin: string, limit?: number): string[];
+/** What one organization page said about the person. */
+interface OrgHit {
+    url: string;
+    named: boolean;
+    /** Text around the name, for the reviewer. */
+    snippet: string;
+}
+/**
+ * Decide whether an organization page establishes the person.
+ *
+ * Deliberately strict about the name and silent about the title: a team page
+ * naming the person is the finding, and inferring their exact title from
+ * surrounding prose would manufacture a fact the page never stated plainly.
+ */
+declare function judgeOrgPage(name: string, url: string, text: string): OrgHit;
+/**
+ * Walk the employer's site looking for the person.
+ *
+ * Requires `companyWebsite` on the person and a `readPage`; without either it
+ * reports itself inapplicable rather than pretending to have checked.
+ */
+declare const orgSiteStrategy: Strategy;
+
+/**
+ * Class a cited source.
+ *
+ * The employer's own domain is first-party even when a search found it rather
+ * than a crawl — what makes evidence first-party is who published it, not how
+ * it was reached.
+ */
+declare function classifySource(url: string, companyWebsite?: string): SourceClass;
+/**
+ * Whether a provider actually grounded a claim in this source, as opposed to
+ * merely consulting it.
+ *
+ * A citation carrying cited text or a text span is attributed: the provider is
+ * saying *this sentence came from here*. One carrying only a URL means the
+ * source was visited. The difference matters enough to grade differently —
+ * consulted-but-unquoted sources are the ones that pad a bibliography without
+ * supporting anything in it.
+ */
+declare function isAttributed(citation: SearchCitation): boolean;
+/**
+ * Research a person with a grounded search, and report the sources rather than
+ * the conclusion.
+ */
+declare const researchStrategy: Strategy;
+
+/** Build the narrow query. Quoting both names is what makes the count meaningful. */
+declare function targetedQuery(person: PersonRow, platform?: string): string;
+/** One candidate profile the search turned up. */
+interface Candidate {
+    url: string;
+    host: string;
+    /** The profile handle, which tells two results apart from one result cited twice. */
+    handle: string;
+}
+/**
+ * Reduce a citation set to distinct candidate profiles.
+ *
+ * Deduplicates by (host, handle) rather than by URL. The same profile arrives
+ * as `linkedin.com/in/x`, `www.linkedin.com/in/x/`, and again with tracking
+ * suffixes; counting those as three candidates turns every confident answer
+ * into a false ambiguity.
+ */
+declare function candidatesFrom(citations: readonly SearchCitation[]): Candidate[];
+/**
+ * Look up one person by a single narrow query.
+ *
+ * Emits a source only when exactly one distinct profile came back. Emitting one
+ * per candidate when the name is ambiguous would manufacture precisely the
+ * confidence this strategy exists to withhold — and because the profile is the
+ * person's own, it is classed `self-asserted`, which under the default standard
+ * cannot anchor a `high` grade by itself.
+ */
+declare const targetedProfileStrategy: Strategy;
+
+/**
+ * How an ontology stores the alias index.
+ *
+ * kg does not own your ontology — you declare the entity, kg reads and writes
+ * it through these names. The alias entity needs a unique natural key and one
+ * attribute holding the person's key.
+ */
+interface PersonIdentityConfig {
+    /** Entity type indexing aliases, e.g. `"person_alias"`. */
+    aliasType: string;
+    /** Unique natural-key attr on the alias entity. Default `"alias"`. */
+    aliasKeyAttr?: string;
+    /** Attr on the alias entity holding the person's key. Default `"personKey"`. */
+    personKeyAttr?: string;
+    /** Entity type of the person the alias points at. Default `"person"`. */
+    personType?: string;
+    /** Edge label from alias to person. Default `"of_person"`. */
+    edgeLabel?: string;
+}
+/**
+ * Mint an opaque person key.
+ *
+ * Random rather than derived, and that is the entire point. Any key computed
+ * from the facts — a hash of name plus employer — collides two namesakes at one
+ * company and mints a second identity the moment someone changes job. A key
+ * that means nothing cannot be wrong about anything.
+ *
+ * @param random Injectable for tests; defaults to `crypto.randomUUID`.
+ */
+declare function mintPersonKey(random?: () => string): string;
+/** Whether a key was minted by {@link mintPersonKey} rather than derived from a name. */
+declare function isMintedKey(key: string): boolean;
+/**
+ * The alias for a public profile: durable, because it belongs to the person
+ * rather than to their current job.
+ */
+declare function profileAlias(kind: PersonLink["kind"], url: string): string | null;
+/**
+ * The bootstrap alias for someone with no profile found yet.
+ *
+ * Employer is part of the key on purpose: without it every namesake resolves to
+ * one person, which is the bug this module exists to close. With it, a job
+ * change produces a *new* alias rather than a wrong match — the person keeps
+ * their key, and the old alias keeps pointing at them.
+ *
+ * Returns null without an employer. A bare name is not an identity, and
+ * indexing one would reintroduce the collision by the back door.
+ */
+declare function nameAlias(name: string, companyName?: string): string | null;
+/**
+ * Every alias a person is recognizable by, strongest first.
+ *
+ * Order is what makes resolution correct rather than merely convenient: a
+ * profile match is trusted over a name-plus-employer match, so someone who
+ * changed jobs still resolves to themselves.
+ */
+declare function aliasesFor(person: PersonRow, links?: readonly PersonLink[]): string[];
+/**
+ * Resolve aliases to an existing person key.
+ *
+ * One batched read, then the *caller's* order decides — the first alias with a
+ * hit wins, so a profile match beats a name match even when the name row was
+ * written first. Returns null when nothing matches, which means mint.
+ */
+declare function resolvePersonKey(db: AdminDb, config: PersonIdentityConfig, aliases: readonly string[]): Promise<string | null>;
+/**
+ * Rewrite a fragment onto a minted person key and index the aliases that lead
+ * back to it.
+ *
+ * Everything referencing the old key moves with it — edges included — so an
+ * affiliation written against the name-derived key does not end up orphaned.
+ * The alias rows are what make the *next* pass idempotent: without them a
+ * minted key would be re-minted every run, which is worse than the name key it
+ * replaced.
+ */
+declare function applyPersonIdentity(fragment: GraphFragment, from: string, to: string, aliases: readonly string[], config: PersonIdentityConfig): GraphFragment;
+
+/** What identifying a person settled on. */
+interface PersonIdentity {
+    /** The opaque key the person is stored under. */
+    personKey: string;
+    /** True when nobody matched and a fresh key was minted. */
+    minted: boolean;
+    /** The aliases now indexed against that key, strongest first. */
+    aliases: string[];
+    /** The fragment, rekeyed onto `personKey` with the alias rows appended. */
+    fragment: GraphFragment;
+}
+/**
+ * Give a person a stable opaque key, reusing the one they already have.
+ *
+ * Aliases found by this pass are indexed too, not just the one that resolved.
+ * That is how someone graduates off the fragile name-plus-employer alias: the
+ * first pass that finds their LinkedIn attaches it to the key they already
+ * have, and every later pass — including after they change jobs — resolves on
+ * the profile instead.
+ *
+ * @param fragment A fragment keyed on `person.slug`, as `personToFragment`
+ *   produces. Its person node and every edge touching it are rekeyed.
+ */
+declare function identifyPerson(db: AdminDb, config: PersonIdentityConfig, person: PersonRow, links: readonly PersonLink[], fragment: GraphFragment): Promise<PersonIdentity>;
+
 /**
  * The LLM seam, now a thin adapter over @odla-ai/ai (which was itself
  * generalized from this package's original Provider). Three verbs stay:
@@ -703,4 +1114,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 { 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 Evidence, 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, PERSON_EXTRACT_SYSTEM, PERSON_EXTRACT_TOOL, PERSON_SEARCH_SYSTEM, type PersonDraft, type PersonEnrichment, type PersonLink, type PersonLinkKind, type PersonResult, type PersonRow, type PipelineDeps, type Provider, type ProviderFamily, RawItem, type SearchCall, type SourceConnector, type SourceEntry, type StepConfig, type StepLike, Store, Usage, type Verdict, type Verification, WRITABLE_VERDICTS, type WriteCall, allJobs, asStepLike, canonicalizeFragment, connectorIds, countyKey, createProvider, enabledSources, enrichCompany, enrichPerson, exportFragment, extractJson, extractJsonArray, factsToFragment, fetchText, fetchUrl, findConnectors, fragmentToOps, getConnector, getProvider, htmlToText, humanAttrsOf, identityKey, ingestFresh, isHttpUrl, isLikelyPersonName, isVerdict, isWritable, jobsForHour, locatePrompt, locationFragment, makeContext, mergeAttrs, mergeRulesOf, mergeScalar, naturalKeysOf, normalizeUrl, normalizeVerification, personPrompt, personToFragment, resilientStep, resolveCounties, resolveName, searchEntities, slugify, toSerializedSchema, urlHash, validateLinks, writeFragment };
+export { ACTIONABLE, type AttrSpec, type AttrType, COMMIT_STEP_CONFIG, type Candidate, type CompanyRow, type Connector, type ConnectorConfig, type ConnectorContext, type ConnectorJob, type ConnectorLens, type ConnectorReport, type ContextConfig, type Corroboration, DEFAULT_STANDARD, type EdgeSpec, type EnrichModels, type EntitySpec, type Evidence, type ExportEntitySpec, type ExportSpec, type ExtractCall, ExtractResult, FACTS_EXTRACT_SYSTEM, FACTS_EXTRACT_TOOL, FACTS_SEARCH_SYSTEM, type FactsDraft, type Finding, type Grade, type GradeReport, type GradeStandard, GraphFragment, IO_STEP_CONFIG, type Investigation, type KVLike, LLM_STEP_CONFIG, LOCATE_SYSTEM, LOCATE_TOOL, type LlmConfig, type LlmEnv, MODEL_TIERS, type MergeRule, type NaturalKeys, type Ontology, type OrgHit, PERSON_EXTRACT_SYSTEM, PERSON_EXTRACT_TOOL, PERSON_SEARCH_SYSTEM, type PageReader, type PersonDraft, type PersonEnrichment, type PersonIdentity, type PersonIdentityConfig, type PersonLink, type PersonLinkKind, type PersonResult, type PersonRow, type PipelineDeps, type Provider, type ProviderFamily, RawItem, type SearchCall, type SourceClass, type SourceConnector, type SourceEntry, type StepConfig, type StepLike, Store, type Strategy, type StrategyContext, TEAM_PATHS, Usage, type Verdict, type Verification, type VerifiedSource, WRITABLE_VERDICTS, type WriteCall, aliasesFor, allJobs, applyPersonIdentity, asStepLike, candidatePages, candidatesFrom, canonicalizeFragment, classifySource, connectorIds, countyKey, createProvider, enabledSources, enrichCompany, enrichPerson, exportFragment, extractJson, extractJsonArray, factsToFragment, fetchText, fetchUrl, findConnectors, fold, fragmentToOps, getConnector, getProvider, gradeSources, htmlToText, humanAttrsOf, identifyPerson, identityKey, independentHosts, ingestFresh, investigatePerson, isActionable, isAttributed, isHttpUrl, isLikelyPersonName, isMintedKey, isVerdict, isWritable, jobsForHour, judgeOrgPage, locatePrompt, locationFragment, makeContext, mentionsName, mergeAttrs, mergeRulesOf, mergeScalar, mintPersonKey, nameAlias, naturalKeysOf, normalizeUrl, normalizeVerification, orgSiteStrategy, peopleLinks, personPrompt, personToFragment, profileAlias, researchStrategy, resilientStep, resolveCounties, resolveName, resolvePersonKey, rootOf, searchEntities, slugify, snippetAround, stripMarkup, targetedProfileStrategy, targetedQuery, toSerializedSchema, urlHash, validateLinks, writeFragment };