Upload 6 files

Dockerfile

@@ -4,29 +4,77 @@ FROM rocker/geospatial:4.4
 
 # DuckDB lives on the edgarodriguez/depth_alpha dataset (public); baked in at
 # build. Override with: docker build --build-arg DDB_URL=... -t depth-hf .
-# If the dataset is ever made PRIVATE, add a build secret instead of an ARG:
-#   RUN --mount=type=secret,id=hf_token curl -H "Authorization: Bearer \
-#       $(cat /run/secrets/hf_token)" -fL "${DDB_URL}" -o /app/depth_mexico.duckdb
 ARG DDB_URL=https://huggingface.co/datasets/edgarodriguez/depth_alpha/resolve/main/depth_mexico.duckdb
 
+# RAG index (corpus chunk text + local embeddings) for the AI assistant. The
+# corpus is copyright-derived, so it lives on a PRIVATE dataset and is pulled
+# with a BuildKit secret (id=hf_token) -- never from a public source. If the
+# secret/dataset are absent the build still succeeds; the assistant just stays
+# offline until rag_chunks.parquet is present.
+ARG RAG_URL=https://huggingface.co/datasets/edgarodriguez/depth_rag/resolve/main/rag_chunks.parquet
+
+# Small local models served in-container by Ollama (no external inference).
+ARG CHAT_MODEL=qwen2.5:3b
+ARG EMBED_MODEL=nomic-embed-text
+
+ENV OLLAMA_MODELS=/app/.ollama \
+    DEPTH_OLLAMA_URL=http://127.0.0.1:11434 \
+    DEPTH_LLM_MODEL=${CHAT_MODEL} \
+    DEPTH_EMBED_MODEL=${EMBED_MODEL} \
+    DEPTH_RAG_PARQUET=/app/rag_chunks.parquet
+
+# R packages. Adds ellmer (chat + tool calling), shinychat (streaming chat UI)
+# and arrow (read the embeddings Parquet) on top of the map's deps.
 RUN install2.r --error --skipinstalled --ncpus 4 \
       shiny bslib DBI duckdb dplyr jsonlite htmltools glue writexl ggplot2 stringr httr2 \
+      ellmer shinychat arrow \
  && R -e "install.packages('mapgl', repos = c('https://walkerke.r-universe.dev', 'https://cloud.r-project.org'))" \
- && R -e "library(mapgl); library(duckdb); library(sf); library(shiny); library(httr2)"
+ && R -e "library(mapgl); library(duckdb); library(sf); library(shiny); library(httr2); library(ellmer); library(shinychat)"
+
+# Ollama runtime + bake the chat and embedding models into the image so the
+# first request needs no network (HF runtime is effectively offline). This adds
+# ~2.3GB to the image and a few minutes to the build.
+RUN curl -fsSL https://ollama.com/install.sh | sh \
+ && mkdir -p "$OLLAMA_MODELS" \
+ && ( ollama serve & srv=$!; \
+      for i in $(seq 1 30); do curl -sf http://127.0.0.1:11434/api/tags >/dev/null 2>&1 && break; sleep 1; done; \
+      ollama pull "${CHAT_MODEL}" && ollama pull "${EMBED_MODEL}"; \
+      kill $srv ) \
+ && chmod -R a+rwX "$OLLAMA_MODELS"
 
 WORKDIR /app
-COPY depth_interactive_map_alpha.R helpers.R styles.css ./
 
-# Bake the DuckDB into the image (build-time download).
+# Pre-bake the DuckDB vss extension under the runtime HOME (/app) so the
+# assistant's vector search works offline; the code falls back to core
+# list_cosine_distance if it is ever missing.
+RUN HOME=/app R -e "library(duckdb); con <- dbConnect(duckdb()); DBI::dbExecute(con, 'INSTALL vss; LOAD vss;'); DBI::dbDisconnect(con, shutdown=TRUE); cat('vss installed\n')"
+
+COPY depth_interactive_map_alpha.R assistant.R helpers.R styles.css entrypoint.sh ./
+
+# Bake the DuckDB map data (public dataset, build-time download).
 RUN curl -fL "${DDB_URL}" -o /app/depth_mexico.duckdb \
  && test -s /app/depth_mexico.duckdb \
  && ls -lh /app/depth_mexico.duckdb
 
-# HF Spaces runs the container as a non-root user -- make /app world-readable.
-RUN chmod -R a+rX /app
+# Bake the private RAG index (best-effort; never fails the build).
+RUN --mount=type=secret,id=hf_token \
+    if [ -f /run/secrets/hf_token ]; then \
+      ( curl -fL -H "Authorization: Bearer $(cat /run/secrets/hf_token)" "${RAG_URL}" -o /app/rag_chunks.parquet \
+        && test -s /app/rag_chunks.parquet \
+        && echo "[build] RAG index baked: $(ls -lh /app/rag_chunks.parquet | awk '{print $5}')" ) \
+      || echo "[build] RAG fetch failed -> assistant offline until rag_chunks.parquet is provided"; \
+    else \
+      echo "[build] no hf_token secret -> assistant offline until rag_chunks.parquet is provided"; \
+    fi
+
+# HF Spaces runs the container as a non-root user -- make /app world-readable,
+# and the Ollama dir world-writable (runtime key generation + model cache).
+RUN chmod +x /app/entrypoint.sh \
+ && chmod -R a+rX /app \
+ && chmod -R a+rwX /app/.ollama
 
 ENV DEPTH_DDB_PATH=/app/depth_mexico.duckdb \
     PORT=7860
 
 EXPOSE 7860
