microsoft--graphrag/packages/graphrag-common/example_notebooks/config_module_example.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 72,
   "id": "cf9db0e4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Copyright (c) 2026 Microsoft Corporation.\n",
    "# Licensed under the MIT License."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "938c7d8b",
   "metadata": {},
   "source": [
    "## Config module example\n",
    "\n",
    "The load_config function provides a comprehensive configuration loading system that automatically discovers and parses YAML/JSON config files into Pydantic models with support for environment variable substitution and .env file loading. It offers flexible features like config overrides, custom parsers for different file formats, and automatically sets the working directory to the config file location for relative path resolution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "id": "673ba055",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Config loaded successfully using basic loading:\n",
      "Name: my-app\n",
      "Logging directory: output/logs\n",
      "Logging filename: app.log\n"
     ]
    }
   ],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "import toml\n",
    "from graphrag_common.config import load_config\n",
    "from pydantic import BaseModel, Field\n",
    "\n",
    "\n",
    "class Logging(BaseModel):\n",
    "    \"\"\"Test nested model.\"\"\"\n",
    "\n",
    "    directory: str = Field(default=\"output/logs\")\n",
    "    filename: str = Field(default=\"logs.txt\")\n",
    "\n",
    "\n",
    "class Config(BaseModel):\n",
    "    \"\"\"Test configuration model.\"\"\"\n",
    "\n",
    "    name: str = Field(description=\"Name field.\")\n",
    "    logging: Logging = Field(description=\"Nested model field.\")\n",
    "\n",
    "\n",
    "# Basic - by default:\n",
    "# - searches for Path.cwd() / settings.[yaml|yml|json]\n",
    "# - sets the CWD to the directory containing the config file.\n",
    "#   so if no custom config path is provided than CWD remains unchanged.\n",
    "# - loads config_directory/.env file\n",
    "# - parses ${env} in the config file\n",
    "config = load_config(Config)\n",
    "\n",
    "# Custom file location\n",
    "config = load_config(Config, \"settings.yaml\")\n",
    "\n",
    "print(\"Config loaded successfully using basic loading:\")\n",
    "\n",
    "print(f\"Name: {config.name}\")\n",
    "print(f\"Logging directory: {config.logging.directory}\")\n",
    "print(f\"Logging filename: {config.logging.filename}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "98d2f980",
   "metadata": {},
   "source": [
    "### Using a custom file extension for the configuration file: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "id": "1969c6d3",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Config loaded successfully using file extension:\n",
      "Name: my-app-test\n",
      "Logging directory: output/logs\n",
      "Logging filename: app.log\n"
     ]
    }
   ],
   "source": [
    "# Using a custom file extension with\n",
    "# custom config parser (str) -> dict[str, Any]\n",
    "config = load_config(\n",
    "    config_initializer=Config,\n",
    "    config_path=\"config.toml\",\n",
    "    config_parser=lambda contents: toml.loads(contents),  # Needs toml pypi package\n",
    ")\n",
    "\n",
    "print(\"Config loaded successfully using file extension:\")\n",
    "print(f\"Name: {config.name}\")\n",
    "print(f\"Logging directory: {config.logging.directory}\")\n",
    "print(f\"Logging filename: {config.logging.filename}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1a2cdcfa",
   "metadata": {},
   "source": [
    "### Overriding properties from the config object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 75,
   "id": "c955e328",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Config loaded successfully with overrides:\n",
      "Name: some name\n",
      "Logging directory: output/logs\n",
      "Logging filename: my_logs.txt\n"
     ]
    }
   ],
   "source": [
    "# With overrides - provided values override whats in the config file\n",
    "# Only overrides what is specified - recursively merges settings.\n",
    "config = load_config(\n",
    "    config_initializer=Config,\n",
    "    overrides={\"name\": \"some name\", \"logging\": {\"filename\": \"my_logs.txt\"}},\n",
    ")\n",
    "\n",
    "print(\"Config loaded successfully with overrides:\")\n",
    "print(f\"Name: {config.name}\")\n",
    "print(f\"Logging directory: {config.logging.directory}\")\n",
    "print(f\"Logging filename: {config.logging.filename}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a9887e7a",
   "metadata": {},
   "source": [
    "### Resolving relative paths"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 76,
   "id": "141e164d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Config loaded successfully with overrides:\n",
      "Name: my-app-config\n",
      "Logging directory: output/logs\n",
      "Logging filename: logs.txt\n"
     ]
    }
   ],
   "source": [
    "# By default, sets CWD to directory containing config file\n",
    "# So custom config paths will change the CWD.\n",
    "config = load_config(\n",
    "    config_initializer=Config,\n",
    "    config_path=\"config.yaml\",\n",
    "    set_cwd=True,  # default\n",
    ")\n",
    "\n",
    "print(\"Config loaded successfully with overrides:\")\n",
    "print(f\"Name: {config.name}\")\n",
    "print(f\"Logging directory: {config.logging.directory}\")\n",
    "print(f\"Logging filename: {config.logging.filename}\")\n",
    "\n",
    "# And now throughout the codebase resolving relative paths in config\n",
    "# will resolve relative to the config directory\n",
    "\n",
    "Path(config.logging.directory)\n",
    "\n",
    "assert str(Path(config.logging.directory)) == \"output/logs\""
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}