feat: refine node merge (#1092)

* feat: update readme kg

* feat: refine node merge

* feat: refine node merge

* feat: refine node merge

Author: earayu

aperag/api/components/schemas/graph.yaml

@@ -195,32 +195,22 @@ targetEntityDataResponse:
 nodeMergeRequest:
   type: object
   description: |
-    Request to merge multiple graph nodes.
-    
-    You can provide either:
-    - entity_ids: List of entity IDs to merge directly
-    - suggestion_id: ID of a suggestion to merge
-    
-    If both are provided, suggestion_id takes precedence and entity_ids will be ignored.
+    Request to merge multiple graph nodes directly using entity IDs.
   properties:
     entity_ids:
       type: array
       items:
         type: string
-      description: List of entity IDs to merge (supports 1 or more entities). Ignored if suggestion_id is also provided.
+      description: List of entity IDs to merge directly
       example: ["墨香居", "书店", "旧书店"]
       minItems: 1
-      nullable: true
-    suggestion_id:
-      type: string
-      description: Single suggestion ID to merge. If provided, takes precedence over entity_ids.
-      example: "msug123"
-      nullable: true
     target_entity_data:
       $ref: '#/targetEntityDataRequest'
+  required:
+    - entity_ids
   additionalProperties: false
   example:
-    suggestion_id: "msug123"
+    entity_ids: ["墨香居", "书店", "旧书店"]
 
 nodeMergeResponse:
   type: object
@@ -506,4 +496,54 @@ mergeSuggestionsResponse:
     - pending_count
     - accepted_count
     - rejected_count
-    - expired_count
+    - expired_count
+
+suggestionActionRequest:
+  type: object
+  description: Request to take action on a merge suggestion
+  properties:
+    action:
+      type: string
+      enum: ["accept", "reject"]
+      description: Action to take on the suggestion (case-insensitive, e.g., 'Accept', 'REJECT', 'accept')
+      example: "accept"
+    target_entity_data:
+      $ref: '#/targetEntityDataRequest'
+      description: Optional override for target entity data (only used when action is 'accept')
+  required:
+    - action
+  additionalProperties: false
+  example:
+    action: "accept"
+
+suggestionActionResponse:
+  type: object
+  description: Response containing suggestion action results
+  properties:
+    status:
+      type: string
+      description: Status of the action operation
+      example: "success"
+      enum: ["success", "error"]
+    message:
+      type: string
+      description: Detailed message about the action operation
+      example: "Suggestion msug123 has been accepted and merge completed"
+    suggestion_id:
+      type: string
+      description: The suggestion ID that was processed
+      example: "msug123"
+    action:
+      type: string
+      enum: ["accept", "reject"]
+      description: The action that was performed (normalized to lowercase)
+      example: "accept"
+    merge_result:
+      $ref: '#/nodeMergeResponse'
+      description: Merge operation result (only present when action is 'accept')
+      nullable: true
+  required:
+    - status
+    - message
+    - suggestion_id
+    - action

aperag/api/openapi.yaml

@@ -67,6 +67,8 @@ paths:
     $ref: './paths/collections.yaml#/graph_nodes_merge'
   /collections/{collection_id}/graphs/merge-suggestions:
     $ref: './paths/collections.yaml#/graph_merge_suggestions'
+  /collections/{collection_id}/graphs/merge-suggestions/{suggestion_id}/action:
+    $ref: './paths/collections.yaml#/graph_suggestion_action'
 
   # apikeys
   /apikeys:

aperag/api/paths/collections.yaml

@@ -753,6 +753,129 @@ graph_merge_suggestions:
             schema:
               $ref: '../components/schemas/common.yaml#/failResponse'
 
+graph_suggestion_action:
+  post:
+    summary: Accept or reject a merge suggestion
+    description: |
+      Take action on a specific merge suggestion.
+      
+      Actions:
+      - accept: Accept the suggestion and perform the merge operation
+      - reject: Reject the suggestion and mark it as rejected
+      
+      When accepting, the system will:
+      1. Update suggestion status to ACCEPTED
+      2. Perform the actual node merge using suggested entity IDs
+      3. Mark related suggestions involving the same entities as EXPIRED
+      
+      When rejecting, the system will:
+      1. Update suggestion status to REJECTED
+      2. No merge operation is performed
+      
+      The target entity data can be optionally overridden when accepting a suggestion.
+    tags:
+      - graph
+    security:
+      - BearerAuth: []
+    parameters:
+      - name: collection_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: Collection ID
+      - name: suggestion_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: Suggestion ID
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: '../components/schemas/graph.yaml#/suggestionActionRequest'
+          examples:
+            accept:
+              summary: Accept suggestion
+              description: Accept the suggestion and perform merge
+              value:
+                action: "accept"
+            reject:
+              summary: Reject suggestion
+              description: Reject the suggestion without merging
+              value:
+                action: "reject"
+            accept_with_override:
+              summary: Accept with custom target data
+              description: Accept suggestion but override target entity data
+              value:
+                action: "accept"
+                target_entity_data:
+                  entity_name: "Custom Name"
+                  description: "Custom description for merged entity"
+    responses:
+      '200':
+        description: Action completed successfully
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/graph.yaml#/suggestionActionResponse'
+            examples:
+              accept_success:
+                summary: Accept action successful
+                description: Suggestion accepted and merge completed
+                value:
+                  status: "success"
+                  message: "Suggestion msug123 has been accepted and merge completed"
+                  suggestion_id: "msug123"
+                  action: "accept"
+                  merge_result:
+                    status: "success"
+                    message: "Successfully merged 2 entities into 墨香居"
+                    entity_ids: ["墨香居", "书店"]
+                    target_entity_data:
+                      entity_name: "墨香居"
+                      entity_type: "ORGANIZATION"
+                      description: "墨香居是这条老巷子里唯一的旧书店，经营着各种书籍"
+                    source_entities: ["书店"]
+                    redirected_edges: 5
+                    merged_description_length: 45
+              reject_success:
+                summary: Reject action successful
+                description: Suggestion rejected successfully
+                value:
+                  status: "success"
+                  message: "Suggestion msug123 has been rejected"
+                  suggestion_id: "msug123"
+                  action: "reject"
+                  merge_result: null
+      '400':
+        description: Bad request - invalid action or suggestion already processed
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/common.yaml#/failResponse'
+      '401':
+        description: Unauthorized
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/common.yaml#/failResponse'
+      '404':
+        description: Collection or suggestion not found
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/common.yaml#/failResponse'
+      '500':
+        description: Internal server error
+        content:
+          application/json:
+            schema:
+              $ref: '../components/schemas/common.yaml#/failResponse'
+
 test_mineru_token:
   post:
     summary: Test MinerU API Token

aperag/db/repositories/merge_suggestion.py

@@ -15,7 +15,7 @@
 from datetime import datetime, timedelta
 from typing import List, Optional
 
-from sqlalchemy import and_, select, update
+from sqlalchemy import and_, select, text, update
 
 from aperag.db.models import MergeSuggestion, MergeSuggestionStatus
 from aperag.db.repositories.base import AsyncRepositoryProtocol
@@ -77,11 +77,11 @@ async def _query(session):
                 and_(
                     MergeSuggestion.collection_id == collection_id,
                     MergeSuggestion.gmt_deleted.is_(None),
-                    MergeSuggestion.entity_ids.overlap(entity_ids),  # PostgreSQL array overlap
+                    text("entity_ids && :entity_ids"),  # PostgreSQL array overlap operator
                 )
             )
 