-CMD ["Rscript", "depth_interactive_map_alpha.R"]
+ENTRYPOINT ["/app/entrypoint.sh"]

README.md

@@ -1,17 +1,18 @@
 ---
-title: DEPTH. Transit Migrant Risk Index
-emoji: 🌍
-colorFrom: gray
-colorTo: blue
+title: DEPTH Risk Map
+emoji: 🗺️
+colorFrom: blue
+colorTo: indigo
 sdk: docker
 app_port: 7860
 pinned: false
-short_description: Prototype for spatial visualization tool for DEPTH projec
 ---
 
 # DEPTH Risk Map
 
-Interactive migration-risk map for Mexico (for prototype use only. data may contain errors)
+Interactive migration-risk map for Mexico, developed by the University of
+Nottingham's Rights Lab. Humanitarian, violence and infrastructure indicators
+overlaid on a rHEALPix hierarchical spatial grid.
 
 ## How this Space works
 
@@ -19,21 +20,46 @@ Interactive migration-risk map for Mexico (for prototype use only. data may cont
   packages, and downloads `depth_mexico.duckdb` from the
   [`edgarodriguez/depth_alpha`](https://huggingface.co/datasets/edgarodriguez/depth_alpha)
   dataset at build time (baked into the image).
-- The Shiny app (`.R`) opens that DuckDB
-  read-only and serves on `0.0.0.0:7860`.
+- The Shiny app (`depth_interactive_map_alpha.R`) opens that DuckDB read-only
+  and serves on `0.0.0.0:7860`.
+- A local AI assistant runs **entirely inside the container**: Ollama serves a
+  small model (`qwen2.5:3b` + `nomic-embed-text`), baked into the image. The app
+  answers questions grounded in the research corpus (RAG over a DuckDB vector
+  search) and the live map data (a few read-only tools). No prompt, document or
+  database row ever leaves the Space. `entrypoint.sh` starts Ollama, then Rscript.
+
+## AI assistant setup
+
+The assistant needs a private RAG index (`rag_chunks.parquet`, corpus chunk
+text + local embeddings). Because the corpus is copyright-derived it is **not**
+in this Space and **not** on the public dataset:
+
+1. Build the index locally: `Rscript R/94_build_rag_embeddings.R` (with Ollama
+   running and `nomic-embed-text` pulled).
+2. Upload `rag_chunks.parquet` to a **private** HF dataset (e.g.
+   `edgarodriguez/depth_rag`).
+3. Add a Space **secret** named `hf_token` (a token that can read that dataset).
+   The Dockerfile pulls the index with `--mount=type=secret,id=hf_token`.
+
+If the secret/dataset are absent the image still builds; the assistant simply
+shows an "offline" state until `rag_chunks.parquet` is present. On the free
+CPU Space, replies take ~10-40s -- upgrade to a GPU Space for speed.
 
 ## Files
 
 | File | Role |
 |---|---|
-| `.R` | Shiny app (HF build) |
+| `depth_interactive_map_alpha.R` | Shiny app (HF build of v9) |
+| `assistant.R` | Local AI assistant: RAG search, system prompt, read-only tools |
 | `helpers.R` | DuckDB connection + formatting helpers |
 | `styles.css` | App stylesheet |
-| `Dockerfile` | Image build + DuckDB bake-in |
+| `entrypoint.sh` | Starts Ollama, then the Shiny app |
+| `Dockerfile` | Image build + DuckDB/RAG/model bake-in |
 
 ## Updating
 
 The app database is not stored in this Space. To refresh data, update
 `depth_mexico.duckdb` in the `edgarodriguez/depth_alpha` dataset and rebuild
-(Factory rebuild). App-logic changes are made upstream in `v9`, then this file
-is regenerated from it.
+(Factory rebuild). To refresh the assistant's corpus, rebuild
+`rag_chunks.parquet` and re-upload it to the private dataset. App-logic changes
+are made upstream in `v9`, then this file is regenerated from it.

assistant.R

@@ -0,0 +1,343 @@
+# --- Local AI assistant for the DEPTH map ------------------------------------
+# Fully in-container: an Ollama-served small LLM (Qwen2.5) answers questions
+# grounded in (a) the docs/md research corpus via local-embedding RAG over a
+# DuckDB vector search, and (b) the live map data via a few constrained,
+# read-only tools (ellmer tool calling). Nothing leaves the container.
+#
+# Sourced into the app's global env AFTER helpers.R and WEB_SPEC are defined.
+# Defines functions only -- no side effects, no hard ellmer/shinychat import --
+# so the app still runs when the AI stack is absent (panel shows a disabled
+# state via assistant_available()).
+# -----------------------------------------------------------------------------
+
+`%||%` <- function(x, y) if (is.null(x) || length(x) == 0) y else x
+
+# --- Config -------------------------------------------------------------------
+assistant_config <- function() {
+  rag_default <- if (file.exists("/app/rag_chunks.parquet")) {
+    "/app/rag_chunks.parquet"
+  } else {
+    "data/export/web/rag_chunks.parquet"
+  }
+  list(
+    host        = Sys.getenv("DEPTH_OLLAMA_URL", "http://127.0.0.1:11434"),
+    chat_model  = Sys.getenv("DEPTH_LLM_MODEL",  "qwen2.5:3b"),
+    embed_model = Sys.getenv("DEPTH_EMBED_MODEL", "nomic-embed-text"),
+    rag_path    = Sys.getenv("DEPTH_RAG_PARQUET", rag_default)
+  )
+}
+
+# TRUE only when every piece is present: both packages, the baked index, and a
+# reachable Ollama server. Used to gate the UI and the server wiring.
+assistant_available <- function(cfg = assistant_config()) {
+  if (!requireNamespace("ellmer", quietly = TRUE))    return(FALSE)
+  if (!requireNamespace("shinychat", quietly = TRUE)) return(FALSE)
+  if (!file.exists(cfg$rag_path))                     return(FALSE)
+  ok <- tryCatch(
+    httr2::request(cfg$host) |>
+      httr2::req_url_path("/api/tags") |>
+      httr2::req_timeout(3) |>
+      httr2::req_perform() |>
+      httr2::resp_status(),
+    error = function(e) NA_integer_
+  )
+  isTRUE(ok == 200L)
+}
+
+# --- Embedding + retrieval ----------------------------------------------------
+ollama_embed <- function(text, cfg = assistant_config()) {
+  resp <- tryCatch(
+    httr2::request(cfg$host) |>
+      httr2::req_url_path("/api/embed") |>
+      httr2::req_body_json(list(model = cfg$embed_model, input = text)) |>
+      httr2::req_timeout(120) |>
+      httr2::req_perform(),
+    error = function(e) NULL
+  )
+  if (is.null(resp)) return(numeric(0))
+  out <- httr2::resp_body_json(resp, simplifyVector = FALSE)
+  if (is.null(out$embeddings) || length(out$embeddings) == 0) return(numeric(0))
+  as.numeric(unlist(out$embeddings[[1]]))
+}
+
+# Decide once whether the vss extension (array_cosine_distance) is available;
+# fall back to DuckDB's core list_cosine_distance otherwise. Both are exact
+# brute-force cosine -- fine for a few thousand chunks.
+.assist_cache <- new.env(parent = emptyenv())
+
+.rag_dist_clause <- function(con, vec_lit, d) {
+  mode <- .assist_cache$dist_mode
+  if (is.null(mode)) {
+    ok <- tryCatch({
+      DBI::dbExecute(con, "INSTALL vss; LOAD vss;")
+      DBI::dbGetQuery(con,
+        "SELECT array_cosine_distance(CAST([1.0,2.0] AS FLOAT[2]), CAST([1.0,2.0] AS FLOAT[2])) AS d")
+      TRUE
+    }, error = function(e) FALSE)
+    mode <- if (isTRUE(ok)) "vss" else "list"
+    .assist_cache$dist_mode <- mode
+    message("[assist] vector search mode: ", mode)
+  }
+  if (mode == "vss") {
+    glue::glue("array_cosine_distance(CAST(embedding AS FLOAT[{d}]), CAST({vec_lit} AS FLOAT[{d}]))")
+  } else {
+    glue::glue("list_cosine_distance(embedding, CAST({vec_lit} AS DOUBLE[]))")
+  }
+}
+
+# Embed the question (with the nomic query prefix) and return the top-k corpus
+# passages as a single context string with [source] tags for citation.
+rag_search <- function(con, query, cfg = assistant_config(), k = 5) {
+  if (is.null(con) || !file.exists(cfg$rag_path)) return("")
+  qvec <- ollama_embed(paste0("search_query: ", query), cfg)
+  if (length(qvec) == 0) return("")
+  vec_lit <- paste0("[", paste(format(qvec, scientific = FALSE, trim = TRUE),
+                               collapse = ","), "]")
+  dist <- .rag_dist_clause(con, vec_lit, length(qvec))
+  sql <- glue::glue(
+    "SELECT source_title, folder, chunk_text, {dist} AS dist
+     FROM read_parquet('{path}')
+     ORDER BY dist ASC
+     LIMIT {k}",
+    path = cfg$rag_path, k = as.integer(k)
+  )
+  res <- tryCatch(DBI::dbGetQuery(con, sql), error = function(e) {
+    message("[assist] rag_search: ", conditionMessage(e)); NULL
+  })
+  if (is.null(res) || nrow(res) == 0) return("")
+  paste(sprintf("[%s] %s", res$source_title, res$chunk_text), collapse = "\n\n")
+}
+
+# --- Grounding text from WEB_SPEC --------------------------------------------
+# Walk the accordion (label + tooltip + source) into a compact data dictionary
+# the model can read. Stays in lockstep with the UI -- no separate codebook.
+assistant_indicator_catalog_txt <- function() {
+  if (!exists("WEB_SPEC")) return("")
+  out <- character(0)
+  for (grp in WEB_SPEC$accordion) {
+    layer_items <- Filter(function(it) identical(it$kind, "layer"), grp$items)
+    if (length(layer_items) == 0) next
+    out <- c(out, paste0("## ", grp$label))
+    for (it in layer_items) {
+      tip  <- it$tooltip
+      body <- if (is.list(tip)) paste(c(tip$body, tip$meta), collapse = " ")
+              else tip %||% ""
+      out <- c(out, sprintf("- %s: %s", it$label, body))
+    }
+  }
+  paste(out, collapse = "\n")
+}
+
+assistant_system_prompt <- function(catalog_txt) {
+  paste0(
+    "You are the research assistant for DEPTH, an interactive map of migration ",
+    "risk in Mexico built by the University of Nottingham Rights Lab. The map ",
+    "overlays humanitarian, violence and infrastructure indicators on a ",
+    "hierarchical grid of Mexico.\n\n",
+    "How to answer:\n",
+    "- For ANY number, ranking, count or aggregation you MUST call a tool. ",
+    "Never invent, estimate or recall figures from memory.\n",
+    "- When the user refers to 'the selection', 'this area', 'the area I drew', ",
+    "'here', or 'visible', call describe_selection first to learn the scope.\n",
+    "- Use the <context> document excerpts supplied with the user's message for ",
+    "background, definitions and qualitative explanation. Cite the document ",
+    "title in square brackets when you rely on it.\n",
+    "- If the data and documents do not cover the question, say so plainly. ",
+    "Do not speculate.\n",
+    "- Reply in the user's language (English or Spanish). Be concise: a few ",
+    "sentences or a short list.\n\n",
+    "Indicators available on the map (label: meaning and source):\n",
+    catalog_txt
+  )
+}
+
+# Prepend retrieved corpus context to the raw question (the UI still shows the
+# raw question; only the model sees the augmented version).
+assistant_user_turn <- function(question, context_txt) {
+  if (is.null(context_txt) || !nzchar(context_txt)) return(question)
+  paste0("<context>\n", context_txt, "\n</context>\n\n", question)
+}
+
+# --- Tool back-ends (operate on a plain snapshot env + read-only con) ---------
+# `state` is a non-reactive environment the server keeps in sync with rv, so
+# tools can be called outside a reactive context during async streaming.
+
+.IND_LABELS <- c(
+  homicidio       = "homicide rate (per 100k)",
+  robo            = "robbery rate (per 100k)",
+  secuestro       = "kidnapping rate (per 100k)",
+  trafico_menores = "child-trafficking rate (per 100k)",
+  trata_personas  = "human-trafficking rate (per 100k)",
+  desap_n         = "disappeared and not located (count)",
+  pam_n           = "irregular-migration (PAM) events (count)"
+)
+.POINT_TO_COUNT <- c(migrants = "n_incidents", graves = "n_graves",
+                     infra = "n_facilities", ocved = "ocved_n", ged = "n_ged")
+
+assistant_selection_summary <- function(state) {
+  cnt <- state$counts %||% list()
+  scope <- if (isTRUE(state$is_national)) {
+    "No specific area is selected; national totals are in view."
+  } else {
+    glue::glue("Current selection: {cnt$n_mun %||% '0'} municipalities.")
+  }
+  glue::glue(
+    "{scope} ",
+    "Migrant-death incidents: {cnt$n_incidents %||% '0'} ",
+    "({cnt$n_fatalities %||% '0'} recorded deaths). ",
+    "Clandestine graves: {cnt$n_graves %||% '0'}. ",
+    "Support facilities: {cnt$n_facilities %||% '0'}. ",
+    "OCVED violence events: {cnt$ocved_n %||% '0'}. ",
+    "GED conflict events: {cnt$n_ged %||% '0'}. ",
+    "Disappeared (sum): {cnt$n_desap %||% '0'}. ",
+    "Irregular-migration (PAM) events: {cnt$n_pam %||% '0'}."
+  )
+}
+
+assistant_count_points <- function(state, layer) {
+  key <- .POINT_TO_COUNT[[layer]]
+  if (is.null(key)) return(paste0("Unknown layer: ", layer))
+  val   <- state$counts[[key]] %||% "0"
+  scope <- if (isTRUE(state$is_national)) "across Mexico" else "in the current selection"
+  extra <- if (identical(layer, "migrants")) {
+    glue::glue(" ({state$counts$n_fatalities %||% '0'} recorded deaths)")
+  } else ""
+  glue::glue("{val} {layer} {scope}{extra}.")
+}
+
+assistant_aggregate <- function(con, state, indicator, statistic = "mean") {
+  if (!indicator %in% names(.IND_LABELS)) return(paste0("Unknown indicator: ", indicator))
+  if (!statistic %in% c("mean", "sum", "max", "min")) statistic <- "mean"
+  lab <- .IND_LABELS[[indicator]]
+
+  # Selection path: aggregate the in-memory municipalities (matches the sidebar).
+  if (!isTRUE(state$is_national) && !is.null(state$mun_df) &&
+      nrow(state$mun_df) > 0 && indicator %in% names(state$mun_df)) {
+    vals <- suppressWarnings(as.numeric(state$mun_df[[indicator]]))
+    vals <- vals[is.finite(vals)]
+    if (length(vals) == 0) return(glue::glue("No {lab} values in the current selection."))
+    res <- switch(statistic, mean = mean(vals), sum = sum(vals),
+                  max = max(vals), min = min(vals))
+    return(glue::glue(
+      "{statistic} of {lab} across {nrow(state$mun_df)} selected municipalities: {round(res, 2)}."))
+  }
+
+  # National path: a single bounded aggregate query (indicator is allow-listed).
+  if (is.null(con)) return("No database connection available.")
+  if (indicator %in% c("desap_n", "pam_n")) {
+    inner_tbl <- if (indicator == "desap_n") "dim_desap_mun" else "dim_pam_mun"
+    inner_col <- if (indicator == "desap_n") "final_desap_nl" else "pam_n"
+    from_clause <- glue::glue("(SELECT CVEGEO, SUM({inner_col}) AS x FROM {inner_tbl} GROUP BY CVEGEO)")
+    col_expr <- "x"
+  } else {
+    from_clause <- "crime_mun"
+    col_expr <- glue::glue("CAST({indicator} AS DOUBLE)")
+  }
+  agg <- switch(statistic,
+    mean = glue::glue("AVG({col_expr})"), sum = glue::glue("SUM({col_expr})"),
+    max  = glue::glue("MAX({col_expr})"), min = glue::glue("MIN({col_expr})"))
+  sql <- glue::glue("SELECT {agg} AS v, COUNT(*) AS n FROM {from_clause}")
+  r <- tryCatch(DBI::dbGetQuery(con, sql), error = function(e) NULL)
+  if (is.null(r) || nrow(r) == 0 || is.na(r$v[1]))
+    return(glue::glue("Could not compute {lab} nationally."))
+  glue::glue("{statistic} of {lab} across all {r$n[1]} municipalities in Mexico: {round(r$v[1], 2)}.")
+}
+
+assistant_top_municipalities <- function(con, state, indicator, n = 5) {
+  if (!indicator %in% names(.IND_LABELS)) return(paste0("Unknown indicator: ", indicator))
+  n   <- max(1L, min(20L, as.integer(n)))
+  lab <- .IND_LABELS[[indicator]]
+
+  # Selection path: rank the in-memory municipalities.
+  if (!isTRUE(state$is_national) && !is.null(state$mun_df) &&
+      nrow(state$mun_df) > 0 && indicator %in% names(state$mun_df)) {
+    d <- state$mun_df
+    d$.v <- suppressWarnings(as.numeric(d[[indicator]]))
+    d <- d[is.finite(d$.v), , drop = FALSE]
+    if (nrow(d) == 0) return(glue::glue("No {lab} data in the current selection."))
+    d <- utils::head(d[order(-d$.v), , drop = FALSE], n)
+    items <- sprintf("%d. %s (%s): %s", seq_len(nrow(d)), d$municipio, d$entidad,
+                     round(d$.v, 2))
+    return(paste0("Top municipalities by ", lab, " (current selection):\n",
+                  paste(items, collapse = "\n")))
+  }
+
+  # National path.
+  if (is.null(con)) return("No database connection available.")
+  if (indicator %in% c("homicidio", "robo", "secuestro", "trafico_menores", "trata_personas")) {
+    sql <- glue::glue(
+      "SELECT municipio, entidad, CAST({indicator} AS DOUBLE) AS v
+       FROM crime_mun WHERE {indicator} IS NOT NULL
+       ORDER BY v DESC NULLS LAST LIMIT {n}")
+  } else {
+    inner_tbl <- if (indicator == "desap_n") "dim_desap_mun" else "dim_pam_mun"
+    inner_col <- if (indicator == "desap_n") "final_desap_nl" else "pam_n"
+    sql <- glue::glue(
+      "SELECT c.municipio, c.entidad, s.v AS v
+       FROM crime_mun c
+       JOIN (SELECT CVEGEO, SUM({inner_col}) AS v FROM {inner_tbl} GROUP BY CVEGEO) s
+         ON c.CVEGEO = s.CVEGEO
+       ORDER BY v DESC NULLS LAST LIMIT {n}")
+  }
+  r <- tryCatch(DBI::dbGetQuery(con, sql), error = function(e) NULL)
+  if (is.null(r) || nrow(r) == 0) return(glue::glue("Could not rank municipalities by {lab}."))
+  items <- sprintf("%d. %s (%s): %s", seq_len(nrow(r)), r$municipio, r$entidad, round(r$v, 2))
+  paste0("Top municipalities by ", lab, " (Mexico):\n", paste(items, collapse = "\n"))
+}
+
+# --- Assemble the per-session chat -------------------------------------------
+# Returns a configured ellmer Chat with the constrained tools registered, or
+# NULL if construction fails (e.g. Ollama dropped). Tools close over `con` and
+# the live `state` snapshot env.
+make_assistant <- function(con, state, cfg = assistant_config()) {
+  chat <- tryCatch(
+    ellmer::chat_ollama(
+      model         = cfg$chat_model,
+      base_url      = cfg$host,
+      system_prompt = assistant_system_prompt(assistant_indicator_catalog_txt()),
+      params        = ellmer::params(temperature = 0.2)
+    ),
+    error = function(e) { message("[assist] chat_ollama: ", conditionMessage(e)); NULL }
+  )
+  if (is.null(chat)) return(NULL)
+
+  ind_enum <- ellmer::type_enum(names(.IND_LABELS), "Indicator column.")
+
+  list_indicators <- function() assistant_indicator_catalog_txt()
+  describe_selection <- function() assistant_selection_summary(state)
+  aggregate_indicator <- function(indicator, statistic = "mean")
+    assistant_aggregate(con, state, indicator, statistic)
+  top_municipalities <- function(indicator, n = 5)
+    assistant_top_municipalities(con, state, indicator, n)
+  count_points <- function(layer) assistant_count_points(state, layer)
+
+  chat$register_tool(ellmer::tool(list_indicators,
+    "List the indicators / data layers available in the DEPTH map, with their meaning and source. Call this when the user asks what data exists."))
+
+  chat$register_tool(ellmer::tool(describe_selection,
+    "Summarise the user's CURRENT map selection (drawn area, clicked municipality or state): how many municipalities and points of each type fall inside, plus key totals. Returns national totals if nothing is selected."))
+
+  chat$register_tool(ellmer::tool(aggregate_indicator,
+    "Aggregate one municipality indicator over the current selection (or nationally if nothing is selected). Use 'mean' for rate indicators and 'sum' for count indicators.",
+    arguments = list(
+      indicator = ind_enum,
+      statistic = ellmer::type_enum(c("mean", "sum", "max", "min"),
+                                    "Aggregation statistic.")
+    )))
+
+  chat$register_tool(ellmer::tool(top_municipalities,
+    "Rank municipalities by an indicator and return the top N (within the current selection if one is active, else nationally).",
+    arguments = list(
+      indicator = ind_enum,
+      n = ellmer::type_integer("How many municipalities to return (1-20).")
+    )))
+
+  chat$register_tool(ellmer::tool(count_points,
+    "Count point features for the current scope: migrant-death incidents, clandestine graves, support facilities, organised-crime violence events (OCVED) or armed-conflict events (GED).",
+    arguments = list(
+      layer = ellmer::type_enum(c("migrants", "graves", "infra", "ocved", "ged"),
+                                "Which point layer to count.")
+    )))
+
+  chat
+}

depth_interactive_map_alpha.R

@@ -51,6 +51,9 @@ library(ggplot2)
 library(httr2)
 
 source("helpers.R")
+# Local AI assistant (Ollama + RAG). Defines functions only; safe to source even
+# when ellmer/shinychat/Ollama are absent -- the panel degrades gracefully.
+source("assistant.R")
 
 `%||%` <- function(x, y) if (is.null(x) || length(x) == 0) y else x
 
@@ -80,6 +83,17 @@ if (requireNamespace("showtext", quietly = TRUE) &&
 # Deployment edit (v10_HF): DuckDB path from env var, baked into the image.
 DB_PATH <- Sys.getenv("DEPTH_DDB_PATH", "/app/depth_mexico.duckdb")
 
+# AI assistant availability, resolved once at startup (skipped in extract mode so
+# the docs converter never pings Ollama). Gates both the UI and the server.
+.ASSIST_CFG <- assistant_config()
+.ASSIST_OK  <- if (isTRUE(getOption("depth.extract_mode", FALSE))) {
+  FALSE
+} else {
+  assistant_available(.ASSIST_CFG)
+}
+message("[assist] available: ", .ASSIST_OK,
+        "  (model=", .ASSIST_CFG$chat_model, ", rag=", .ASSIST_CFG$rag_path, ")")
+
 # --- Colour constants -----------------------------------------------------------
 # Recalibrated for Spatial UI light mode: saturation dropped ~10%, no neon,
 # all foreground/data colours stay AA-distinguishable on the near-white canvas.
@@ -1169,7 +1183,7 @@ WEB_SPEC <- list(
          geom = "polygon", color = "envipe_step", value = "insecurity_perc",
          opacity = 0.6,  visible = FALSE),
     list(id = "routes-lines",    type = "line",   src = "src_routes",
-         geom = "line",    color = "#FFDF9E",      opacity = 0.1, visible = FALSE),
+         geom = "line",    color = "#FCA311",      opacity = 0.1, visible = FALSE),
     list(id = "viaferrea-lines", type = "line",   src = "src_via",
          geom = "line",    color = "#990f0f",      opacity = 0.9,  visible = FALSE,
          dash = c(4, 2)),
@@ -1264,7 +1278,7 @@ WEB_SPEC <- list(
       list(kind = "layer", value = "routes-lines",
            label = "Main migration routes through Mexico",
            tooltip = "Key routes migrants use to travel through Mexico towards the northern border.",
-           legend = list(type = "line", color = COL_AMBER, label = "Potential routes following national roads")),
+           legend = list(type = "line", color = "#FCA311", label = "Potential routes following national roads")),
       list(kind = "layer", value = "viaferrea-lines",
            label = "Railway network",
            tooltip = "Railway lines used by migrants, including freight routes",
@@ -3237,7 +3251,7 @@ ui <- page_fillable(
             tags$span(class = "side-panel-icon",
               HTML('<i data-lucide="sparkles" style="width:18px;height:18px;stroke-width:2" aria-hidden="true"></i>')),
             tags$h2(class = "side-panel-title", "Assistance"),
-            tags$span(class = "side-panel-tag", "Idea"),
+            tags$span(class = "side-panel-tag", if (isTRUE(.ASSIST_OK)) "Local AI" else "Idea"),
             tags$button(class = "side-panel-collapse",
                         type = "button",
                         onclick = "togglePanel('assist')",
@@ -3246,27 +3260,39 @@ ui <- page_fillable(
                         HTML('<i data-lucide="panel-right-close" style="width:16px;height:16px;stroke-width:2" aria-hidden="true"></i>'))
           ),
           div(class = "side-panel-body assist-body",
-            div(class = "assist-card",
-              tags$p(class = "assist-intro",
-                "An exploratory idea -- ", tags$em("may not ship."),
-                " The goal is to let researchers ask short questions about the visible data layers in natural language and get a grounded answer from the underlying DuckDB."
-              ),
-              tags$div(class = "assist-status",
-                HTML('<i data-lucide="flask-conical" style="width:12px;height:12px;stroke-width:2;color:var(--c-text-mid)" aria-hidden="true"></i>'),
-                tags$span("Research preview -- feasibility uncertain")
-              ),
-              tags$div(class = "assist-examples-label", "Example questions you'd ask"),
-              tags$ul(class = "assist-examples",
-                tags$li("Which municipalities in the visible area have the highest homicide rate?"),
-                tags$li("How many migrant shelters fall inside the current selection?"),
-                tags$li("Compare OCVED events over time for the area I drew.")
-              ),
-              tags$div(class = "assist-input-mock", role = "presentation",
-                HTML('<i data-lucide="message-circle" style="width:14px;height:14px;stroke-width:2;color:var(--c-text-dim)" aria-hidden="true"></i>'),
-                tags$span("Ask a question..."),
-                tags$span(class = "assist-soon-tag", "Soon")
+            if (isTRUE(.ASSIST_OK)) {
+              tagList(
+                tags$p(class = "assist-intro",
+                  "Ask about the visible data layers in plain language. Answers are grounded in the project's research corpus and the live database, computed ",
+                  tags$strong("locally on this server"), " -- nothing leaves the container."
+                ),
+                tags$div(class = "assist-examples-label", "Try asking"),
+                tags$ul(class = "assist-examples",
+                  tags$li("Which municipalities in my selection have the highest homicide rate?"),
+                  tags$li("How many migrant shelters fall inside the current selection?"),
+                  tags$li("What does the disappearances indicator measure?")
+                ),
+                shinychat::chat_ui("assist_chat",
+                  placeholder = "Ask a question about the map...",
+                  fill = TRUE)
               )
-            )
+            } else {
+              div(class = "assist-card",
+                tags$p(class = "assist-intro",
+                  "The local AI assistant is offline in this build."
+                ),
+                tags$div(class = "assist-status",
+                  HTML('<i data-lucide="flask-conical" style="width:12px;height:12px;stroke-width:2;color:var(--c-text-mid)" aria-hidden="true"></i>'),
+                  tags$span("Requires the in-container Ollama model and the embeddings index.")
+                ),
+                tags$div(class = "assist-examples-label", "When enabled, you could ask"),
+                tags$ul(class = "assist-examples",
+                  tags$li("Which municipalities in the visible area have the highest homicide rate?"),
+                  tags$li("How many migrant shelters fall inside the current selection?"),
+                  tags$li("What does the disappearances indicator measure?")
+                )
+              )
+            }
           )
         )
       ),
@@ -3853,6 +3879,62 @@ server <- function(input, output, session) {
     )
   }
 
+  # --- AI assistant (local Ollama + RAG + read-only tools) --------------------
+  # Active only when the model, embeddings index and packages are all present
+  # (.ASSIST_OK). Everything runs in-container; no data leaves the server.
+  if (isTRUE(.ASSIST_OK)) {
+    # Plain (non-reactive) snapshot of the current scope, kept in sync with rv so
+    # the ellmer tools can read it during async streaming (outside reactive ctx).
+    assist_state <- new.env(parent = emptyenv())
+    assist_state$is_national <- TRUE
+    assist_state$mun_df      <- NULL
+    assist_state$counts      <- list()
+    observe({
+      assist_state$is_national <- isTRUE(rv$is_national)
+      assist_state$mun_df      <- rv$mun_df
+      assist_state$counts <- list(
+        n_mun        = rv$n_mun,    n_incidents  = rv$n_incidents,
+        n_fatalities = rv$n_fatalities,
+        n_graves     = rv$n_graves, n_facilities = rv$n_facilities,
+        ocved_n      = rv$ocved_n,  n_ged        = rv$n_ged,
+        n_desap      = rv$n_desap,  n_pam        = rv$n_pam,
+        n_fosas      = rv$n_fosas,  n_cuerpos    = rv$n_cuerpos
+      )
+    })
+
+    # One chat per session, built lazily on the first question so a slow model
+    # load never blocks session startup.
+    assist_chat <- NULL
+    get_assist_chat <- function() {
+      if (is.null(assist_chat)) {
+        assist_chat <<- make_assistant(con, assist_state, .ASSIST_CFG)
+      }
+      assist_chat
+    }
+
+    observeEvent(input$assist_chat_user_input, {
+      q <- input$assist_chat_user_input
+      if (is.null(q) || !nzchar(trimws(q))) return()
+      chat <- get_assist_chat()
+      if (is.null(chat)) {
+        shinychat::chat_append("assist_chat",
+          "Sorry -- the local model is unavailable right now.")
+        return()
+      }
+      ctx    <- tryCatch(rag_search(con, q, .ASSIST_CFG, k = 5),
+                         error = function(e) "")
+      prompt <- assistant_user_turn(q, ctx)
+      tryCatch(
+        shinychat::chat_append("assist_chat", chat$stream_async(prompt)),
+        error = function(e) {
+          message("[assist] stream: ", conditionMessage(e))
+          shinychat::chat_append("assist_chat",
+            paste0("Sorry -- I hit an error answering that: ", conditionMessage(e)))
+        }
+      )
+    })
+  }
+
   # Satellite fade-in expression helper
   zoom_fade_in <- function(from_zoom, to_zoom) {
     list("interpolate", list("linear"), list("zoom"), from_zoom, 0, to_zoom, 1)
@@ -4702,16 +4784,16 @@ server <- function(input, output, session) {
   # tile the bottom row. Avoids the treemapify dependency.
   # Re-toned to the muted Spatial data palette so the treemaps speak the same
   # colour language as the map points (no Tailwind-bright sky / red / purple).
-  CAUSE_PAL <- c("Other / unknown"   = "#3A4B5C",   # neutral slate (COL_COUNT)
+  CAUSE_PAL <- c("Other / unknown"   = "#407076",   # neutral slate (COL_COUNT)
                  "Drowning"          = "#1B9AAA",   # teal-blue / water
-                 "Harsh environment" = "#DDDBCB",   # ochre / heat
-                 "Vehicle accident"  = "#F5F1E3",   # mauve
+                 "Harsh environment" = "#B49FCC",   # ochre / heat
+                 "Accident"          = "#92AA83",   # mauve
                  "Violence"          = "#9E2A3A")   # brick red
   # Demographics are nominal (not ordered) and carry no risk valence -- three
   # distinct muted hues, avoiding the pink = female / blue = male cliche.
-  DEMO_PAL  <- c(Children = "#DDDBCB",   # ochre
+  DEMO_PAL  <- c(Children = "#B49FCC",   # ochre
                  Female   = "#1B9AAA",   # mauve
-                 Male     = "#3A4B5C")   # slate
+                 Male     = "#407076")   # slate
 
   # Stacked-bar layout: one horizontal row of segments, widths proportional
   # to value. Returns the same shape as the treemap layout did (xmin/xmax/

entrypoint.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Start the in-container Ollama server, then launch the Shiny app. Both run as
+# the HF non-root user; nothing leaves the container.
+set -euo pipefail
+
+# Deterministic, writable home so Ollama can store its key + model cache.
+export HOME=/app
+export OLLAMA_MODELS="${OLLAMA_MODELS:-/app/.ollama}"
+export OLLAMA_HOST="127.0.0.1:11434"
+
+echo "[entrypoint] starting ollama serve (models in ${OLLAMA_MODELS})..."
+ollama serve &
+
+# Wait for the API to answer (model weights load lazily on first request).
+for i in $(seq 1 60); do
+  if curl -sf "http://${OLLAMA_HOST}/api/tags" >/dev/null 2>&1; then
+    echo "[entrypoint] ollama is up."
+    break
+  fi
+  sleep 1
+done
+
+echo "[entrypoint] launching Shiny app..."
+exec Rscript depth_interactive_map_alpha.R

styles.css

@@ -2025,6 +2025,50 @@ button.mapbox-gl-draw_uncombine { display: none !important; }
   padding: 2px 6px;
 }
 
+/* ---- Local AI assistant chat (shinychat) ---- */
+/* When the live chat is mounted, the body becomes a flex column so the message
+   list scrolls and the input stays pinned at the bottom of the panel. */
+.assist-body:has(shiny-chat-container) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  min-height: 0;
+}
+
+.assist-body shiny-chat-container {
+  flex: 1 1 auto;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  font-family: var(--font-ui);
+}
+
+.assist-body shiny-chat-messages {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  min-height: 120px;
+}
+
+.assist-body shiny-chat-message {
+  font-size: 12.5px;
+  line-height: 1.55;
+  color: var(--c-text);
+}
+
+.assist-body shiny-chat-input textarea {
+  font-family: var(--font-ui);
+  font-size: 12.5px;
+  border-radius: var(--radius-md);
+  border: 1px solid var(--c-glass-stroke-strong);
+  color: var(--c-text);
+}
+
+.assist-body shiny-chat-input button {
+  background: var(--c-accent);
+  border-color: var(--c-accent);
+}
+
 /* ---- MapLibre popup (data layer hover tooltip) ---- */
 .maplibregl-popup-content {
   background: oklch(15% 0.012 250 / 0.94) !important;