Knowledge Bindings

[upstream]                 [knowledge engine]              [your script]
   ─────                       ────────                       ──────
attach features  ──►  match against knowledge sets  ──►  read items, dispatch

{
  id: string;                  // primary key of kdxa_knowledge_features
  uuid: string;                // stable UUID
  slug: string;                // computed from feature type + properties
  active: boolean;             // is_active column; not filtered server-side
  properties: object | null;   // free-form map; shape depends on featureType
  extendedProperties: object | null;  // free-form map; shape depends on featureType
  featureType: KnowledgeFeatureType | null;  // null if type was deleted
}

{
  slug: string;                // type identifier (lowercase by convention)
  name: string;                // display name
  description: string | null;  // long-form description
  icon: string | null;         // icon ref (e.g. "tag", "barcode")
  color: string | null;        // hex or theme colour ref
  options: KnowledgeOption[] | null;          // schema for `properties`
  extendedOptions: KnowledgeOption[] | null;  // schema for `extendedProperties`
  labelJsonPath: string | null;  // JSONPath / JSONata expression for human label
  useJSONata: boolean;           // true => labelJsonPath is JSONata, not JSONPath
}

{
  id: string;                  // KDDB-side identifier
  uuid: string;                // stable UUID
  slug: string;                // type-scoped slug
  title: string;               // display title
  description: string | null;  // long-form description
  active: boolean;             // is_active flag from the resolved set
  sequenceOrder: number;       // ordering hint within the type
  properties: object | null;   // free-form map; shape depends on itemType
  knowledgeSetId: string | null;  // owning knowledge set
  itemType: KnowledgeItemType | null;  // null if type was deleted
}

{
  slug: string;                // type identifier (lowercase by convention)
  name: string;                // display name
  description: string | null;  // long-form description
  options: KnowledgeOption[] | null;  // schema for `properties`
  supportsAttachment: boolean; // whether this type accepts file attachments
}

{
  name: string;                // property key
  type: string;                // "string", "boolean", "selection", ...
  label: string;               // display label
  description: string;         // help text
  required: boolean;
  default: any;
  possibleValues: any[];       // present for "selection" type
}

knowledge.<accessor> requires exactly one document family in scope (found N). Use knowledge.<explicit-accessor>(familyId) explicitly for multi-family scripts.

for (var i = 0; i < families.length; i++) {
  var fam = families[i];
  var feats = knowledge.getFeatures(fam.id);
  var route = knowledge.getItemsByType(fam.id, "processing-model")[0];
  // ...
}

knowledge: familyId "<id>" is not in scope for this script

var feats = knowledge.features;
// var enriched = feats[0];                  // frozen, can't assign new keys
// enriched.computed = "x";                  // throws in strict mode

var copy = Object.assign({}, feats[0], { computed: "x" });  // OK -- new object

var activeOnly = knowledge.features.filter(function (f) { return f.active; });
var activeRoutes = knowledge.itemsByType("processing-model").filter(function (it) { return it.active; });

var route = knowledge.itemsByType("processing-model")[0];
if (!route) {
  throw new Error("no processing-model resolved -- vendor missing or unmapped");
}
// safe to use route.properties from here on

var feats = knowledge.features;
for (var i = 0; i < feats.length; i++) {
  var slug = feats[i].featureType ? feats[i].featureType.slug : "(orphaned)";
  log.info("feature", feats[i].uuid, "type:", slug);
}

// Step 1 (upstream) emits the vendor feature from the family's metadata.
// Step 2 (this script step) reads the resolved processing-model item and
// returns a dispatch action.

const route = knowledge.itemsByType("processing-model")[0];
if (!route) {
    throw new Error("no processing-model resolved -- vendor missing or unmapped");
}

// route.properties is shaped by the processing-model item type's options:
//   { domain: "utilities", pipeline: "template", hasLineItemsTemplate: false }
switch (route.properties.pipeline) {
    case "template": return { action: "template_path" };
    case "llm":      return { action: "llm_path" };
    default:         return { action: "unknown" };
}

var dispatches = [];
for (var i = 0; i < families.length; i++) {
  var fam = families[i];
  var route = knowledge.getItemsByType(fam.id, "processing-model")[0];
  if (!route) {
    log.warn("no processing-model for family", fam.id);
    continue;
  }
  dispatches.push({ familyId: fam.id, pipeline: route.properties.pipeline });
}
return { dispatches: dispatches };

// Step 1: emit_features (script step, dependsOn: [])
// Read upstream metadata and emit a feature so the knowledge engine
// can resolve which items apply to this document.
var doc = loadDocument(families[0].id);
var vendorId = (doc.metadata || {})["CustomFields.PrimaryVendorId"];
if (!vendorId) {
  throw new Error("PrimaryVendorId missing -- intake metadata is incomplete");
}
return {
  action: "ok",
  features: [{
    documentFamilyId: families[0].id,
    featureTypeSlug: "vendor",
    properties: { vendorId: String(vendorId) }
  }]
};

// Step 2: classify_path (script step, dependsOn: [emit_features, ocr])
// AssessAndEnrich has run between the two steps. Read the resolved item.
var route = knowledge.itemsByType("processing-model")[0];
if (!route) {
  // Useful fallback: keep the legacy path active until coverage is complete.
  log.warn("No processing-model resolved; falling back to template_single");
  return { action: "template_single" };
}
switch (route.properties.pipeline) {
  case "template": return { action: "template_path" };
  case "llm":      return { action: "llm_path" };
  default:         return { action: "unknown" };
}

// Before: vendor-specific knowledge baked into the script
var TEMPLATE_VENDORS = ["VEN-001", "VEN-005", "VEN-018"];
var LINE_ITEM_VENDORS = ["VEN-002", "VEN-018"];
if (TEMPLATE_VENDORS.indexOf(vendorId) >= 0) { /* ... */ }

// After: read the vendor's processing-model item; let knowledge sets resolve it
var route = knowledge.itemsByType("processing-model")[0];
if (route && route.properties.pipeline === "template") {
  // ...
  if (route.properties.hasLineItemsTemplate) { /* ... */ }
}

// Skip OCR if the document has already been classified as machine-readable upstream.
var classifications = knowledge.featuresByType("document-classification");
var alreadyOCRed = classifications.some(function (f) {
  return f.properties.layer === "text-extracted";
});
if (alreadyOCRed) {
  return { action: "skip_ocr" };
}

var dispatches = [];
for (var i = 0; i < families.length; i++) {
  var fam = families[i];
  var route = knowledge.getItemsByType(fam.id, "processing-model")[0];
  if (!route) {
    log.warn("no processing-model for family", fam.id);
    continue;
  }
  dispatches.push({ familyId: fam.id, pipeline: route.properties.pipeline });
}
return { action: "dispatched", count: dispatches.length, items: dispatches };

var feats = knowledge.features;
var items = knowledge.items;
log.info("knowledge state",
  "features", feats.length,
  "items", items.length,
  "byType", items.reduce(function (acc, it) {
    var t = it.itemType ? it.itemType.slug : "(orphaned)";
    acc[t] = (acc[t] || 0) + 1;
    return acc;
  }, {})
);
return { action: "audited" };