docs: document patent PDF volume mount for containerized deployments

Switch docker-compose.yml from bind mount to a named volume (patent_data)
so downloaded PDFs survive container recreation. Add a "Patent PDF Storage"
section to DEPLOYMENT.md covering Docker Compose, Kubernetes PVC, and S3
alternatives.

Closes leeworks-agents/SPARC#1360

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

SPARC/api.py

@@ -479,6 +479,20 @@ SUPPORTED_MODELS = [
     {"id": "meta-llama/llama-3.1-70b-instruct", "name": "Llama 3.1 70B", "provider": "Meta"},
 ]
 
+_SUPPORTED_MODEL_IDS = {m["id"] for m in SUPPORTED_MODELS}
+
+
+def _validate_model(model: str | None) -> None:
+    """Raise HTTP 400 if *model* is not in the supported allow-list."""
+    if model is not None and model not in _SUPPORTED_MODEL_IDS:
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                f"Unsupported model '{model}'. "
+                f"Supported models: {', '.join(sorted(_SUPPORTED_MODEL_IDS))}"
+            ),
+        )
+
 
 @app.get("/models", tags=["System"])
 async def list_models():
@@ -814,6 +828,7 @@ async def analyze_company(
     Returns:
         Analysis results including patent count, AI insights, and success status
     """
+    _validate_model(model)
     if not _analyzer:
         raise HTTPException(status_code=503, detail="Analyzer not initialized")
 
@@ -873,6 +888,7 @@ async def analyze_companies_batch(
     Returns:
         Batch results with individual company analyses and summary statistics
     """
+    _validate_model(request.model)
     if not _analyzer:
         raise HTTPException(status_code=503, detail="Analyzer not initialized")
 
@@ -983,6 +999,7 @@ async def analyze_companies_async(
     Returns:
         Job status with job_id for polling
     """
+    _validate_model(request.model)
     global _job_counter
 
     _job_counter += 1

docker-compose.yml

@@ -49,7 +49,7 @@ services:
       init-db:
         condition: service_completed_successfully
     volumes:
-      - ./patents:/app/patents
+      - patent_data:/app/patents
     restart: unless-stopped
 
   # Optional: MinIO for S3-compatible local object storage
@@ -86,4 +86,5 @@ services:
 
 volumes:
   postgres_data:
+  patent_data:
   minio_data:

docs/DEPLOYMENT.md

@@ -276,7 +276,7 @@ The `docker-compose.yml` includes all services needed for production:
 |---------|-----------|------|-------------|
 | `postgres` | sparc-postgres | 5432 | PostgreSQL database |
 | `init-db` | sparc-init-db | - | One-time database initialization (seeds admin user) |
-| `api` | sparc-api | 8000 | FastAPI REST API with JWT auth |
+| `api` | sparc-api | 8000 | FastAPI REST API with JWT auth (patent PDFs stored in `patent_data` volume) |
 | `dashboard` | sparc-dashboard | 8080 | React TypeScript web UI |
 
 ### Common Docker Compose Commands
@@ -307,6 +307,81 @@ docker-compose restart api
 
 ---
 
+## Patent PDF Storage
+
+The SPARC API downloads patent PDFs during analysis and stores them at `/app/patents` inside the container. These files are used for subsequent single-patent analysis requests and as a local cache to avoid re-downloading. If this directory is not persisted, all downloaded PDFs are lost when the container is recreated.
+
+### Docker Compose (default)
+
+The default `docker-compose.yml` declares a named volume called `patent_data` that is mounted at `/app/patents`:
+
+```yaml
+# In the api service:
+volumes:
+  - patent_data:/app/patents
+
+# At the top-level volumes section:
+volumes:
+  patent_data:
+```
+
+This means PDFs survive `docker compose down` and `docker compose up` cycles. To remove patent data intentionally, run:
+
+```bash
+docker compose down -v   # WARNING: also removes postgres_data
+# or selectively:
+docker volume rm sparc_patent_data
+```
+
+If you prefer a bind mount (e.g., for easy host-side access during development), replace the volume with:
+
+```yaml
+volumes:
+  - ./patents:/app/patents
+```
+
+### Kubernetes
+
+For Kubernetes deployments, create a PersistentVolumeClaim and mount it into the API pod:
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: sparc-patent-data
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 5Gi
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: sparc-api
+spec:
+  template:
+    spec:
+      containers:
+        - name: api
+          volumeMounts:
+            - name: patent-data
+              mountPath: /app/patents
+      volumes:
+        - name: patent-data
+          persistentVolumeClaim:
+            claimName: sparc-patent-data
+```
+
+Adjust the storage size based on expected patent volume. Each patent PDF is typically 1-5 MB.
+
+### S3 Object Storage (alternative)
+
+For production deployments that need shared or highly durable storage, set `STORAGE_BACKEND=s3` in your `.env` file. This stores patent PDFs in an S3-compatible bucket (AWS S3 or MinIO) instead of the local filesystem, eliminating the need for a persistent volume. See the S3/MinIO section in `.env.example` for configuration details.
+
+---
+
 ## Troubleshooting
 
 ### Database Connection Issues

frontend/src/context/useChartTheme.ts

@@ -0,0 +1,41 @@
+import { useTheme } from './ThemeContext';
+
+/**
+ * Returns theme-aware color values for recharts components.
+ *
+ * Recharts accepts only raw color strings (not CSS variables),
+ * so this hook bridges the Tailwind/CSS-variable theme system
+ * to the imperative recharts API.
+ */
+export function useChartTheme() {
+  const { theme } = useTheme();
+  const isDark = theme === 'dark';
+
+  return {
+    /** Axis tick and grid line stroke color */
+    axisStroke: isDark ? '#94a3b8' : '#64748b',
+    /** Tooltip container background */
+    tooltipBg: isDark ? '#1e293b' : '#ffffff',
+    /** Tooltip container border */
+    tooltipBorder: isDark
+      ? '1px solid rgba(99, 102, 241, 0.3)'
+      : '1px solid rgba(99, 102, 241, 0.2)',
+    /** Tooltip label text color */
+    tooltipLabelColor: isDark ? '#f8fafc' : '#0f172a',
+    /** Tooltip item text color */
+    tooltipItemColor: isDark ? '#e2e8f0' : '#334155',
+    /** Convenience: full contentStyle object for recharts Tooltip */
+    tooltipContentStyle: {
+      backgroundColor: isDark ? '#1e293b' : '#ffffff',
+      border: isDark
+        ? '1px solid rgba(99, 102, 241, 0.3)'
+        : '1px solid rgba(99, 102, 241, 0.2)',
+      borderRadius: '8px',
+      color: isDark ? '#f8fafc' : '#0f172a',
+    },
+    /** Convenience: labelStyle for recharts Tooltip */
+    tooltipLabelStyle: {
+      color: isDark ? '#f8fafc' : '#0f172a',
+    },
+  };
+}

frontend/src/pages/Analytics.tsx

@@ -3,11 +3,13 @@ import { useQuery } from '@tanstack/react-query';
 import { analyticsApi } from '../api/client';
 import { AlertCircle, Database } from 'lucide-react';
 import { PieChart, Pie, Cell, BarChart, Bar, LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer, Legend } from 'recharts';
+import { useChartTheme } from '../context/useChartTheme';
 
 const COLORS = ['#6366f1', '#0ea5e9', '#10b981', '#f59e0b', '#ef4444', '#8b5cf6', '#ec4899', '#14b8a6'];
 
 export function AnalyticsPage() {
   const [days, setDays] = useState(30);
+  const chartTheme = useChartTheme();
 
   const { data, isLoading, isError, refetch } = useQuery({
     queryKey: ['analytics', days],
@@ -160,11 +162,7 @@ export function AnalyticsPage() {
                   ))}
                 </Pie>
                 <Tooltip
-                  contentStyle={{
-                    backgroundColor: '#1e293b',
-                    border: '1px solid rgba(99, 102, 241, 0.3)',
-                    borderRadius: '8px',
-                  }}
+                  contentStyle={chartTheme.tooltipContentStyle}
                 />
                 <Legend />
               </PieChart>
@@ -178,15 +176,11 @@ export function AnalyticsPage() {
             <h3 className="text-lg font-semibold text-text-primary mb-4">Analysis Types</h3>
             <ResponsiveContainer width="100%" height={300}>
               <BarChart data={typeData}>
-                <XAxis dataKey="name" stroke="#94a3b8" fontSize={12} />
-                <YAxis stroke="#94a3b8" fontSize={12} />
+                <XAxis dataKey="name" stroke={chartTheme.axisStroke} fontSize={12} />
+                <YAxis stroke={chartTheme.axisStroke} fontSize={12} />
                 <Tooltip
-                  contentStyle={{
-                    backgroundColor: '#1e293b',
-                    border: '1px solid rgba(99, 102, 241, 0.3)',
-                    borderRadius: '8px',
-                  }}
-                  labelStyle={{ color: '#f8fafc' }}
+                  contentStyle={chartTheme.tooltipContentStyle}
+                  labelStyle={chartTheme.tooltipLabelStyle}
                 />
                 <Bar dataKey="count" fill="#6366f1" radius={[4, 4, 0, 0]} />
               </BarChart>
@@ -222,15 +216,11 @@ export function AnalyticsPage() {
                   <h4 className="text-md font-semibold text-text-primary mb-4">Analyses per Company Over Time</h4>
                   <ResponsiveContainer width="100%" height={300}>
                     <LineChart data={pivoted}>
-                      <XAxis dataKey="month" stroke="#94a3b8" fontSize={12} />
-                      <YAxis stroke="#94a3b8" fontSize={12} />
+                      <XAxis dataKey="month" stroke={chartTheme.axisStroke} fontSize={12} />
+                      <YAxis stroke={chartTheme.axisStroke} fontSize={12} />
                       <Tooltip
-                        contentStyle={{
-                          backgroundColor: '#1e293b',
-                          border: '1px solid rgba(99, 102, 241, 0.3)',
-                          borderRadius: '8px',
-                        }}
-                        labelStyle={{ color: '#f8fafc' }}
+                        contentStyle={chartTheme.tooltipContentStyle}
+                        labelStyle={chartTheme.tooltipLabelStyle}
                       />
                       <Legend />
                       {companies.map((company, idx) => (
@@ -268,15 +258,11 @@ export function AnalyticsPage() {
                   <h4 className="text-md font-semibold text-text-primary mb-4">Analysis Types Over Time</h4>
                   <ResponsiveContainer width="100%" height={300}>
                     <BarChart data={pivoted}>
-                      <XAxis dataKey="month" stroke="#94a3b8" fontSize={12} />
-                      <YAxis stroke="#94a3b8" fontSize={12} />
+                      <XAxis dataKey="month" stroke={chartTheme.axisStroke} fontSize={12} />
+                      <YAxis stroke={chartTheme.axisStroke} fontSize={12} />
                       <Tooltip
-                        contentStyle={{
-                          backgroundColor: '#1e293b',
-                          border: '1px solid rgba(99, 102, 241, 0.3)',
-                          borderRadius: '8px',
-                        }}
-                        labelStyle={{ color: '#f8fafc' }}
+                        contentStyle={chartTheme.tooltipContentStyle}
+                        labelStyle={chartTheme.tooltipLabelStyle}
                       />
                       <Legend />
                       {types.map((type, idx) => (

frontend/src/pages/Batch.tsx

@@ -3,6 +3,7 @@ import { useMutation, useQuery } from '@tanstack/react-query';
 import { analysisApi } from '../api/client';
 import { Rocket, CheckCircle, AlertCircle, ChevronDown, ChevronUp, RefreshCw, Inbox } from 'lucide-react';
 import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer, Cell } from 'recharts';
+import { useChartTheme } from '../context/useChartTheme';
 import type { BatchAnalysisResult } from '../types';
 
 export function Batch() {
@@ -12,6 +13,8 @@ export function Batch() {
   const [result, setResult] = useState<BatchAnalysisResult | null>(null);
   const [expandedItems, setExpandedItems] = useState<Set<string>>(new Set());
 
+  const chartTheme = useChartTheme();
+
   const modelsQuery = useQuery({
     queryKey: ['models'],
     queryFn: () => analysisApi.listModels(),
@@ -210,15 +213,11 @@ export function Batch() {
             <div className="bg-bg-card/60 border border-primary/15 rounded-2xl p-6">
               <ResponsiveContainer width="100%" height={300}>
                 <BarChart data={chartData}>
-                  <XAxis dataKey="name" stroke="#94a3b8" fontSize={12} />
-                  <YAxis stroke="#94a3b8" fontSize={12} />
+                  <XAxis dataKey="name" stroke={chartTheme.axisStroke} fontSize={12} />
+                  <YAxis stroke={chartTheme.axisStroke} fontSize={12} />
                   <Tooltip
-                    contentStyle={{
-                      backgroundColor: '#1e293b',
-                      border: '1px solid rgba(99, 102, 241, 0.3)',
-                      borderRadius: '8px',
-                    }}
-                    labelStyle={{ color: '#f8fafc' }}
+                    contentStyle={chartTheme.tooltipContentStyle}
+                    labelStyle={chartTheme.tooltipLabelStyle}
                   />
                   <Bar dataKey="patents" radius={[4, 4, 0, 0]}>
                     {chartData.map((entry, index) => (

tests/test_api.py

@@ -182,3 +182,47 @@ class TestJobEndpoints:
         """Test listing jobs with status filter."""
         response = client.get("/jobs?status=completed")
         assert response.status_code == 200
+
+
+class TestModelValidation:
+    """Test that unsupported model identifiers are rejected."""
+
+    def test_analyze_rejects_unsupported_model(self, client, mock_analyzer):
+        """GET /analyze/{company} with unsupported model returns 400."""
+        response = client.get("/analyze/nvidia?model=fake/nonexistent-model")
+        assert response.status_code == 400
+        assert "Unsupported model" in response.json()["detail"]
+
+    def test_analyze_accepts_supported_model(self, client, mock_analyzer):
+        """GET /analyze/{company} with a supported model succeeds."""
+        mock_result = CompanyAnalysisResult(
+            company_name="nvidia",
+            analysis="test",
+            patent_count=1,
+            success=True,
+            timestamp=datetime.now(),
+            model="anthropic/claude-3.5-sonnet",
+        )
+        mock_analyzer._analyze_company_safe.return_value = mock_result
+
+        response = client.get("/analyze/nvidia?model=anthropic/claude-3.5-sonnet")
+        assert response.status_code == 200
+
+    def test_batch_rejects_unsupported_model(self, client, mock_analyzer):
+        """POST /analyze/batch with unsupported model returns 400."""
+        response = client.post(
+            "/analyze/batch",
+            json={"companies": ["nvidia"], "model": "fake/nonexistent-model"},
+        )
+        assert response.status_code == 400
+        assert "Unsupported model" in response.json()["detail"]
+
+    def test_list_models_returns_supported(self, client):
+        """GET /models returns the allow-list."""
+        response = client.get("/models")
+        assert response.status_code == 200
+        data = response.json()
+        assert "models" in data
+        assert "default" in data
+        assert len(data["models"]) > 0
+        assert all("id" in m and "name" in m and "provider" in m for m in data["models"])