plant-disease-id/tasks/multi-image-user-feedback/04-enhanced-identify-api-route.md

04. Enhanced API Route for Multi-Image, Species-Aware Identification

meta: id: multi-image-user-feedback-04 feature: multi-image-user-feedback priority: P1 depends_on: [multi-image-user-feedback-01, multi-image-user-feedback-02, multi-image-user-feedback-03] tags: [api, backend]

objective:

• Update the /api/identify route to accept optional options (secondImageId, userSpecies), run ensemble inference when multiple images provided, apply species-constrained softmax when species is known, and return top-5 species+disease combo predictions with confidence metadata.

deliverables:

• src/app/api/identify/route.ts — updated route handler

steps:

1. Update the request parsing to accept options?: IdentifyOptions alongside imageId:

   const { imageId, options } = body;
   const secondImageId = options?.secondImageId;
   const userSpecies = options?.userSpecies;
   

2. Update image loading to support optional second image:

   • Load first image tensor (existing logic)
   • If secondImageId provided, load and preprocess that image too
   • Validate both images exist before inference

3. Update inference logic to use the new pipeline:

   • If 2 images provided → call runEnsembleInference(tensors, topK=10)
   • If userSpecies provided → get species class range, call runSpeciesConstrainedInference or runEnsembleSpeciesConstrained
   • If 2 images + species → use full ensemble+constrained
   • If 1 image + no species → use existing single-inference path (backward compatible)
   • Pass the infoProvided list to the response (which optional inputs were used)

4. Generate top-5 species+disease combo predictions:

   • After enrichment, construct TopPrediction[] from the top enriched predictions
   • Each entry: { speciesName, diseaseName, diseaseId, confidence, rank }
   • Include species confidence when userSpecies was provided

5. Add speciesConfidence to response:

   • When user provides species, compute how much the constraint improves confidence vs unconstrained
   • Return both constrained and unconstrained confidence for comparison

6. Handle demo/mock mode:

   • When no real model loaded, return mock top-5 combos with appropriate demo_mode flag
   • Mock combos should be realistic (use knowledge base to generate plausible species/disease pairs)

tests:

• Integration: single image + no options → existing behavior unchanged
• Integration: single image + species → constrained results, all predictions belong to that species
• Integration: 2 images → ensemble results, confidence should differ from single image
• Integration: 2 images + species → fully constrained ensemble
• Integration: missing secondImageId returns 400 error
• Integration: demo mode returns mock data

acceptance_criteria:

• Existing single-image identify flow works unchanged when options omitted
• When secondImageId is provided, inference runs on both images
• When userSpecies is provided, only diseases of that species are returned
• Top-5 species/disease combos are included in response
• Confidence reflects whether 1 or 2 images were used
• 400 error for invalid/missing second image

validation:

• npx tsc --noEmit passes
• Existing identify API tests pass: npx vitest run src/app/api/identify/
• Manual test with curl sending multi-image request

notes:

• The infoProvided array helps the UI show what data was used for the diagnosis
• When userSpecies is given but no model can restrict to that species (e.g., mock mode), fall back to filtering results client-side by the plant name