dev/dev_260101_12_isolated_environment_setup.md

[dev_260101_12] Isolated Environment Setup

Date: 2026-01-01 Type: Issue Status: Resolved Related Dev: dev_260101_11 (Stage 1 Completion)

Problem Description

Environment confusion arose during Stage 1 validation. The HF project existed as a subdirectory within parent /Users/mangobee/Documents/Python (uv-managed workspace), but had only requirements.txt without project-specific environment configuration.

Core Issues:

1. Unclear where uv pip install installs packages (parent's .venv vs project-specific location)
2. Package installation incomplete - some packages (google-genai, tavily-python) not found in parent environment
3. Mixing parent's pyproject.toml dependencies with HF project dependencies causes potential conflicts
4. .env vs .env.example confusion - user accidentally put real API keys in template file
5. No .gitignore file - risk of committing secrets to git

Root Cause: HF project treated as subdirectory without isolated environment, creating dependency confusion and security risks.

---

Key Decisions

• Isolated uv Environment: Create project-specific .venv/ within HF project directory, managed by its own pyproject.toml
• Dual Configuration Strategy: Maintain both pyproject.toml (local development) and requirements.txt (HF Spaces compatibility)
• Environment Separation: Complete isolation from parent's .venv/ to prevent package conflicts
• Security Setup: Proper .env file handling with .gitignore protection
• Package Source: Install all 102 packages directly into project's .venv/lib/python3.12/site-packages

Rejected Alternatives:

• Using parent's shared .venv/ - rejected due to package conflict risks and unclear dependency boundaries
• HF Spaces-only testing without local environment - rejected due to slow iteration cycles
• Manual virtual environment (python -m venv) - rejected in favor of uv's superior dependency management

Outcome

Successfully established isolated uv environment for HF project with complete dependency isolation from parent workspace.

Validation Results:

• ✓ All 102 packages installed in local .venv/ (tavily-python, google-genai, anthropic, langgraph, etc.)
• ✓ Configuration loads correctly (LLM=gemini, Search=tavily)
• ✓ All Stage 1 tests passing with isolated environment
• ✓ Security setup complete (.env protected, .gitignore configured)
• ✓ Imports working: from src.agent import GAIAAgent; from src.config import Settings

Deliverables:

Environment Configuration:

• pyproject.toml - UV project configuration with 102 dependencies, dev-dependencies (pytest, pytest-asyncio), hatchling build backend
• .venv/ - Local isolated virtual environment (gitignored)
• uv.lock - Auto-generated lock file for reproducible installs (gitignored)
• .gitignore - Protection for .env, .venv/, uv.lock, Python artifacts

Security Setup:

• .env.example - Template with placeholders (safe to commit)
• .env - Real API keys for local testing (gitignored)
• API keys verified: ANTHROPIC_API_KEY, GOOGLE_API_KEY, TAVILY_API_KEY, EXA_API_KEY
• SPACE_ID configured: mangoobee/Final_Assignment_Template

Learnings and Insights

• uv Workspace Behavior: When running uv pip install from subdirectory without local pyproject.toml, uv searches upward and uses parent's .venv/, creating hidden dependencies
• Dual Configuration Pattern: Maintaining both pyproject.toml (uv local dev) and requirements.txt (HF Spaces deployment) ensures compatibility across environments
• Security Best Practice: Never put real API keys in .env.example - it's a template file that gets committed to git
• Hatchling Requirement: When using hatchling build backend, must specify packages = ["src"] in [tool.hatch.build.targets.wheel] to avoid build errors
• Package Location Verification: Always verify package installation location with uv pip show <package> to confirm expected environment isolation
• uv sync vs uv pip install: uv sync reads from pyproject.toml and creates lockfile; uv pip install is lower-level and doesn't modify project configuration

Changelog

Created:

• pyproject.toml - UV project configuration (name="gaia-agent", 102 dependencies)
• .venv/ - Local isolated virtual environment
• uv.lock - Auto-generated dependency lock file
• .gitignore - Git ignore rules for secrets and build artifacts
• .env - Local API keys (real secrets, gitignored)

Modified:

• .env.example - Restored placeholders (removed accidentally committed real API keys)

Commands Executed:

uv venv                           # Create isolated .venv
uv sync                          # Install all dependencies from pyproject.toml
uv pip show tavily-python        # Verify package location
uv run python tests/test_stage1.py  # Validate with isolated environment

Validation Evidence:

tavily-python: .../Final_Assignment_Template/.venv/lib/python3.12/site-packages
google-genai: .../Final_Assignment_Template/.venv/lib/python3.12/site-packages
✓ All Stage 1 tests passing
✓ Configuration loaded correctly

Next Steps: Environment setup complete - ready to proceed with Stage 2: Tool Development or deploy to HF Spaces for integration testing.

---

Reference: Environment Management Guide

Strategy: This HF project has its own isolated virtual environment managed by uv, separate from the parent Python folder.

Project Structure

16_HuggingFace/Final_Assignment_Template/
├── .venv/              # LOCAL isolated virtual environment
├── pyproject.toml      # UV project configuration
├── uv.lock            # Lock file (auto-generated, gitignored)
├── requirements.txt    # For HF Spaces compatibility
└── .env               # Local API keys (gitignored)

How It Works

Local Development:

• Uses local .venv/ with uv-managed packages
• All 102 packages installed in isolation
• No interference with parent /Users/mangobee/Documents/Python/.venv

HuggingFace Spaces Deployment:

• Reads requirements.txt (not pyproject.toml)
• Creates its own cloud environment
• Reads API keys from HF Secrets (not .env)

Common Commands

Run Python code:

uv run python app.py
uv run python tests/test_stage1.py

Add new package:

uv add package-name          # Adds to pyproject.toml + installs

Install dependencies:

uv sync                      # Install from pyproject.toml

Update requirements.txt for HF Spaces:

uv pip freeze > requirements.txt  # Export current packages

Package Locations Verified

All packages installed in LOCAL .venv/:

tavily-python: .../Final_Assignment_Template/.venv/lib/python3.12/site-packages
google-genai: .../Final_Assignment_Template/.venv/lib/python3.12/site-packages

NOT in parent's .venv/:

Parent: /Users/mangobee/Documents/Python/.venv  (isolated)
HF:     /Users/mangobee/.../Final_Assignment_Template/.venv  (isolated)

Key Benefits

✓ Isolation: No package conflicts between projects ✓ Clean: Each project manages its own dependencies ✓ Compatible: Still works with HF Spaces via requirements.txt ✓ Reproducible: uv.lock ensures consistent installs