[pull] main from microsoft:main

.semversioner/next-release/patch-20260824180455220107.json

@@ -0,0 +1,4 @@
+{
+  "type": "patch",
+  "description": "Fix broken doc links and doc string parameter mismatches."
+}

docs/config/models.md

@@ -37,7 +37,7 @@ Versions of GraphRAG before 2.2.0 made extensive use of `max_tokens` and `logit_
 - Previously, GraphRAG used `max_tokens` to limit responses in a few locations. This is done so that we can have predictable content sizes when building downstream context windows for summarization. We have now switched from using `max_tokens` to use a prompted approach, which is working well in our tests. We suggest using `max_tokens` in your language model config only for budgetary reasons if you want to limit consumption, and not for expected response length control. We now also support the o-series equivalent `max_completion_tokens`, but if you use this keep in mind that there may be some unknown fixed reasoning consumption amount in addition to the response tokens, so it is not a good technique for response control.
 - Previously, GraphRAG used a combination of `max_tokens` and `logit_bias` to strictly control a binary yes/no question during gleanings. This is not possible with reasoning models, so again we have switched to a prompted approach. Our tests with gpt-4o, gpt-4o-mini, and o1 show that this works consistently, but could have issues if you have an older or smaller model.
 - The o-series models are much slower and more expensive. It may be useful to use an asymmetric approach to model use in your config: you can define as many models as you like in the `models` block of your settings.yaml and reference them by key for every workflow that requires a language model. You could use gpt-4o for indexing and o1 for query, for example. Experiment to find the right balance of cost, speed, and quality for your use case.
-- The o-series models contain a form of native native chain-of-thought reasoning that is absent in the non-o-series models. GraphRAG's prompts sometimes contain CoT because it was an effective technique with the gpt-4\* series. It may be counterproductive with the o-series, so you may want to tune or even re-write large portions of the prompt templates (particularly for graph and claim extraction).
+- The o-series models contain a form of native chain-of-thought reasoning that is absent in the non-o-series models. GraphRAG's prompts sometimes contain CoT because it was an effective technique with the gpt-4\* series. It may be counterproductive with the o-series, so you may want to tune or even re-write large portions of the prompt templates (particularly for graph and claim extraction).
 
 Example config with asymmetric model use:
 

docs/config/yaml.md

@@ -356,7 +356,7 @@ These are the settings used for Leiden hierarchical clustering of the graph to c
 - `data_max_tokens` **int** - The maximum tokens to use constructing the final response from the reduces responses.
 - `map_max_length` **int** - The maximum length to request for map responses, in words.
 - `reduce_max_length` **int** - The maximum length to request for reduce responses, in words.
-- `dynamic_search_threshold` **int** - Rating threshold in include a community report.
+- `dynamic_search_threshold` **int** - Rating threshold to include a community report.
 - `dynamic_search_keep_parent` **bool** - Keep parent community if any of the child communities are relevant.
 - `dynamic_search_num_repeats` **int** - Number of times to rate the same community report.
 - `dynamic_search_use_summary` **bool** - Use community summary instead of full_context.

docs/index/architecture.md

@@ -1,4 +1,4 @@
-# Indexing Architecture 
+# Indexing Architecture
 
 ## Key Concepts
 
@@ -48,6 +48,6 @@ The following subsystems use a factory pattern that allows you to register your
 - [vector store](https://github.com/microsoft/graphrag/blob/main/packages/graphrag-vectors/graphrag_vectors/vector_store_factory.py) - implement your own vector store other than the built-in lancedb, Azure AI Search, and CosmosDB ones built in
 - [pipeline + workflows](https://github.com/microsoft/graphrag/blob/main/packages/graphrag/graphrag/index/workflows/factory.py) - implement your own workflow steps with a custom `run_workflow` function, or register an entire pipeline (list of named workflows)
 
-The links for each of these subsystems point to the source code of the factory, which includes registration of the default built-in implementations. In addition, we have a detailed discussion of [language models](../config/models.md), which includes and example of a custom provider, and a [sample notebook](../examples_notebooks/custom_vector_store.ipynb) that demonstrates a custom vector store.
+The links for each of these subsystems point to the source code of the factory, which includes registration of the default built-in implementations. In addition, we have a detailed discussion of [language models](../config/models.md), which includes an example of a custom provider, and a [sample notebook](../../packages/graphrag-vectors/example_notebooks/custom_vector_store.ipynb) that demonstrates a custom vector store.
 
-All of these factories allow you to register an impl using any string name you would like, even overriding built-in ones directly.
+All of these factories allow you to register an impl using any string name you would like, even overriding built-in ones directly.

docs/query/notebooks/overview.md

@@ -1,7 +1,7 @@
 # API Notebooks
 
 - [API Overview Notebook](../../examples_notebooks/api_overview.ipynb)
-- [Bring-Your-Own Vector Store](../../examples_notebooks/custom_vector_store.ipynb)
+- [Bring-Your-Own Vector Store](../../../packages/graphrag-vectors/example_notebooks/custom_vector_store.ipynb)
 
 # Query Engine Notebooks
 

packages/graphrag-cache/README.md

@@ -1,22 +1,25 @@
 # GraphRAG Cache
 
+> [!WARNING]
+> GraphRAG is a research project that explores the functional use of graphs to form a targeted context for question answering. Since our first release in July 2024 the capabilities of frontier models have changed dramatically, and our portfolio of research projects has diversified to match. This project is largely in maintenance mode, and won't be accepting new PRs or implementing new features. We'll perform bug fixes and dependency updates as appropriate, particularly to address CVEs as they arise.
+
 This package contains a collection of utilities to handle GraphRAG caching implementation.
 
 ### Basic
 
-This example shows how to create a JSON cache with file storage using the GraphRAG cache package's configuration system. 
+This example shows how to create a JSON cache with file storage using the GraphRAG cache package's configuration system.
 
-[Open the notebook to explore the basic example code](example-notebooks/basic_cache_example.ipynb)
+[Open the notebook to explore the basic example code](example_notebooks/basic_cache_example.ipynb)
 
 ### Custom Cache
 
 This example demonstrates how to create a custom cache implementation by extending the base Cache class and registering it with the GraphRAG cache system. Once registered, the custom cache can be instantiated through the factory pattern using either CacheConfig or directly via cache_factory, allowing for extensible caching solutions tailored to specific needs.
 
-[Open the notebook to explore the basic custom example code](example-notebooks/custom_cache_example.ipynb)
+[Open the notebook to explore the basic custom example code](example_notebooks/custom_cache_example.ipynb)
 
 #### Details
 
-By default, the `create_cache` comes with the following cache providers registered that correspond to the entries in the `CacheType` enum. 
+By default, the `create_cache` comes with the following cache providers registered that correspond to the entries in the `CacheType` enum.
 
 - `JsonCache`
 - `MemoryCache`
@@ -40,4 +43,4 @@ cache = cache_factory.create(
 )
 
 ...
-```
+```

packages/graphrag-chunking/README.md

@@ -1,5 +1,8 @@
 # GraphRAG Chunking
 
+> [!WARNING]
+> GraphRAG is a research project that explores the functional use of graphs to form a targeted context for question answering. Since our first release in July 2024 the capabilities of frontier models have changed dramatically, and our portfolio of research projects has diversified to match. This project is largely in maintenance mode, and won't be accepting new PRs or implementing new features. We'll perform bug fixes and dependency updates as appropriate, particularly to address CVEs as they arise.
+
 This package contains a collection of text chunkers, a core config model, and a factory for acquiring instances.
 
 ## Examples
@@ -16,7 +19,6 @@ The TokenChunker splits text into fixed-size chunks based on token count rather
 
 [Open the notebook to explore the token chunking example code](example_notebooks/token_chunking_example.ipynb)
 
-
 ### Using the factory via helper util
 
 The create_chunker factory function provides a configuration-driven approach to instantiate chunkers by accepting a ChunkingConfig object that specifies the chunking strategy and parameters. This allows for more flexible and maintainable code by separating chunker configuration from direct instantiation.

packages/graphrag-common/README.md

@@ -1,5 +1,8 @@
 # GraphRAG Common
 
+> [!WARNING]
+> GraphRAG is a research project that explores the functional use of graphs to form a targeted context for question answering. Since our first release in July 2024 the capabilities of frontier models have changed dramatically, and our portfolio of research projects has diversified to match. This project is largely in maintenance mode, and won't be accepting new PRs or implementing new features. We'll perform bug fixes and dependency updates as appropriate, particularly to address CVEs as they arise.
+
 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

packages/graphrag-input/README.md

@@ -1,5 +1,8 @@
 # GraphRAG Inputs
 
+> [!WARNING]
+> GraphRAG is a research project that explores the functional use of graphs to form a targeted context for question answering. Since our first release in July 2024 the capabilities of frontier models have changed dramatically, and our portfolio of research projects has diversified to match. This project is largely in maintenance mode, and won't be accepting new PRs or implementing new features. We'll perform bug fixes and dependency updates as appropriate, particularly to address CVEs as they arise.
+
 This package provides input document loading utilities for GraphRAG, supporting multiple file formats including CSV, JSON, JSON Lines, and plain text.
 
 ## Supported File Types
@@ -21,22 +24,21 @@ Additionally, we support the `InputType.MarkItDown` format, which uses the [Mark
 
 Basic usage with the factory:
 
-
 1. Import a pdf with MarkItDown:
 
 ```bash
 pip install 'markitdown[pdf]' # required dependency for pdf processing
 ```
 
-
 2. YAML config example for above:
+
 ```yaml
 input:
   type: markitdown
   file_pattern: ".*\\.pdf$$"
 input_storage:
