graphrag-common 3.0.0__py3-none-any.whl

graphrag_common/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2024 Microsoft Corporation.
+# Licensed under the MIT License
+
+"""GraphRAG Common package."""

graphrag_common/config/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2024 Microsoft Corporation.
+# Licensed under the MIT License
+
+"""The GraphRAG config module."""
+
+from graphrag_common.config.load_config import ConfigParsingError, load_config
+
+__all__ = ["ConfigParsingError", "load_config"]

graphrag_common/config/load_config.py

@@ -0,0 +1,205 @@
+# Copyright (c) 2024 Microsoft Corporation.
+# Licensed under the MIT License
+
+"""Load configuration."""
+
+import json
+import os
+from collections.abc import Callable
+from pathlib import Path
+from string import Template
+from typing import Any, TypeVar
+
+import yaml
+from dotenv import load_dotenv
+
+T = TypeVar("T", covariant=True)
+
+_default_config_files = ["settings.yaml", "settings.yml", "settings.json"]
+
+
+class ConfigParsingError(ValueError):
+    """Configuration Parsing Error."""
+
+    def __init__(self, msg: str) -> None:
+        """Initialize the ConfigParsingError."""
+        super().__init__(msg)
+
+
+def _get_config_file_path(config_dir_or_file: Path) -> Path:
+    """Resolve the config path from the given directory or file."""
+    config_dir_or_file = Path(config_dir_or_file)
+
+    if config_dir_or_file.is_file():
+        return config_dir_or_file
+
+    if not config_dir_or_file.is_dir():
+        msg = f"Invalid config path: {config_dir_or_file} is not a directory"
+        raise FileNotFoundError(msg)
+
+    for file in _default_config_files:
+        if (config_dir_or_file / file).is_file():
+            return config_dir_or_file / file
+
+    msg = f"No 'settings.[yaml|yml|json]' config file found in directory: {config_dir_or_file}"
+    raise FileNotFoundError(msg)
+
+
+def _load_dotenv(env_file_path: Path, required: bool) -> None:
+    """Load the .env file if it exists."""
+    if not env_file_path.is_file():
+        if not required:
+            return
+        msg = f"dot_env_path not found: {env_file_path}"
+        raise FileNotFoundError(msg)
+    load_dotenv(env_file_path)
+
+
+def _parse_json(data: str) -> dict[str, Any]:
+    """Parse JSON data."""
+    return json.loads(data)
+
+
+def _parse_yaml(data: str) -> dict[str, Any]:
+    """Parse YAML data."""
+    return yaml.safe_load(data)
+
+
+def _get_parser_for_file(file_path: str | Path) -> Callable[[str], dict[str, Any]]:
+    """Get the parser for the given file path."""
+    file_path = Path(file_path).resolve()
+    match file_path.suffix.lower():
+        case ".json":
+            return _parse_json
+        case ".yaml" | ".yml":
+            return _parse_yaml
+        case _:
+            msg = (
+                f"Failed to parse, {file_path}. Unsupported file extension, "
+                + f"{file_path.suffix}. Pass in a custom config_parser argument or "
+                + "use one of the supported file extensions, .json, .yaml, .yml, .toml."
+            )
+            raise ConfigParsingError(msg)
+
+
+def _parse_env_variables(text: str) -> str:
+    """Parse environment variables in the configuration text."""
+    try:
+        return Template(text).substitute(os.environ)
+    except KeyError as error:
+        msg = f"Environment variable not found: {error}"
+        raise ConfigParsingError(msg) from error
+
+
+def _recursive_merge_dicts(dest: dict[str, Any], src: dict[str, Any]) -> None:
+    """Recursively merge two dictionaries in place."""
+    for key, value in src.items():
+        if isinstance(value, dict):
+            if isinstance(dest.get(key), dict):
+                _recursive_merge_dicts(dest[key], value)
+            else:
+                dest[key] = value
+        else:
+            dest[key] = value
+
+
+def load_config(
+    config_initializer: Callable[..., T],
+    config_path: str | Path | None = None,
+    overrides: dict[str, Any] | None = None,
+    set_cwd: bool = True,
+    parse_env_vars: bool = True,
+    load_dot_env_file: bool = True,
+    dot_env_path: str | Path | None = None,
+    config_parser: Callable[[str], dict[str, Any]] | None = None,
+    file_encoding: str = "utf-8",
+) -> T:
+    """Load configuration from a file.
+
+    Parameters
+    ----------
+    config_initializer : Callable[..., T]
+        Configuration constructor/initializer.
+        Should accept **kwargs to initialize the configuration,
+        e.g., Config(**kwargs).
+    config_path : str | Path | None, optional (default=None)
+        Path to the configuration directory containing settings.[yaml|yml|json].
+        Or path to a configuration file itself.
+        If None, search the current working directory for
+        settings.[yaml|yml|json].
+    overrides : dict[str, Any] | None, optional (default=None)
+        Configuration overrides.
+        Useful for overriding configuration settings programmatically,
+        perhaps from CLI flags.
+    set_cwd : bool, optional (default=True)
+        Whether to set the current working directory to the directory
+        containing the configuration file. Helpful for resolving relative paths
+        in the configuration file.
+    parse_env_vars : bool, optional (default=True)
+        Whether to parse environment variables in the configuration text.
+    load_dot_env_file : bool, optional (default=True)
+        Whether to load the .env file prior to parsing environment variables.
+    dot_env_path : str | Path | None, optional (default=None)
+        Optional .env file to load prior to parsing env variables.
+        If None and load_dot_env_file is True, looks for a .env file in the
+        same directory as the config file.
+    config_parser : Callable[[str], dict[str, Any]] | None, optional (default=None)
+        function to parse the configuration text, (str) -> dict[str, Any].
+        If None, the parser is inferred from the file extension.
+        Supported extensions: .json, .yaml, .yml.
+    file_encoding : str, optional (default="utf-8")
+        File encoding to use when reading the configuration file.
+
+    Returns
+    -------
+    T
+        The initialized configuration object.
+
+    Raises
+    ------
+    FileNotFoundError
+        - If the config file is not found.
+        - If the .env file is not found when parse_env_vars is True and dot_env_path is provided.
+
+    ConfigParsingError
+        - If an environment variable is not found when parsing env variables.
+        - If there was a problem merging the overrides with the configuration.
+        - If parser=None and load_config was unable to determine how to parse
+        the file based on the file extension.
+        - If the parser fails to parse the configuration text.
+    """
+    config_path = Path(config_path).resolve() if config_path else Path.cwd()
+    config_path = _get_config_file_path(config_path)
+
+    file_contents = config_path.read_text(encoding=file_encoding)
+
+    if parse_env_vars:
+        if load_dot_env_file:
+            required = dot_env_path is not None
+            dot_env_path = (
+                Path(dot_env_path) if dot_env_path else config_path.parent / ".env"
+            )
+            _load_dotenv(dot_env_path, required=required)
+        file_contents = _parse_env_variables(file_contents)
+
+    if config_parser is None:
+        config_parser = _get_parser_for_file(config_path)
+
+    config_data: dict[str, Any] = {}
+    try:
+        config_data = config_parser(file_contents)
+    except Exception as error:
+        msg = f"Failed to parse config_path: {config_path}. Error: {error}"
+        raise ConfigParsingError(msg) from error
+
+    if overrides is not None:
+        try:
+            _recursive_merge_dicts(config_data, overrides)
+        except Exception as error:
+            msg = f"Failed to merge overrides with config_path: {config_path}. Error: {error}"
+            raise ConfigParsingError(msg) from error
+
+    if set_cwd:
+        os.chdir(config_path.parent)
+
+    return config_initializer(**config_data)

