ci: ensure backwards/forward compatibility of the API (#306)

Author: nicoloboschi

.github/workflows/test.yml

@@ -1084,4 +1084,52 @@ jobs:
           git diff --stat
           exit 1
         fi
-        echo "✓ All generated files are up to date"
+        echo "✓ All generated files are up to date"
+
+  check-openapi-compatibility:
+    runs-on: ubuntu-latest
+    env:
+      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Fetch full git history to access base branch
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: ".python-version"
+
+    - name: Install hindsight-dev dependencies
+      run: |
+        cd hindsight-dev && uv sync --frozen --index-strategy unsafe-best-match
+
+    - name: Check OpenAPI compatibility with base branch
+      run: |
+        # Get the base branch (usually main)
+        BASE_BRANCH="${{ github.base_ref }}"
+
+        if [ -z "$BASE_BRANCH" ]; then
+          echo "⚠️  Warning: No base branch found (not a PR?). Skipping compatibility check."
+          exit 0
+        fi
+
+        echo "Checking OpenAPI compatibility against base branch: $BASE_BRANCH"
+
+        # Extract the old OpenAPI spec from base branch
+        git show "origin/$BASE_BRANCH:hindsight-docs/static/openapi.json" > /tmp/old-openapi.json
+
+        if [ ! -s /tmp/old-openapi.json ]; then
+          echo "⚠️  Warning: Could not find OpenAPI spec in base branch. Skipping compatibility check."
+          exit 0
+        fi
+
+        # Check compatibility using our tool
+        cd hindsight-dev
+        uv run check-openapi-compatibility /tmp/old-openapi.json ../hindsight-docs/static/openapi.json

hindsight-api/hindsight_api/api/http.py

@@ -1161,7 +1161,7 @@ class CreateMentalModelRequest(BaseModel):
 class CreateMentalModelResponse(BaseModel):
     """Response model for mental model creation."""
 
-    mental_model_id: str = Field(description="ID of the created mental model")
+    mental_model_id: str | None = Field(None, description="ID of the created mental model")
     operation_id: str = Field(description="Operation ID to track refresh progress")
 
 

hindsight-clients/python/hindsight_client_api/models/create_mental_model_response.py

@@ -18,15 +18,15 @@
 import json
 
 from pydantic import BaseModel, ConfigDict, Field, StrictStr
-from typing import Any, ClassVar, Dict, List
+from typing import Any, ClassVar, Dict, List, Optional
 from typing import Optional, Set
 from typing_extensions import Self
 
 class CreateMentalModelResponse(BaseModel):
     """
     Response model for mental model creation.
     """ # noqa: E501
-    mental_model_id: StrictStr = Field(description="ID of the created mental model")
+    mental_model_id: Optional[StrictStr] = None
     operation_id: StrictStr = Field(description="Operation ID to track refresh progress")
     __properties: ClassVar[List[str]] = ["mental_model_id", "operation_id"]
 
@@ -69,6 +69,11 @@ def to_dict(self) -> Dict[str, Any]:
             exclude=excluded_fields,
             exclude_none=True,
         )
+        # set to None if mental_model_id (nullable) is None
+        # and model_fields_set contains the field
+        if self.mental_model_id is None and "mental_model_id" in self.model_fields_set:
+            _dict['mental_model_id'] = None
+
         return _dict
 
     @classmethod

hindsight-clients/typescript/generated/types.gen.ts

@@ -440,7 +440,7 @@ export type CreateMentalModelResponse = {
    *
    * ID of the created mental model
    */
-  mental_model_id: string;
+  mental_model_id?: string | null;
   /**
    * Operation Id
    *