auto-env

Demonstrates kdeps automatic environment variable scoping for components.

What It Shows

Feature	Description
Scoped env vars	TRANSLATOR_OPENAI_API_KEY overrides OPENAI_API_KEY inside translator only
Auto-scaffolded .env	On first run, kdeps creates a .env template in each component dir
Auto-scaffolded README.md	Generated from component metadata on first run
.env fallback	Values in a component's .env file are the lowest-priority source
kdeps component update	Explicitly regenerates or merges .env and README.md

Structure

auto-env/
├── workflow.yaml
├── components/
│   ├── translator/
│   │   └── component.yaml     # uses env('OPENAI_API_KEY')
│   └── summarizer/
│       └── component.yaml     # uses env('OPENAI_API_KEY')
└── resources/
    ├── 01-translate.yaml
    ├── 02-summarize.yaml
    └── 03-response.yaml

Priority: How env('OPENAI_API_KEY') Resolves

When the translator component calls env('OPENAI_API_KEY'):

1. TRANSLATOR_OPENAI_API_KEY   ← scoped os env (highest priority)
2. OPENAI_API_KEY              ← plain os env
3. translator/.env             ← component .env file (lowest priority)

When the summarizer component calls env('OPENAI_API_KEY'):

1. SUMMARIZER_OPENAI_API_KEY   ← scoped os env (highest priority)
2. OPENAI_API_KEY              ← plain os env
3. summarizer/.env             ← component .env file (lowest priority)

No YAML changes needed — the prefix is derived automatically from the component name.

Setup

# Global fallback key (used by both components)
export OPENAI_API_KEY=sk-global

# Optional: component-specific overrides
export TRANSLATOR_OPENAI_API_KEY=sk-translate-key   # translator only
export SUMMARIZER_OPENAI_API_KEY=sk-summary-key     # summarizer only

If no API key is set:

• translator returns an error field instead of a translation
• summarizer falls back to a simple extractive summary (no API call)

Run

kdeps run examples/auto-env

Auto-Scaffolded Files (First Run)

On the first run, kdeps automatically creates in each component directory:

components/translator/.env (auto-generated template):

# Auto-generated by kdeps - fill in values before running the component.
# Component: translator v1.0.0

# Env vars can be overridden at the shell level:
#   export TRANSLATOR_VAR_NAME=value

OPENAI_API_KEY=

components/translator/README.md (auto-generated):

# translator

Translates text to a target language using the OpenAI API.
...

These files are never overwritten by kdeps. Edit them freely.

Explicitly Updating .env and README.md

When you add a new env() call to a component, run:

# Merge new vars into existing .env (existing values are preserved)
kdeps component update examples/auto-env

# Or update a specific component
kdeps component update examples/auto-env/components/translator

kdeps component update will:

• Create README.md if absent (never overwrite)
• Create .env if absent, OR append missing var entries if .env already exists

Naming Convention

The scoped prefix is the component name uppercased with non-alphanumeric characters replaced by _:

Component name	Scoped prefix
scraper	SCRAPER_
my-bot	MY_BOT_
gpt.4	GPT_4_

Real-World Use Case

Use scoped env vars to rotate API keys per-component without touching shared config:

# CI/CD: different keys per service
export SCRAPER_OPENAI_API_KEY=$SCRAPER_KEY
export EMBEDDING_OPENAI_API_KEY=$EMBED_KEY
export SUMMARIZER_OPENAI_API_KEY=$SUMMARY_KEY
export OPENAI_API_KEY=$DEFAULT_KEY   # fallback for everything else

kdeps run my-workflow

Validate

kdeps validate examples/auto-env