Reference lists to reference nodes

Split each library entry’s reference lists (a References, Bibliography or Further reading section or heading, in the six UN languages and Portuguese) into folio-reference/v1 nodes in the instance’s declared references directory, one per cited work, keyed <doc-id>.<section>.<n>: provenance extracted, derivedFrom the section file, printed the entry verbatim, and only the fields read without guessing (URL, DOI, ISBN, year, access date). The bibliography page lists them as the document’s own bibliography. --check writes nothing and fails when a node is stale.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

l1-document-ingestion

The detailed method for turning a DOCUMENT in uploads/ into a complete L1 entry in library/<bib-slug>/ — which rung reads it and why, what a complete L1 entry holds, why an inferred structure is refused rather than guessed, and the archive, dataset, narrative, image and vector-label arms. Refines the harness’s basic library-ingestion flow; one entry point: bun run cat ingest.

Source: folio-assistant-core/skills/library/ingestion/l1-document-ingestion.md.

The skill declares no I/O contract (schemas/skills/l1-document-ingestion/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
ininstanceRepoPathyesThe instance root whose library sections are read and whose references directory is written.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inentryRepoPathOne library entry’s slug, to extract only its lists.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
incheckFlagFail if a node is stale, instead of writing.boolean · A boolean switch — projects to a bare flag, with no value word
outreferencesRepoPathThe extracted reference nodes: <references dir>/<doc-id>.<section>.<n>.json.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
L1 document ingestion — a document to the L1 source knowledge graphL1 completeness gateIngestion Engine (agent, runs unattended)l1-document-ingestion
L1 document ingestion — a document to the L1 source knowledge graphSummarise prose blocks, in every languageIngestion Engine (agent, runs unattended)l1-document-ingestion
L1 document ingestion — a document to the L1 source knowledge graphRecord errata in the source’s own textIngestion Engine (agent, runs unattended)l1-document-ingestion
Ingestion subprocess — build the L1 knowledge graphExtract reference listsIngestion Engine (agent, runs unattended)l1-document-ingestion
Ingestion subprocess — derive content from the assetsFootnotes and the marks that call themIngestion Engine (agent, runs unattended)l1-document-ingestion
Ingestion subprocess — extract structureCheck each page; OCR pages that failIngestion Engine (agent, runs unattended)l1-document-ingestion
DTH authoringExtract L1 from WHO publicationsLibrarianl1-document-ingestion

How it is deployed and reached

  • Command line. From the repository root: bun run cat references:extract. cat references:extract runs bun run folio-assistant-core/scripts/references-extract.ts (declared in folio-assistant-core/package.json).
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkno
when to choose it
whenA library entry’s source prints a reference list and the document should have its own bibliography. For glossary and abbreviations sections use glossary-from-source.
limitsReads L1 sections, not the PDF; no title or author is parsed (the node keeps the printed text). Only nodes with provenance extracted are written or removed.
costSeconds for a few hundred entries; reads sections, no network.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/references-extract.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/references-extract.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
  "name": "references-extract",
  "title": "Reference lists to reference nodes",
  "description": "Split each library entry's reference lists (a References, Bibliography or Further reading section or heading, in the six UN languages and Portuguese) into folio-reference/v1 nodes in the instance's declared `references` directory, one per cited work, keyed `<doc-id>.<section>.<n>`: provenance extracted, derivedFrom the section file, printed the entry verbatim, and only the fields read without guessing (URL, DOI, ISBN, year, access date). The bibliography page lists them as the document's own bibliography. `--check` writes nothing and fails when a node is stale.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run cat references:extract"
  },
  "io": {
    "inputs": [
      {
        "name": "instance",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The instance root whose library sections are read and whose references directory is written.",
        "required": true,
        "arg": {
          "flag": "--instance"
        }
      },
      {
        "name": "entry",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "One library entry's slug, to extract only its lists.",
        "required": false,
        "arg": {
          "flag": "--entry"
        }
      },
      {
        "name": "check",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Fail if a node is stale, instead of writing.",
        "required": false,
        "arg": {
          "flag": "--check"
        }
      }
    ],
    "outputs": [
      {
        "name": "references",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The extracted reference nodes: `<references dir>/<doc-id>.<section>.<n>.json`."
      }
    ]
  },
  "satisfies": [
    "l1-document-ingestion"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "A library entry's source prints a reference list and the document should have its own bibliography. For glossary and abbreviations sections use glossary-from-source.",
    "limits": "Reads L1 sections, not the PDF; no title or author is parsed (the node keeps the printed text). Only nodes with provenance extracted are written or removed.",
    "cost": "Seconds for a few hundred entries; reads sections, no network."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev