HMS-Unicorn/Automated_Detection_of_Flower

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Gemini API configuration (2026-09-26)

For Azure Container Apps migration, see AZURE_DEPLOYMENT.md.

Image analysis uses Google Gen AI SDK (google-genai) with a Google AI Studio API key and the Gemini Developer API. The default model remains gemini-3.5-flash-lite, configurable through GEMINI_MODEL. Upload, single-URL and batch-URL analysis retain the same seven result fields and CSV/history formats.

Single-image flower-shape RAG

Single-image upload and single-URL results include a short flower-shape introduction below the seven analysis fields. The only knowledge source is knowledge/flower_shape_backend_rag_en_v2.jsonl, supplied for this project. It contains one record for each of the 17 labels in the image prompt, plus N/A. Following the Python RAG tutorial, the backend splits each shape's reference into passages, embeds them with an English SentenceTransformer, indexes them in Chroma's in-memory EphemeralClient, retrieves by vector similarity, reranks with a CrossEncoder, and asks Gemini to write 1–2 sentences from the retrieved material. Chroma retrieval is filtered by the image model's exact flower-shape label so similar labels cannot mix. The definition from that same record is always included in the generation context. N/A and unknown labels have no introduction.

The introduction is returned separately from single_result; it is not added to CSV or the existing browser history. Batch URL results do not invoke the RAG step. The JSONL and both retrieval models ship with the Space image; the vector index is rebuilt in memory after each process start and does not persist. Model loading and indexing warm in the background. If they are unavailable, generation uses the record's definition and diagnostic features; if generation fails, the definition is displayed. Index readiness waits up to 3 seconds, retrieval up to 5 seconds, and the optional Gemini call has an 18-second timeout, so a stalled RAG step does not block the image result indefinitely.

Space configuration

Your existing two Space secrets can stay as they are:

The page uses the current Turnstile site key by default. If you created a new Cloudflare widget, set the optional Space variable CF_TURNSTILE_SITE_KEY to its public site key and ensure CF_TURNSTILE_SECRET_KEY is the secret from that same widget. The browser success display is followed by a separate server-side Siteverify call. The app logs Cloudflare's error-codes (never the token or secret) and reports whether the configured secret is invalid, a token is expired or already used, or Siteverify cannot be reached.

Do not add {}, quotes, or JSON around the API key. No service-account file is needed. The previous JSON errors came from attempting to load an API key as service-account credentials.

For a clearer name you may optionally use GEMINI_API_KEY instead of GCP_SA_KEY. If more than one key variable is set, precedence is GOOGLE_API_KEY, then GEMINI_API_KEY, then GCP_SA_KEY. Only the variable name, never the key, is logged.

start.py checks that a raw key is configured before starting Gunicorn. The application passes it explicitly to genai.Client with enterprise=False, using generativelanguage.googleapis.com and API version v1beta. It does not load ADC or write /tmp/gcp_key.json; old project, location and credential-file settings are unused. Configuration checks do not make a Google request or verify the key's permissions.

To deploy, push the reviewed changes to the Space's main branch and let its Docker image rebuild. Keep the existing API key unchanged and reload the analysis page after startup.

Waiting-state fixes (2026-09-26)

• —A process-wide SDK client reuses its API key and connections. Model HTTP requests have a 60-second timeout with no automatic retries.
• —The browser stops waiting after 120 seconds for a single analysis, 20 seconds for batch submission, or 15 seconds for a status/results request. Batch polling is sequential and reports an error after 3 minutes without progress. A timed-out batch may still finish on the server.
• —Batch coordinators use a separate executor from image workers, avoiding a pool in which every worker waits for another task in the same pool. Results advance as individual downloads/analyses finish.
• —Page errors stop the spinner and restore the button even if browser storage or optional UI enhancements fail. The updated service worker removes its old shell cache and uses the network first; the analysis script has a versioned URL.
• —Gunicorn access logs and application-stage logs are written to the Space logs. Look for Analysis request received, Turnstile accepted, Gemini request, and Gemini response received to identify where a request stops. The configured model is included in the request logs.

After deploying, reload the analysis page to load the versioned script. No automated tests or live inference were run for these fixes, as requested; only syntax and diff checks were performed.

Local verification

Install requirements.txt into a Python virtual environment, then run:

python -m unittest discover -s tests -v

Tests use the real SDK with mocked HTTP transport; they do not send images to Google or require credentials. For local live inference, export GEMINI_API_KEY (or the legacy GCP_SA_KEY) with the raw AI Studio API key and supply CF_TURNSTILE_SECRET_KEY. Environment variables must be exported explicitly; the app does not load .env automatically.

Official references:

• —Using Gemini API keys
• —Structured outputs
• —Google Gen AI Python SDK