-    type: file
-    base_dir: "input"
+  type: file
+  base_dir: "input"
 ```
 
-[Open the notebook to explore the input example code](example_notebooks/input_example.ipynb)
+[Open the notebook to explore the input example code](example_notebooks/input_example.ipynb)

packages/graphrag-llm/README.md

@@ -1,16 +1,18 @@
 # GraphRAG LLM
 
+> [!WARNING]
+> GraphRAG is a research project that explores the functional use of graphs to form a targeted context for question answering. Since our first release in July 2024 the capabilities of frontier models have changed dramatically, and our portfolio of research projects has diversified to match. This project is largely in maintenance mode, and won't be accepting new PRs or implementing new features. We'll perform bug fixes and dependency updates as appropriate, particularly to address CVEs as they arise.
+
 ## Basic Completion
 
 This example demonstrates basic usage of the LLM library to interact with Azure OpenAI. It loads environment variables for API configuration, creates a ModelConfig for Azure OpenAI, and sends a simple question to the model. The code handles both streaming and non-streaming responses (streaming responses are printed chunk by chunk in real-time, while non-streaming responses are printed all at once). It also shows how to use the gather_completion_response utility function as a simpler alternative that automatically handles both response types and returns the complete text.
 
 [Open the notebook to explore the basic completion example code](example_notebooks/basic_completion_example.ipynb)
 
-
 ## Basic Embedding
 
 This examples demonstrates how to generate text embeddings using the GraphRAG LLM library with Azure OpenAI's embedding service. It loads API credentials from environment variables, creates a ModelConfig for the Azure embedding model and configures authentication to use either API key or Azure Managed Identity. The script then creates an embedding client and processes a batch of two text strings ("Hello world" and "How are you?") to generate their vector embeddings.
 
-[Open the notebook to explore the basic embeddings example code](example_notebooks/basic_completion_example.ipynb)
+[Open the notebook to explore the basic embeddings example code](example_notebooks/basic_embedding_example.ipynb)
 
-View the [notebooks](example_notebooks/README.md) for more examples.
+View the [notebooks](notebooks/README.md) for more examples.

packages/graphrag-llm/graphrag_llm/utils/create_embedding_response.py

@@ -13,9 +13,7 @@ def create_embedding_response(
 
     Args:
         embeddings: List of embedding vectors.
-        model: The model used to create the embeddings.
-
-    Returns
+            batch_size: The number of embedding objects to generate.
     -------
         An LLMEmbeddingResponse object.
     """

packages/graphrag-storage/README.md

@@ -1,5 +1,8 @@
 # GraphRAG Storage
 
+> [!WARNING]
+> GraphRAG is a research project that explores the functional use of graphs to form a targeted context for question answering. Since our first release in July 2024 the capabilities of frontier models have changed dramatically, and our portfolio of research projects has diversified to match. This project is largely in maintenance mode, and won't be accepting new PRs or implementing new features. We'll perform bug fixes and dependency updates as appropriate, particularly to address CVEs as they arise.
+
 This package provides a unified storage abstraction layer with support for multiple backends including file system, Azure Blob, Azure Cosmos, and memory storage. It features a factory-based creation system with configuration-driven setup and extensible architecture for implementing custom storage providers.
 
 ## Basic
@@ -14,10 +17,9 @@ Here we create a custom storage implementation by extending the base Storage cla
 
 [Open the notebook to explore the custom storage example code](example_notebooks/basic_storage_example.ipynb)
 
-
 ## Details
 
-By default, the `create_storage` comes with the following storage providers registered that correspond to the entries in the `StorageType` enum. 
+By default, the `create_storage` comes with the following storage providers registered that correspond to the entries in the `StorageType` enum.
 
 - `FileStorage`
 - `AzureBlobStorage`
@@ -42,4 +44,4 @@ storage = storage_factory.create(
 )
 
 ...
-```
+```

packages/graphrag-vectors/README.md

@@ -1,5 +1,8 @@
 # GraphRAG Vectors
 
+> [!WARNING]
+> GraphRAG is a research project that explores the functional use of graphs to form a targeted context for question answering. Since our first release in July 2024 the capabilities of frontier models have changed dramatically, and our portfolio of research projects has diversified to match. This project is largely in maintenance mode, and won't be accepting new PRs or implementing new features. We'll perform bug fixes and dependency updates as appropriate, particularly to address CVEs as they arise.
+
 This package provides vector store implementations for GraphRAG with support for multiple backends including LanceDB, Azure AI Search, and Azure Cosmos DB. It offers both a convenient configuration-driven API and direct factory access for creating and managing vector stores with flexible index schema definitions.
 
 ## Basic usage with the utility function (recommended)
@@ -29,5 +32,6 @@ You can register custom vector store implementations:
 ## Configuration
 
 Vector stores are configured using:
+
 - `VectorStoreConfig`: baseline parameters for the store
 - `IndexSchema`: Schema configuration for the specific index to create/connect to (index name, field names, vector size)