@lexbuild/usc

This package is part of the LexBuild monorepo, a tool that converts U.S. legislative XML into structured Markdown optimized for AI, RAG pipelines, and semantic search. See the monorepo for full documentation, architecture details, and contribution guidelines.

It converts official USLM XML from the Office of the Law Revision Counsel (OLRC) into structured Markdown. It also provides a downloader for fetching the XML directly from OLRC.

Install

npm install @lexbuild/usc

Usage

Convert a Title

import { convertTitle } from "@lexbuild/usc";

const result = await convertTitle({
  input: "./downloads/usc/xml/usc01.xml",
  output: "./output",
  granularity: "section",
  linkStyle: "plaintext",
  includeSourceCredits: true,
  includeNotes: true,
  includeEditorialNotes: false,
  includeStatutoryNotes: false,
  includeAmendments: false,
  dryRun: false,
});

console.log(`Wrote ${result.sectionsWritten} sections`);
console.log(`Chapters: ${result.chapterCount}`);
console.log(`Estimated tokens: ${result.totalTokenEstimate}`);

Download Titles from OLRC

import { downloadTitles } from "@lexbuild/usc";

// Download specific titles
const result = await downloadTitles({
  outputDir: "./downloads/usc/xml",
  titles: [1, 5, 26],
});

// Download all 54 titles (uses a single bulk zip)
const all = await downloadTitles({
  outputDir: "./downloads/usc/xml",
});

console.log(`Downloaded ${result.files.length} files`);
console.log(`Release point: ${result.releasePoint}`);

API Reference

Functions

Export	Description
`convertTitle(options)`	Convert a USC XML file to section-level Markdown
`downloadTitles(options)`	Download USC XML from OLRC
`buildDownloadUrl(titleNumber, releasePoint)`	Build URL for a single title zip
`buildAllTitlesUrl(releasePoint)`	Build URL for the bulk zip
`releasePointToPath(releasePoint)`	Convert release point to URL path segment
`isAllTitles(titles)`	Check if a title list covers all 54 titles

Types

Export	Description
`ConvertOptions`	Options for `convertTitle()`
`ConvertResult`	Result of a conversion (sections, chapters, tokens, files)
`DownloadOptions`	Options for `downloadTitles()`
`DownloadResult`	Result of a download (files, errors, release point)
`DownloadedFile`	Info about a downloaded file (title, path, size)
`DownloadError`	Info about a failed download

Constants

Export	Description
`CURRENT_RELEASE_POINT`	Current OLRC release point (e.g., `"119-73not60"`)
`USC_TITLE_NUMBERS`	Array of valid title numbers (1-54)

Output

Each title produces a directory tree of Markdown files with YAML frontmatter and JSON metadata indexes:

output/usc/title-01/
  README.md
  _meta.json
  chapter-01/
    _meta.json
    section-1.md
    section-2.md
  chapter-02/
    _meta.json
    section-101.md

See the output format specification for details.

Documentation

License

MIT