Skip to content

ascota_classification.decoration

The classification type is a multi-stage classification pipeline for classifying pottery types. It uses a pre-trained DINOv2 ViT-L/14 model for feature extraction combined with optimized SVM classifiers for each stage. The pipeline is as follows: 1. Stage 1: body vs everything else 2. Stage 2: base vs rim vs appendage 3. Stage 3: appendage subtypes using Azure OpenAI GPT-4o


Pottery type classification module for pottery images with transparent backgrounds.

This module classifies pottery types using a multi-stage pipeline: - Stage 1: body vs everything else (base+rim+appendages) - Stage 2: base vs rim vs appendage (if not body) - Stage 3: appendage subtypes using Azure OpenAI GPT-4o (optional, if appendage)

The classification uses pre-trained DINOv2 ViT-L/14 model for feature extraction with optimized classifiers for each stage.

_load_dino_model

_load_dino_model(device)

Load the DINOv2 ViT-L/14 model for feature extraction.

Parameters:

Name Type Description Default
device device

PyTorch device (cpu or cuda)

required

Returns:

Type Description
AutoModel

Loaded DINOv2 model in eval mode

Source code in src/ascota_classification/type.py
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
def _load_dino_model(device: torch.device) -> AutoModel:
    """
    Load the DINOv2 ViT-L/14 model for feature extraction.

    Args:
        device: PyTorch device (cpu or cuda)

    Returns:
        Loaded DINOv2 model in eval mode
    """
    try:
        model = AutoModel.from_pretrained('facebook/dinov2-large')
        model.eval()
        model.to(device)
        return model
    except Exception as e:
        raise RuntimeError(f"Failed to load DINOv2 model: {e}")

_extract_features

_extract_features(image, model, device)

Extract DINO features from pottery image.

Parameters:

Name Type Description Default
image Image

PIL Image with transparent background (RGBA)

required
model AutoModel

Pre-loaded DINOv2 model

required
device device

PyTorch device

required

Returns:

Type Description
ndarray

Feature vector as numpy array

Source code in src/ascota_classification/type.py
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def _extract_features(
    image: Image.Image,
    model: AutoModel,
    device: torch.device
) -> np.ndarray:
    """
    Extract DINO features from pottery image.

    Args:
        image: PIL Image with transparent background (RGBA)
        model: Pre-loaded DINOv2 model
        device: PyTorch device

    Returns:
        Feature vector as numpy array
    """
    # Convert RGBA to RGB with white background
    if image.mode == 'RGBA':
        # Create white background
        background = Image.new('RGB', image.size, (255, 255, 255))
        background.paste(image, mask=image.split()[-1])  # Use alpha channel as mask
        image = background
    elif image.mode != 'RGB':
        image = image.convert('RGB')

    # Standard DINO preprocessing
    transform = transforms.Compose([
        transforms.Resize(224),
        transforms.CenterCrop(224),
        transforms.ToTensor(),
        transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
    ])

    # Preprocess image
    image_tensor = transform(image).unsqueeze(0).to(device)

    # Extract features
    with torch.no_grad():
        outputs = model(image_tensor)
        # Use pooler output if available, otherwise mean of last hidden state
        if hasattr(outputs, 'pooler_output') and outputs.pooler_output is not None:
            features = outputs.pooler_output
        else:
            features = outputs.last_hidden_state.mean(dim=1)

    return features.cpu().numpy().flatten()

_load_classifier

_load_classifier(model_path)

Load a trained classifier and its parameters.

Parameters:

Name Type Description Default
model_path Path

Path to the saved model file

required

Returns:

Type Description
Tuple[any, Optional[Dict]]

Tuple of (classifier, parameters dict or None)

Source code in src/ascota_classification/type.py
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def _load_classifier(model_path: Path) -> Tuple[any, Optional[Dict]]:
    """
    Load a trained classifier and its parameters.

    Args:
        model_path: Path to the saved model file

    Returns:
        Tuple of (classifier, parameters dict or None)
    """
    if not model_path.exists():
        raise FileNotFoundError(
            f"Model file not found: {model_path}\n"
            f"Please ensure the trained model is available at this location."
        )

    try:
        classifier = joblib.load(model_path)

        # Try to load parameters file if it exists
        params_path = model_path.parent / model_path.name.replace('.pkl', '_params.pkl')
        params = None
        if params_path.exists():
            params = joblib.load(params_path)

        return classifier, params
    except Exception as e:
        raise RuntimeError(f"Failed to load classifier: {e}")

_classify_stage1

_classify_stage1(features, classifier, debug=False)

Stage 1: Classify body vs everything else.

Parameters:

Name Type Description Default
features ndarray

Feature vector from DINOv2

required
classifier any

Trained Stage 1 classifier

required
debug bool

If True, print debug information

False

Returns:

Type Description
Tuple[str, float]

Tuple of (label, confidence)

Source code in src/ascota_classification/type.py
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
def _classify_stage1(
    features: np.ndarray,
    classifier: any,
    debug: bool = False
) -> Tuple[str, float]:
    """
    Stage 1: Classify body vs everything else.

    Args:
        features: Feature vector from DINOv2
        classifier: Trained Stage 1 classifier
        debug: If True, print debug information

    Returns:
        Tuple of (label, confidence)
    """
    # Reshape features for prediction
    features_2d = features.reshape(1, -1)

    # Get prediction probabilities
    if hasattr(classifier, 'predict_proba'):
        proba = classifier.predict_proba(features_2d)[0]
        prediction = classifier.predict(features_2d)[0]
        confidence = float(np.max(proba))
    else:
        prediction = classifier.predict(features_2d)[0]
        confidence = 1.0  # Default if no probability available

    # Map prediction: 0 = everything_else, 1 = body
    label = "body" if prediction == 1 else "everything_else"

    if debug:
        print(f"_classify_stage1: Stage 1: {label} (confidence: {confidence:.4f})")

    return label, confidence

_classify_stage2

_classify_stage2(features, classifier, debug=False)

Stage 2: Classify base vs rim vs appendage.

Parameters:

Name Type Description Default
features ndarray

Feature vector from DINOv2

required
classifier any

Trained Stage 2 classifier

required
debug bool

If True, print debug information

False

Returns:

Type Description
Tuple[str, float]

Tuple of (label, confidence)

Source code in src/ascota_classification/type.py
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def _classify_stage2(
    features: np.ndarray,
    classifier: any,
    debug: bool = False
) -> Tuple[str, float]:
    """
    Stage 2: Classify base vs rim vs appendage.

    Args:
        features: Feature vector from DINOv2
        classifier: Trained Stage 2 classifier
        debug: If True, print debug information

    Returns:
        Tuple of (label, confidence)
    """
    # Reshape features for prediction
    features_2d = features.reshape(1, -1)

    # Get prediction probabilities
    if hasattr(classifier, 'predict_proba'):
        proba = classifier.predict_proba(features_2d)[0]
        prediction = classifier.predict(features_2d)[0]
        confidence = float(np.max(proba))

        # LabelEncoder classes for Stage 2: ['appendage', 'base', 'rim']
        # So: 0=appendage, 1=base, 2=rim
        class_names = ['appendage', 'base', 'rim']
        if prediction < len(class_names):
            label = class_names[prediction]
        else:
            # Fallback if prediction index is out of range
            label = class_names[np.argmax(proba)]
    else:
        prediction = classifier.predict(features_2d)[0]
        class_names = ['appendage', 'base', 'rim']
        label = class_names[prediction] if prediction < len(class_names) else 'appendage'
        confidence = 1.0

    if debug:
        print(f"_classify_stage2: Stage 2: {label} (confidence: {confidence:.4f})")

    return label, confidence

_prepare_image_for_gpt4o

_prepare_image_for_gpt4o(image, max_size=512)

Resize image and convert to base64 for GPT-4o.

Parameters:

Name Type Description Default
image Image

PIL Image

required
max_size int

Maximum size for thumbnail

512

Returns:

Type Description
str

Base64 encoded image string

Source code in src/ascota_classification/type.py
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
def _prepare_image_for_gpt4o(image: Image.Image, max_size: int = 512) -> str:
    """
    Resize image and convert to base64 for GPT-4o.

    Args:
        image: PIL Image
        max_size: Maximum size for thumbnail

    Returns:
        Base64 encoded image string
    """
    # Resize while maintaining aspect ratio
    image_copy = image.copy()
    image_copy.thumbnail((max_size, max_size), Image.Resampling.LANCZOS)

    # Convert to base64
    buffered = BytesIO()
    image_copy.save(buffered, format="PNG")
    img_base64 = base64.b64encode(buffered.getvalue()).decode('utf-8')

    return img_base64

_classify_appendage_with_gpt4o

_classify_appendage_with_gpt4o(image, debug=False)

Stage 3: Classify appendage subtype using Azure OpenAI GPT-4o.

Parameters:

Name Type Description Default
image Image

PIL Image of appendage

required
debug bool

If True, print debug information

False

Returns:

Type Description
Tuple[Optional[str], Optional[float]]

Tuple of (label, confidence) or (None, None) if failed

Source code in src/ascota_classification/type.py
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
def _classify_appendage_with_gpt4o(
    image: Image.Image,
    debug: bool = False
) -> Tuple[Optional[str], Optional[float]]:
    """
    Stage 3: Classify appendage subtype using Azure OpenAI GPT-4o.

    Args:
        image: PIL Image of appendage
        debug: If True, print debug information

    Returns:
        Tuple of (label, confidence) or (None, None) if failed
    """
    if not AZURE_OPENAI_AVAILABLE:
        if debug:
            print("_classify_appendage_with_gpt4o: Azure OpenAI SDK not available. Skipping GPT-4o classification.")
        return None, None

    # Get credentials from environment variables
    azure_endpoint = os.getenv('AZURE_OPENAI_ENDPOINT')
    azure_api_key = os.getenv('AZURE_OPENAI_API_KEY')

    if azure_endpoint is None or azure_api_key is None:
        if debug:
            print("_classify_appendage_with_gpt4o: Azure OpenAI credentials not found in environment variables.")
            print("_classify_appendage_with_gpt4o: Set AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY")
        return None, None

    try:
        # Prepare image
        img_base64 = _prepare_image_for_gpt4o(image, max_size=512)

        # Initialize Azure OpenAI client
        client = AzureOpenAI(
            azure_endpoint=azure_endpoint,
            api_key=azure_api_key,
            api_version="2024-02-15-preview"
        )

        # Create prompt
        prompt = """Classify this pottery sherd appendage into one of the following categories:
- lid
- rim-handle
- spout
- rounded
- body-decorated
- tile

Please respond with:
1. The classification label (one of the categories above)
2. Your confidence level (0.0 to 1.0)
3. A brief explanation of why you chose this classification

Format your response as:
Label: <category>
Confidence: <number>
Explanation: <brief explanation>"""

        # Call GPT-4o
        response = client.chat.completions.create(
            model="gpt-4o",
            temperature=0.0,
            messages=[
                {
                    "role": "user",
                    "content": [
                        {"type": "text", "text": prompt},
                        {
                            "type": "image_url",
                            "image_url": {
                                "url": f"data:image/png;base64,{img_base64}"
                            }
                        }
                    ]
                }
            ],
            max_tokens=500
        )

        # Parse response
        response_text = response.choices[0].message.content

        # Extract label and confidence
        label = None
        confidence = None

        for line in response_text.split('\n'):
            if line.startswith('Label:'):
                label = line.split('Label:')[1].strip().lower()
            elif line.startswith('Confidence:'):
                try:
                    confidence = float(line.split('Confidence:')[1].strip())
                except:
                    confidence = 0.5  # Default

        # Validate label
        valid_labels = ['lid', 'rim-handle', 'spout', 'rounded', 'body-decorated', 'tile']
        if label not in valid_labels:
            # Try to find label in response
            for valid_label in valid_labels:
                if valid_label in response_text.lower():
                    label = valid_label
                    break

        # If still not found, default to first valid label
        if label not in valid_labels:
            label = valid_labels[0]
            if debug:
                print(f"_classify_appendage_with_gpt4o: Warning: Could not parse label from GPT-4o response, using default: {label}")

        if confidence is None:
            confidence = 0.5  # Default confidence

        if debug:
            print(f"_classify_appendage_with_gpt4o: Stage 3 (GPT-4o): {label} (confidence: {confidence:.4f})")

        return label, confidence

    except Exception as e:
        if debug:
            print(f"_classify_appendage_with_gpt4o: Error calling GPT-4o: {e}")
        return None, None

classify_pottery_type

classify_pottery_type(
    image, model_path_stage1=None, model_path_stage2=None, use_azure_openai=False, debug=False
)

Classify pottery type from an image with transparent background.

Uses a multi-stage pipeline: 1. Stage 1: body vs everything else 2. Stage 2: base vs rim vs appendage (if not body) 3. Stage 3: appendage subtypes using Azure OpenAI (optional, if appendage)

Parameters:

Name Type Description Default
image Image

PIL Image with transparent background (RGBA or RGB format)

required
model_path_stage1 Optional[Path]

Path to Stage 1 model. If None, uses default path.

None
model_path_stage2 Optional[Path]

Path to Stage 2 model. If None, uses default path.

None
use_azure_openai bool

If True, use Azure OpenAI GPT-4o for appendage subtypes

False
debug bool

If True, print debug information

False

Returns:

Type Description
Dict[str, any]

Dictionary with conditional structure:

Dict[str, any]
  • If Stage 1 = "body": {"label": "body", "stage1": {...}}
Dict[str, any]
  • If Stage 2 = "base" or "rim": {"label": "...", "stage1": {...}, "stage2": {...}}
Dict[str, any]
  • If Stage 2 = "appendage": {"label": "...", "stage1": {...}, "stage2": {...}, "stage3": {...}?}
Dict[str, any]
  • If Azure disabled and appendage: no stage3 field

Raises:

Type Description
FileNotFoundError

If model file is not found

RuntimeError

If model loading or inference fails

Examples:

