From 95a4c81c778408f03d9fb9e58ef7628d080fd0d2 Mon Sep 17 00:00:00 2001 From: Jordan Corbett-Frank Date: Tue, 11 Nov 2025 19:03:11 -0500 Subject: [PATCH] feat: Add direnv support for automatic API key management MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add direnv configuration with automatic .env setup: - .envrc automatically creates .env from template on first use - .env.example provides template with all environment variables - Update README with direnv as recommended setup method - Keep shell RC file method as alternative option Benefits: - Project-scoped environment variables - Auto-loads when entering repo directory - Zero manual file copying required - Prevents accidental API key commits 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude comment out .env.example values docs: Improve direnv documentation and add error handling Comprehensive documentation improvements for direnv support: **Error Handling:** - Add safety check to .envrc for missing .env.example - Provides helpful error message if template is missing - Prevents silent failures during setup **DEVELOPMENT.md:** - Add dedicated "Environment Setup" section for direnv - Include installation and setup instructions - Update troubleshooting section with direnv-specific guidance - Maintain manual export as alternative approach **examples/README.md:** - Add direnv as recommended option for API key setup - Reference main README for detailed setup - Keep manual export as Option 2 **tests/integration/README.md:** - Clarify that direnv users don't need `source .env` - Add note explaining auto-loading behavior - Prevent confusion about when to use `source .env` All documentation now consistently promotes direnv as the recommended approach while maintaining compatibility with manual environment variable export. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude docs: Restructure DEVELOPMENT.md for better flow Move "Environment Setup" section to the top of DEVELOPMENT.md so developers configure their environment BEFORE running Quick Start commands. This prevents the confusing flow where users would follow export instructions before learning about the recommended direnv approach. **Changes:** - Move "Environment Setup (Recommended: direnv)" to position #1 - Update Quick Start sections to reference env setup instead of inline exports - Add note to BLENDER_PATH section about using direnv - Add "Alternative (manual export)" inline for quick reference **New flow:** 1. Environment Setup (direnv recommended, manual export alternative) 2. Quick Start (uv) - references env setup above 3. Alternative (pip/venv) - references env setup above 4. Install Blender - mentions direnv for BLENDER_PATH 5. Rest unchanged This creates a logical progression: setup → install → test 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .env.example | 17 ++++++++++ .envrc | 26 +++++++++++++++ DEVELOPMENT.md | 66 +++++++++++++++++++++++++++++++++---- README.md | 53 +++++++++++++++++++++++++++-- examples/README.md | 8 +++++ tests/integration/README.md | 5 ++- 6 files changed, 165 insertions(+), 10 deletions(-) create mode 100644 .env.example create mode 100644 .envrc diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..96de0ff --- /dev/null +++ b/.env.example @@ -0,0 +1,17 @@ +# BlockSmith Environment Variables +# +# This file is automatically copied to .env when you first run direnv allow. +# Edit .env (not this file) with your actual API keys. + +# Required: Gemini API Key (default provider) +# Get yours at: https://aistudio.google.com/apikey +# GEMINI_API_KEY=your-gemini-api-key-here + +# Optional: OpenAI API Key (if using OpenAI models) +# Get yours at: https://platform.openai.com/api-keys +# OPENAI_API_KEY=your-openai-api-key-here + +# Optional: Blender path (only needed for GLB/GLTF export) +# Uncomment and set if blender is not in your PATH +# BLENDER_PATH=/Applications/Blender.app/Contents/MacOS/Blender # macOS +# BLENDER_PATH=/usr/bin/blender # Linux diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..3bb5416 --- /dev/null +++ b/.envrc @@ -0,0 +1,26 @@ +# BlockSmith direnv configuration +# +# This file automatically sets up your environment when you cd into the repo. +# +# First time setup: +# 1. Install direnv: https://direnv.net/docs/installation.html +# 2. Run: direnv allow +# 3. Edit .env with your actual API keys +# +# direnv will automatically create .env from .env.example if it doesn't exist. + +# Auto-create .env from example if it doesn't exist +if [ ! -f .env ]; then + if [ -f .env.example ]; then + echo "Creating .env from .env.example..." + cp .env.example .env + echo "✓ Created .env - please edit it with your API keys" + else + echo "⚠️ Warning: .env.example not found" + echo "Please ensure you have the template file or create .env manually" + exit 1 + fi +fi + +# Load environment variables from .env +dotenv .env diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index a3b900e..f4f3064 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -2,6 +2,46 @@ Quick guide for testing BlockSmith locally before it's published to PyPI. +## Environment Setup (Recommended: direnv) + +For a better development experience, use **direnv** to automatically manage environment variables: + +**Install direnv:** +```bash +# macOS +brew install direnv + +# Linux (Ubuntu/Debian) +sudo apt install direnv + +# Add to your shell (~/.bashrc, ~/.zshrc, etc.) +eval "$(direnv hook bash)" # or zsh, fish, etc. +``` + +**Setup (automatic):** +```bash +cd blocksmith +direnv allow # Creates .env from template automatically +``` + +Edit `.env` with your actual API keys: +```bash +GEMINI_API_KEY=your-actual-key-here +``` + +**Benefits:** +- ✅ Project-scoped (only loaded in this directory) +- ✅ Auto-loads when entering repo, unloads when leaving +- ✅ No need for manual `export` or `source` commands +- ✅ `.env` is gitignored (prevents accidental commits) + +**Alternative (manual export):** If you prefer not to use direnv, you can manually export environment variables: +```bash +export GEMINI_API_KEY="your-key-here" +``` + +For detailed setup instructions, see the [main README](README.md#2-set-up-api-key). + ## Quick Start (Using uv - Recommended) **uv** is much faster than pip/venv. Install it first: @@ -23,13 +63,12 @@ uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e . -# Set your API key -export GEMINI_API_KEY="your-key-here" - # Test it! python examples/quickstart.py ``` +**Note:** Make sure you've configured your API key using the Environment Setup section above. + ## Alternative: Standard pip/venv If you prefer the standard Python workflow: @@ -44,13 +83,12 @@ source venv/bin/activate # On Windows: venv\Scripts\activate # Install in editable mode pip install -e . -# Set API key -export GEMINI_API_KEY="your-key-here" - # Test python examples/quickstart.py ``` +**Note:** Make sure you've configured your API key using the Environment Setup section above. + ## Install Blender BlockSmith requires Blender for GLTF/GLB export: @@ -88,6 +126,8 @@ export BLENDER_PATH="/usr/bin/blender" set BLENDER_PATH="C:\Program Files\Blender Foundation\Blender\blender.exe" ``` +If using direnv, add this to your `.env` file instead. + ## Quick Test ```python @@ -129,7 +169,19 @@ blocksmith/ ## Troubleshooting ### "No API key found" -Set your LLM API key: + +**If using direnv:** +1. Make sure you ran `direnv allow` +2. Check that `.env` exists and contains your key: + ```bash + cat .env # Should show GEMINI_API_KEY=your-key + ``` +3. Verify it's loaded: + ```bash + echo $GEMINI_API_KEY # Should print your key + ``` + +**If using manual export:** ```bash export GEMINI_API_KEY="your-key" # or diff --git a/README.md b/README.md index f22e1e4..bc5604f 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,43 @@ BlockSmith uses **Gemini 2.5 Pro** by default (best quality for block models). If you need help with this, let me know. OR, just use OpenAI, or even a free and local model if you want. If you run into a lot of issues with 429/rate limit errors, it's worth adding your billing info to get more use out of Gemini. -**Set the environment variable:** +**Configure your API key:** + +#### Option 1: direnv (Recommended) + +direnv automatically loads environment variables when you `cd` into the project: + +```bash +# Install direnv +# macOS +brew install direnv + +# Linux (Ubuntu/Debian) +sudo apt install direnv + +# Then add to your shell (~/.bashrc, ~/.zshrc, etc.) +eval "$(direnv hook bash)" # or zsh, fish, etc. +``` + +**Setup (automatic):** +```bash +cd blocksmith +direnv allow # Creates .env from template automatically +``` + +Then edit `.env` with your API key: +```bash +GEMINI_API_KEY=your-actual-key-here +``` + +That's it! Your keys are now: +- ✅ Project-scoped (only loaded in this directory) +- ✅ Auto-loaded when you `cd` into the repo +- ✅ Never accidentally committed (`.env` is gitignored) + +#### Option 2: Shell RC file (Global) + +Add to your shell configuration file: ```bash # macOS/Linux - Add to ~/.bashrc or ~/.zshrc @@ -119,7 +155,7 @@ set GEMINI_API_KEY=your-key-here echo $GEMINI_API_KEY # Should print your key ``` -### 3. Install Blender (Optional) +### 3. Install Blender (Optional, for GLB/GLTF only) **Skip this if you only need BBModel, JSON, or Python DSL formats!** @@ -374,6 +410,19 @@ bs.generate("a tower").save("tower.glb") **Problem:** `Exception: No GEMINI_API_KEY found` **Solution:** + +**If using direnv:** +1. Make sure you ran `direnv allow` in the project directory +2. Check that `.env` exists and contains your key: + ```bash + cat .env # Should show GEMINI_API_KEY=your-key + ``` +3. Verify it's loaded: + ```bash + echo $GEMINI_API_KEY # Should print your key + ``` + +**If using shell RC file:** 1. Make sure you set the environment variable: ```bash export GEMINI_API_KEY="your-key-here" diff --git a/examples/README.md b/examples/README.md index 3930df6..148cd66 100644 --- a/examples/README.md +++ b/examples/README.md @@ -8,6 +8,14 @@ Make sure you have BlockSmith installed and your API key set: ```bash pip install blocksmith +``` + +**Set your API key:** + +**Option 1: direnv (Recommended)** - See [main README](../README.md#2-set-up-api-key) for setup + +**Option 2: Manual export** +```bash export GEMINI_API_KEY="your-key-here" ``` diff --git a/tests/integration/README.md b/tests/integration/README.md index e736458..2363544 100644 --- a/tests/integration/README.md +++ b/tests/integration/README.md @@ -16,7 +16,8 @@ ## Running Integration Tests ```bash -# Source your API key first +# If using direnv, variables are already loaded (skip this step) +# If NOT using direnv, load your API key first: source .env # Run all integration tests @@ -29,6 +30,8 @@ pytest tests/integration/test_generation.py -v -s pytest tests/integration/test_generation.py::TestBasicGeneration::test_simple_generation -v -s ``` +**Note:** If you're using direnv (see [main README](../../README.md#2-set-up-api-key)), environment variables are automatically loaded when you `cd` into the repo - no need to run `source .env`. + ## What Gets Tested - ✅ Basic model generation with real LLM