# Install pyenv (macOS / Linux)
curl https://pyenv.run | bash

# Add to ~/.bashrc or ~/.zshrc
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# Install a specific version
pyenv install 3.12.3

# Set a version globally
pyenv global 3.12.3

# Set a version for a single project directory
cd ~/projects/my-ai-app
pyenv local 3.12.3        # writes .python-version file

# Verify
python --version           # Python 3.12.3

# Install pyenv-win
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"
.\install-pyenv-win.ps1

pyenv install 3.12.3
pyenv global 3.12.3

# Create a venv named .venv in the project root
python -m venv .venv

# Activate on Linux / macOS
source .venv/bin/activate

# Activate on Windows PowerShell
.\.venv\Scripts\Activate.ps1

# You should see (.venv) in your prompt
# Deactivate when done
deactivate

# Always upgrade pip first
pip install --upgrade pip

# Install packages
pip install openai httpx pydantic python-dotenv

# Install a specific version (important for reproducibility)
pip install openai==1.30.1

# Install from a requirements file
pip install -r requirements.txt

# Install in editable mode (for your own packages)
pip install -e .

# After installing everything your project needs:
pip freeze > requirements.txt

# requirements.txt
openai==1.30.1
httpx==0.27.0
pydantic==2.7.1
pydantic-settings==2.2.1
python-dotenv==1.0.1
structlog==24.2.0
tenacity==8.3.0
redis==5.0.4
sqlalchemy==2.0.30
alembic==1.13.1
fastapi==0.111.0
uvicorn[standard]==0.30.0
pytest==8.2.0
pytest-asyncio==0.23.7

# requirements-dev.txt
-r requirements.txt          # include all production deps
pytest==8.2.0
pytest-asyncio==0.23.7
black==24.4.2
ruff==0.4.4
mypy==1.10.0

pip install -r requirements-dev.txt

# .env  (never commit this file!)
OPENAI_API_KEY=sk-proj-...
AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_DEPLOYMENT=gpt-4o
REDIS_URL=redis://localhost:6379
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/mydb
APP_ENV=development
LOG_LEVEL=DEBUG

echo ".env" >> .gitignore
echo ".env.local" >> .gitignore

# .env.example  (commit this)
OPENAI_API_KEY=your-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-azure-key-here
AZURE_OPENAI_DEPLOYMENT=gpt-4o
REDIS_URL=redis://localhost:6379
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/mydb
APP_ENV=development
LOG_LEVEL=INFO

# config.py
from dotenv import load_dotenv
import os

# Load .env from the current directory (or parent dirs)
load_dotenv()

OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
APP_ENV = os.getenv("APP_ENV", "production")   # with default
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")

print(f"Running in {APP_ENV} mode")

load_dotenv(".env.local")       # override with local file
load_dotenv(override=True)      # env vars in the file override existing env vars

# settings.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import Field


class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
    )

    # Required — will raise if missing
    openai_api_key: str

    # Optional with defaults
    azure_openai_endpoint: str = ""
    azure_openai_deployment: str = "gpt-4o"
    redis_url: str = "redis://localhost:6379"
    database_url: str = ""

    app_env: str = "production"
    log_level: str = "INFO"
    max_tokens: int = Field(default=1024, ge=1, le=8192)


# Singleton — import this everywhere
settings = Settings()

# main.py
from settings import settings
import openai

client = openai.OpenAI(api_key=settings.openai_api_key)
print(f"Using model: {settings.azure_openai_deployment}")

my-ai-app/
├── .env                    # secrets — never commit
├── .env.example            # template — commit this
├── .gitignore
├── .python-version         # pyenv version pin
├── requirements.txt
├── requirements-dev.txt
├── pyproject.toml          # optional: modern packaging
├── README.md
│
├── src/
│   └── my_ai_app/
│       ├── __init__.py
│       ├── settings.py     # Pydantic Settings
│       ├── main.py         # FastAPI app or entry point
│       │
│       ├── agents/         # Agent logic
│       │   ├── __init__.py
│       │   └── assistant.py
│       │
│       ├── tools/          # Tool implementations
│       │   ├── __init__.py
│       │   ├── search.py
│       │   └── calendar.py
│       │
│       ├── models/         # Pydantic models / DB models
│       │   ├── __init__.py
│       │   ├── schemas.py
│       │   └── db.py
│       │
│       ├── services/       # Business logic
│       │   ├── __init__.py
│       │   └── llm_service.py
│       │
│       └── utils/          # Shared utilities
│           ├── __init__.py
│           ├── logging.py
│           └── retry.py
│
├── tests/
│   ├── conftest.py
│   ├── test_agents/
│   └── test_tools/
│
└── docs/

# Makefile
.PHONY: install dev-install test lint format run

install:
	pip install --upgrade pip
	pip install -r requirements.txt

dev-install:
	pip install --upgrade pip
	pip install -r requirements-dev.txt

test:
	pytest tests/ -v

lint:
	ruff check src/
	mypy src/

format:
	black src/ tests/
	ruff check --fix src/

run:
	uvicorn src.my_ai_app.main:app --reload --port 8000

# verify_setup.py
import sys
import importlib

print(f"Python version: {sys.version}")
print(f"Python executable: {sys.executable}")

required = ["openai", "httpx", "pydantic", "dotenv", "structlog", "tenacity"]

for package in required:
    try:
        mod = importlib.import_module(package)
        version = getattr(mod, "__version__", "unknown")
        print(f"  {package}: {version}")
    except ImportError:
        print(f"  {package}: NOT INSTALLED")

python verify_setup.py

Python version: 3.12.3 (main, ...)
Python executable: /home/user/projects/my-ai-app/.venv/bin/python
  openai: 1.30.1
  httpx: 0.27.0
  pydantic: 2.7.1
  dotenv: 1.0.1
  structlog: 24.2.0
  tenacity: 8.3.0

#!/usr/bin/env bash
# setup.sh — run once after cloning

set -e

echo "Creating virtual environment..."
python -m venv .venv

echo "Activating..."
source .venv/bin/activate

echo "Upgrading pip..."
pip install --upgrade pip

echo "Installing dependencies..."
pip install -r requirements-dev.txt

echo "Copying .env template..."
if [ ! -f .env ]; then
  cp .env.example .env
  echo "Edit .env and fill in your API keys."
fi

echo "Done. Run: source .venv/bin/activate"