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.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | file | RepoPath | yes | The 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. |
| in | outdir | RepoPath | Library 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. | |
| in | dryRun | Flag | Report the chosen rung and stop. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| out | slug | Slug | The 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:
| process | step | lane | via skill |
|---|---|---|---|
| Content acquisition | Route it, and watch the queue | Agent | library-ingestion |
| Basic ingestion — an upload to an asset catalogued in library/ | [Place the asset in library/ | Ingestion Engine (agent, runs unattended) | library-ingestion |
| Basic ingestion — an upload to an asset catalogued in library/ | Record it in library/ as referenced | Ingestion Engine (agent, runs unattended) | library-ingestion |
| L1 document ingestion — a document to the L1 source knowledge graph | Basic ingestion (harness) | Ingestion Engine (agent, runs unattended) | library-ingestion |
| DTH authoring | 1 · Ingest sources into library/ | Librarian | library-ingestion |
How it is deployed and reached
- Command line. From the repository root:
bun run cat ingest.cat ingestrunsbun run cat-harness-tools/scripts/ingest-document.ts(declared incat-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.
| install | none |
| runtime | python3 |
| network | no |
| when to choose it | |
|---|---|
| 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. |
Alternatives (same signature, a shared skill): ingest-extended.
What it is made of
| role | file | |
|---|---|---|
| definition | cat-harness/tools/ingest-stdlib/ingest-stdlib.json | |
| script | cat-harness-tools/scripts/ingest-document.ts |
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."
}
}