DEC Chatbot — User Manual Clavardage DEC — Manuel d'utilisation

OverviewVue d'ensemble

The DEC Chatbot is a conversational AI assistant that lets researchers and scientists search Canadian Earth Observation (EO) data catalogues using plain-language queries in English or French. It is live at dec-chat-dev.csadecai.com.

Le clavardage DEC est un assistant d'intelligence artificielle conversationnel qui permet aux chercheurs et aux scientifiques d'effectuer des recherches dans les catalogues de données d'observation de la Terre (OT) canadiens à l'aide de requêtes en langage naturel, en anglais ou en français. Il est accessible à dec-chat-dev.csadecai.com.

Users can ask questions like:

Les utilisateurs peuvent poser des questions telles que :

• "Show me RCM SAR imagery over the Canadian Arctic from last month"
• "Show me recent SAR data for Quebec"
• "What lake water quality data is available for Lake Erie in 2024?"

• « Montre-moi les images SAR RCM au-dessus de l'Arctique canadien du mois dernier »
• « Montre-moi les données SAR récentes pour le Québec »
• « Quelles données sur la qualité de l'eau des lacs sont disponibles pour le lac Érié en 2024 ? »

The chatbot returns a text summary of what was found, a satellite image thumbnail (when available), and a Source link to the verified catalogue record — so every response is traceable back to real data.

Le chatbot retourne un résumé textuel de ce qui a été trouvé, une vignette d'image satellite (lorsque disponible) et un lien Source vers l'enregistrement de catalogue vérifié — ainsi, chaque réponse est traçable jusqu'aux données réelles.

Architecture

Backend files (mounted as ConfigMap in the pod)Fichiers du serveur (montés comme ConfigMap dans le pod)

Kubernetes

AI ModelsModèles d'IA

Using the ChatbotUtilisation du chatbot

Searching for dataRecherche de données

Ask in plain language. Include a location and/or time period for best results. The chatbot searches DEC and EODMS in parallel.

Posez votre question en langage naturel. Incluez un lieu et/ou une période pour de meilleurs résultats. Le chatbot effectue des recherches simultanément dans DEC et EODMS.

• Geographic references (provinces, cities, "Arctic", "Canada-wide") are automatically converted to bounding boxes.
• Relative dates ("last month", "summer 2024") are converted to ISO 8601 intervals.
• If the query is too vague, the chatbot will ask a clarifying question.

