Update config docs (2.1.0) (#1818)

* Align docs with config

* Semver

* Spelling

* Format

* Spelling

Author: natoverse

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

@@ -0,0 +1,4 @@
+{
+  "type": "patch",
+  "description": "Align config classes and docs better."
+}

docs/config/yaml.md

@@ -55,17 +55,6 @@
     tokens_per_minute: 0              # set to 0 to disable rate limiting
     requests_per_minute: 0            # set to 0 to disable rate limiting
 
-vector_store:
-  {defs.DEFAULT_VECTOR_STORE_ID}:
-    type: {vector_store_defaults.type}
-    db_uri: {vector_store_defaults.db_uri}
-    container_name: {vector_store_defaults.container_name}
-    overwrite: {vector_store_defaults.overwrite}
-
-embed_text:
-  model_id: {graphrag_config_defaults.embed_text.model_id}
-  vector_store_id: {graphrag_config_defaults.embed_text.vector_store_id}
-
 ### Input settings ###
 
 input:
@@ -78,10 +67,14 @@
   overlap: {graphrag_config_defaults.chunks.overlap}
   group_by_columns: [{",".join(graphrag_config_defaults.chunks.group_by_columns)}]
 
-### Output settings ###
+### Output/storage settings ###
 ## If blob storage is specified in the following four sections,
 ## connection_string and container_name must be provided
 
+output:
+  type: {graphrag_config_defaults.output.type.value} # [file, blob, cosmosdb]
+  base_dir: "{graphrag_config_defaults.output.base_dir}"
+    
 cache:
   type: {graphrag_config_defaults.cache.type.value} # [file, blob, cosmosdb]
   base_dir: "{graphrag_config_defaults.cache.base_dir}"
@@ -90,12 +83,19 @@
   type: {graphrag_config_defaults.reporting.type.value} # [file, blob, cosmosdb]
   base_dir: "{graphrag_config_defaults.reporting.base_dir}"
 
-output:
-  type: {graphrag_config_defaults.output.type.value} # [file, blob, cosmosdb]
-  base_dir: "{graphrag_config_defaults.output.base_dir}"
+vector_store:
+  {defs.DEFAULT_VECTOR_STORE_ID}:
+    type: {vector_store_defaults.type}
+    db_uri: {vector_store_defaults.db_uri}
+    container_name: {vector_store_defaults.container_name}
+    overwrite: {vector_store_defaults.overwrite}
 
 ### Workflow settings ###
 
+embed_text:
+  model_id: {graphrag_config_defaults.embed_text.model_id}
+  vector_store_id: {graphrag_config_defaults.embed_text.vector_store_id}
+
 extract_graph:
   model_id: {graphrag_config_defaults.extract_graph.model_id}
   prompt: "prompts/extract_graph.txt"
@@ -111,6 +111,9 @@
   text_analyzer:
     extractor_type: {graphrag_config_defaults.extract_graph_nlp.text_analyzer.extractor_type.value} # [regex_english, syntactic_parser, cfg]
 
+cluster_graph:
+  max_cluster_size: {graphrag_config_defaults.cluster_graph.max_cluster_size}
+
 extract_claims:
   enabled: false
   model_id: {graphrag_config_defaults.extract_claims.model_id}
@@ -125,9 +128,6 @@
   max_length: {graphrag_config_defaults.community_reports.max_length}
   max_input_length: {graphrag_config_defaults.community_reports.max_input_length}
 
-cluster_graph:
-  max_cluster_size: {graphrag_config_defaults.cluster_graph.max_cluster_size}
-
 embed_graph:
   enabled: false # if true, will generate node2vec embeddings for nodes
 

graphrag/config/init_content.py

@@ -14,6 +14,10 @@
 class CommunityReportsConfig(BaseModel):
     """Configuration section for community reports."""
 
+    model_id: str = Field(
+        description="The model ID to use for community reports.",
+        default=graphrag_config_defaults.community_reports.model_id,
+    )
     graph_prompt: str | None = Field(
         description="The community report extraction prompt to use for graph-based summarization.",
         default=graphrag_config_defaults.community_reports.graph_prompt,
@@ -34,10 +38,6 @@ class CommunityReportsConfig(BaseModel):
         description="The override strategy to use.",
         default=graphrag_config_defaults.community_reports.strategy,
     )
-    model_id: str = Field(
-        description="The model ID to use for community reports.",
-        default=graphrag_config_defaults.community_reports.model_id,
-    )
 
     def resolved_strategy(
         self, root_dir: str, model_config: LanguageModelConfig

graphrag/config/models/community_reports_config.py

@@ -18,6 +18,10 @@ class ClaimExtractionConfig(BaseModel):
         description="Whether claim extraction is enabled.",
         default=graphrag_config_defaults.extract_claims.enabled,
     )
+    model_id: str = Field(
+        description="The model ID to use for claim extraction.",
+        default=graphrag_config_defaults.extract_claims.model_id,
+    )
     prompt: str | None = Field(
         description="The claim extraction prompt to use.",
         default=graphrag_config_defaults.extract_claims.prompt,
@@ -38,10 +42,6 @@ class ClaimExtractionConfig(BaseModel):
         default=graphrag_config_defaults.extract_claims.encoding_model,
         description="The encoding model to use.",
     )
-    model_id: str = Field(
-        description="The model ID to use for claim extraction.",
-        default=graphrag_config_defaults.extract_claims.model_id,
-    )
 
     def resolved_strategy(
         self, root_dir: str, model_config: LanguageModelConfig

graphrag/config/models/extract_claims_config.py

@@ -14,6 +14,10 @@
 class ExtractGraphConfig(BaseModel):
     """Configuration section for entity extraction."""
 
+    model_id: str = Field(
+        description="The model ID to use for text embeddings.",
+        default=graphrag_config_defaults.extract_graph.model_id,
+    )
     prompt: str | None = Field(
         description="The entity extraction prompt to use.",
         default=graphrag_config_defaults.extract_graph.prompt,
@@ -34,10 +38,6 @@ class ExtractGraphConfig(BaseModel):
         default=graphrag_config_defaults.extract_graph.encoding_model,
         description="The encoding model to use.",
     )
-    model_id: str = Field(
-        description="The model ID to use for text embeddings.",
-        default=graphrag_config_defaults.extract_graph.model_id,
-    )
 
     def resolved_strategy(
         self, root_dir: str, model_config: LanguageModelConfig

graphrag/config/models/extract_graph_config.py

@@ -89,20 +89,24 @@ def _validate_models(self) -> None:
         if defs.DEFAULT_EMBEDDING_MODEL_ID not in self.models:
             raise LanguageModelConfigMissingError(defs.DEFAULT_EMBEDDING_MODEL_ID)
 
-    reporting: ReportingConfig = Field(
-        description="The reporting configuration.", default=ReportingConfig()
+    input: InputConfig = Field(
+        description="The input configuration.", default=InputConfig()
     )
-    """The reporting configuration."""
+    """The input configuration."""
 
-    def _validate_reporting_base_dir(self) -> None:
-        """Validate the reporting base directory."""
-        if self.reporting.type == defs.ReportingType.file:
-            if self.reporting.base_dir.strip() == "":
-                msg = "Reporting base directory is required for file reporting. Please rerun `graphrag init` and set the reporting configuration."
-                raise ValueError(msg)
-            self.reporting.base_dir = str(
-                (Path(self.root_dir) / self.reporting.base_dir).resolve()
-            )
+    def _validate_input_pattern(self) -> None:
+        """Validate the input file pattern based on the specified type."""
+        if len(self.input.file_pattern) == 0:
+            if self.input.file_type == defs.InputFileType.text:
+                self.input.file_pattern = ".*\\.txt$"
+            else:
+                self.input.file_pattern = f".*\\.{self.input.file_type.value}$"
+
+    chunks: ChunkingConfig = Field(
+        description="The chunking configuration to use.",
+        default=ChunkingConfig(),
+    )
+    """The chunking configuration to use."""
 
     output: OutputConfig = Field(
         description="The output configuration.",
@@ -161,66 +165,71 @@ def _validate_update_index_output_base_dir(self) -> None:
     )
     """The cache configuration."""
 
-    input: InputConfig = Field(
-        description="The input configuration.", default=InputConfig()
+    reporting: ReportingConfig = Field(
+        description="The reporting configuration.", default=ReportingConfig()
     )
-    """The input configuration."""
+    """The reporting configuration."""
 
-    def _validate_input_pattern(self) -> None:
-        """Validate the input file pattern based on the specified type."""
-        if len(self.input.file_pattern) == 0:
-            if self.input.file_type == defs.InputFileType.text:
-                self.input.file_pattern = ".*\\.txt$"
-            else:
-                self.input.file_pattern = f".*\\.{self.input.file_type.value}$"
+    def _validate_reporting_base_dir(self) -> None:
+        """Validate the reporting base directory."""
+        if self.reporting.type == defs.ReportingType.file:
+            if self.reporting.base_dir.strip() == "":
+                msg = "Reporting base directory is required for file reporting. Please rerun `graphrag init` and set the reporting configuration."
+                raise ValueError(msg)
+            self.reporting.base_dir = str(
+                (Path(self.root_dir) / self.reporting.base_dir).resolve()
+            )
 
-    embed_graph: EmbedGraphConfig = Field(
-        description="Graph embedding configuration.",
-        default=EmbedGraphConfig(),
+    vector_store: dict[str, VectorStoreConfig] = Field(
+        description="The vector store configuration.",
+        default_factory=lambda: {
+            k: VectorStoreConfig(**asdict(v))
+            for k, v in graphrag_config_defaults.vector_store.items()
+        },
     )
-    """Graph Embedding configuration."""
+    """The vector store configuration."""
+
+    workflows: list[str] | None = Field(
+        description="List of workflows to run, in execution order. This always overrides any built-in workflow methods.",
+        default=graphrag_config_defaults.workflows,
+    )
+    """List of workflows to run, in execution order."""
 
     embed_text: TextEmbeddingConfig = Field(
         description="Text embedding configuration.",
         default=TextEmbeddingConfig(),
     )
     """Text embedding configuration."""
 
-    chunks: ChunkingConfig = Field(
-        description="The chunking configuration to use.",
-        default=ChunkingConfig(),
-    )
-    """The chunking configuration to use."""
-
-    snapshots: SnapshotsConfig = Field(
-        description="The snapshots configuration to use.",
-        default=SnapshotsConfig(),
-    )
-    """The snapshots configuration to use."""
-
     extract_graph: ExtractGraphConfig = Field(
         description="The entity extraction configuration to use.",
         default=ExtractGraphConfig(),
     )
     """The entity extraction configuration to use."""
 
+    summarize_descriptions: SummarizeDescriptionsConfig = Field(
+        description="The description summarization configuration to use.",
+        default=SummarizeDescriptionsConfig(),
+    )
+    """The description summarization configuration to use."""
+
     extract_graph_nlp: ExtractGraphNLPConfig = Field(
         description="The NLP-based graph extraction configuration to use.",
         default=ExtractGraphNLPConfig(),
     )
     """The NLP-based graph extraction configuration to use."""
 
-    summarize_descriptions: SummarizeDescriptionsConfig = Field(
-        description="The description summarization configuration to use.",
-        default=SummarizeDescriptionsConfig(),
+    prune_graph: PruneGraphConfig = Field(
+        description="The graph pruning configuration to use.",
+        default=PruneGraphConfig(),
     )
-    """The description summarization configuration to use."""
+    """The graph pruning configuration to use."""
 
-    community_reports: CommunityReportsConfig = Field(
-        description="The community reports configuration to use.",
-        default=CommunityReportsConfig(),
+    cluster_graph: ClusterGraphConfig = Field(
+        description="The cluster graph configuration to use.",
+        default=ClusterGraphConfig(),
     )
-    """The community reports configuration to use."""
+    """The cluster graph configuration to use."""
 
     extract_claims: ClaimExtractionConfig = Field(
         description="The claim extraction configuration to use.",
@@ -230,23 +239,29 @@ def _validate_input_pattern(self) -> None:
     )
     """The claim extraction configuration to use."""
 
-    prune_graph: PruneGraphConfig = Field(
-        description="The graph pruning configuration to use.",
-        default=PruneGraphConfig(),
+    community_reports: CommunityReportsConfig = Field(
+        description="The community reports configuration to use.",
+        default=CommunityReportsConfig(),
     )
-    """The graph pruning configuration to use."""
+    """The community reports configuration to use."""
 
-    cluster_graph: ClusterGraphConfig = Field(
-        description="The cluster graph configuration to use.",
-        default=ClusterGraphConfig(),
+    embed_graph: EmbedGraphConfig = Field(
+        description="Graph embedding configuration.",
+        default=EmbedGraphConfig(),
     )
-    """The cluster graph configuration to use."""
+    """Graph Embedding configuration."""
 
     umap: UmapConfig = Field(
         description="The UMAP configuration to use.", default=UmapConfig()
     )
     """The UMAP configuration to use."""
 
+    snapshots: SnapshotsConfig = Field(
+        description="The snapshots configuration to use.",
+        default=SnapshotsConfig(),
+    )
+    """The snapshots configuration to use."""
+
     local_search: LocalSearchConfig = Field(
         description="The local search configuration.", default=LocalSearchConfig()
     )
@@ -267,21 +282,6 @@ def _validate_input_pattern(self) -> None:
     )
     """The basic search configuration."""
 
-    vector_store: dict[str, VectorStoreConfig] = Field(
-        description="The vector store configuration.",
-        default_factory=lambda: {
-            k: VectorStoreConfig(**asdict(v))
-            for k, v in graphrag_config_defaults.vector_store.items()
-        },
-    )
-    """The vector store configuration."""
-
-    workflows: list[str] | None = Field(
-        description="List of workflows to run, in execution order. This always overrides any built-in workflow methods.",
-        default=graphrag_config_defaults.workflows,
-    )
-    """List of workflows to run, in execution order."""
-
     def _validate_vector_store_db_uri(self) -> None:
         """Validate the vector store configuration."""
         for store in self.vector_store.values():