Merge pull request #10 from Annotation-Garden/claude/update-gpu-docs-01UeUn4bN1MiBzCjTQTdbKvt

Update GPU inference platform documentation

Author: neuromechanist

.gitignore

@@ -58,6 +58,7 @@ yarn-error.log*
 out/
 .nuxt/
 .cache/
+tsconfig.tsbuildinfo
 
 # Virtual environments
 venv/

README.md

@@ -86,6 +86,10 @@ Annotations follow stimuli-BIDS specifications:
 - **Storage**: JSON files with database support for large datasets
 - **Processing**: Stateless VLM calls with comprehensive metrics
 
+### Inference Platform
+
+All performance metrics in this repository were generated using an **NVIDIA GeForce RTX 4090 GPU** with OLLAMA for local model inference. See [Quality Control](docs/quality-control.md#inference-platform) for details.
+
 ## Annotation Tools
 
 Powerful CLI tools for post-processing annotations:

docs/quality-control.md

@@ -108,8 +108,14 @@ python scripts/reannotate_missing_prompts.py
 python scripts/check_annotation_quality.py annotations/nsd/
 ```
 
+## Inference Platform
+
+All inference was performed on an **NVIDIA GeForce RTX 4090 GPU** using OLLAMA for local model execution. This platform information applies to all performance metrics documented in this repository.
+
 ## Case Study: Issue #4
 
+**Inference Platform**: NVIDIA RTX 4090 GPU
+
 **Analysis** of 30,000 responses (1,000 images × 6 models × 5 prompts):
 - 143 problematic responses (0.5% of total)
 - 139 files affected (13.9%)

frontend/app/components/AnnotationViewer.tsx

@@ -1,14 +1,16 @@
 'use client'
 
 import { useState } from 'react'
-import { PromptAnnotation } from '../types'
+import { PromptAnnotation, PlatformInfo } from '../types'
 import { Copy, Check, FileText, FileJson, Activity, Zap } from 'lucide-react'
+import PlatformBadge from './PlatformBadge'
 
 interface AnnotationViewerProps {
   annotation: PromptAnnotation
+  platform?: PlatformInfo | null
 }
 
-export default function AnnotationViewer({ annotation }: AnnotationViewerProps) {
+export default function AnnotationViewer({ annotation, platform }: AnnotationViewerProps) {
   const [copied, setCopied] = useState(false)
   const [viewMode, setViewMode] = useState<'text' | 'json'>('text')
 
@@ -190,6 +192,14 @@ export default function AnnotationViewer({ annotation }: AnnotationViewerProps)
           )}
         </div>
       )}
+
+      {/* Platform info (shown inline with metrics) */}
+      {platform && (
+        <div className="flex items-center gap-2 mt-3">
+          <span className="text-xs text-agi-teal-500 dark:text-zinc-500">Platform:</span>
+          <PlatformBadge platform={platform} />
+        </div>
+      )}
     </div>
   )
 }

frontend/app/components/PlatformBadge.tsx

@@ -0,0 +1,68 @@
+'use client'
+
+import { PlatformInfo } from '../types'
+import { Cpu, Monitor } from 'lucide-react'
+
+interface PlatformBadgeProps {
+  platform?: PlatformInfo | null
+}
+
+// Map vendor to display color
+const vendorColors: Record<string, string> = {
+  nvidia: 'text-green-600 dark:text-green-400',
+  amd: 'text-red-600 dark:text-red-400',
+  intel: 'text-blue-600 dark:text-blue-400',
+  apple: 'text-gray-600 dark:text-gray-400',
+}
+
+// Map compute backend to display name
+const backendNames: Record<string, string> = {
+  cuda: 'CUDA',
+  rocm: 'ROCm',
+  mps: 'Metal',
+  oneapi: 'oneAPI',
+  cpu: 'CPU',
+}
+
+export default function PlatformBadge({ platform }: PlatformBadgeProps) {
+  if (!platform) {
+    return null
+  }
+
+  const hasGPU = platform.accelerators && platform.accelerators.length > 0
+  const primaryGPU = hasGPU ? platform.accelerators[0] : null
+  const backendDisplay = platform.compute_backend
+    ? backendNames[platform.compute_backend] || platform.compute_backend.toUpperCase()
+    : null
+
+  return (
+    <div className="flex items-center gap-2 px-3 py-1.5 bg-agi-teal/5 dark:bg-agi-teal/10 rounded-lg border border-agi-teal/10 dark:border-agi-teal/20">
+      {hasGPU ? (
+        <Monitor className="w-4 h-4 text-agi-orange" />
+      ) : (
+        <Cpu className="w-4 h-4 text-agi-teal-500" />
+      )}
+      <div className="flex items-center gap-2 text-xs">
+        {primaryGPU ? (
+          <>
+            <span className={`font-medium ${vendorColors[primaryGPU.vendor] || 'text-agi-teal-600'}`}>
+              {primaryGPU.name}
+            </span>
+            {primaryGPU.memory_mb && (
+              <span className="text-agi-teal-500 dark:text-zinc-500">
+                ({Math.round(primaryGPU.memory_mb / 1024)}GB)
+              </span>
+            )}
+          </>
+        ) : (
+          <span className="text-agi-teal-600 dark:text-zinc-400">CPU Only</span>
+        )}
+        {backendDisplay && (
+          <span className="text-agi-teal-400 dark:text-zinc-500">
+            • {backendDisplay}
+          </span>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/app/page.tsx

@@ -4,13 +4,15 @@ import { useState, useEffect, useMemo } from 'react'
 import Image from 'next/image'
 import ThumbnailRibbon from './components/ThumbnailRibbon'
 import AnnotationViewer from './components/AnnotationViewer'
-import { ImageData, Annotation, PromptAnnotation } from './types'
+import PlatformBadge from './components/PlatformBadge'
+import { ImageData, Annotation, PromptAnnotation, PlatformInfo } from './types'
 import { Sparkles, ChevronDown, Loader2, ExternalLink, Sun, Moon } from 'lucide-react'
 
 export default function Dashboard() {
   const [images, setImages] = useState<ImageData[]>([])
   const [selectedImageIndex, setSelectedImageIndex] = useState(0)
   const [annotations, setAnnotations] = useState<Record<string, Annotation[]>>({})
+  const [platformInfo, setPlatformInfo] = useState<PlatformInfo | null>(null)
   const [selectedModel, setSelectedModel] = useState<string>('')
   const [selectedPromptKey, setSelectedPromptKey] = useState<string>('')
   const [loading, setLoading] = useState(true)
@@ -87,13 +89,23 @@ export default function Dashboard() {
     return []
   }, [annotations, selectedImageIndex, images, selectedModel])
 
+  // Get current model annotation (includes platform override if present)
+  const currentModelAnnotation = useMemo(() => {
+    if (!images[selectedImageIndex] || !selectedModel) return null
+    const imageAnnotations = annotations[images[selectedImageIndex].id] || []
+    return imageAnnotations.find(a => a.model === selectedModel) || null
+  }, [annotations, selectedImageIndex, images, selectedModel])
+
   // Get current prompt annotation
   const currentPromptAnnotation = useMemo(() => {
-    if (!images[selectedImageIndex] || !selectedModel || !selectedPromptKey) return null
-    const imageAnnotations = annotations[images[selectedImageIndex].id] || []
-    const modelAnnotation = imageAnnotations.find(a => a.model === selectedModel)
-    return modelAnnotation?.prompts[selectedPromptKey] || null
-  }, [annotations, selectedImageIndex, images, selectedModel, selectedPromptKey])
+    if (!currentModelAnnotation || !selectedPromptKey) return null
+    return currentModelAnnotation.prompts[selectedPromptKey] || null
+  }, [currentModelAnnotation, selectedPromptKey])
+
+  // Get effective platform (annotation override or default)
+  const effectivePlatform = useMemo(() => {
+    return currentModelAnnotation?.platform || platformInfo
+  }, [currentModelAnnotation, platformInfo])
 
   async function loadAnnotationsForImage(imageId: string) {
     setImageLoading(true)
@@ -104,6 +116,11 @@ export default function Dashboard() {
         const data = await response.json()
         setAnnotations(prev => ({ ...prev, [imageId]: data.annotations || [] }))
 
+        // Extract platform info from metadata if available
+        if (data.metadata?.platform) {
+          setPlatformInfo(data.metadata.platform)
+        }
+
         // Auto-select first model and prompt if nothing selected
         if (data.annotations && data.annotations.length > 0) {
           const firstAnnotation = data.annotations[0]
@@ -300,7 +317,7 @@ export default function Dashboard() {
               </h3>
               <div className="flex-1 overflow-auto">
                 {currentPromptAnnotation ? (
-                  <AnnotationViewer annotation={currentPromptAnnotation} />
+                  <AnnotationViewer annotation={currentPromptAnnotation} platform={effectivePlatform} />
                 ) : (
                   <div className="text-agi-teal-500 dark:text-zinc-500 text-center py-8">
                     {!selectedModel ? 'Select a vision model to explore annotations' :
@@ -324,17 +341,25 @@ export default function Dashboard() {
 
         {/* Footer */}
         <footer className="glass-footer px-6 py-3">
-          <div className="text-center text-sm text-agi-teal-600 dark:text-zinc-400">
-            © 2025{' '}
-            <a
-              href="https://annotation.garden"
-              target="_blank"
-              rel="noopener noreferrer"
-              className="text-agi-teal dark:text-agi-teal-400 hover:text-agi-orange transition-colors inline-flex items-center gap-1"
-            >
-              Annotation Garden Initiative
-              <ExternalLink className="w-3 h-3" />
-            </a>
+          <div className="flex flex-col md:flex-row items-center justify-between gap-2">
+            <div className="text-sm text-agi-teal-600 dark:text-zinc-400">
+              © 2025{' '}
+              <a
+                href="https://annotation.garden"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-agi-teal dark:text-agi-teal-400 hover:text-agi-orange transition-colors inline-flex items-center gap-1"
+              >
+                Annotation Garden Initiative
+                <ExternalLink className="w-3 h-3" />
+              </a>
+            </div>
+            {platformInfo && (
+              <div className="flex items-center gap-2">
+                <span className="text-xs text-agi-teal-500 dark:text-zinc-500">Inference Platform:</span>
+                <PlatformBadge platform={platformInfo} />
+              </div>
+            )}
           </div>
         </footer>
       </main>

frontend/app/types.ts

@@ -29,6 +29,22 @@ export interface Annotation {
   model: string
   temperature?: number
   prompts: Record<string, PromptAnnotation>
+  platform?: PlatformInfo | null  // Override for this annotation (e.g., cloud API)
+}
+
+export interface GPUInfo {
+  name: string
+  vendor: string  // nvidia, amd, intel, apple
+  memory_mb?: number | null
+  driver_version?: string | null
+}
+
+export interface PlatformInfo {
+  os_name: string
+  os_version: string
+  python_version: string
+  accelerators: GPUInfo[]
+  compute_backend?: string | null  // cuda, rocm, mps, oneapi, cpu
 }
 
 export interface AnnotationFile {
@@ -37,6 +53,7 @@ export interface AnnotationFile {
   annotations: Annotation[]
   metadata?: {
     processed_at?: string
+    platform?: PlatformInfo
     [key: string]: any
   }
 }

src/image_annotation/services/vlm_service.py

@@ -10,6 +10,8 @@
 from langchain_ollama import ChatOllama
 from pydantic import BaseModel, Field
 
+from image_annotation.utils.platform_info import PlatformInfo, get_platform_info
+
 
 class VLMPrompt(BaseModel):
     """Configuration for a VLM prompt."""
@@ -65,6 +67,11 @@ class VLMResult(BaseModel):
 
     # Additional metadata
     temperature: float | None = None
+    platform: dict | None = Field(
+        None,
+        description="Platform info override for this annotation (e.g., cloud API). "
+        "If None, uses the default platform from metadata.",
+    )
 
 
 class VLMService:
@@ -76,6 +83,7 @@ def __init__(
         base_url: str = "http://localhost:11434",
         temperature: float = 0.3,
         timeout: int = 60,
+        platform_override: dict | None = None,
     ):
         """Initialize the VLM service.
 
@@ -84,11 +92,14 @@ def __init__(
             base_url: OLLAMA API base URL.
             temperature: Generation temperature.
             timeout: Request timeout in seconds.
+            platform_override: Optional platform info to use instead of auto-detection.
+                Useful for cloud APIs (OpenAI, Anthropic) or custom setups.
         """
         self.model = model
         self.base_url = base_url
         self.temperature = temperature
         self.timeout = timeout
+        self.platform_override = platform_override
         self._llm_cache = {}
 
     def _get_llm(self, model: str | None = None) -> ChatOllama:
@@ -287,6 +298,7 @@ def annotate_image(
                 performance_metrics=performance_metrics,
                 temperature=self.temperature,
                 error=error,
+                platform=self.platform_override,  # Include if set (for cloud APIs, etc.)
             )
 
         except Exception as e:
@@ -303,6 +315,7 @@ def annotate_image(
                 performance_metrics=PerformanceMetrics(total_duration_ms=total_time_ms),
                 temperature=self.temperature,
                 error=str(e),
+                platform=self.platform_override,
             )
 
     def annotate_batch(
@@ -400,6 +413,9 @@ def save_results(results: list[VLMResult], output_dir: str | Path) -> Path:
     if num_with_speed > 0:
         avg_speed = avg_speed / num_with_speed
 
+    # Get platform information
+    platform_info = get_platform_info()
+
     # Convert results to dict format
     results_dict = {
         "metadata": {
@@ -409,6 +425,7 @@ def save_results(results: list[VLMResult], output_dir: str | Path) -> Path:
             "failed": sum(1 for r in results if r.error is not None),
             "total_tokens_used": total_tokens,
             "average_tokens_per_second": round(avg_speed, 2) if num_with_speed > 0 else None,
+            "platform": platform_info.to_dict(),
         },
         "annotations": [r.model_dump(mode="json") for r in results],
     }

src/image_annotation/utils/__init__.py

@@ -7,11 +7,21 @@
     remove_model,
     reorder_annotations,
 )
+from .platform_info import (
+    GPUInfo,
+    PlatformInfo,
+    get_platform_info,
+    get_platform_summary,
+)
 
 __all__ = [
     "reorder_annotations",
     "remove_model",
     "get_annotation_stats",
     "filter_annotations_by_tokens",
     "export_to_csv",
+    "GPUInfo",
+    "PlatformInfo",
+    "get_platform_info",
+    "get_platform_summary",
 ]