graphrag_common/factory/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2024 Microsoft Corporation.
+# Licensed under the MIT License
+
+"""The GraphRAG factory module."""
+
+from graphrag_common.factory.factory import Factory, ServiceScope
+
+__all__ = ["Factory", "ServiceScope"]

graphrag_common/factory/factory.py

@@ -0,0 +1,113 @@
+# Copyright (c) 2025 Microsoft Corporation.
+# Licensed under the MIT License
+
+"""Factory ABC."""
+
+from abc import ABC
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, ClassVar, Generic, Literal, TypeVar
+
+from graphrag_common.hasher import hash_data
+
+T = TypeVar("T", covariant=True)
+
+ServiceScope = Literal["singleton", "transient"]
+
+
+@dataclass
+class _ServiceDescriptor(Generic[T]):
+    """Descriptor for a service."""
+
+    scope: ServiceScope
+    initializer: Callable[..., T]
+
+
+class Factory(ABC, Generic[T]):
+    """Abstract base class for factories."""
+
+    _instance: ClassVar["Factory | None"] = None
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "Factory[T]":
+        """Create a new instance of Factory if it does not exist."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls, *args, **kwargs)
+        return cls._instance
+
+    def __init__(self):
+        if not hasattr(self, "_initialized"):
+            self._service_initializers: dict[str, _ServiceDescriptor[T]] = {}
+            self._initialized_services: dict[str, T] = {}
+            self._initialized = True
+
+    def __contains__(self, strategy: str) -> bool:
+        """Check if a strategy is registered."""
+        return strategy in self._service_initializers
+
+    def keys(self) -> list[str]:
+        """Get a list of registered strategy names."""
+        return list(self._service_initializers.keys())
+
+    def register(
+        self,
+        strategy: str,
+        initializer: Callable[..., T],
+        scope: ServiceScope = "transient",
+    ) -> None:
+        """
+        Register a new service.
+
+        Args
+        ----
+            strategy: str
+                The name of the strategy.
+            initializer: Callable[..., T]
+                A callable that creates an instance of T.
+            scope: ServiceScope (default: "transient")
+                The scope of the service ("singleton" or "transient").
+                Singleton services are cached based on their init args
+                so that the same instance is returned for the same init args.
+        """
+        self._service_initializers[strategy] = _ServiceDescriptor(scope, initializer)
+
+    def create(self, strategy: str, init_args: dict[str, Any] | None = None) -> T:
+        """
+        Create a service instance based on the strategy.
+
+        Args
+        ----
+            strategy: str
+                The name of the strategy.
+            init_args: dict[str, Any] | None
+                A dictionary of keyword arguments to pass to the service initializer.
+
+        Returns
+        -------
+            An instance of T.
+
+        Raises
+        ------
+            ValueError: If the strategy is not registered.
+        """
+        if strategy not in self._service_initializers:
+            msg = f"Strategy '{strategy}' is not registered. Registered strategies are: {', '.join(list(self._service_initializers.keys()))}"
+            raise ValueError(msg)
+
+        # Delete entries with value None
+        # That way services can have default values
+        init_args = {k: v for k, v in (init_args or {}).items() if v is not None}
+
+        service_descriptor = self._service_initializers[strategy]
+        if service_descriptor.scope == "singleton":
+            cache_key = hash_data({
+                "strategy": strategy,
+                "init_args": init_args,
+            })
+
+            if cache_key not in self._initialized_services:
+                self._initialized_services[cache_key] = service_descriptor.initializer(
+                    **init_args
+                )
+            return self._initialized_services[cache_key]
+
+        return service_descriptor.initializer(**(init_args or {}))

graphrag_common/hasher/__init__.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2024 Microsoft Corporation.
+# Licensed under the MIT License
+
+"""The GraphRAG hasher module."""
+
+from graphrag_common.hasher.hasher import (
+    Hasher,
+    hash_data,
+    make_yaml_serializable,
+    sha256_hasher,
+)
+
+__all__ = [
+    "Hasher",
+    "hash_data",
+    "make_yaml_serializable",
+    "sha256_hasher",
+]

graphrag_common/hasher/hasher.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2024 Microsoft Corporation.
+# Licensed under the MIT License
+
+"""The GraphRAG hasher module."""
+
+import hashlib
+from collections.abc import Callable
+from typing import Any
+
+import yaml
+
+Hasher = Callable[[str], str]
+"""Type alias for a hasher function (data: str) -> str."""
+
+
+def sha256_hasher(data: str) -> str:
+    """Generate a SHA-256 hash for the input data."""
+    return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+
+def make_yaml_serializable(data: Any) -> Any:
+    """Convert data to a YAML-serializable format."""
+    if isinstance(data, (list, tuple)):
+        return tuple(make_yaml_serializable(item) for item in data)
+
+    if isinstance(data, set):
+        return tuple(sorted(make_yaml_serializable(item) for item in data))
+
+    if isinstance(data, dict):
+        return tuple(
+            sorted((key, make_yaml_serializable(value)) for key, value in data.items())
+        )
+
+    return str(data)
+
+
+def hash_data(data: Any, *, hasher: Hasher | None = None) -> str:
+    """Hash the input data dictionary using the specified hasher function.
+
+    Args
+    ----
+        data: dict[str, Any]
+            The input data to be hashed.
+            The input data is serialized using yaml
+            to support complex data structures such as classes and functions.
+        hasher: Hasher | None (default: sha256_hasher)
+            The hasher function to use. (data: str) -> str
+
+    Returns
+    -------
+        str
+            The resulting hash of the input data.
+
+    """
+    hasher = hasher or sha256_hasher
+    try:
+        return hasher(yaml.dump(data, sort_keys=True))
+    except TypeError:
+        return hasher(yaml.dump(make_yaml_serializable(data), sort_keys=True))

graphrag_common-3.0.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: graphrag-common
+Version: 3.0.0
+Summary: Common utilities and types for GraphRAG
+Project-URL: Source, https://github.com/microsoft/graphrag
+Author: Mónica Carvajal
+Author-email: Alonso Guevara Fernández <alonsog@microsoft.com>, Andrés Morales Esquivel <andresmor@microsoft.com>, Chris Trevino <chtrevin@microsoft.com>, David Tittsworth <datittsw@microsoft.com>, Dayenne de Souza <ddesouza@microsoft.com>, Derek Worthen <deworthe@microsoft.com>, Gaudy Blanco Meneses <gaudyb@microsoft.com>, Ha Trinh <trinhha@microsoft.com>, Jonathan Larson <jolarso@microsoft.com>, Josh Bradley <joshbradley@microsoft.com>, Kate Lytvynets <kalytv@microsoft.com>, Kenny Zhang <zhangken@microsoft.com>, Nathan Evans <naevans@microsoft.com>, Rodrigo Racanicci <rracanicci@microsoft.com>, Sarah Smith <smithsarah@microsoft.com>
+License: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Requires-Dist: python-dotenv~=1.0
+Requires-Dist: pyyaml~=6.0
+Description-Content-Type: text/markdown
+
+# GraphRAG Common
+
+This package provides utility modules for GraphRAG, including a flexible factory system for dependency injection and service registration, and a comprehensive configuration loading system with Pydantic model support, environment variable substitution, and automatic file discovery.
+
+## Factory module
+
+The Factory class provides a flexible dependency injection pattern that can register and create instances of classes implementing a common interface using string-based strategies. It supports both transient scope (creates new instances on each request) and singleton scope (returns the same instance after first creation).
+
+```python
+from abc import ABC, abstractmethod
+
+from graphrag_common.factory import Factory
+
+class SampleABC(ABC):
+
+    @abstractmethod
+    def get_value(self) -> str:
+        msg = "Subclasses must implement the get_value method."
+        raise NotImplementedError(msg)
+
+
+class ConcreteClass(SampleABC):
+    def __init__(self, value: str):
+        self._value = value
+
+    def get_value(self) -> str:
+        return self._value
+
+class SampleFactory(Factory[SampleABC]):
+"""A Factory for SampleABC classes."""
+
+factory = SampleFactory()
+
+# Registering transient services
+# A new one is created for every request
+factory.register("some_strategy", ConcreteTestClass)
+
+trans1 = factory.create("some_strategy", {"value": "test1"})
+trans2 = factory.create("some_strategy", {"value": "test2"})
+
+assert trans1 is not trans2
+assert trans1.get_value() == "test1"
+assert trans2.get_value() == "test2"
+
+# Registering singleton services
+# After first creation, the same one is returned every time
+factory.register("some_other_strategy", ConcreteTestClass, scope="singleton")
+
+single1 = factory.create("some_other_strategy", {"value": "singleton"})
+single2 = factory.create("some_other_strategy", {"value": "ignored"})
+
+assert single1 is single2
+assert single1.get_value() == "singleton"
+assert single2.get_value() == "singleton"
+```
+
+## Config module
+
+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.
+
+```python
+from pydantic import BaseModel, Field
+from graphrag_common.config import load_config
+
+from pathlib import Path
+
+class Logging(BaseModel):
+    """Test nested model."""
+
+    directory: str = Field(default="output/logs")
+    filename: str = Field(default="logs.txt")
+
+class Config(BaseModel):
+    """Test configuration model."""
+
+    name: str = Field(description="Name field.")
+    logging: Logging = Field(description="Nested model field.")
+
+# Basic - by default:
+# - searches for Path.cwd() / settings.[yaml|yml|json] 
+# - sets the CWD to the directory containing the config file.
+#   so if no custom config path is provided than CWD remains unchanged.
+# - loads config_directory/.env file
+# - parses ${env} in the config file
+config = load_config(Config)
+
+# Custom file location
+config = load_config(Config, "path_to_config_filename_or_directory_containing_settings.[yaml|yml|json]")
+
+# Using a custom file extension with 
+# custom config parser (str) -> dict[str, Any]
+config = load_config(
+    config_initializer=Config,
+    config_path="config.toml",
+    config_parser=lambda contents: toml.loads(contents) # Needs toml pypi package
+)
+
+# With overrides - provided values override whats in the config file
+# Only overrides what is specified - recursively merges settings.
+config = load_config(
+    config_initializer=Config,
+    overrides={
+        "name": "some name",
+        "logging": {
+            "filename": "my_logs.txt"
+        }
+    },
+)
+
+# By default, sets CWD to directory containing config file
+# So custom config paths will change the CWD.
+config = load_config(
+    config_initializer=Config,
+    config_path="some/path/to/config.yaml",
+    set_cwd=True # default
+)
+
+# now cwd == some/path/to
+assert Path.cwd() == "some/path/to"
+
+# And now throughout the codebase resolving relative paths in config
+# will resolve relative to the config directory
+Path(config.logging.directory) == "some/path/to/output/logs"
+
+```

graphrag_common-3.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+graphrag_common/__init__.py,sha256=s68tLiBfUEDmUvx-HugWKjamxVULHs70LCS4DoMlU7I,109
+graphrag_common/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graphrag_common/config/__init__.py,sha256=SjctkqbxSprZSkpDa9s-1l39dyNOPqfPyGXNj33RSEo,241
+graphrag_common/config/load_config.py,sha256=9pGAnRP8ZfzD5yDOBMqumBPnQ3acnDgaK3HtgnJTJmY,7361
+graphrag_common/factory/__init__.py,sha256=UVp3KH-wSfJSXJpIyTxPSml6tPZWsyfNrUIJFlMJqPo,219
+graphrag_common/factory/factory.py,sha256=rHXGkYZztKD_rid-kxYk8-2qio0O3htWRLlM1myNWMg,3749
+graphrag_common/hasher/__init__.py,sha256=6CxkLbWyTFfQvwTkkzqtxUGUuUPEEquJ6_YXhWKj3xE,330
+graphrag_common/hasher/hasher.py,sha256=JaPTwJnWru4Nhx9UXNdFwV8y7RSb-XLR6OOYIRJiovc,1709
+graphrag_common-3.0.0.dist-info/METADATA,sha256=2MLK4ExHqIVBAp6bmf7sjZ2xv6MyVAwatT6GTXoZ_QI,5563
+graphrag_common-3.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+graphrag_common-3.0.0.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+graphrag_common-3.0.0.dist-info/RECORD,,

graphrag_common-3.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

graphrag_common-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE