kaos-content

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-content is the canonical document model for KAOS — a typed Block/Inline AST with provenance, annotations, views, and round-trip serializers.

Every KAOS document processor (kaos-pdf, kaos-office, kaos-web) produces a ContentDocument; every downstream consumer (search, chunking, LLM programs, MCP resources) reads one. The shape is inspired by Pandoc's Block/Inline discipline and Docling's provenance model. kaos-content does not parse PDFs, fetch URLs, or call LLMs — companion packages do. This package is what makes them interoperable.

To expose kaos-content parsers and serializers over MCP, add the companion package kaos-mcp.

Install

uv add kaos-content
# or
pip install kaos-content

kaos-content requires Python 3.13 or newer. Optional extras unlock specific capabilities:

Quick start

Build a small document, serialize it, search it, and walk its sections:

from kaos_content.model.document import ContentDocument
from kaos_content.model.metadata import DocumentMetadata
from kaos_content.shortcuts import bold, heading, link, paragraph, text
from kaos_content.search import search_document
from kaos_content.serializers.markdown import serialize_markdown
from kaos_content.serializers.html import serialize_html
from kaos_content.views.document_view import DocumentView

doc = ContentDocument(
    metadata=DocumentMetadata(title="Hello"),
    body=(
        heading(1, "Hello, KAOS"),
        paragraph(
            text("Built on a "),
            bold("typed AST"),
            text(" with "),
            link("https://kelvin.legal", "provenance"),
            text("."),
        ),
    ),
)

print(serialize_markdown(doc))
# # Hello, KAOS
#
# Built on a **typed AST** with [provenance](https://kelvin.legal).

print(serialize_html(doc, allow_raw_html=False))
# <h1>Hello, KAOS</h1><p>Built on a <strong>typed AST</strong> with
# <a href="https://kelvin.legal">provenance</a>.</p>

results = search_document(doc, "typed AST", top_k=5)
for r in results.results:
    print(r.score, r.block_ref, r.text[:80])

for section in DocumentView(doc).flat_sections:
    print(section.heading_text, section.heading_ref)

The AST is constructed entirely from frozen Pydantic models — every field is type-validated at construction time, content-model constraints (blocks contain blocks or inlines, never mixed) are enforced before a node ever reaches a serializer, and the same ContentDocument round-trips losslessly through JSON via model_dump_json() / model_validate_json().

Concepts

The package is built around nine composable primitives.

Compatibility & status

Security model

kaos-content ships safe-by-default serializers and bridges. The contract:

See SECURITY.md for the disclosure policy and threat model.

MCP tools

kaos-content registers 17 MCP tools through kaos_content.tools.register_content_tools(runtime) (count enforced by tests/unit/test_tools.py::TestRegistration to prevent README drift):

Configuration

kaos-content has no module-level environment variables — its public APIs are all in-process. Settings that affect behaviour are documented inline at the call site (MAX_IMAGE_PIXELS, DEFAULT_LOAD_IMAGE_MAX_BYTES, allow_raw_html, untrusted_sql).

Companion packages

kaos-content 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-content
cd kaos-content
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_content tests
uv run ruff check kaos_content tests
uv run ty check kaos_content tests
uv run pytest -m "not live and not network and not slow"

Build from source

uv build
uv pip install dist/*.whl

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.