• Les références géographiques (provinces, villes, « Arctique », « à l'échelle du Canada ») sont automatiquement converties en boîtes englobantes.
• Les dates relatives (« le mois dernier », « été 2024 ») sont converties en intervalles ISO 8601.
• Si la requête est trop vague, le chatbot posera une question de clarification.

Source linksLiens vers les sources

Every response with real data includes a Source: Catalogue record link. Clicking it opens the STAC item record in the DEC or EODMS catalogue, which shows full metadata, download links, and provenance. This is how you verify the response is not hallucinated.

Chaque réponse contenant de vraies données inclut un lien Source : Enregistrement de catalogue. En cliquant dessus, vous ouvrez l'enregistrement STAC dans le catalogue DEC ou EODMS, qui affiche les métadonnées complètes, les liens de téléchargement et la provenance. C'est ainsi que vous vérifiez que la réponse n'est pas hallucinée.

Satellite imagesImages satellites

Preview thumbnails are served through /proxy/image. GeoTIFF files are converted to PNG on the fly. Some collections (SENTINEL-5P, Landsat, climate normals) do not have thumbnail assets in the catalogue — those return text-only responses.

Les vignettes d'aperçu sont servies via /proxy/image. Les fichiers GeoTIFF sont convertis en PNG à la volée. Certaines collections (SENTINEL-5P, Landsat, normales climatiques) n'ont pas de vignettes dans le catalogue — celles-ci retournent des réponses textuelles uniquement.

Conversation memoryMémoire de conversation

The chatbot remembers the last 10 turns of your conversation so you can ask follow-ups like "show me more" or "what about July?". Memory is per-session and is lost if the pod restarts.

Le chatbot se souvient des 10 derniers échanges de votre conversation, ce qui vous permet de poser des questions de suivi comme « montre-moi plus » ou « qu'en est-il de juillet ? ». La mémoire est par session et est perdue si le pod redémarre.

Acquisition planningPlanification d'acquisitions

Ask when a satellite will next pass over a location and the chatbot will return a predicted overpass time. It supports any active LEO satellite — Sentinel-1, Sentinel-2, Sentinel-3, Sentinel-5P, Sentinel-6, Landsat 8/9, MODIS Terra/Aqua, RADARSAT Constellation Mission (RCM-1/2/3), NOAA-20, Suomi NPP, the ISS, and others. Two prediction backends are used:

• Copernicus DataSpace catalog (Sentinel-1 and Sentinel-2): the most recent confirmed overpass over the location is read from the public OData catalog and projected forward using the observed cadence.
• TLE orbit propagation (everything else): the latest Two-Line Element for the satellite is fetched from Celestrak (cached for 24h) and propagated with pyorbital to find the next time the satellite will be physically over the location.

Example queries: "When is the next Sentinel-2 image over Montreal?", "When does Landsat 9 next pass over Toronto?", "When is the next RCM acquisition over Quebec City?". The chatbot answers in UTC with a local-time conversion, lists upcoming passes, and is explicit about the difference between an overhead pass and an actual imaging acquisition (Landsat WRS-2 path/row, RCM tasking, etc. mean the satellite isn't always imaging on every pass).

Demandez quand un satellite passera ensuite au-dessus d'un emplacement et le chatbot retournera l'heure de survol prédite. Il prend en charge tout satellite LEO actif — Sentinel-1, Sentinel-2, Sentinel-3, Sentinel-5P, Sentinel-6, Landsat 8/9, MODIS Terra/Aqua, la mission de la Constellation RADARSAT (RCM-1/2/3), NOAA-20, Suomi NPP, la SSI et autres. Deux moteurs de prédiction sont utilisés :

• Catalogue Copernicus DataSpace (Sentinel-1 et Sentinel-2) : le passage confirmé le plus récent est lu dans le catalogue OData public et projeté vers l'avant en utilisant la cadence observée.
• Propagation orbitale TLE (tout autre satellite) : le dernier élément orbital (Two-Line Element) est récupéré depuis Celestrak (mis en cache 24 h) et propagé avec pyorbital pour trouver le prochain moment où le satellite survolera l'emplacement.

Exemples de questions : « Quand aura lieu la prochaine image Sentinel-2 au-dessus de Montréal ? », « Quand Landsat 9 passera-t-il au-dessus de Toronto ? », « Quand est la prochaine acquisition RCM au-dessus de Québec ? ». Le chatbot répond en UTC avec une conversion en heure locale, liste les survols à venir, et précise la distinction entre un simple survol et une acquisition réelle (cycle WRS-2 de Landsat, tâches RCM, etc. — un satellite n'image pas systématiquement à chaque passage).

Uploading files for analysisTéléverser des fichiers pour analyse

Use the paperclip button next to the input box (or drag-and-drop) to attach files alongside your question. The chatbot can then look at what you uploaded and answer questions about it.

• Images (PNG, JPEG, GIF, WEBP): passed straight to the model for visual analysis. Maximum 5 MB per image.
• GeoTIFF / TIFF: rendered server-side to a percentile-stretched PNG preview (max 2000 px) so the model can analyse the imagery. The reply will mention that values reflect the stretch, not original sensor units.
• Documents (PDF, DOC/DOCX, XLS/XLSX, CSV, HTML, TXT, MD): handed to the model as native document blocks. Maximum 4 MB per document.
• Other text (JSON, YAML, log files, source code): inlined into the prompt as text, truncated at 50 000 characters.
• Unsupported binaries (e.g. ZIP, EXE, executables): skipped with a short note in the reply explaining what was dropped.

Up to 6 files per message. Uploaded files are kept in the in-memory conversation history, so follow-up questions like "what's in the lower-left of the image?" work without re-uploading. They are lost when the pod restarts.

Utilisez le bouton trombone à côté de la zone de texte (ou glissez-déposez) pour joindre des fichiers à votre question. Le chatbot peut ensuite examiner ce que vous avez téléversé et répondre à des questions à son sujet.

• Images (PNG, JPEG, GIF, WEBP) : transmises directement au modèle pour analyse visuelle. Limite de 5 Mo par image.
• GeoTIFF / TIFF : rendues côté serveur en aperçu PNG étiré par centiles (max 2000 px) pour que le modèle puisse analyser l'imagerie. La réponse précise que les valeurs reflètent l'étirement, pas les unités du capteur.
• Documents (PDF, DOC/DOCX, XLS/XLSX, CSV, HTML, TXT, MD) : passés au modèle en blocs de document natifs. Limite de 4 Mo par document.
• Autres textes (JSON, YAML, journaux, code source) : intégrés à l'invite, tronqués à 50 000 caractères.
• Binaires non pris en charge (ex. ZIP, EXE) : ignorés avec une note dans la réponse expliquant ce qui a été écarté.

Jusqu'à 6 fichiers par message. Les fichiers téléversés sont conservés dans l'historique de conversation en mémoire, ce qui permet aux questions de suivi comme « qu'y a-t-il en bas à gauche de l'image ? » de fonctionner sans nouveau téléversement. Ils sont perdus au redémarrage du pod.

Change DetectionDétection de changements

The chatbot can compare two time periods over an area of interest (AOI) and tell you what changed — either as a numerical analysis backed by real pixel statistics, or as a visual change-detection map. Just say what kind of change you want to see and which two years; it picks the right path automatically.

Le chatbot peut comparer deux périodes pour une zone d'intérêt (AOI) et identifier les changements — soit sous forme d'analyse numérique appuyée sur des statistiques de pixels réels, soit sous forme de carte de détection de changements. Indiquez simplement le type de changement et les deux années; le système choisit automatiquement la voie appropriée.

Two output modesDeux modes de sortie

Compute mode (default) — opens the underlying COGs over your AOI and runs zonal statistics. Returns numbers (mean values, percentage changes) plus clickable source links so you can verify the underlying data. Triggered by phrases like "compare X between 2022 and 2024", "how much did X change?", or "did vegetation decline?".

Visual mode — overlays the NRCan Planaura cosine-similarity change map on the map. Coverage: Montreal/Quebec only, 2020–2025, spring/summer, consecutive 1-year pairs. Triggered by "show me the change map", "visualize the change", or "Planaura". If the AOI/years fall outside Planaura's coverage, the system silently falls back to compute mode.

Mode calcul (par défaut) — ouvre les COGs sous-jacents sur votre AOI et calcule les statistiques zonales. Retourne des valeurs numériques (moyennes, variations en pourcentage) et des liens cliquables vers les sources pour permettre la vérification. Déclenché par des phrases comme « compare X entre 2022 et 2024 », « de combien X a-t-il changé ? », ou « la végétation a-t-elle décliné ? ».

Mode visuel — superpose la carte de similarité cosinus du modèle Planaura de RNCan sur la carte. Couverture : Montréal/Québec uniquement, 2020–2025, printemps/été, paires d'années consécutives. Déclenché par « montre la carte des changements », « visualise », ou « Planaura ». Si l'AOI/années ne sont pas couvertes, le système bascule silencieusement en mode calcul.

Compute capabilities (8 operations)Capacités de calcul (8 opérations)

Example queriesExemples de requêtes

• compare vegetation in Ottawa between 2022 and 2024 → NDVI compute path
• did the area near Fort McMurray burn between 2022 and 2024? → NBR compute path
• did Toronto urbanize between 2018 and 2024? → NDBI compute path
• did water bodies expand near Calgary between 2022 and 2024? → NDWI compute path
• how did leaf area index change in Saskatoon between 2020 and 2023? → LAI compute path
• did fAPAR change in Edmonton between 2020 and 2023? → fAPAR compute path
• how did vegetation cover change in Saskatoon between 2020 and 2023? → fCOVER compute path
• did Lake Erie water quality change between 2023 and 2024? → Lake Erie compute path
• was the Fraser Valley flooded between 2020 and 2021? → NDWI (open-water proxy) compute path
• show me the change detection map for Montreal between 2022 and 2023 → Planaura visual map

• compare la végétation à Ottawa entre 2022 et 2024 → calcul NDVI
• la région de Fort McMurray a-t-elle brûlé entre 2022 et 2024 ? → calcul NBR
• Toronto s'est-il urbanisé entre 2018 et 2024 ? → calcul NDBI
• les plans d'eau près de Calgary se sont-ils étendus entre 2022 et 2024 ? → calcul NDWI
• comment l'indice de surface foliaire a-t-il changé à Saskatoon entre 2020 et 2023 ? → calcul LAI
• fAPAR a-t-il changé à Edmonton entre 2020 et 2023 ? → calcul fAPAR
• comment le couvert végétal a-t-il changé à Saskatoon entre 2020 et 2023 ? → calcul fCOVER
• la qualité de l'eau du lac Érié a-t-elle changé entre 2023 et 2024 ? → calcul lac Érié
• la vallée du Fraser a-t-elle été inondée entre 2020 et 2021 ? → calcul NDWI (approximation eau libre)
• montre la carte de détection de changements pour Montréal entre 2022 et 2023 → carte visuelle Planaura

Source attribution and honestyAttribution des sources et honnêteté

Every compute response embeds two clickable links to the underlying STAC items used in the comparison. These are not estimates — they come from real pixel reads via rio-tiler with HTTP range requests. If no comparable scene pair exists for your AOI/years, the chatbot tells you plainly rather than fabricating numbers. End-to-end latency is typically 15–30 seconds.

Chaque réponse en mode calcul intègre deux liens cliquables vers les éléments STAC sous-jacents utilisés dans la comparaison. Ce ne sont pas des estimations — elles proviennent de lectures de pixels réels via rio-tiler avec des requêtes HTTP par plages d'octets. Si aucune paire de scènes comparable n'existe pour votre AOI/années, le chatbot le dit clairement plutôt que de fabriquer des chiffres. La latence de bout en bout est généralement de 15 à 30 secondes.

Available Data CollectionsCollections de données disponibles

Digital Earth Canada (DEC)

EODMS (NRCan)

UK EO DataHub

Copernicus Data Space

Government of Canada Datacube

Adding a New STAC CatalogueAjouter un nouveau catalogue STAC

The chatbot supports any standard STAC 1.0.0 catalogue with a /search endpoint. Adding a new catalogue requires no code changes — set one environment variable and redeploy. Images will work automatically as long as the catalogue's items have a thumbnail asset with a public HTTPS URL.

Le chatbot prend en charge tout catalogue STAC 1.0.0 standard disposant d'un point de terminaison /search. L'ajout d'un nouveau catalogue ne nécessite aucune modification du code — définissez une variable d'environnement et redéployez. Les images fonctionneront automatiquement si les éléments du catalogue ont un actif thumbnail avec une URL HTTPS publique.

Step 1 — Set the env varÉtape 1 — Définir la variable d'environnement

Run this command, replacing the values with your catalogue's details:

Exécutez cette commande en remplaçant les valeurs par les détails de votre catalogue :

kubectl -n dec-chatbot-dev set env deployment/chat-backend \
  EXTRA_STAC_CATALOGUES='[
    {
      "name":        "my_catalogue",
      "url":         "https://example.com/stac/search",
      "label":       "My Catalogue",
      "description": "Brief description of the data",
      "browse_url":  "https://example.com/stac/collections/{collection}/items/{id}"
    }
  ]'

To add multiple catalogues, include more objects in the JSON array.

Pour ajouter plusieurs catalogues, incluez d'autres objets dans le tableau JSON.

Step 2 — Restart the podÉtape 2 — Redémarrer le pod

kubectl -n dec-chatbot-dev rollout restart deployment/chat-backend

Step 3 — Update the AI prompt (recommended)Étape 3 — Mettre à jour l'invite du modèle (recommandé)

The catalogue will be searched automatically for broad queries ("all" mode), but the AI won't know its collection IDs by name. For the best results, add the catalogue's known collection IDs to the _LITE_SYSTEM prompt in bedrock_client.py under a new "Known <CatalogueName> collection IDs" block, then redeploy the backend.

Le catalogue sera interrogé automatiquement pour les requêtes générales (mode « all »), mais le modèle ne connaîtra pas ses identifiants de collection par nom. Pour de meilleurs résultats, ajoutez les identifiants de collection connus du catalogue dans l'invite _LITE_SYSTEM de bedrock_client.py sous un nouveau bloc « Known <NomDuCatalogue> collection IDs », puis redéployez le serveur.

Verify it's connectedVérifier la connexion

After restart, check the pod logs for confirmation:

Après le redémarrage, vérifiez les journaux du pod pour confirmer :

kubectl -n dec-chatbot-dev logs -l app=chat-backend --tail=20 | grep -i "registered\|catalogue"

You should see a line like: Registered catalogues: ['dec', 'eodms', ..., 'my_catalogue']

Vous devriez voir une ligne comme : Registered catalogues: ['dec', 'eodms', ..., 'my_catalogue']

Updating the ChatbotMise à jour du chatbot

Backend logic lives in four Python files mounted via ConfigMap. No Docker image rebuild is needed for code changes — just update the ConfigMap and restart the deployment.

La logique du serveur réside dans quatre fichiers Python montés via ConfigMap. Aucune reconstruction de l'image Docker n'est nécessaire pour les modifications de code — il suffit de mettre à jour le ConfigMap et de redémarrer le déploiement.

Update backend Python filesMettre à jour les fichiers Python du serveur

kubectl -n dec-chatbot-dev create configmap chat-backend-app \
  --from-file=bedrock_client.py=/c/Users/lwang/bedrock_client.py \
  --from-file=data_access.py=/c/Users/lwang/data_access.py \
  --from-file=stac_client.py=/c/Users/lwang/stac_client.py \
  --from-file=server.py=/c/Users/lwang/server.py \
  --dry-run=client -o yaml | kubectl apply -f - && \
kubectl -n dec-chatbot-dev rollout restart deployment/chat-backend

Update frontend HTMLMettre à jour le HTML du client

kubectl -n dec-chatbot-dev create configmap chat-frontend \
  --from-file=index.html=/c/Users/lwang/chat-frontend-index.html \
  --from-file=manual.html=/c/Users/lwang/manual.html \
  --dry-run=client -o yaml | kubectl apply -f - && \
kubectl -n dec-chatbot-dev rollout restart deployment/chat-frontend

Rebuild the Docker image (after pip dependency changes)Reconstruire l'image Docker (après des modifications de dépendances pip)

Only needed if you add or update Python packages. The image is pre-baked (no pip install on startup).

Nécessaire uniquement si vous ajoutez ou mettez à jour des paquets Python. L'image est préconstruite (aucun pip install au démarrage).

aws codebuild start-build \
  --profile "DEC AI" \
  --region ca-central-1 \
  --project-name dec-chatbot-backend-build

Check rollout statusVérifier l'état du déploiement

kubectl -n dec-chatbot-dev rollout status deployment/chat-backend
kubectl -n dec-chatbot-dev rollout status deployment/chat-frontend

View pod logsConsulter les journaux du pod

kubectl -n dec-chatbot-dev logs -l app=chat-backend --tail=100 -f

Run the audit regression testExécuter le test de régression d'audit

Run after every deploy to confirm nothing broke. Baseline: 104 passed, 1 warned, 0 failed.

À exécuter après chaque déploiement pour confirmer que rien n'est cassé. Référence : 104 réussis, 1 avertissement, 0 échec.

POD=$(kubectl -n dec-chatbot-dev get pod -l app=chat-backend \
  -o jsonpath='{.items[0].metadata.name}')
kubectl -n dec-chatbot-dev exec -i "$POD" -- \
  bash -c 'cat > /tmp/audit_test.py' < /c/Users/lwang/audit_test.py
kubectl -n dec-chatbot-dev exec "$POD" -- \
  bash -c 'python3 /tmp/audit_test.py' 2>&1

Updating EODMS CredentialsMise à jour des identifiants EODMS

The EODMS catalogue requires Basic Auth to fetch thumbnail images and search certain collections. Credentials are stored as a Kubernetes Secret and injected into the pod as environment variables (EODMS_USERNAME and EODMS_PASSWORD).

Le catalogue EODMS requiert une authentification Basic Auth pour récupérer les vignettes et rechercher certaines collections. Les identifiants sont stockés comme un Secret Kubernetes et injectés dans le pod sous forme de variables d'environnement (EODMS_USERNAME et EODMS_PASSWORD).

Step 1 — Update the Kubernetes SecretÉtape 1 — Mettre à jour le Secret Kubernetes

kubectl -n dec-chatbot-dev create secret generic eodms-credentials \
  --from-literal=username=YOUR_EODMS_USERNAME \
  --from-literal=password=YOUR_NEW_PASSWORD \
  --dry-run=client -o yaml | kubectl apply -f -

Step 2 — Restart the backend pod to pick up the new secretÉtape 2 — Redémarrer le pod serveur pour prendre en compte le nouveau secret

kubectl -n dec-chatbot-dev rollout restart deployment/chat-backend

Step 3 — VerifyÉtape 3 — Vérifier

POD=$(kubectl -n dec-chatbot-dev get pod -l app=chat-backend \
  -o jsonpath='{.items[0].metadata.name}')
kubectl -n dec-chatbot-dev exec "$POD" -- \
  bash -c 'echo "user=$EODMS_USERNAME pass=${EODMS_PASSWORD:0:3}***"'

Current EODMS accountCompte EODMS actuel

The EODMS account used is a shared service account managed by the CSA DEC AI team. For account issues or password resets, contact NRCan EODMS support.

Le compte EODMS utilisé est un compte de service partagé géré par l'équipe IA DEC de l'ASC. Pour les problèmes de compte ou les réinitialisations de mot de passe, contactez le soutien EODMS de RNCan.

AI Model ConfigurationConfiguration du modèle d'IA

The synthesizer model is set by the SYNTHESIZER constant at the top of bedrock_client.py. To switch models, update this line and redeploy.

Le modèle synthétiseur est défini par la constante SYNTHESIZER en haut de bedrock_client.py. Pour changer de modèle, modifiez cette ligne et redéployez.

# In bedrock_client.py — line ~55
SYNTHESIZER = "us.anthropic.claude-sonnet-4-6"   # current

TroubleshootingDépannage

Images not displaying (broken image icon)Images non affichées (icône d'image brisée)

• Check /proxy/image?url=<encoded-url> directly — should return 200 with image/png or image/jpeg.
• If EODMS thumbnails are broken, EODMS credentials may have expired — see Updating EODMS Credentials.
• Run the audit test: Section 4 (Image Proxy) tests every preview URL.

• Vérifiez /proxy/image?url=<url-encodée> directement — doit retourner 200 avec image/png ou image/jpeg.
• Si les vignettes EODMS sont brisées, les identifiants EODMS ont peut-être expiré — voir Mise à jour des identifiants EODMS.
• Exécutez le test d'audit : la Section 4 (Proxy d'images) teste toutes les URL d'aperçu.

Chatbot returns "no data found" for queries that should have resultsLe chatbot retourne « aucune donnée trouvée » pour des requêtes qui devraient avoir des résultats

• Check DEC STAC connectivity: curl "https://resource-catalogue.dec.alpha.canada.ca/stac/search?limit=1"
• Check EODMS connectivity: requires Basic Auth, test with the audit script Section 2.
• The bbox may be wrong — Nova Lite occasionally extracts incorrect coordinates. Check the pod logs for the parsed intent JSON.

• Vérifiez la connectivité DEC STAC : curl "https://resource-catalogue.dec.alpha.canada.ca/stac/search?limit=1"
• Vérifiez la connectivité EODMS : nécessite Basic Auth, testez avec la Section 2 du script d'audit.
• La bbox est peut-être incorrecte — Nova Lite extrait parfois des coordonnées erronées. Consultez les journaux du pod pour le JSON d'intention analysé.

Pod logs show Bedrock errorsLes journaux du pod affichent des erreurs Bedrock

• AccessDeniedException: private marketplace — primary model is marketplace-blocked; fallback should activate automatically.
• ValidationException: invalid model identifier — model ID is wrong or not available in this region. Check the Model Configuration section.
• ThrottlingException — request rate too high; Bedrock will retry automatically via the SDK.

• AccessDeniedException: private marketplace — le modèle principal est bloqué par la place de marché ; le secours doit s'activer automatiquement.
• ValidationException: invalid model identifier — l'identifiant du modèle est incorrect ou non disponible dans cette région. Consultez la section Configuration du modèle d'IA.
• ThrottlingException — taux de requêtes trop élevé ; Bedrock réessaiera automatiquement via le SDK.

Health checkVérification de l'état

curl https://dec-chat-dev.csadecai.com/health

Expected response: {"status":"ok","model":"Claude Sonnet 4.6 (DEC)"}

Réponse attendue : {"status":"ok","model":"Claude Sonnet 4.6 (DEC)"}

Pod is stuck / not respondingLe pod est bloqué / ne répond pas

# Force restart
kubectl -n dec-chatbot-dev rollout restart deployment/chat-backend

# Check pod status
kubectl -n dec-chatbot-dev get pods -l app=chat-backend

# Tail logs
kubectl -n dec-chatbot-dev logs -l app=chat-backend --tail=200 -f

Developer Handover ReferenceRéférence de passation aux développeurs

This section captures institutional knowledge for a developer or administrator taking over maintenance of the platform — things that are not obvious from reading the code alone.

Cette section capture les connaissances institutionnelles pour un développeur ou un administrateur prenant en charge la maintenance de la plateforme — des éléments qui ne sont pas évidents à la seule lecture du code.

AWS environmentEnvironnement AWS

Kubernetes cluster accessAccès au cluster Kubernetes

The EKS cluster is devdec-cluster in ca-central-1. All chatbot resources live in the dec-chatbot-dev namespace.

Le cluster EKS est devdec-cluster dans ca-central-1. Toutes les ressources du chatbot se trouvent dans l'espace de noms dec-chatbot-dev.

# Configure kubectl (run once, after SSO login)
aws eks update-kubeconfig \
  --profile "DEC AI" \
  --region ca-central-1 \
  --name devdec-cluster

# Verify access
kubectl -n dec-chatbot-dev get pods

Source files (local working copies)Fichiers sources (copies de travail locales)

All working copies live in C:\Users\lwang\. There is no git repository for the backend Python files — the ConfigMap is the source of truth once deployed. Keep local copies in sync manually.

Toutes les copies de travail se trouvent dans C:\Users\lwang\. Il n'y a pas de dépôt git pour les fichiers Python du serveur — le ConfigMap est la source de vérité une fois déployé. Gardez les copies locales synchronisées manuellement.

Request pipeline (step by step)Pipeline de requêtes (étape par étape)

1. User message arrives at POST /chat/stream (SSE endpoint in server.py). Body: {"message": "...", "conversation_id": "..."}.
2. Nova Lite extracts intent (bedrock_client.py). Returns a JSON object with query_type, collections, bbox (decimal degrees), and datetime (ISO 8601 interval). Known issue: Nova Lite occasionally returns a null bbox or wrong-hemisphere coordinates — bbox validation guards are in place but not foolproof. Check pod logs for the parsed intent JSON when debugging "no results" queries.
3. STAC search runs in parallel against the DEC catalogue (https://resource-catalogue.dec.alpha.canada.ca/stac/search) and EODMS (https://www.eodms-sgdot.nrcan-rncan.gc.ca/api/v1/stac/search). Max 10 results per source, sorted by date descending.
4. DataAccessClient enriches each item (data_access.py). Resolves the best preview URL (checks thumbnail, overview, visual assets in order) and builds an llm_summary dict with key metadata and an embedded image markdown tag pointing at /proxy/image?url=....
5. Claude Sonnet 4.6 synthesizes the final response, receiving all enriched items plus conversation history (last 10 turns). Text tokens are streamed back as SSE (data: {"token": "..."}).
6. map_action event is emitted after the text stream, before {"done": true}:

   data: {"type": "map_action", "url": "<asset href>",
          "bounds": [west, south, east, north],
          "item_id": "...", "collection": "..."}

   The frontend is intended to use this to pan/zoom a map viewer. The event is deployed but the frontend JS handler is not yet wired up.
7. ImageSanitizer in server.py post-processes every response to strip any hallucinated ![...](...) image tags invented by Claude. Only URLs that came from real catalogue assets during the enrichment step are allowed through.

1. Le message de l'utilisateur arrive à POST /chat/stream (point de terminaison SSE dans server.py). Corps : {"message": "...", "conversation_id": "..."}.
2. Nova Lite extrait l'intention (bedrock_client.py). Retourne un objet JSON avec query_type, collections, bbox (degrés décimaux) et datetime (intervalle ISO 8601). Problème connu : Nova Lite retourne parfois une bbox nulle ou des coordonnées dans le mauvais hémisphère — des gardes de validation bbox sont en place mais ne sont pas infaillibles. Consultez les journaux du pod pour le JSON d'intention analysé lors du débogage des requêtes « aucun résultat ».
3. La recherche STAC s'exécute en parallèle sur le catalogue DEC (https://resource-catalogue.dec.alpha.canada.ca/stac/search) et EODMS (https://www.eodms-sgdot.nrcan-rncan.gc.ca/api/v1/stac/search). Maximum 10 résultats par source, triés par date décroissante.
4. DataAccessClient enrichit chaque élément (data_access.py). Résout la meilleure URL d'aperçu (vérifie les assets thumbnail, overview, visual dans l'ordre) et construit un dict llm_summary avec les métadonnées clés et une balise markdown d'image intégrée pointant vers /proxy/image?url=....
5. Claude Sonnet 4.6 synthétise la réponse finale, recevant tous les éléments enrichis plus l'historique de conversation (10 derniers échanges). Les tokens de texte sont diffusés en SSE (data: {"token": "..."}).
6. L'événement map_action est émis après le flux de texte, avant {"done": true} :

   data: {"type": "map_action", "url": "<asset href>",
          "bounds": [west, south, east, north],
          "item_id": "...", "collection": "..."}

   Le client est censé utiliser ceci pour déplacer/zoomer un visualiseur de carte. L'événement est déployé mais le gestionnaire JS du client n'est pas encore câblé.
7. ImageSanitizer dans server.py post-traite chaque réponse pour supprimer toute balise d'image ![...](...) hallucinée inventée par Claude. Seules les URL provenant de vrais assets du catalogue lors de l'étape d'enrichissement sont autorisées.

Image proxy (/proxy/image)Proxy d'images (/proxy/image)

Fetches the upstream image URL (with EODMS Basic Auth if needed), detects format via magic bytes, and converts GeoTIFFs to 800×800 PNG using tifffile + numpy + Pillow. HTML responses (e.g. login redirects returned as 200) are detected and rejected.

Récupère l'URL d'image en amont (avec Basic Auth EODMS si nécessaire), détecte le format via les octets magiques et convertit les GeoTIFF en PNG 800×800 à l'aide de tifffile + numpy + Pillow. Les réponses HTML (ex. redirections de connexion retournées comme 200) sont détectées et rejetées.

Blocked domains: Some image hosts require session cookies or redirect to login pages and cannot be proxied. If a new collection's thumbnails are broken, check the pod logs for the raw upstream response — the domain may need to be added to the blocked list in server.py.

Domaines bloqués : Certains hôtes d'images nécessitent des cookies de session ou redirigent vers des pages de connexion et ne peuvent pas être proxifiés. Si les vignettes d'une nouvelle collection sont brisées, consultez les journaux du pod pour la réponse brute en amont — le domaine devra peut-être être ajouté à la liste bloquée dans server.py.

Performance note: The proxy downloads the full GeoTIFF before converting. For large COG files this can be slow. A future improvement is to use HTTP range requests for overview tiles only.

Note de performance : Le proxy télécharge le GeoTIFF complet avant de le convertir. Pour les grands fichiers COG, cela peut être lent. Une amélioration future consiste à utiliser des requêtes HTTP range pour les tuiles d'aperçu uniquement.

Speech-to-text (STT)Reconnaissance vocale (STT)

Voice input is handled by a separate AWS Lambda accessed via API Gateway. The frontend POSTs audio to /stt on the backend, which proxies it to the Lambda. The Lambda is managed separately from the Kubernetes deployment.

La saisie vocale est gérée par une fonction AWS Lambda distincte accessible via API Gateway. Le client envoie l'audio en POST à /stt sur le serveur, qui le proxifie vers la Lambda. La Lambda est gérée séparément du déploiement Kubernetes.

STT Lambda: https://lyrtolu416.execute-api.ca-central-1.amazonaws.com/stt

Docker imageImage Docker

The image is pre-baked — all Python dependencies are installed at build time, not on startup. The Python application files are not baked into the image; they are mounted from the ConfigMap at runtime. This means code changes only require a ConfigMap update + rollout restart, not an image rebuild. Only rebuild when adding or changing Python package dependencies.

L'image est préconstruite — toutes les dépendances Python sont installées au moment de la construction, pas au démarrage. Les fichiers de l'application Python ne sont pas intégrés dans l'image ; ils sont montés depuis le ConfigMap à l'exécution. Cela signifie que les modifications de code nécessitent uniquement une mise à jour du ConfigMap + un redémarrage du déploiement, pas une reconstruction de l'image. Ne reconstruisez que lors de l'ajout ou de la modification de dépendances de paquets Python.

Conversation memoryMémoire de conversation

History is stored in an in-memory Python dict keyed by conversation_id, capped at 10 turns. Memory is lost when the pod restarts — any deployment or pod crash resets all active conversations. A DynamoDB-backed persistence layer is the planned solution but has not been implemented yet.

L'historique est stocké dans un dict Python en mémoire, indexé par conversation_id, limité à 10 échanges. La mémoire est perdue lors du redémarrage du pod — tout déploiement ou crash du pod réinitialise toutes les conversations actives. Une couche de persistance DynamoDB est la solution prévue mais n'a pas encore été mise en œuvre.

AuthenticationAuthentification

The API is currently completely open — there is no authentication on /chat/stream or /stt. Anyone who knows the URL can use it. Adding an API key header check is the minimum recommended step before broader rollout.

L'API est actuellement complètement ouverte — il n'y a pas d'authentification sur /chat/stream ou /stt. Quiconque connaît l'URL peut l'utiliser. L'ajout d'une vérification d'en-tête de clé API est l'étape minimale recommandée avant un déploiement plus large.

CostingCoûts

The chatbot's running costs are split between AWS Bedrock inference (the dominant cost) and shared infrastructure on the devdec-cluster EKS cluster. Prices are in USD and reflect AWS ca-central-1 / us-east-1 on-demand rates as of early 2026 — verify current rates on the Amazon Bedrock pricing page.

Les coûts d'exploitation du chatbot se répartissent entre l'inférence AWS Bedrock (poste de dépense dominant) et l'infrastructure partagée sur le cluster EKS devdec-cluster. Les prix sont en USD et reflètent les tarifs à la demande AWS ca-central-1 / us-east-1 du début 2026 — vérifiez les tarifs actuels sur la page de tarification Amazon Bedrock.

Bedrock model ratesTarifs des modèles Bedrock

Cost per queryCoût par requête

Each user query triggers two Bedrock calls. The synthesizer call is the dominant cost — it receives the full STAC search results (up to 50 items) as context, so token counts vary with result set size.

Chaque requête utilisateur déclenche deux appels Bedrock. L'appel du synthétiseur est le poste dominant — il reçoit les résultats complets de la recherche STAC (jusqu'à 50 éléments) en contexte, donc le nombre de tokens varie selon la taille des résultats.

Monthly Bedrock cost estimatesEstimations mensuelles des coûts Bedrock

Other infrastructure costsAutres coûts d'infrastructure

Contacts