>>> from PIL import Image
>>> img = Image.open("pottery_type.png")
>>> result = classify_pottery_type(img, debug=True)
>>> print(result["label"])
'body'
>>> result = classify_pottery_type(img, use_azure_openai=True)
>>> print(result["label"])  # Could be appendage subtype if appendage
'spout'
Source code in src/ascota_classification/type.py
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
def classify_pottery_type(
    image: Image.Image,
    model_path_stage1: Optional[Path] = None,
    model_path_stage2: Optional[Path] = None,
    use_azure_openai: bool = False,
    debug: bool = False
) -> Dict[str, any]:
    """
    Classify pottery type from an image with transparent background.

    Uses a multi-stage pipeline:
    1. Stage 1: body vs everything else
    2. Stage 2: base vs rim vs appendage (if not body)
    3. Stage 3: appendage subtypes using Azure OpenAI (optional, if appendage)

    Args:
        image: PIL Image with transparent background (RGBA or RGB format)
        model_path_stage1: Path to Stage 1 model. If None, uses default path.
        model_path_stage2: Path to Stage 2 model. If None, uses default path.
        use_azure_openai: If True, use Azure OpenAI GPT-4o for appendage subtypes
        debug: If True, print debug information

    Returns:
        Dictionary with conditional structure:
        - If Stage 1 = "body": {"label": "body", "stage1": {...}}
        - If Stage 2 = "base" or "rim": {"label": "...", "stage1": {...}, "stage2": {...}}
        - If Stage 2 = "appendage": {"label": "...", "stage1": {...}, "stage2": {...}, "stage3": {...}?}
        - If Azure disabled and appendage: no stage3 field

    Raises:
        FileNotFoundError: If model file is not found
        RuntimeError: If model loading or inference fails

    Examples:
        >>> from PIL import Image
        >>> img = Image.open("pottery_type.png")
        >>> result = classify_pottery_type(img, debug=True)
        >>> print(result["label"])
        'body'

        >>> result = classify_pottery_type(img, use_azure_openai=True)
        >>> print(result["label"])  # Could be appendage subtype if appendage
        'spout'
    """
    # Use default model paths if not provided
    if model_path_stage1 is None:
        model_path_stage1 = Path(__file__).parent / DEFAULT_MODEL_PATH_STAGE1
    elif isinstance(model_path_stage1, str):
        model_path_stage1 = Path(model_path_stage1)

    if model_path_stage2 is None:
        model_path_stage2 = Path(__file__).parent / DEFAULT_MODEL_PATH_STAGE2
    elif isinstance(model_path_stage2, str):
        model_path_stage2 = Path(model_path_stage2)

    if debug:
        print(f"classify_pottery_type: Using Stage 1 model: {model_path_stage1}")
        print(f"classify_pottery_type: Using Stage 2 model: {model_path_stage2}")
        print(f"classify_pottery_type: Azure OpenAI: {use_azure_openai}")

    # Setup device
    device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
    if debug:
        print(f"classify_pottery_type: Using device: {device}")

    try:
        # Load DINOv2 model
        if debug:
            print("classify_pottery_type: Loading DINOv2 model...")
        dino_model = _load_dino_model(device)

        # Extract features
        if debug:
            print("classify_pottery_type: Extracting features...")
        features = _extract_features(image, dino_model, device)

        if debug:
            print(f"classify_pottery_type: Feature shape: {features.shape}")

        # Stage 1: body vs everything else
        if debug:
            print("classify_pottery_type: Stage 1: Classifying body vs everything else...")
        classifier_stage1, _ = _load_classifier(model_path_stage1)
        stage1_label, stage1_confidence = _classify_stage1(features, classifier_stage1, debug)

        result = {
            "label": stage1_label,
            "stage1": {
                "label": stage1_label,
                "confidence": stage1_confidence
            }
        }

        # If Stage 1 is "body", return early
        if stage1_label == "body":
            if debug:
                print("classify_pottery_type: Result: body (Stage 1 only)")
            return result

        # Stage 2: base vs rim vs appendage
        if debug:
            print("classify_pottery_type: Stage 2: Classifying base vs rim vs appendage...")
        classifier_stage2, _ = _load_classifier(model_path_stage2)
        stage2_label, stage2_confidence = _classify_stage2(features, classifier_stage2, debug)

        result["label"] = stage2_label
        result["stage2"] = {
            "label": stage2_label,
            "confidence": stage2_confidence
        }

        # If Stage 2 is "appendage" and Azure OpenAI is enabled, do Stage 3
        if stage2_label == "appendage" and use_azure_openai:
            if debug:
                print("classify_pottery_type: Stage 3: Classifying appendage subtype with Azure OpenAI...")
            stage3_label, stage3_confidence = _classify_appendage_with_gpt4o(image, debug)

            if stage3_label is not None and stage3_confidence is not None:
                result["label"] = stage3_label
                result["stage3"] = {
                    "label": stage3_label,
                    "confidence": stage3_confidence
                }
                if debug:
                    print(f"classify_pottery_type: Result: {stage3_label} (with Stage 3)")
            else:
                # Azure OpenAI failed, keep appendage label (no stage3 field)
                if debug:
                    print("classify_pottery_type: Azure OpenAI failed, returning appendage (no Stage 3)")
        # If Stage 2 is "appendage" but Azure is disabled, label stays "appendage" (no stage3 field)
        elif stage2_label == "appendage":
            if debug:
                print("classify_pottery_type: Result: appendage (Azure OpenAI disabled, no Stage 3)")

        if debug:
            print(f"classify_pottery_type: Final result: {result['label']}")

        return result

    except Exception as e:
        raise RuntimeError(f"Classification failed: {e}")

batch_classify_pottery_type

batch_classify_pottery_type(
    images, model_path_stage1=None, model_path_stage2=None, use_azure_openai=False, debug=False
)

Classify multiple pottery type images efficiently.

This function loads the models once and reuses them for all images, making it more efficient than calling classify_pottery_type repeatedly.

Parameters:

Name Type Description Default
images list[Image]

List of PIL Images with transparent backgrounds

required
model_path_stage1 Optional[Path]

Path to Stage 1 model. If None, uses default path.

None
model_path_stage2 Optional[Path]

Path to Stage 2 model. If None, uses default path.

None
use_azure_openai bool

If True, use Azure OpenAI GPT-4o for appendage subtypes

False
debug bool

If True, print debug information

False

Returns:

Type Description
list[Dict[str, any]]

List of classification result dictionaries, one per image

Examples:

