Api Contract Test + Fixes (#32)

dupontcyborg · github-advanced-security[bot] · web-flow · commit 3354dc6c7422 · 2025-09-22T11:45:37.000-04:00
* Implemented API Contract test

* Enhanced contract test with content checking

* Fixed API-level bugs:

- Using default index config (None) would fail
- `contents` was not supported in upsert
- `include` was ignored in query when limiting fields to return

* Implemented API contract testing workflows

* Added query_contents to API contract test

* Potential fix for code scanning alert no. 5: Workflow does not contain permissions

Co-authored-by: Copilot Autofix powered by AI &lt;62310815+github-advanced-security[bot]@users.noreply.github.com&gt;

* Linting &amp; formatting

* Updated API Contract check workflow

---------

Co-authored-by: Copilot Autofix powered by AI &lt;62310815+github-advanced-security[bot]@users.noreply.github.com&gt;
diff --git a/.github/workflows/check_api_changes.yml b/.github/workflows/check_api_changes.yml
@@ -0,0 +1,75 @@
+name: API Contract Test
+
+permissions:
+  contents: read
+  pull-requests: write
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+
+jobs:
+  check-contract:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for git diff
+
+      - name: Check for Contract Changes
+        if: github.event_name == 'pull_request'
+        id: check_changes
+        run: |
+          # Check if the API contract test file was modified
+          git diff --name-only ${{ github.event.pull_request.base.sha }}..HEAD | grep -q "tests/test_api_contract.py"
+
+          if [ $? -eq 0 ]; then
+            echo "contract_changed=true" >> $GITHUB_OUTPUT
+            echo "API contract test file was modified in this PR"
+          else
+            echo "contract_changed=false" >> $GITHUB_OUTPUT
+            echo "API contract test file was not modified"
+          fi
+
+      - name: Request Changes if Contract Changed
+        if: github.event_name == 'pull_request' && steps.check_changes.outputs.contract_changed == 'true'
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const body = `## ⚠️ API Contract Change Detected
+
+            This PR modifies the public API contract of the CyborgDB Python SDK.
+
+            **Please provide an explanation for this change:**
+            - Why is this change necessary?
+            - Is this a breaking change or backward compatible?
+            - Have you updated the documentation?
+
+            **This review must be dismissed or addressed before the PR can be merged.**`;
+
+            // Check if we already have a review requesting changes
+            const { data: reviews } = await github.rest.pulls.listReviews({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number,
+            });
+
+            const existingReview = reviews.find(review =>
+              review.user.type === 'Bot' &&
+              review.body.includes('API Contract Change Detected')
+            );
+
+            if (!existingReview) {
+              // Create a review requesting changes
+              await github.rest.pulls.createReview({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.issue.number,
+                body: body,
+                event: 'REQUEST_CHANGES'
+              });
+            }
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -152,10 +152,25 @@ jobs:
           fi
           
           # Run all tests (full version tests will run, lite tests will also work)
-          pytest tests/ -v --cov=cyborgdb --cov-report=term-missing --cov-append
+            pytest tests/ -v --cov=cyborgdb --cov-report=term-missing --cov-append --ignore=tests/test_api_contract.py
           
-          # Stop standard server
-          kill $(cat server-standard.pid) || true
+          # Store the server pid for later cleanup
+          echo "Standard server PID: $(cat server-standard.pid)"
+
+      - name: Check API Contract
+        run: |
+          echo "=== Checking API Contract ==="
+          # Run the API contract test separately to avoid affecting coverage of other tests
+          pytest tests/test_api_contract.py -v
+
+      - name: Kill Server
+        run: |
+          if [ -f server-lite.pid ]; then
+            kill $(cat server-lite.pid) || true
+          fi
+          if [ -f server-standard.pid ]; then
+            kill $(cat server-standard.pid) || true
+          fi
           
       - name: Upload coverage reports
         uses: codecov/codecov-action@v3
diff --git a/cyborgdb/client/client.py b/cyborgdb/client/client.py
@@ -162,6 +162,9 @@ def create_index(
             # Convert binary key to hex string
             key_hex = binascii.hexlify(index_key).decode("ascii")
 
+            if index_config is None:
+                index_config = IndexIVFFlatModel()  # Default config
+
             # Create an IndexConfig instance with the appropriate model
             index_config_obj = IndexConfig(index_config)
 
diff --git a/cyborgdb/client/encrypted_index.py b/cyborgdb/client/encrypted_index.py
@@ -4,11 +4,12 @@
 This module provides the EncryptedIndex class for interacting with encrypted vector indexes in CyborgDB.
 """
 
+import base64
+import binascii
+import logging
 from typing import Dict, List, Optional, Union, Any
 import json
 import numpy as np
-import logging
-import binascii
 
 # Import the OpenAPI generated client
 try:
@@ -24,6 +25,7 @@
     from cyborgdb.openapi_client.models.query_request import QueryRequest
     from cyborgdb.openapi_client.models.list_ids_request import ListIDsRequest
     from cyborgdb.openapi_client.models.request import Request
+    from cyborgdb.openapi_client.models import Contents
 except ImportError:
     raise ImportError(
         "Failed to import openapi_client. Make sure the OpenAPI client library is properly installed."
@@ -312,7 +314,23 @@ def upsert(
                         item["vector"] = item_dict["vector"]
 
                     if "contents" in item_dict:
-                        item["contents"] = item_dict["contents"]
+                        contents_value = item_dict["contents"]
+
+                        # Convert bytes to base64 string for JSON serialization
+                        if isinstance(contents_value, bytes):
+                            # Convert bytes to base64 string
+                            contents_value = base64.b64encode(contents_value).decode(
+                                "utf-8"
+                            )
+                        elif isinstance(contents_value, bytearray):
+                            # Convert bytearray to base64 string
+                            contents_value = base64.b64encode(
+                                bytes(contents_value)
+                            ).decode("utf-8")
+                        # If it's already a string, use as-is
+
+                        # Contents model accepts string or bytearray
+                        item["contents"] = Contents(contents_value)
 
                     if "metadata" in item_dict:
                         # Convert dict metadata to JSON string if needed
@@ -494,6 +512,12 @@ def query(
                 response_text = raw_response.data.decode("utf-8")
                 response_json = json.loads(response_text)
 
+                # Determine include filtering strategy
+                include_all = (
+                    include is None
+                )  # None means include everything server returns
+                include_set = set(include) if include else set()
+
                 # Process the results as plain dictionaries
                 results = []
                 if "results" in response_json:
@@ -506,23 +530,37 @@ def query(
                             query_items = []
                             for item in query_result:
                                 result_item = {"id": item["id"]}
+
+                                # Always include distance if present (core part of query results)
                                 if "distance" in item:
                                     result_item["distance"] = item["distance"]
-                                if "metadata" in item:
+
+                                # Check metadata against include list
+                                if "metadata" in item and (
+                                    include_all or "metadata" in include_set
+                                ):
                                     result_item["metadata"] = item["metadata"]
+
                                 query_items.append(result_item)
                             results.append(query_items)
                     else:
                         # It's a flat list (single query results)
                         query_items = []
                         for item in response_json["results"]:
                             result_item = {"id": item["id"]}
+
+                            # Always include distance if present (core part of query results)
                             if "distance" in item:
                                 result_item["distance"] = item["distance"]
-                            if "metadata" in item:
+
+                            # Check metadata against include list
+                            if "metadata" in item and (
+                                include_all or "metadata" in include_set
+                            ):
                                 result_item["metadata"] = item["metadata"]
+
                             query_items.append(result_item)
-                        results.append(query_items)
+                        results = query_items
 
                 return results
             except Exception as e:
diff --git a/tests/test_api_contract.py b/tests/test_api_contract.py
