kaos-source

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-source is the source discovery and materialization layer for KAOS — filesystem, archive, HTTP, and browser transport connectors, plus REST clients for the Federal Register, eCFR, EDGAR, GovInfo, and GLEIF, and forensic parsers for VCard, EML / MBOX email, PACER docket HTML, and image EXIF.

It is the layer between "I have a URL / path / docket number" and "give me a typed SourceDescriptor plus an artifact handle in kaos-core's VFS." Every fetch goes through a strict-by-default SSRF guard, every response body is size-capped, every archive iteration enforces decompression-ratio and symlink protection. Configurability lives in KAOS_SECURITY_* and KAOS_SOURCE_* env vars.

The base install carries only httpx, kaos-core, and pydantic — most of the heavy lifting (lxml, pillow, playwright, kaos-content, kaos-nlp-core) is gated behind opt-in extras ([browser], [content], [pacer]).

Install

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

Optional extras (all additive — none of the base functionality requires them):

uv add 'kaos-source[browser]>=0.1.0'   # Playwright-backed browser fetches
uv add 'kaos-source[content]>=0.1.0'   # parse-into-ContentDocument bridges
uv add 'kaos-source[pacer]>=0.1.0'     # lxml-backed PACER docket parser

kaos-source requires Python 3.13 or newer.

Quick start

Discover, preview, and materialize a local file through the in-memory SourceService:

import asyncio
from pathlib import Path

from kaos_core import KaosContext, KaosRuntime
from kaos_core.protocol.roots import Root
from kaos_source import (
    SourceDiscoverOptions,
    SourceLocator,
    SourcePreviewOptions,
    SourceService,
)


async def main() -> None:
    runtime = KaosRuntime()
    service = SourceService()  # registers the five default connectors
    workspace = Path.cwd()
    context = KaosContext.create(
        session_id="quickstart",
        runtime=runtime,
        roots=[Root(uri=workspace.as_uri(), name="cwd")],
    )

    page = await service.discover(
        SourceLocator.filesystem(workspace),
        context,
        SourceDiscoverOptions(limit=5, patterns=["*.py"]),
    )
    print([item.name for item in page.items])

    if page.items:
        preview = await service.preview(
            page.items[0].locator,
            context,
            SourcePreviewOptions(max_bytes=120),
        )
        print(preview.text_preview)


asyncio.run(main())

The same SourceService API also handles archive://, http(s)://, browser://, and memory:// locators — only the Root allowlist and the SSRF guard change behaviour per scheme.

Concepts

The package is organized around three layers — contracts, runtime, and domain-specific catalogues — that auto-register on import.

CLI

kaos-source ships a kaos-source administrative CLI plus a kaos-source-serve MCP launcher. Every structured command supports --json for machine-readable output:

kaos-source discover ./data/ --recursive --pattern "*.pdf"  # list sources
kaos-source preview document.pdf --max-bytes 2048           # bounded preview
kaos-source info document.pdf --json                        # source metadata
kaos-source materialize document.pdf --name my-artifact     # stage to artifact store
kaos-source inspect-archive bundle.zip                      # list archive members

kaos-source-serve --http --port 8765                        # MCP server (stdio default)

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-source 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-source
cd kaos-source
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_source tests
uv run ruff check kaos_source tests
uv run ty check kaos_source tests
uv run pytest tests/unit --no-cov

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.