Ingest, standard library only

Ingest an upload into library/ using only the Python standard library — archive listings, CSV and spreadsheet records, technical file metadata, and the content sniff that routes a file to its rung.

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.

library-ingestion

The BASIC ingestion flow every asset takes: an upload is accepted, its metadata goes into the knowledge graph, and the asset lands in library/<slug>/ if it is materialized. The two entry points (a drop in uploads/, or materializing an asset a remote graph lists), what happens to the upload afterwards, and why content-type methods refine this flow from above rather than living in it. Command: bun run cat ingest.

Source: cat-harness/library/skills/library-core/library-ingestion.md.

Also satisfied by: ingest-extended, l1-complete-check, narrative-queue, openapi-ingest-rendered, openapi-ingest-source, transcribe-faster-whisper, transcribe-vosk, transcribe-whisper-cpp.

The skill declares no I/O contract (schemas/skills/library-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
infileRepoPathyesThe upload to ingest, under the declared uploads graph.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inoutdirRepoPathLibrary root; defaults to the declared library graph.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
indryRunFlagReport the chosen rung and stop.boolean · A boolean switch — projects to a bare flag, with no value word
outslugSlugThe library entry written.string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe

Processes and tasks

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

processsteplanevia skill
Content acquisitionRoute it, and watch the queueAgentlibrary-ingestion
Basic ingestion — an upload to an asset catalogued in library/[Place the asset in library//](../../../processes/document-ingestion.html#step-Task_PlaceInLibrary)Ingestion Engine (agent, runs unattended)library-ingestion
Basic ingestion — an upload to an asset catalogued in library/Record it in library/ as referencedIngestion Engine (agent, runs unattended)library-ingestion
L1 document ingestion — a document to the L1 source knowledge graphBasic ingestion (harness)Ingestion Engine (agent, runs unattended)library-ingestion
DTH authoring1 · Ingest sources into library/Librarianlibrary-ingestion

How it is deployed and reached

  • Command line. From the repository root: bun run cat ingest. cat ingest runs bun run cat-harness-tools/scripts/ingest-document.ts (declared in cat-harness-tools/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
runtimepython3
networkno
when to choose it
whenReach for this first, and in CI always. It is the only one of the pair that runs where nothing has been installed — which is every fresh container and every CI job here, since the workflow installs ruff and nothing else. It covers archives, CSV and spreadsheets, technical metadata, and the sniff that decides which rung a file takes, including the OOXML/ODF container check that stops a workbook being listed as a bag of XML parts.
limitsIt cannot read a PDF. Text layer, embedded outline, page rendering, OCR and image extraction all need a backend it deliberately does not have, so a PDF routes to undetermined and is REFUSED rather than half-ingested. ingest-extended is the sibling that does those.
costNone beyond python3 itself. No wheels, no C toolchain, no network, nothing to keep current, and no CI minutes spent installing.

Alternatives (same signature, a shared skill): ingest-extended.

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/cat-harness/tools/ingest-stdlib.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/cat-harness/cat-harness.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/cat-harness/tools/ingest-stdlib.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.jsonld",
  "name": "ingest-stdlib",
  "title": "Ingest, standard library only",
  "description": "Ingest an upload into `library/` using only the Python standard library — archive listings, CSV and spreadsheet records, technical file metadata, and the content sniff that routes a file to its rung.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run cat ingest"
  },
  "io": {
    "inputs": [
      {
        "name": "file",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The upload to ingest, under the declared `uploads` graph.",
        "required": true,
        "arg": {
          "positional": 0
        }
      },
      {
        "name": "outdir",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Library root; defaults to the declared `library` graph.",
        "required": false,
        "arg": {
          "flag": "--outdir"
        }
      },
      {
        "name": "dryRun",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
        "description": "Report the chosen rung and stop.",
        "required": false,
        "arg": {
          "flag": "--dry-run"
        }
      }
    ],
    "outputs": [
      {
        "name": "slug",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
        "description": "The library entry written."
      }
    ]
  },
  "satisfies": [
    "library-ingestion"
  ],
  "requirements": {
    "runtime": [
      "python3"
    ],
    "network": false
  },
  "selection": {
    "when": "Reach for this first, and in CI always. It is the only one of the pair that runs where nothing has been installed — which is every fresh container and every CI job here, since the workflow installs `ruff` and nothing else. It covers archives, CSV and spreadsheets, technical metadata, and the sniff that decides which rung a file takes, including the OOXML/ODF container check that stops a workbook being listed as a bag of XML parts.",
    "limits": "It cannot read a PDF. Text layer, embedded outline, page rendering, OCR and image extraction all need a backend it deliberately does not have, so a PDF routes to `undetermined` and is REFUSED rather than half-ingested. `ingest-extended` is the sibling that does those.",
    "cost": "None beyond `python3` itself. No wheels, no C toolchain, no network, nothing to keep current, and no CI minutes spent installing."
  }
}

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