>>> from PIL import Image
>>> images = [Image.open(f"pottery_{i}.png") for i in range(5)]
>>> results = batch_classify_pottery_type(images)
>>> for i, result in enumerate(results):
...     print(f"Image {i}: {result['label']}")
Source code in src/ascota_classification/type.py
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
def batch_classify_pottery_type(
    images: list[Image.Image],
    model_path_stage1: Optional[Path] = None,
    model_path_stage2: Optional[Path] = None,
    use_azure_openai: bool = False,
    debug: bool = False
) -> list[Dict[str, any]]:
    """
    Classify multiple pottery type images efficiently.

    This function loads the models once and reuses them for all images,
    making it more efficient than calling classify_pottery_type repeatedly.

    Args:
        images: List of PIL Images with transparent backgrounds
        model_path_stage1: Path to Stage 1 model. If None, uses default path.
        model_path_stage2: Path to Stage 2 model. If None, uses default path.
        use_azure_openai: If True, use Azure OpenAI GPT-4o for appendage subtypes
        debug: If True, print debug information

    Returns:
        List of classification result dictionaries, one per image

    Examples:
        >>> from PIL import Image
        >>> images = [Image.open(f"pottery_{i}.png") for i in range(5)]
        >>> results = batch_classify_pottery_type(images)
        >>> for i, result in enumerate(results):
        ...     print(f"Image {i}: {result['label']}")
    """
    # Use default model paths if not provided
    if model_path_stage1 is None:
        model_path_stage1 = Path(__file__).parent / DEFAULT_MODEL_PATH_STAGE1
    elif isinstance(model_path_stage1, str):
        model_path_stage1 = Path(model_path_stage1)

    if model_path_stage2 is None:
        model_path_stage2 = Path(__file__).parent / DEFAULT_MODEL_PATH_STAGE2
    elif isinstance(model_path_stage2, str):
        model_path_stage2 = Path(model_path_stage2)

    if debug:
        print(f"batch_classify_pottery_type: Using Stage 1 model: {model_path_stage1}")
        print(f"batch_classify_pottery_type: Using Stage 2 model: {model_path_stage2}")
        print(f"Processing {len(images)} images...")

    # Setup device
    device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
    if debug:
        print(f"batch_classify_pottery_type: Using device: {device}")

    try:
        # Load models once
        if debug:
            print("batch_classify_pottery_type: Loading DINOv2 model...")
        dino_model = _load_dino_model(device)

        if debug:
            print("batch_classify_pottery_type: Loading Stage 1 classifier...")
        classifier_stage1, _ = _load_classifier(model_path_stage1)

        if debug:
            print("batch_classify_pottery_type: Loading Stage 2 classifier...")
        classifier_stage2, _ = _load_classifier(model_path_stage2)

        # Process all images
        results = []
        for i, image in enumerate(images):
            if debug and (i + 1) % 10 == 0:
                print(f"batch_classify_pottery_type: Processing image {i + 1}/{len(images)}...")

            # Extract features
            features = _extract_features(image, dino_model, device)

            # Stage 1: body vs everything else
            stage1_label, stage1_confidence = _classify_stage1(features, classifier_stage1, False)

            result = {
                "label": stage1_label,
                "stage1": {
                    "label": stage1_label,
                    "confidence": stage1_confidence
                }
            }

            # If Stage 1 is "body", continue to next image
            if stage1_label == "body":
                results.append(result)
                continue

            # Stage 2: base vs rim vs appendage
            stage2_label, stage2_confidence = _classify_stage2(features, classifier_stage2, False)

            result["label"] = stage2_label
            result["stage2"] = {
                "label": stage2_label,
                "confidence": stage2_confidence
            }

            # If Stage 2 is "appendage" and Azure OpenAI is enabled, do Stage 3
            if stage2_label == "appendage" and use_azure_openai:
                stage3_label, stage3_confidence = _classify_appendage_with_gpt4o(image, False)

                if stage3_label is not None and stage3_confidence is not None:
                    result["label"] = stage3_label
                    result["stage3"] = {
                        "label": stage3_label,
                        "confidence": stage3_confidence
                    }

            results.append(result)

        if debug:
            print(f"batch_classify_pottery_type: ✓ Processed {len(images)} images successfully!")
            # Print summary
            label_counts = {}
            for r in results:
                label = r["label"]
                label_counts[label] = label_counts.get(label, 0) + 1
            print(f"batch_classify_pottery_type: Summary: {label_counts}")

        return results

    except Exception as e:
        raise RuntimeError(f"Batch classification failed: {e}")