madomeda/CONFIGURATION.md

---
title: Configuration Management
created: '2025-10-23T19:29:26+02:00'
status: draft
priority: 5
published: false
tags:
- aiml
- python
reviewers: []
---
# Configuration Management

## Configuration Directory

Madomeda stores its configuration in a platform-specific location:

- **Windows**: `%USERPROFILE%\.config\madomeda`
- **macOS**: `~/.config/madomeda`
- **Linux**: `~/.config/madomeda`

## First Run

On first run, Madomeda automatically creates:

```
~/.config/madomeda/
├── .env                    # API configuration
├── templates/
│   └── default.json        # Default frontmatter template
├── rules/
│   ├── lowercase_keys.json
│   ├── summary_to_description.json
│   ├── tag_to_tags.json
│   └── tags_normalization.json
└── prompts/
    └── default.txt         # Default LLM prompt
```

## Configuration Display

When running in an **interactive shell**, Madomeda displays configuration info:

```
Configuration directory: C:\Users\YourName\.config\madomeda
  .env file: C:\Users\YourName\.config\madomeda\.env
  Templates: C:\Users\YourName\.config\madomeda\templates
  Rules: C:\Users\YourName\.config\madomeda\rules
  Prompts: C:\Users\YourName\.config\madomeda\prompts
  API Key: Not configured (LLM features disabled)
```

In **non-interactive mode** (pipes, scripts), this info is suppressed.

## API Key Configuration

The `.env` file supports three modes for `OPENAI_API_KEY`:

### 1. No API Key (Default)

```bash
OPENAI_API_KEY=""
```

**Output:**
```
API Key: Not configured (LLM features disabled)
```

**Behavior:** LLM features are disabled, only heuristics and original values used.

### 2. Environment Variable Reference

```bash
OPENAI_API_KEY=$MY_API_KEY
```

**Output:**
```
API Key: From environment variable $MY_API_KEY
```

**Behavior:** 
- Reads key from environment variable `MY_API_KEY`
- **Error if not found:** 
  ```
  ValueError: Environment variable 'MY_API_KEY' not found.
  Referenced in .env as OPENAI_API_KEY=$MY_API_KEY
  ```

**Setup:**
```bash
# Linux/macOS
export MY_API_KEY="sk-your-actual-key"

# Windows (PowerShell)
$env:MY_API_KEY = "sk-your-actual-key"

# Windows (CMD)
set MY_API_KEY=sk-your-actual-key
```

### 3. Plain Text Key

```bash
OPENAI_API_KEY=sk-1234567890abcdef
```

**Output:**
```
API Key: Configured (plain text)
WARNING: Storing API keys in plain text is a security risk!
         Consider using environment variable: OPENAI_API_KEY=$YOUR_ENV_VAR
```

**Behavior:** Works but shows security warning every run.

## Best Practices

### ✅ Recommended: Environment Variable

```bash
# In .env file
OPENAI_API_KEY=$OPENAI_API_KEY

# In your shell profile (~/.bashrc, ~/.zshrc, etc.)
export OPENAI_API_KEY="sk-your-actual-key"
```

**Benefits:**
- Key not stored in config file
- Can be different per user/machine
- Easy to rotate without editing files
- Can use system keyring tools

### ⚠️ Acceptable: Empty String

```bash
OPENAI_API_KEY=""
```

**Use when:**
- Don't have LLM access
- Only using heuristics
- Testing/development

### ❌ Not Recommended: Plain Text

```bash
OPENAI_API_KEY=sk-1234567890abcdef
```

**Risks:**
- Key visible to anyone with file access
- Accidentally committed to version control
- Hard to rotate across systems

## Customizing Configuration

### Custom Templates

Create in `~/.config/madomeda/templates/`:

```bash
# Create minimal template
cat > ~/.config/madomeda/templates/minimal.json << 'EOF'
{
  "title": "heur|orig",
  "date": "heur|orig",
  "tags": "orig"
}
EOF

# Use it
madomeda --template minimal
```

### Custom Rules

Create in `~/.config/madomeda/rules/`:

```bash
cat > ~/.config/madomeda/rules/my_rule.json << 'EOF'
{
  "name": "my_custom_rule",
  "description": "My custom rule description",
  "type": "custom"
}
EOF
```

Note: Custom rules require code changes in `core/rules.py` to implement logic.

### Custom Prompts

Create in `~/.config/madomeda/prompts/`:

```bash
cat > ~/.config/madomeda/prompts/technical.txt << 'EOF'
You are a technical documentation expert.
Focus on API documentation and code examples.
...
EOF
```

Reference in template:
```json
{
  "summary": "ai technical"
}
```

## Multiple API Providers

Edit `OPENAI_API_URL` in `.env`:

```bash
# OpenAI
OPENAI_API_URL=https://api.openai.com/v1

# Azure OpenAI
OPENAI_API_URL=https://your-resource.openai.azure.com/

# Local LLM (Ollama)
OPENAI_API_URL=http://localhost:11434/v1

# Other OpenAI-compatible APIs
OPENAI_API_URL=https://api.your-provider.com/v1
```

## Troubleshooting

### Config Not Created

Ensure write permissions:
```bash
mkdir -p ~/.config/madomeda
chmod 755 ~/.config/madomeda
```

### Environment Variable Not Found

Check it's set:
```bash
# Linux/macOS
echo $MY_API_KEY

# Windows (PowerShell)
echo $env:MY_API_KEY
```

If not set, add to shell profile or set before running:
```bash
MY_API_KEY="sk-key" madomeda
```

### Wrong Config Location

Madomeda uses `$USERPROFILE` (Windows) or `$HOME` (Unix).

Check:
```bash
# Linux/macOS
echo ~/.config/madomeda

# Windows (PowerShell)
echo $env:USERPROFILE\.config\madomeda
```

### API Key Warning on Every Run

This is intentional for plain text keys. Switch to environment variable to suppress.

## Migration from Old Version

If you had local `.env`, `templates/`, `rules/`, `prompts/` in the repo:

1. Copy to new location:
   ```bash
   cp -r templates ~/.config/madomeda/
   cp -r rules ~/.config/madomeda/
   cp -r prompts ~/.config/madomeda/
   cp .env ~/.config/madomeda/
   ```

2. Update `.gitignore` (no longer need to ignore these locally)

3. Old local files are now ignored by the program

## Security Notes

- Never commit `.env` with plain text keys
- Use environment variables or secret management tools
- Config directory is user-specific (not shared)
- On shared systems, ensure `~/.config/madomeda/` has proper permissions:
  ```bash
  chmod 700 ~/.config/madomeda
  ```