diff --git a/docs/configuration.md b/docs/configuration.md
index 30d5b5f5..9e522a44 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -102,6 +102,34 @@ a2a:
   max_contexts: 1000
 ```
 
+## Programmatic Configuration
+
+When using haiku.rag as a Python library, you can configure it programmatically using `set_config()`:
+
+```python
+from haiku.rag.config import set_config, AppConfig
+from haiku.rag.client import HaikuRAG
+
+# Create custom configuration
+custom_config = AppConfig(
+    qa={"provider": "openai", "model": "gpt-4o"},
+    embeddings={"provider": "ollama", "model": "qwen3-embedding"},
+    processing={"chunk_size": 512}
+)
+
+# Set the configuration globally
+set_config(custom_config)
+
+# All subsequent operations use this configuration
+client = HaikuRAG(db_path)
+```
+
+This is useful for:
+- Jupyter notebooks
+- Python scripts
+- Testing with different configurations
+- Applications that need runtime configuration
+
 ## API Keys
 
 API keys are configured through **environment variables**, not in the YAML file.
diff --git a/src/haiku/rag/config/__init__.py b/src/haiku/rag/config/__init__.py
index e0299a6f..b5717060 100644
--- a/src/haiku/rag/config/__init__.py
+++ b/src/haiku/rag/config/__init__.py
@@ -40,15 +40,53 @@ __all__ = [
     "load_yaml_config",
     "generate_default_config",
     "load_config_from_env",
+    "set_config",
 ]
 
-# Load config from YAML file or use defaults
-config_path = find_config_file(None)
-if config_path:
-    yaml_data = load_yaml_config(config_path)
-    Config = AppConfig.model_validate(yaml_data)
-else:
-    Config = AppConfig()
+
+class ConfigProxy:
+    """Proxy for the global configuration that allows runtime updates."""
+
+    def __init__(self):
+        # Load config from YAML file or use defaults
+        config_path = find_config_file(None)
+        if config_path:
+            yaml_data = load_yaml_config(config_path)
+            self._config = AppConfig.model_validate(yaml_data)
+        else:
+            self._config = AppConfig()
+
+    def __getattr__(self, name):
+        """Proxy attribute access to the underlying config."""
+        return getattr(self._config, name)
+
+    def set(self, config: AppConfig) -> None:
+        """Replace the current configuration."""
+        self._config = config
+
+
+# Create the global Config instance
+Config = ConfigProxy()
 
 # Check for deprecated .env file
 check_for_deprecated_env()
+
+
+def set_config(config: AppConfig) -> None:
+    """Set the global configuration programmatically.
+
+    This allows library users to configure haiku.rag without needing
+    a YAML file or environment variables.
+
+    Args:
+        config: The AppConfig instance to use globally.
+
+    Example:
+        >>> from haiku.rag.config import set_config, AppConfig
+        >>> custom_config = AppConfig(
+        ...     qa={"provider": "openai", "model": "gpt-4o"},
+        ...     embeddings={"provider": "voyage", "model": "voyage-3"}
+        ... )
+        >>> set_config(custom_config)
+    """
+    Config.set(config)