@factbag/jev 0.0.0-alpha.5 → 0.0.0-alpha.6

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @factbag/jev
 
+## 0.0.0-alpha.6
+
+### Minor Changes
+
+- 6433c6b: Classify open-ended `String`, `Number`, and `Date` fields, and entity fields with no registered entities, over the values each passage offers. Pass `createChunkSymbolExtractor` to `classifier(...)` from `@factbag/jev` or `@factbag/clef` to build an extractor per chunk whose `query` answers candidate values for the open fields of the predicates it classifies. Both packages export the `ChunkSymbolExtractor`, `CreateChunkSymbolExtractor`, and `SymbolAnswer` types.
+
+  Extracted values are candidates only. An extracted entity is registered in `run.kb.entities` when asserted or denied evidence mentions it; entities the model does not admit evidence for are discarded.
+
+### Patch Changes
+
+- Updated dependencies [7225a51]
+- Updated dependencies [7f26b45]
+- Updated dependencies [b7c85ff]
+- Updated dependencies [ed6ec84]
+- Updated dependencies [5114b2f]
+- Updated dependencies [15391f2]
+- Updated dependencies [eab3679]
+- Updated dependencies [ecbd8d9]
+- Updated dependencies [e4b343e]
+  - factbag@0.0.0-alpha.6
+
 ## 0.0.0-alpha.5
 
 ### Minor Changes

package/README.md

@@ -102,14 +102,14 @@ field that cannot be classified. A nonempty metadata description is required.
 
 Supported field domains:
 
-| Schema field               | Candidate values                         |
-| -------------------------- | ---------------------------------------- |
-| `Boolean`                  | `false`, `true`                          |
-| `enumeration(...)`         | Explicit string, number, or Date members |
-| Entity constructor         | Instances registered in `kb.entities`    |
-| `String`, `Number`, `Date` | Unsupported open-ended domains           |
-
-An entity domain must contain registered instances. Existing scalar facts do not
+| Schema field               | Candidate values                                     |
+| -------------------------- | ---------------------------------------------------- |
+| `Boolean`                  | `false`, `true`                                      |
+| `enumeration(...)`         | Explicit string, number, or Date members             |
+| Entity constructor         | Registered instances, plus each chunk's extracted    |
+| `String`, `Number`, `Date` | Each chunk's extracted values; unsupported otherwise |
+
+Without `createChunkSymbolExtractor`, an entity domain must contain registered instances. Existing scalar facts do not
 turn an open-ended schema into an enum. To model a fixed value, declare it explicitly
 with `enumeration(value)` rather than asking the classifier to discover it.
 
@@ -132,6 +132,49 @@ proposition. Every candidate gets an independent `Choice(ASSERT, DENY, IRRELEVAN
 question. Assert and deny permissions for the same predicate share one question.
 No enum exclusivity or Boolean equivalence is assumed; those belong to the ruleset.
 
+### Passage symbols
+
+Pass `createChunkSymbolExtractor` to fill open-ended and entity fields from the text
+being classified. The classifier builds one extractor per job over that job's chunk,
+and asks it for the open fields of the predicates it classifies:
+
+```ts
+const run = classifier({
+  corpus,
+  input: access,
+  createChunkSymbolExtractor: (chunks) => {
+    const found = scan(chunks);
+    return {
+      query: (requests) =>
+        new Map(
+          [...requests].map(([predicate, fields]) => [
+            predicate,
+            Object.fromEntries(fields.map((name) => [name, found.for(predicate, name)])),
+          ]),
+        ),
+    };
+  },
+});
+```
+
+- Open fields are `String`, `Number`, `Date`, and entity fields. Boolean and
+  enumeration fields keep their declared domains.
+- `query` receives a map from each predicate to its open field names, and answers with
+  a map from each predicate to the values for each field, possibly asynchronously. How
+  it finds them, and what it caches, is up to the extractor.
+- The answer must cover exactly the requested predicates and fields, with values each
+  field can hold: strings, finite numbers, valid dates, or entities of the field's
+  type. Otherwise the job rejects before anything is classified.
+- Scalar fields take exactly the values answered. Entity fields take them alongside
+  their registered instances. Extracted entities are only candidates: those that
+  asserted or denied evidence mentions are registered in `run.kb.entities`, and the
+  rest are discarded.
+- A predicate with a field left empty is skipped for that chunk.
+
+An entity's type and `id` are its identity, so the extractor decides which mentions
+are the same entity by the ids it mints. `new Person("Alice")` from two chunks is one
+entity.
+
 ## Jobs and execution
 
 `run` is a single-cursor `IterableIterator`. Each yielded job classifies one chunk

package/dist/public/index.d.ts

@@ -1,5 +1,6 @@
 import { GuardedKB, KnowledgeBase } from "factbag/kb";
-import { Corpus, Metadata } from "factbag/corpus";
+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;
@@ -32,6 +33,25 @@ type Settings = {
 };
 /** 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>;
@@ -57,12 +77,15 @@ export declare function createConfig(config?: Config): Normalized & Config;
  * 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.
@@ -76,4 +99,4 @@ export declare function classifier<M extends Metadata = Metadata>(input: {
  * @beta
  */
 export declare function resolver<M extends Metadata = Metadata>(corpus: Corpus<M>, kb: KnowledgeBase, config?: Config): Run;
-export type { Job, Normalized, Run, Settings };
+export type { ChunkSymbolExtractor, CreateChunkSymbolExtractor, Job, Normalized, Run, Settings, SymbolAnswer };

package/dist/public/index.js

@@ -11,7 +11,9 @@ import { TypeSafeClient } from "@typesafe-ai/sdk";
 * Query-only predicates are excluded.
 *
 * Called once when constructing a run, so unsupported predicates fail before reading
-* the corpus or calling Jev. Candidate combinations are built later, after filtering.
+* the corpus or calling Jev. Each field starts with the values known before any passage
+* is read: open-ended fields, and entity fields with no registered entities, start empty.
+* Candidate combinations are built later, after filtering.
 */
 function classifiablePredicates(access) {
 	const actions = /* @__PURE__ */ new Map();
@@ -30,10 +32,12 @@ function classifiablePredicates(access) {
 		};
 	});
 }
-/** Validate a finite field domain and collect its values. */
+/** Validate a field's type and collect the values known before reading any passage. */
 function fieldValues({ predicate, name, kb }) {
 	const type = predicate.params[name];
-	if (type === String || type === Number || type === Date || type === void 0) throw new UnsupportedPredicateError(`Cannot classify predicate "${predicate.name}": field "${name}" has an unsupported open-ended domain. Use Boolean, enumeration(...), or registered entities.`, predicate, name);
+	if (type === void 0) throw new UnsupportedPredicateError(`Invalid schema for ${predicate.name}: field "${name}" has no type`, predicate, name);
+	/** Open-ended fields take values only from passages. */
+	if (type === String || type === Number || type === Date) return [];
 	if (type === Boolean) return [false, true];
 	if (typeof type === "object") {
 		const kind = type.values[0] instanceof Date ? "date" : typeof type.values[0];
@@ -41,14 +45,57 @@ function fieldValues({ predicate, name, kb }) {
 		if (type.values.length === 0 || kind !== "string" && kind !== "number" && kind !== "date" || type.values.some((value) => (value instanceof Date ? "date" : typeof value) !== kind) || keys.some((key) => typeof key === "number" && Number.isNaN(key)) || new Set(keys).size !== type.values.length) throw new UnsupportedPredicateError(`Invalid enum domain for ${predicate.name}.${name}`, predicate, name);
 		return [...type.values];
 	}
-	const ids = kb.entities.ids(type);
-	if (ids.length === 0) throw new UnsupportedPredicateError(`No registered entities for ${predicate.name}.${name}`, predicate, name);
-	return ids.map((id) => {
+	return kb.entities.ids(type).map((id) => {
 		const entity = kb.entities.get(type, id);
 		if (entity === void 0) throw new Error("A registered entity domain was modified");
 		return entity;
 	});
 }
+// ../../packages/system-one/src/utils.ts
+/** Snapshot JSON data, including nested dates and entities identified by a string id. */
+function encode(value) {
+	const entities = /* @__PURE__ */ new WeakMap();
+	const json = JSON.stringify(value, (_, item) => {
+		if (!isRecord(item) || typeof item["id"] !== "string") return item;
+		let entity = entities.get(item);
+		if (entity === void 0) {
+			entity = {
+				...item,
+				type: typeof item.constructor === "function" ? item.constructor.name : "Object"
+			};
+			entities.set(item, entity);
+		}
+		return entity;
+	});
+	if (typeof json !== "string") throw new TypeError("Cannot encode a value without a JSON representation");
+	return JSON.parse(json);
+}
+/** A compact diagnostic label, using entity ids and the predicate's declared field order. */
+function formatAtom({ predicate, fields }) {
+	return `${predicate.name}(${predicate.paramNames.map((name) => format(fields[name])).join(", ")})`;
+}
+function format(value) {
+	if (value instanceof Date) return value.toISOString();
+	return isRecord(value) && "id" in value ? String(value["id"]) : String(value);
+}
+/**
+* Fail fast when an invariant breaks: a bug in Factbag, never bad input from the caller,
+* which gets a descriptive error of its own.
+*/
+function assert(condition, message) {
+	if (!condition) throw new Error(`Assertion failed: ${message}`);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** An entity value: an object with a string id, other than a Date. */
+function isEntity(value) {
+	return typeof value === "object" && value !== null && !(value instanceof Date) && "id" in value && typeof value.id === "string";
+}
+/** A finite probability, including both endpoints. */
+function isProbability(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
 // ../../packages/system-one/src/classifier/extract-evidence.ts
 /**
 * Assess the retained propositions against one passage and add admitted evidence to
@@ -68,6 +115,12 @@ async function extractEvidence({ chunk, predicates, symbols, config, kb }) {
 	})))).flat();
 	for (const { sign, atom, metadata } of evidence) if (sign === "+") kb.asserts(atom, metadata);
 	else kb.denies(atom, metadata);
+	/**
+	* Register the entities that written evidence mentions, so later readers of the KB can
+	* enumerate them. Extracted candidates that no evidence mentions stay unregistered.
+	* Identity is type and id, so an entity from several chunks is registered once.
+	*/
+	kb.entities.add(...evidence.flatMap(({ atom }) => Object.values(atom.fields)).filter((value) => isEntity(value)));
 }
 /**
 * Enumerate one predicate's candidate facts, have the model judge each against the passage,
@@ -124,6 +177,59 @@ function enumerateCandidateFacts({ predicate, symbols }) {
 		fields: values
 	}));
 }
+// ../../packages/system-one/src/classifier/extract-symbols.ts
+/**
+* Widen each retained predicate's open fields with the values this chunk offers. This is
+* the second pipeline step, after predicate filtering, so only fields of predicates the
+* passage may bear on are queried. Boolean and enumeration fields keep their declared
+* domains; entity fields keep their registered entities. Extracted entities are only
+* candidates: nothing is registered here. Fields may still be empty afterwards.
+*/
+async function extractSymbols({ chunk, predicates, createExtractor }) {
+	const requests = new Map(predicates.map(({ declaration }) => [declaration, openFields(declaration)]).filter(([, fields]) => fields.length > 0));
+	/** Nothing to ask builds no extractor. */
+	if (createExtractor === void 0 || requests.size === 0) return predicates;
+	const answer = await createExtractor([chunk]).query(requests);
+	assertAnswers(requests, answer);
+	return predicates.map((predicate) => ({
+		...predicate,
+		roles: Object.fromEntries(Object.entries(predicate.roles).map(([name, domain]) => [name, unique([...domain, ...answer.get(predicate.declaration)?.[name] ?? []])]))
+	}));
+}
+/** The fields whose values come from the passage: every field but Boolean and enumeration ones. */
+function openFields(predicate) {
+	return predicate.paramNames.filter((name) => {
+		const type = predicate.params[name];
+		return typeof type === "function" && type !== Boolean;
+	});
+}
+/**
+* The answer must cover exactly the requested predicates and fields, with values each
+* field can hold, so an extractor bug fails the job before anything is asked.
+*/
+function assertAnswers(requests, answer) {
+	for (const predicate of answer.keys()) if (!requests.has(predicate)) throw new TypeError(`Extracted symbols answer unrequested predicate "${predicate.name}"`);
+	for (const [predicate, fields] of requests) {
+		const values = answer.get(predicate);
+		if (values === void 0) throw new TypeError(`Extracted symbols omit requested predicate "${predicate.name}"`);
+		if (Object.keys(values).length !== fields.length || !fields.every((name) => Object.hasOwn(values, name))) throw new TypeError(`Extracted symbols for "${predicate.name}" must answer exactly its fields: ${fields.join(", ")}`);
+		for (const name of fields) {
+			const type = predicate.params[name];
+			if (!(values[name] ?? []).every((value) => holds(type, value))) throw new TypeError(`Extracted symbols for ${predicate.name}.${name} must be valid values of its type`);
+		}
+	}
+}
+/** Whether a field of this type can hold the value: a finite number, valid date, or own entity. */
+function holds(type, value) {
+	if (type === String) return typeof value === "string";
+	if (type === Number) return typeof value === "number" && Number.isFinite(value);
+	if (type === Date) return value instanceof Date && !Number.isNaN(value.getTime());
+	return isEntity(value) && value.constructor === type;
+}
+/** Drop structural duplicates, keeping the first occurrence. */
+function unique(values) {
+	return values.filter((value, index) => values.findIndex((other) => fieldEquals(value, other)) === index);
+}
 // ../../packages/system-one/src/classifier/filter-predicates.ts
 /** Retain the predicates relevant to this passage. This is the first pipeline step. */
 async function filterPredicates({ chunk, predicates, config }) {
@@ -162,11 +268,15 @@ function needsFiltering(predicates, config) {
 * 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. Without one, a predicate
+* with a field that has no values fails here.
 */
-function classifier$1({ corpus, input, config }) {
+function classifier$1({ corpus, input, config, createChunkSymbolExtractor }) {
 	const baselineKB = (input instanceof GuardedKB ? input : guard(input).permit("*")).fork();
 	const outputKB = baselineKB.kb.fork();
 	const predicates = classifiablePredicates(baselineKB);
+	if (createChunkSymbolExtractor === void 0) assertAskable(predicates);
 	const chunker = chunkers.recursive({
 		size: 8e3,
 		overlap: 200
@@ -174,16 +284,21 @@ function classifier$1({ corpus, input, config }) {
 	const jobs = corpus.documents().values().filter(() => predicates.length > 0).flatMap((document) => corpus.chunk(document, chunker)).map((chunk) => ({ execute: async () => await processChunk({
 		chunk,
 		predicates,
+		createExtractor: createChunkSymbolExtractor,
 		config,
 		kb: outputKB
 	}) }));
 	return Object.assign(jobs, { kb: outputKB });
 }
-async function processChunk({ chunk, predicates: inputPredicates, config, kb }) {
-	const predicates = await filterPredicates({
+async function processChunk({ chunk, predicates: inputPredicates, createExtractor, config, kb }) {
+	const predicates = await extractSymbols({
 		chunk,
-		predicates: inputPredicates,
-		config
+		predicates: await filterPredicates({
+			chunk,
+			predicates: inputPredicates,
+			config
+		}),
+		createExtractor
 	});
 	await extractEvidence({
 		chunk,
@@ -197,39 +312,25 @@ async function processChunk({ chunk, predicates: inputPredicates, config, kb })
 		kb
 	});
 }
-// ../../packages/system-one/src/utils.ts
-/** Snapshot JSON data, including nested dates and entities identified by a string id. */
-function encode(value) {
-	const entities = /* @__PURE__ */ new WeakMap();
-	const json = JSON.stringify(value, (_, item) => {
-		if (!isRecord(item) || typeof item["id"] !== "string") return item;
-		let entity = entities.get(item);
-		if (entity === void 0) {
-			entity = {
-				...item,
-				type: typeof item.constructor === "function" ? item.constructor.name : "Object"
-			};
-			entities.set(item, entity);
-		}
-		return entity;
-	});
-	if (typeof json !== "string") throw new TypeError("Cannot encode a value without a JSON representation");
-	return JSON.parse(json);
-}
-/** A compact diagnostic label, using entity ids and the predicate's declared field order. */
-function formatAtom({ predicate, fields }) {
-	return `${predicate.name}(${predicate.paramNames.map((name) => format(fields[name])).join(", ")})`;
-}
-function format(value) {
-	if (value instanceof Date) return value.toISOString();
-	return isRecord(value) && "id" in value ? String(value["id"]) : String(value);
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Throw for the first predicate with a field that has no values. Without a symbol
+* extractor, fields hold only the values known up front, so such a predicate could never
+* be asked about.
+*/
+function assertAskable(predicates) {
+	for (const { declaration, roles } of predicates) {
+		const name = emptyField({
+			declaration,
+			roles
+		});
+		if (name === void 0) continue;
+		const type = declaration.params[name];
+		throw new UnsupportedPredicateError(type === String || type === Number || type === Date ? `Cannot classify predicate "${declaration.name}": field "${name}" has an unsupported open-ended domain. Use Boolean, enumeration(...), registered entities, or a symbol extractor.` : `No registered entities for ${declaration.name}.${name}`, declaration, name);
+	}
 }
-/** A finite probability, including both endpoints. */
-function isProbability(value) {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+/** The first field, in declared order, with no values. */
+function emptyField({ declaration, roles }) {
+	return declaration.paramNames.find((name) => (roles[name] ?? []).length === 0);
 }
 // ../../packages/system-one/src/config.ts
 /** Default minimum probability for admitting signed evidence. @beta */
@@ -412,7 +513,7 @@ function systemOneModel(endpoint) {
 				judgement: choice(response, OUTCOMES, id, name)
 			})
 		})),
-		adjudicate: async ({ atom, passages }) => await ask({
+		adjudicate: async ({ atom, passages }) => passages.length === 0 ? [] : await ask({
 			endpoint,
 			prefix: "passage",
 			items: passages,
@@ -434,10 +535,12 @@ async function inBatches(items, size, request) {
 * Ask one question per item in a single request and turn each answer into a result.
 * Question keys are positional, so they are minted and matched only here. Validation
 * happens while building results, so one bad answer rejects the whole request.
-* Nothing to ask sends nothing; more than the provider allows sends nothing and throws.
+* Every request holds at least one question: callers send nothing when there is nothing
+* to ask, so an empty request is a bug. More than the provider allows sends nothing and
+* throws.
 */
 async function ask({ endpoint: { name, maxBatchSize, transport }, prefix, items, state, question, answer }) {
-	if (items.length === 0) return [];
+	assert(items.length > 0, `Asked ${name} an empty ${prefix} request`);
 	if (items.length > maxBatchSize) throw new RangeError(`Cannot ask ${items.length} ${prefix} questions in one request: ${name} accepts at most ${maxBatchSize}`);
 	const keyed = items.map((item, index) => ({
 		id: `${prefix}_${index}`,
@@ -584,10 +687,11 @@ function systemOne(provider) {
 			pipelines.set(normalized, resolved);
 			return normalized;
 		},
-		classifier: ({ corpus, input, config }) => classifier$1({
+		classifier: ({ corpus, input, config, createChunkSymbolExtractor }) => classifier$1({
 			corpus,
 			input,
-			config: pipeline(config)
+			config: pipeline(config),
+			createChunkSymbolExtractor
 		}),
 		resolver: (corpus, kb, config) => resolver$1(corpus, kb, pipeline(config))
 	};
@@ -613,6 +717,8 @@ function createConfig(config) {
 * 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
 */
 function classifier(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factbag/jev",
-  "version": "0.0.0-alpha.5",
+  "version": "0.0.0-alpha.6",
   "description": "Lazy AI-assisted classification and evidence resolution for Factbag.",
   "keywords": [
     "classification",
@@ -89,7 +89,7 @@
     "vitest": "5.0.5"
   },
   "peerDependencies": {
-    "factbag": "0.0.0-alpha.5",
+    "factbag": "0.0.0-alpha.6",
     "@typesafe-ai/sdk": "^0.7.0"
   },
   "scripts": {