-            result = await session.execute(stmt)
+            result = await session.execute(stmt, {"entity_ids": entity_ids})
             return result.scalars().all()
 
         return await self._execute_query(_query)

aperag/graph/lightrag/lightrag.py

@@ -1356,11 +1356,14 @@ async def amerge_nodes(
 
         # Apply target entity data overrides (from target_entity_data parameter)
         user_provided_description = None
-        for key, value in target_entity_data.items():
-            if key != "entity_name":  # Don't override entity_name in the data
-                merged_entity_data[key] = value
-                if key == "description" and value:  # Track if user provided description
-                    user_provided_description = value
+        if target_entity_data:  # Only iterate if target_entity_data is not None
+            for key, value in target_entity_data.items():
+                if key != "entity_name":  # Don't override entity_name in the data
+                    merged_entity_data[key] = value
+                    if (
+                        key == "description" and value is not None
+                    ):  # Track if user provided description (including empty strings)
+                        user_provided_description = value
 
         merged_entity_data["entity_id"] = target_entity_name
 

aperag/migration/versions/20250711123338-694591d5df94.py

@@ -1,7 +1,7 @@
 """empty message
 
 Revision ID: 694591d5df94
-Revises: c09204152091
+Revises: add_index_audit_resource
 Create Date: 2025-07-11 12:33:38.799759
 
 """

aperag/schema/view_models.py

@@ -14,7 +14,7 @@
 
 # generated by datamodel-codegen:
 #   filename:  openapi.merged.yaml
-#   timestamp: 2025-07-11T05:56:53+00:00
+#   timestamp: 2025-07-11T06:38:38+00:00
 
 from __future__ import annotations
 
@@ -859,30 +859,19 @@ class TargetEntityDataRequest(BaseModel):
 
 class NodeMergeRequest(BaseModel):
     """
-    Request to merge multiple graph nodes.
-
-    You can provide either:
-    - entity_ids: List of entity IDs to merge directly
-    - suggestion_id: ID of a suggestion to merge
-
-    If both are provided, suggestion_id takes precedence and entity_ids will be ignored.
+    Request to merge multiple graph nodes directly using entity IDs.
 
     """
 
     class Config:
         extra = Extra.forbid
 
-    entity_ids: Optional[list[str]] = Field(
-        None,
-        description='List of entity IDs to merge (supports 1 or more entities). Ignored if suggestion_id is also provided.',
+    entity_ids: list[str] = Field(
+        ...,
+        description='List of entity IDs to merge directly',
         example=['墨香居', '书店', '旧书店'],
         min_items=1,
     )
-    suggestion_id: Optional[str] = Field(
-        None,
-        description='Single suggestion ID to merge. If provided, takes precedence over entity_ids.',
-        example='msug123',
-    )
     target_entity_data: Optional[TargetEntityDataRequest] = None
 
 
@@ -1058,6 +1047,52 @@ class MergeSuggestionsResponse(BaseModel):
     )
 
 
+class SuggestionActionRequest(BaseModel):
+    """
+    Request to take action on a merge suggestion
+    """
+
+    class Config:
+        extra = Extra.forbid
+
+    action: Literal['accept', 'reject'] = Field(
+        ...,
+        description="Action to take on the suggestion (case-insensitive, e.g., 'Accept', 'REJECT', 'accept')",
+        example='accept',
+    )
+    target_entity_data: Optional[TargetEntityDataRequest] = Field(
+        None,
+        description="Optional override for target entity data (only used when action is 'accept')",
+    )
+
+
+class SuggestionActionResponse(BaseModel):
+    """
+    Response containing suggestion action results
+    """
+
+    status: Literal['success', 'error'] = Field(
+        ..., description='Status of the action operation', example='success'
+    )
+    message: str = Field(
+        ...,
+        description='Detailed message about the action operation',
+        example='Suggestion msug123 has been accepted and merge completed',
+    )
+    suggestion_id: str = Field(
+        ..., description='The suggestion ID that was processed', example='msug123'
+    )
+    action: Literal['accept', 'reject'] = Field(
+        ...,
+        description='The action that was performed (normalized to lowercase)',
+        example='accept',
+    )
+    merge_result: Optional[NodeMergeResponse] = Field(
+        None,
+        description="Merge operation result (only present when action is 'accept')",
+    )
+
+
 class ApiKey(BaseModel):
     id: Optional[str] = None
     key: Optional[str] = None