From c83519283fff53b334109a2771a1f11ac8d3b6c6 Mon Sep 17 00:00:00 2001
From: fderuiter <127706008+fderuiter@users.noreply.github.com>
Date: Sun, 5 Apr 2026 20:53:52 +0000
Subject: [PATCH] =?UTF-8?q?=E2=9C=8D=EF=B8=8F=20Scribe:=20Fix=20broken=20q?=
 =?UTF-8?q?uickstart=20onboarding=20path?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💡 What: Added `load_dotenv()` from `python-dotenv` to the quick start examples (`examples/quick_start.py` and `examples/async_quick_start.py`) and updated the `README.md` to reflect this code addition. Removed the confusing caveat that warned users they had to add this themselves.

🎯 Why: The previous `README.md` instructed users to copy `.env.example` to `.env` to authenticate, but running the examples failed with a misleading "API key required" error because the code didn't actually parse the `.env` file. This is a common and immediate blocker for new users.

🧠 Cognitive Impact: Fixes a first-run crash. A new developer can now copy `.env.example`, fill it out, and immediately run `poetry run python examples/quick_start.py` successfully. This matches the behavior of the CLI and eliminates a frustrating "why isn't my config working?" moment.

📖 Preview:
```python
from dotenv import load_dotenv

# Load environment variables from .env file if it exists
load_dotenv()

# Load credentials from environment variables
cfg = load_config()
```

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
---
 README.md                     | 11 +++++++++--
 examples/async_quick_start.py |  5 +++++
 examples/quick_start.py       |  5 +++++
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 7d89bfd4..2c9f7291 100644
--- a/README.md
+++ b/README.md
@@ -97,12 +97,17 @@ export IMEDNET_SECURITY_KEY="your_security_key"
 ### Synchronous Example
 
 ```python
+from dotenv import load_dotenv
+
 from imednet import ImednetSDK, load_config
 from imednet.utils import configure_json_logging
 
 # Optional: Configure structured JSON logging
 configure_json_logging()
 
+# Load environment variables from .env file if it exists
+load_dotenv()
+
 # Load credentials from environment variables
 cfg = load_config()
 
@@ -121,6 +126,7 @@ with ImednetSDK(
 
 ```python
 import asyncio
+from dotenv import load_dotenv
 from imednet import AsyncImednetSDK, load_config
 from imednet.utils import configure_json_logging
 
@@ -129,6 +135,9 @@ async def main() -> None:
     # Optional: Configure structured JSON logging
     configure_json_logging()
 
+    # Load environment variables from .env file if it exists
+    load_dotenv()
+
     # Load credentials from environment variables
     cfg = load_config()
 
@@ -155,8 +164,6 @@ The SDK and CLI read credentials from environment variables such as
 `IMEDNET_API_KEY` and `IMEDNET_SECURITY_KEY`. You can set these in your shell or
 use a `.env` file. Copy `.env.example` to `.env` to get started.
 
-> **Note**: `imednet.load_config()` only reads from existing environment variables (`os.getenv`). While the CLI automatically loads `.env` files, standalone Python scripts must explicitly call `load_dotenv()` from the `python-dotenv` package to read from a `.env` file before calling `load_config()`.
-
 See [configuration](docs/configuration.rst) for the complete list of options.
 Use `imednet.config.load_config()` to access these values in your code.
 
diff --git a/examples/async_quick_start.py b/examples/async_quick_start.py
index 3cfcdbbe..19215053 100644
--- a/examples/async_quick_start.py
+++ b/examples/async_quick_start.py
@@ -4,6 +4,8 @@
 import os
 import sys
 
+from dotenv import load_dotenv
+
 from imednet import AsyncImednetSDK, load_config
 from imednet.utils import configure_json_logging
 
@@ -25,6 +27,9 @@ async def main() -> None:
     """Run a minimal async SDK example using environment variables."""
     configure_json_logging()
 
+    # Load environment variables from .env file if it exists
+    load_dotenv()
+
     try:
         cfg = load_config()
     except ValueError as e:
diff --git a/examples/quick_start.py b/examples/quick_start.py
index bbcdd9a6..539b5353 100644
--- a/examples/quick_start.py
+++ b/examples/quick_start.py
@@ -2,6 +2,8 @@
 
 import sys
 
+from dotenv import load_dotenv
+
 from imednet import ImednetSDK, load_config
 from imednet.utils import configure_json_logging
 
@@ -22,6 +24,9 @@ def main() -> None:
     """Run a minimal SDK example using environment variables."""
     configure_json_logging()
 
+    # Load environment variables from .env file if it exists
+    load_dotenv()
+
     try:
         cfg = load_config()
     except ValueError as e: