Dracon

Dracon turns YAML configs into composable, type-safe Python objects. Define your schema as a Pydantic model, write your config in YAML with expressions and includes, and get a validated CLI for free.

What it looks like

config.yaml

log_level: ${getenv('LOG_LEVEL', 'INFO')}
workers: 2
database:
  host: db.${@/environment}.local
  port: 5432
  password: !include env:DB_PASS

app.py

from pydantic import BaseModel
from dracon import dracon_program, Arg
from typing import Annotated

@dracon_program()
class App(BaseModel):
    environment: Annotated[str, Arg(short='e')]
    log_level: str = "INFO"
    workers: int = 1
    database: DatabaseConfig

App.cli()

python app.py +config.yaml -e prod --workers 8

How it works

Dracon processes configuration in three phases:

• Compose -- YAML files are parsed, includes resolved, merges applied, and instructions (!if, !define, !each) executed. The result is a single YAML node graph. No Python objects exist yet.
• Construct -- The node graph is walked and turned into Python objects (Pydantic models, dicts, lists, primitives). Type validation happens here.
• Resolve -- Interpolations like ${@/environment} are wrapped as lazy values and evaluated only when accessed. This lets expressions reference the final, fully-merged config.

Start here

• Quickstart -- zero to working in 90 seconds
• Tutorial 1: Your First Config -- load YAML, get typed Python objects

Features

• Composable configs -- includes, merges, layered overrides
• Auto-generated CLIs -- turn any Pydantic model into a CLI with Arg annotations
• YAML functions (!fn, !pipe) -- reusable templates and pipelines inside YAML
• Type-safe with Pydantic -- Pydantic validation, nested models, discriminated unions
• The open vocabulary -- values, constructors, and callables all become composable named building blocks
• Deferred execution -- values that depend on runtime context
• Interpolation engine -- embed Python expressions with ${...}, reference other keys with @/path
• Config introspection -- dracon show to inspect composition before writing Python
• Real-world patterns -- runtime contracts, layered vocabularies, hybrid pipelines, dynamic skeletons