kaos-names

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-names is a tiny, dependency-free Python package that mints friendly, legal-flavored handles such as sunny-docket-07 for sessions, traces, demo data, jobs, attorney/judge avatars, and short-lived agent workspaces. The default vocabulary is curated to be memorable, easy to say out loud, and free of pejorative or obscure terms — names show up next to real users in the KAOS web app, so they need to feel friendly, not backhanded.

The package has zero runtime dependencies and only uses the Python standard library. It exposes a stable vocabulary, a deterministic testing hook through random.Random, and a CLI that emits plain text or JSON. The default vocabulary has 120 friendly descriptors and 327 slug-safe legal terms — 3,884,760 possible default names before random collision.

Install

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

kaos-names requires Python 3.13 or newer and runs on Linux, macOS, and Windows from a single pure-Python wheel.

Quick start

from kaos_names import generate_name

print(generate_name())
# e.g. "sunny-docket-07"

For deterministic output in tests, pass a seeded random source:

import random

from kaos_names import generate_name

rng = random.Random(273)
assert generate_name(rng=rng) == generate_name(rng=random.Random(273))

The original Kelvin Agent API helper was named generate_combination(). kaos-names keeps that alias so existing callers can migrate without changing behavior:

from kaos_names import generate_combination

session_name = generate_combination()

New code should prefer generate_name() or generate_session_name().

Concepts

The package is intentionally tiny — three helpers and two vocabularies.

The default output format is <descriptor>-<noun>-<NN>, with a two-digit number from 01 through 99. Pass separator, number_min, number_max, and number_width to change the shape.

CLI

kaos-names ships a kaos-names command. Every subcommand supports --json for machine-readable output:

kaos-names generate                              # one name
kaos-names generate --count 5                    # five names, one per line
kaos-names generate --count 5 --seed 273         # deterministic output
kaos-names generate --count 3 --json             # JSON envelope
kaos-names generate --separator _ --number-width 3   # sunny_docket_007 shape
kaos-names vocabulary                            # vocabulary counts
kaos-names vocabulary --list                     # full word lists
kaos-names vocabulary --json                     # vocabulary as JSON

You can also run the package as a module: python -m kaos_names generate.

Compatibility & status

Companion packages

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

kaos-names is a leaf utility — it has no kaos-* dependencies and is safe to use from any of the packages above (or anywhere outside KAOS).

Development

git clone https://github.com/273v/kaos-names
cd kaos-names
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_names tests
uv run ruff check kaos_names tests
uv run ty check kaos_names 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.