codex-core

Core utilities, immutable DTOs, and environment-driven settings for the Codex WaaS toolkit. Provides the foundational building blocks and PII masking used by all other Codex components.

Install

# Core only
pip install codex-core

# With Loguru support for advanced structured logging
pip install "codex-core[loguru]"

Requires Python 3.12 or newer.

Optional agent skill

Starting with version 0.5.0, the package includes an offline codex-core usage skill for coding agents. From the consumer project root, use the same Python environment that has the package installed:

python -m pip install "codex-core>=0.5.0"
python -m codex_core.agent_skills install --project .
python -m codex_core.agent_skills status --project .

install creates a managed copy under .agents/skills/codex-core/ and a marked instruction in AGENTS.md. After upgrading the Python package, run python -m codex_core.agent_skills update --project . to refresh the skill. The installer refuses to discard local edits to managed files and preserves unrelated project content. See the agent skill guide for the full lifecycle, removal, and recovery steps. The canonical editable source is src/codex_core/agent_skills/resources/ in this repository.

Development

uv sync --extra dev
uv run pytest
uv run mypy src/codex_core/
uv run pre-commit run --all-files
uv build --no-sources

Requires Python 3.12 or newer.

Quick Start

from codex_core.core.base_dto import BaseDTO

# 1. Define an immutable, PII-aware data transfer object
class UserDTO(BaseDTO):
    id: int
    email: str         # Automatically masked in logs
    phone_number: str  # Automatically masked in logs

user = UserDTO(id=42, email="user@example.com", phone_number="+491511234567")

# 2. Safely log the DTO without leaking personal data
print(user)
# Output: UserDTO(id=42, email='***', phone_number='***')

Modules

Documentation

Full docs with architecture, API reference, and data flow diagrams:

https://codexdlc.github.io/codex-core/

Part of the Codex ecosystem

Each library is fully standalone — install only what your project needs. Together they form the backbone of codex-bot (Telegram AI-agent infrastructure built on aiogram) and codex-django (Django integration layer).