fix: update GitHub Actions artifact actions from v3 to v4

- Update all workflow files to use actions/upload-artifact@v4
- Update all workflow files to use actions/download-artifact@v4
- Fixes CI pipeline failures due to deprecated v3 artifact actions
- Affects: v2-api-tests.yml, v2-api-pr-validation.yml, v2-api-nightly.yml, v2-api-release.yml

Author: tazarov

.DS_Store

@@ -97,7 +97,7 @@ jobs:
 
       - name: Upload test artifacts
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: nightly-v2-chroma-${{ matrix.chroma-version }}-java-${{ matrix.java-version }}
           path: |
@@ -287,7 +287,7 @@ jobs:
 
       - name: Upload stress test results
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: stress-test-results-v2
           path: |
@@ -302,7 +302,7 @@ jobs:
 
     steps:
       - name: Download all artifacts
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           path: test-artifacts
 

.github/workflows/v2-api-nightly.yml

@@ -258,7 +258,7 @@ jobs:
 
       - name: Upload quality reports
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: quality-reports-v2
           path: |

.github/workflows/v2-api-pr-validation.yml

@@ -139,7 +139,7 @@ jobs:
           cat release-notes.md >> $GITHUB_STEP_SUMMARY
 
       - name: Upload release artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: release-artifacts-v2
           path: |
@@ -197,7 +197,7 @@ jobs:
 
       - name: Upload compatibility results
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: compatibility-chroma-${{ matrix.chroma-version }}-java-${{ matrix.java-version }}
           path: compatibility-results.txt
@@ -224,7 +224,7 @@ jobs:
           gpg-passphrase: MAVEN_GPG_PASSPHRASE
 
       - name: Download release artifacts
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: release-artifacts-v2
           path: ./release

.github/workflows/v2-api-release.yml

@@ -159,7 +159,7 @@ jobs:
 
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: test-results-v2-chroma-${{ matrix.chroma-version }}-java-${{ matrix.java-version }}
           path: |
@@ -168,7 +168,7 @@ jobs:
 
       - name: Upload coverage reports
         if: success()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: coverage-v2-chroma-${{ matrix.chroma-version }}-java-${{ matrix.java-version }}
           path: target/site/jacoco/
@@ -197,7 +197,7 @@ jobs:
 
     steps:
       - name: Download all test results
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           path: test-artifacts
 
@@ -292,7 +292,7 @@ jobs:
           CHROMA_URL: http://localhost:8000
 
       - name: Upload performance results
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: performance-results-v2
           path: target/performance-reports/

.github/workflows/v2-api-tests.yml

@@ -28,10 +28,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `HF_API_KEY` - Required for HuggingFace embedding tests
 - `CHROMA_VERSION` - Specifies ChromaDB version for integration tests
 
-## Architecture Overview
+## API Design Principles (V2)
 
-### Core Client Structure
-The client follows a standard Swagger/OpenAPI generated client pattern with custom enhancements:
+### Radical Simplicity
+The V2 API follows principles of radical simplicity based on successful Java libraries like OkHttp, Retrofit, and Jedis:
+
+1. **Single Configuration Pattern**: Use ONLY fluent builders, NEVER Consumer<Builder> patterns
+2. **Flat Package Structure**: All public API classes in `tech.amikos.chromadb.v2` package (no sub-packages)
+3. **One Way to Do Things**: Each task has exactly one idiomatic approach
+4. **Minimal Public API Surface**: ~20-25 classes total (following OkHttp's model)
+5. **Concrete Over Abstract**: Prefer concrete classes over interfaces where possible
+
+### Architecture Overview
+
+#### V1 Client (Legacy - Maintained for Compatibility)
+The V1 client (`tech.amikos.chromadb`) follows a standard Swagger/OpenAPI generated client pattern:
 
 1. **Generated API Layer** (`target/generated-sources/swagger/`)
    - Auto-generated from OpenAPI specifications
@@ -48,6 +59,31 @@ The client follows a standard Swagger/OpenAPI generated client pattern with cust
    - Each implements `EmbeddingFunction` interface
    - Default embedding uses ONNX Runtime for local inference
 
+#### V2 Client (Recommended - Radical Simplicity)
+The V2 client (`tech.amikos.chromadb.v2`) implements radical simplicity:
+
+1. **Single Flat Package** - All classes in `tech.amikos.chromadb.v2`
+   - No sub-packages for auth, model, client, etc.
+   - Everything discoverable in one location
+
+2. **Core Classes** (~20 total)
+   - `ChromaClient` - Single client class with builder
+   - `Collection` - Concrete collection class (not interface)
+   - `Metadata` - Strongly-typed metadata with builder
+   - Query builders: `QueryBuilder`, `AddBuilder`, etc.
+   - Model classes: `Where`, `WhereDocument`, `Include`
+   - Auth: `AuthProvider` interface with implementations
+   - Exceptions: Strongly-typed exception hierarchy
+
+3. **Builder-Only Pattern**
+   ```java
+   // Only way to query - no Consumer<Builder> alternative
+   collection.query()
+       .where(Where.eq("type", "article"))
+       .nResults(10)
+       .execute();
+   ```
+
 ### Key Design Patterns
 
 1. **Authentication Handling**