@factbag/jev 0.0.0-bootstrap.0 → 0.1.0-alpha.7

package/dist/public/index.d.ts

@@ -0,0 +1,102 @@
+import { GuardedKB, KnowledgeBase } from "factbag/kb";
+import { Chunk, Corpus, Metadata } from "factbag/corpus";
+import { Entity, PredicateDeclaration, Scalar } from "factbag/dsl";
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+/** Default minimum probability for admitting signed evidence. @beta */
+export declare const DEFAULT_MINIMUM_PROBABILITY = .4;
+/** Default maximum probability gap from the strongest signed outcome. @beta */
+export declare const DEFAULT_AMBIGUITY_MARGIN = 0;
+/** Whether heuristic predicate and symbol filtering is enabled by default. @beta */
+export declare const DEFAULT_ROUTING_ENABLED: boolean;
+/** Default inclusive probability threshold for retaining a predicate. @beta */
+export declare const DEFAULT_PREDICATE_THRESHOLD = .3;
+/** Default inclusive probability threshold for retaining a symbol. @beta */
+export declare const DEFAULT_SYMBOL_THRESHOLD = .3;
+/** Default candidate product size above which symbol filtering runs. @beta */
+export declare const DEFAULT_CANDIDATE_PRODUCT_CUTOFF = 16;
+/** How classification and resolution use a model's answers, whichever model gives them. @beta */
+type Settings = {
+  /** Minimum probability for admitting signed evidence or retracting a passage, default 0.4. */
+  readonly minimumProbability?: number;
+  /** Classification: maximum gap from the strongest signed outcome. Resolution: required RETRACT lead over KEEP. Default 0. */
+  readonly ambiguityMargin?: number;
+  /** Enable heuristic predicate and symbol filtering, default false. */
+  readonly routing?: boolean;
+  /** Inclusive probability at which a predicate is kept for a passage, default 0.3. */
+  readonly predicateThreshold?: number;
+  /** Inclusive probability at which a symbol is kept for a passage, default 0.3. */
+  readonly symbolThreshold?: number;
+  /** Run symbol filtering if a retained predicate with non-Boolean roles exceeds this raw Cartesian product, default 16. */
+  readonly candidateProductCutoff?: number;
+  /** Questions per request when work can be split, up to the provider's limit. Defaults to the provider's choice. */
+  readonly batchSize?: number;
+};
+/** Settings with every default applied. @beta */
+type Normalized = Readonly<Required<Settings>>;
+/**
+ * Candidate values for each requested field, by predicate and then by field name. Open
+ * fields are `String`, `Number`, `Date`, and entity fields. The same value may be offered
+ * to any number of fields.
+ * @beta
+ */
+type SymbolAnswer = ReadonlyMap<PredicateDeclaration, Readonly<Record<string, readonly (Scalar | Entity)[]>>>;
+/**
+ * Candidate symbols found in a fixed set of chunks. How and when it reads them, and what
+ * it caches between queries, is up to the implementation. An entity's type and id are its
+ * identity, so the ids it mints decide which mentions are the same entity.
+ * @beta
+ */
+type ChunkSymbolExtractor = {
+  /** Candidate values for exactly the requested fields of each requested predicate. */
+  readonly query: (requests: ReadonlyMap<PredicateDeclaration, readonly string[]>) => SymbolAnswer | Promise<SymbolAnswer>;
+};
+/** Build an extractor over the chunks it will be queried about. @beta */
+type CreateChunkSymbolExtractor = (chunks: readonly Chunk[]) => ChunkSymbolExtractor;
+/** One opaque unit of work. Its effects are written to the run’s knowledge base. @beta */
+type Job = {
+  readonly execute: () => Promise<void>;
+};
+/** A single-cursor stream of jobs sharing an independent output knowledge base. @beta */
+type Run = IterableIterator<Job> & {
+  readonly kb: KnowledgeBase;
+};
+/**
+ * Jev settings. Model, timeout, and retry settings belong to the SDK client. `batchSize`
+ * defaults to 64 questions per request; TypeSafe sets no upper limit.
+ *
+ * @beta
+ */
+export type Config = Settings & {
+  /** Defaults to a lazy TypeSafeClient configured from TYPESAFE_* environment variables. */
+  readonly client?: TypeSafeClient;
+};
+/** Normalize settings once, sharing a lazy SDK client when reused across runs. @beta */
+export declare function createConfig(config?: Config): Normalized & Config;
+/**
+ * Parse corpus evidence into a new knowledge base using guarded predicate operations.
+ * Validate available predicates eagerly and return a lazy iterator of executable jobs.
+ * Bare KBs expose all known predicates; explicit guards retain their permission policy.
+ * Only job.execute() makes a remote call. The consumer owns pacing and concurrency.
+ * With `createChunkSymbolExtractor`, open-ended and entity fields also take the values
+ * each chunk offers, so they need no finite domain up front.
+ * @beta
+ */
+export declare function classifier<M extends Metadata = Metadata>(input: {
+  corpus: Corpus<M>;
+  input: KnowledgeBase | GuardedKB;
+  config?: Config;
+  createChunkSymbolExtractor?: CreateChunkSymbolExtractor;
+}): Run;
+/**
+ * Settle contradictions in a knowledge base by reading each one's evidence together.
+ * Find every atom with evidence of both signs and return a lazy iterator of jobs, one per
+ * contradiction. Each job sends all of the contradiction's passages to Jev in one request
+ * and asks, for each passage, whether its account still stands. Evidence from superseded
+ * passages is retracted from `kb`; the rest is kept, so the solver decides what the
+ * surviving evidence means. The input KB is not modified. Throws during construction if
+ * conflicting evidence has no source, and propagates corpus errors for sources that are not
+ * resolvable chunk IDs. The consumer owns pacing and concurrency.
+ * @beta
+ */
+export declare function resolver<M extends Metadata = Metadata>(corpus: Corpus<M>, kb: KnowledgeBase, config?: Config): Run;
+export type { ChunkSymbolExtractor, CreateChunkSymbolExtractor, Job, Normalized, Run, Settings, SymbolAnswer };