# 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

```bash
# 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

```bash
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):
```dotenv
# 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):
```markdown
# 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:

```bash
# 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:

```bash
# 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

```bash
kdeps validate examples/auto-env
```
