@tarogo/document-ir

Portable TypeScript types and utilities for structured document IR.

The package is designed for applications that need to exchange, validate, inspect, or transform structured document data. The root import is browser-safe and has no dependency on a backend, database, storage service, Admin configuration, or a particular document parser.

Install

npm install @tarogo/document-ir

Core usage

import {
  buildDocumentOutline,
  documentIrToSectionDocument,
  validateDocumentIr,
  type StructuredDocumentIr
} from "@tarogo/document-ir";

const validation = validateDocumentIr(input);
if (!validation.ok) {
  console.warn(validation.issues);
}

const ir = input as StructuredDocumentIr;
const outline = buildDocumentOutline(ir);
const sections = documentIrToSectionDocument(ir);

The package does not persist documents, publish records, register sources, or decide how locators are resolved. Consumers own storage, permissions, parser configuration, and application-specific derived data.

New producers should use the generic document-ir schema name. The historical aiqc-document-ir name remains valid for existing payloads:

import {
  DOCUMENT_IR_LEGACY_SCHEMA_NAME,
  DOCUMENT_IR_PUBLIC_DEFAULTS,
  DOCUMENT_IR_SCHEMA_NAME,
  isDocumentIrSchemaName
} from "@tarogo/document-ir";

const documentDefaults = DOCUMENT_IR_PUBLIC_DEFAULTS;
const schemaName = documentDefaults.schema_name;
isDocumentIrSchemaName(input.schema_name); // true for public and legacy names
// DOCUMENT_IR_LEGACY_SCHEMA_NAME is "aiqc-document-ir".

Contract boundary

The package provides a stable JSON-oriented contract for documents, nodes, sections, chunks, tables, source spans, source anchors, parse quality, and parse issues. It is intentionally separate from any parser implementation. A parser may produce this IR, while an editor, quality checker, knowledge service, or export pipeline may consume it.

The 1.x package is core-only. Parser consumers should install the separately released @tarogo/document-ir-parser adapter. The historical 0.2.x package line included a Node/Python parser bridge; that published line remains available for existing consumers but is no longer part of the core source package.

Compatibility

The package can validate IR produced by other runtimes as long as the payload satisfies the public contract. Existing aiqc-document-ir payloads remain supported as a compatibility profile, and producer-specific schema names are accepted as opaque strings without being treated as package-owned profiles. The package does not require consumers to use the AIQC backend or its storage model.

Publishing from the current monorepo location

The package source currently remains at packages/document-ir in the jb-aigc-aiqc repository. This is a temporary source location, not a runtime dependency requirement for the AIQC backend. The parser adapter source is maintained separately at packages/document-ir-parser; the later move of both packages to an independent repository and release pipeline is tracked separately.

cd packages/document-ir
npm.cmd install
npm.cmd run check
npm.cmd test
npm.cmd pack --dry-run
npm.cmd publish --access public

Before publishing, verify that the tarball contains no customer documents, private configuration, credentials, or project-specific runtime artifacts. This package is released under the MIT License; the included LICENSE file and license: MIT metadata must remain in sync.