kaos-office

Part of Kelvin Agentic OS (KAOS) — open agentic infrastructure for legal work, built by 273 Ventures. See the full KAOS package map for the rest of the stack.

kaos-office is the Office-document layer of KAOS — it turns Microsoft Office files (.docx, .pptx, .xlsx) into typed kaos-content AST models with provenance, and turns those models back into round-trip-fidelity Office files. DOCX and PPTX produce ContentDocument (Block / Inline flow content with headings, paragraphs, lists, tables, footnotes, annotations, tracked changes, and per-section page setup); XLSX produces TabularDocument (typed columns over a 13-type ColumnType system, one Table per sheet, formulas and merged ranges preserved as metadata). The package also ships 18 read / write MCP tools and a 13-subcommand admin CLI for agentic workflows.

The base install is intentionally small — four runtime dependencies (kaos-content[markdown], kaos-core, lxml, python-pptx) and no compiled native code beyond the lxml wheel. DOCX and XLSX read / write paths use lxml directly so they stay symmetric; PPTX read / write goes through python-pptx (MIT) — both parse_pptx() and write_pptx() work without any extras. [pptx] is now a no-op alias kept for backwards compatibility. [xlsx] aggregates python-calamine (MIT, Rust — 7-28× faster XLSX read) and openpyxl (MIT, formula extraction) — pick [xlsx-calamine] or [xlsx-formulas] individually if you want only one. We do not and will not depend on AGPL or GPL libraries.

Install

uv add "kaos-office>=0.1.0"
# or
pip install "kaos-office>=0.1.0"

# PPTX writer (python-pptx)
uv add 'kaos-office[pptx]>=0.1.0'

# Calamine XLSX fast-path + openpyxl formula extraction
uv add 'kaos-office[xlsx]>=0.1.0'

# BM25 sentence-level search via kaos-nlp-core
uv add 'kaos-office[nlp]>=0.1.0'

kaos-office requires Python 3.13 or newer (3.14 is supported). The package is pure Python — the only native code is the lxml wheel, which has prebuilt wheels for Linux, macOS, and Windows on x86_64 and arm64.

Quick start

Read a DOCX into the AST, render it as markdown, and search it; then read an XLSX as a typed tabular document:

from kaos_office import (
    extract_to_markdown,
    parse_docx,
    parse_pptx,
    search_document,
)
from kaos_office.xlsx import list_sheets, parse_xlsx

# DOCX → ContentDocument with Block/Inline + provenance on every node
doc = parse_docx("contract.docx")
print(len(doc.body), "top-level blocks")
print(doc.metadata.title, doc.metadata.source.uri)

# Same shape for PPTX (each slide becomes a Div(classes="slide"))
deck = parse_pptx("brief.pptx")
print(deck.metadata.extra.get("slide_count"), "slides")

# AST-grounded search — paragraph-level by default
hits = search_document(doc, "indemnification", top_k=5)
for hit in hits.results:
    print(f"score={hit.score:.2f} :: {hit.text[:80]}")

# XLSX → TabularDocument (one Table per sheet, typed columns)
tab = parse_xlsx("report.xlsx")
for table in tab.tables:
    print(f"{table.name}: {table.row_count} rows × {len(table.columns)} cols")
print(list_sheets("report.xlsx"))  # cheap workbook metadata, no parse

# Format-agnostic shortcut: any of the three → markdown
print(extract_to_markdown("contract.docx")[:200])

Every node in the returned ContentDocument carries a Provenance (source URI, page or slide number, char span, extractor name) so downstream consumers — citation verifiers, redaction tooling, labelers — can ground answers back to the original file.

Concepts

The package is a thin, typed surface over the OOXML wire format. The most important entries:

CLI

kaos-office ships two entry-point scripts. Every structured command on the admin CLI supports --json for machine-readable output piped to other agents:

kaos-office --help                                  # admin CLI
kaos-office-serve --help                            # MCP server

# DOCX
kaos-office extract contract.docx -f markdown       # AST → markdown / text / json / html
kaos-office search contract.docx "indemnification"  # AST-grounded ranked search
kaos-office metadata contract.docx --json           # title, author, page setup, sections

# PPTX
kaos-office pptx-extract brief.pptx -f markdown
kaos-office pptx-slides brief.pptx --json           # slide inventory (number, title, layout)
kaos-office pptx-slide brief.pptx 3                 # text from a single slide (1-based)

# XLSX
kaos-office xlsx-extract report.xlsx -f markdown    # tabular markdown
kaos-office xlsx-sheets report.xlsx --json          # sheet names + dimensions
kaos-office xlsx-sheet report.xlsx Revenue          # one sheet as TSV

# Writers (JSON file or '-' for stdin)
kaos-office write-docx body.json out.docx --force
kaos-office write-pptx body.json out.pptx --template brand.pptx
kaos-office write-xlsx tabular.json out.xlsx

kaos-office-serve                                   # stdio (Claude Code / Desktop)
kaos-office-serve --http --port 8000                # streamable HTTP

The admin CLI uses 1-based slide / page numbers (consistent with how the file opens in any viewer) and translates internally to the 0-based indices the Python API uses. kaos-office-serve exposes the 18 MCP tools listed in Concepts above.

Compatibility & status

Documentation

Per-package reference: see in-tree docstrings and CHANGELOG.md.

Cross-cutting KAOS guides (agentic patterns, persona presets, settings policy, citations, MCP data flow, migration to 0.1.0 GA) live in kaos-modules/docs/guides/.

Companion packages

kaos-office is one of the packages in the Kelvin Agentic OS. The broader stack:

Packages depend on kaos-core; everything else is opt-in. Mix and match the ones you need.

Development

git clone https://github.com/273v/kaos-office
cd kaos-office
uv sync --group dev

Install pre-commit hooks (recommended — they run the same checks as CI on every commit, scoped to staged files):

uvx pre-commit install
uvx pre-commit run --all-files     # one-time full sweep

Manual QA commands (the same set CI runs):

uv run ruff format --check kaos_office tests
uv run ruff check kaos_office tests
uv run ty check kaos_office tests
uv run pytest tests/unit -q --no-cov

Build from source

uv build
uv pip install dist/*.whl
python -c "import kaos_office; print(kaos_office.__version__)"  # smoke import

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, quality gates, pull request expectations, and engineering standards. By contributing you agree to follow the project conduct expectations and certify the Developer Certificate of Origin v1.1 — sign every commit with git commit -s. Please open an issue before starting on a non-trivial change so we can align on scope.

Security

For security issues, please do not file a public issue. Report privately via GitHub Private Vulnerability Reporting or email security@273ventures.com. See SECURITY.md for the full disclosure policy.

License

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 273 Ventures LLC. Built for kelvin.legal.