Cookbook

Copy-paste recipes for common tasks. Each recipe is self-contained.

Compress Docker Compose for LLM Context

decoct compress docker-compose.yml --schema docker-compose --stats

Output includes @class headers listing stripped defaults so an LLM can reconstruct full values:

# decoct: defaults stripped using docker-compose schema
# @class service-defaults: init=false, network_mode=bridge, privileged=false, ...
services:
  web:
    image: nginx:1.25.3
    ports:
      - "8080:80"
Tokens: 312 -> 94 (saved 218, 69.9%)

Compress Kubernetes Manifests

Pipe live cluster state through decoct to strip system-managed fields and defaults:

kubectl get deployment myapp -o yaml | decoct compress --schema kubernetes

Save to file:

kubectl get deployment myapp -o yaml \
  | decoct compress --schema kubernetes -o myapp-compressed.yaml

See what was removed:

kubectl get deployment myapp -o yaml \
  | decoct compress --schema kubernetes --show-removed

Compress Terraform State

decoct compress terraform.tfstate --schema terraform-state --stats

For large state files, check potential savings first:

decoct compress terraform.tfstate --schema terraform-state --stats-only

Compress Ansible Playbooks

decoct compress playbook.yaml --schema ansible-playbook --stats

Ansible playbooks are auto-detected, so --schema can often be omitted:

decoct compress playbook.yaml --stats

Build a Custom Schema

Create my-schema.yaml:

platform: my-platform
source: Internal documentation v2.1
confidence: high
defaults:
  settings.debug: false
  settings.log_level: info
  settings.timeout: 30
  server.port: 8080
  server.workers: 1
drop_patterns:
  - "**.internal_id"
system_managed:
  - "**.last_modified"

Test it:

decoct compress my-config.yaml --schema my-schema.yaml --show-removed --stats

Learn a Schema from Production Configs

Requires pip install decoct[llm] and ANTHROPIC_API_KEY.

decoct schema learn \
  -e prod-config1.yaml \
  -e prod-config2.yaml \
  -p my-platform \
  -o my-schema.yaml

With vendor documentation:

decoct schema learn -e prod-config.yaml -d vendor-docs.md -p my-platform -o my-schema.yaml

Merge into existing schema:

decoct schema learn -e new-config.yaml -m my-schema.yaml -o my-schema.yaml

Encode Team Standards as Assertions

Create team-standards.yaml:

assertions:
  - id: no-latest-tags
    assert: Image tags must not use :latest
    match:
      path: services.*.image
      pattern: "^(?!.*:latest$)(?=.*:.+$)"
    rationale: Reproducible deployments require pinned versions
    severity: must

  - id: restart-policy
    assert: Restart policy must be unless-stopped or always
    match:
      path: services.*.restart
      pattern: "^(unless-stopped|always)$"
    rationale: Services must recover from crashes
    severity: must

  - id: healthcheck-required
    assert: All services should have health checks
    match:
      path: services.*.healthcheck
      exists: true
    rationale: Health checks enable proper dependency ordering
    severity: should

Test:

decoct compress docker-compose.yaml \
  --schema docker-compose \
  --assertions team-standards.yaml \
  --stats

Learn Assertions from a Corpus

decoct assertion learn \
  -c configs/service-a.yml \
  -c configs/service-b.yml \
  -c configs/service-c.yml \
  -p docker-compose \
  -o learned-standards.yaml

From a standards document:

decoct assertion learn -s deployment-policy.md -p docker-compose -o standards.yaml

Set Up a Profile for CI

Create .decoct/docker-compose.yaml:

name: docker-compose
schema: schemas/docker-compose.yaml
assertions:
  - assertions/team-standards.yaml
passes:
  strip-secrets:
  strip-comments:
  strip-defaults:
  emit-classes:
  strip-conformant:
  prune-empty:
  annotate-deviations:
  deviation-summary:

Use locally:

decoct compress docker-compose.yaml --profile .decoct/docker-compose.yaml --stats

In GitHub Actions:

- run: pip install decoct
- run: |
    decoct compress docker-compose.yaml \
      --profile .decoct/docker-compose.yaml \
      --stats-only

Batch-Process a Directory

decoct compress ./configs/ --recursive --schema docker-compose --stats

Matches .yaml, .yml, .json, .ini, .conf, .cfg, .cnf, .properties. Each file is separated with a # --- <filename> --- header:

configs/app1/docker-compose.yaml: Tokens: 185 -> 62 (saved 123, 66.5%)
configs/app2/docker-compose.yaml: Tokens: 210 -> 71 (saved 139, 66.2%)
Total: Tokens: 395 -> 133 (saved 262, 66.3%)

Compare Compression Tiers

Measure savings at each tier with --stats-only:

# Tier 1 — Generic cleanup (no schema)
decoct compress config.yaml --stats-only
# Tokens: 487 -> 412 (saved 75, 15.4%)

# Tier 2 — Platform defaults
decoct compress config.yaml --schema docker-compose --stats-only
# Tokens: 487 -> 268 (saved 219, 45.0%)

# Tier 3 — Standards conformance
decoct compress config.yaml --profile docker-compose --stats-only
# Tokens: 487 -> 195 (saved 292, 59.9%)

Pipe kubectl Output

# All resources in a namespace
kubectl get all -n production -o yaml | decoct compress --schema kubernetes

# Specific resource type
kubectl get configmaps -n production -o yaml | decoct compress --schema kubernetes --stats

# With assertions
kubectl get deployments -o yaml \
  | decoct compress --schema kubernetes --assertions k8s-standards.yaml

Use as a Python Library

from io import StringIO
from ruamel.yaml import YAML
from decoct.pipeline import Pipeline
from decoct.passes.strip_secrets import StripSecretsPass
from decoct.passes.strip_comments import StripCommentsPass
from decoct.passes.strip_defaults import StripDefaultsPass
from decoct.passes.emit_classes import EmitClassesPass
from decoct.passes.prune_empty import PruneEmptyPass
from decoct.schemas.loader import load_schema
from decoct.schemas.resolver import resolve_schema
from decoct.tokens import create_report, format_report

schema = load_schema(resolve_schema("docker-compose"))
pipeline = Pipeline([
    StripSecretsPass(),
    StripCommentsPass(),
    StripDefaultsPass(schema=schema),
    EmitClassesPass(schema=schema),
    PruneEmptyPass(),
])

yaml = YAML(typ="rt")
with open("docker-compose.yaml") as f:
    input_text = f.read()
doc = yaml.load(input_text)

stats = pipeline.run(doc)

stream = StringIO()
yaml.dump(doc, stream)
output_text = stream.getvalue()

report = create_report(input_text, output_text)
print(format_report(report))