kaos-core

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-core is the foundational runtime for KAOS modules — an MCP-native type system, runtime container, registries, execution engine, agent primitives, and virtual filesystem.

It is the dependency-light base every other kaos-* package builds on. kaos-core does not run servers, talk to LLMs, or extract documents — companion packages do those things. This package is what makes them all consistent.

To expose kaos-core runtimes over the Model Context Protocol, add the companion package kaos-mcp (ships separately).

Install

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

kaos-core requires Python 3.13 or newer and has only three runtime dependencies (click, pydantic, pydantic-settings).

Quick start

Define a tool, register it on a runtime, and execute it:

import asyncio

from kaos_core import (
    KaosRuntime,
    ToolAnnotations,
    ToolCapability,
    ToolCategory,
    kaos_tool,
)


@kaos_tool(
    name="kaos-demo-square",
    description="Square an integer",
    category=ToolCategory.DATA,
    capability=ToolCapability.TRANSFORM,
    annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True),
    auto_register=False,
)
async def square(value: int) -> int:
    return value * value


async def main() -> None:
    runtime = KaosRuntime()
    runtime.tools.register_tool(square)

    tool = runtime.tools.get_tool("kaos-demo-square")
    result = await tool.execute({"value": 7})
    print(result.text)  # "49"


asyncio.run(main())

Inputs are checked against the JSON Schema generated from your type hints for required fields, unexpected fields, primitive types, literal enum values, and list item types — tool.execute({"value": "not-int"}) raises ValidationError before reaching the function body.

Concepts

The package is built around six small, composable primitives.

CLI

kaos-core ships a kaos-core administrative CLI. Every command supports --json for machine-readable output:

kaos-core tools list                              # registered tools
kaos-core tools search "pdf" --category document  # search by query + facet
kaos-core artifacts list --session my-session     # stored artifacts
kaos-core config show                             # runtime settings (with secrets redacted)
kaos-core vfs ls /artifacts/ --cursor 100         # paginated VFS contents

Compatibility & status

Companion packages

kaos-core 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-core
cd kaos-core
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_core tests
uv run ruff check kaos_core tests
uv run ty check kaos_core tests
uv run pytest -m "not live and not network and not slow" --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 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.