chore: Add logo, explain data & methodology

README.md

@@ -9,6 +9,8 @@ app_port: 7860
 
 # Gazet
 
+<img src="assets/gazet-logo.svg" alt="Gazet logo" width="64" />
+
 Lean natural-language geocoder with GIS operations over Overture and Natural Earth parquet datasets.
 
 Gazet  is built to be easily packagable and minimal in setup, trying to push the boundaries on how small we can go in setup for LLM driven data applications. It is built for working with small language models and parquet files.

gazet_demo.py

@@ -4,6 +4,7 @@ import json
 import math
 import os
 import re
+from pathlib import Path
 
 import pandas as pd
 import requests
@@ -182,17 +183,28 @@ def _track(event_name: str, **props):
     )
 
 EXAMPLES = [
-    "Odisha, India",
+    "Goa, India",
     "Neighbouring states of Odisha",
-    "Odisha excluding Cuttack",
-    "Coastal districts of Odisha",
-    "1 km buffer along the border of Odisha and West Bengal",
-    "Western half of Odisha",
-    "Rivers flowing through Odisha",
-    "Districts along the Indravati river",
+    "Karnataka excluding Bengaluru",
+    "Coastal districts of Kerala",
+    "1 km buffer along the border of West Bengal and Odisha",
+    "Northern half of India",
+    "Rivers flowing through Tamil Nadu",
+    "Districts along the Cauvery river",
+    "Largest district of Bihar",
+    "merge Bihar and Jharkhand"
 ]
 
-st.set_page_config(page_title="Gazet", page_icon="🌍", layout="wide")
+LOGO_PATH = str(Path(__file__).parent / "assets" / "gazet-logo.svg")
+DEVSEED_LOGO_PATH = str(Path(__file__).parent / "assets" / "ds-logo-pos.svg")
+
+st.set_page_config(
+    page_title="Gazet",
+    page_icon=LOGO_PATH,
+    layout="wide",
+    initial_sidebar_state="collapsed",
+)
+st.logo(LOGO_PATH, size="large")
 _inject_plausible()
 st.markdown("""<style>
 [data-testid="stBaseButton-tertiary"] {
@@ -212,6 +224,71 @@ st.caption(
     "/ask plain english to geometry"
 )
 
+with st.sidebar:
+    st.header("Learn how this was built")
+    st.markdown(
+        """
+**Gazet** turns plain English questions into geometries on a map.
+
+### Behind the scenes
+
+This demo is powered by a small language model (SLM) finetuned from
+**Qwen3.5 0.8B**. We picked a small model on purpose: it is fast, cheap to
+run, and easy to host. The trade off is that it works best on the kinds of
+questions it was trained for. Wide open queries may not always work, but
+that is also the point of this work.
+
+### Why a small model?
+
+Small models are easy to improve. When the model fails on a new kind of
+question, we can add a few examples, finetune again in a short cycle, and
+ship the fix. The dataset for this demo was generated synthetically from
+templates and grew over time as we added new question patterns. You can
+follow the same approach for your own domain.
+
+### Data sources
+
+The model queries two open geographic datasets:
+
+- [Overture Maps – Divisions Area](https://docs.overturemaps.org/schema/reference/divisions/division_area/)
+  for administrative boundaries (countries, states, districts, localities).
+- [Natural Earth](https://www.naturalearthdata.com/) for physical
+  features such as rivers, lakes, mountain ranges, and coastlines.
+
+### Links
+
+- Dataset:
+  [developmentseed/gazet-dataset](https://huggingface.co/datasets/developmentseed/gazet-dataset)
+- Model:
+  [developmentseed/gazet-model](https://huggingface.co/developmentseed/gazet-model)
+- Hosted Space:
+  [developmentseed/gazet](https://huggingface.co/spaces/developmentseed/gazet)
+- Source code:
+  [developmentseed/gazet](https://github.com/developmentseed/gazet)
+
+### Talk to us
+
+Interested in small models for your own vertical, or want to try this
+approach on a different domain? Reach out:
+
+- Soumya: [soumya@developmentseed.org](mailto:soumya@developmentseed.org)
+- Daniel: [danielwiesmann@developmentseed.org](mailto:danielwiesmann@developmentseed.org)
+
+### Tips for asking good questions
+
+- Use a place name the model is likely to know (countries, states,
+  major districts, well known rivers and lakes).
+- Combine simple operations: union, intersection, difference, buffer,
+  half splits, neighbours.
+- If a query fails, try rephrasing it more concretely or narrow down
+  the search space, for example: "Coastal districts of Odisha" instead of 
+  "Areas near the sea".
+"""
+    )
+    st.divider()
+    st.caption("Built by")
+    st.image(DEVSEED_LOGO_PATH, width=180)
+
 backend = "gguf"
 
 if "run_q" not in st.session_state:

modal_serve/README.md

@@ -1,3 +1,5 @@
+<img src="../assets/gazet-logo.svg" alt="Gazet logo" width="64" />
+
 # Modal Deployment
 
 Deploys Gazet to Modal as three independently scaled containers:
@@ -59,54 +61,10 @@ API directly:
 curl "https://<workspace>--gazet-api-fastapi-app.modal.run/search?q=Odisha"
 ```
 
-Expected timings:
-
-- First request after idle: ~25-30s (cold start cascade across all three)
-- Warm requests within scaledown windows: ~1-3s
-
-## 4. Set the budget cap
-
-Modal dashboard -> Settings -> Billing:
-
-- Workspace spending limit: **$50/mo**
-- Email alerts at $25 / $40 / $50
-
-Modal pauses new container starts when the limit is hit.
-
 ## Updating
 
-Code or dependency changes:
-
 ```bash
 modal deploy modal_serve/serve.py
 ```
 
 Model updates: re-upload to the `gazet` volume; running containers pick up the new file at next cold start.
-
-## Architecture notes
-
-- **No supervisord.** Each Cls runs one logical service.
-- **`@modal.asgi_app`** serves FastAPI natively, no uvicorn subprocess.
-- **`@modal.web_server`** wraps non-ASGI processes (`llama-server` binary, Streamlit).
-- **Cross-Cls URLs** resolved at runtime via `modal.Cls.from_name(...)`.
-- **`scaledown_window`** tuned per tier: 120s GPU, 300s API, 600s Demo (UI sessions are sticky).
-
-## Cost reference
-
-| Traffic | Monthly estimate |
-|---|---|
-| 200 queries/day | ~$5-7 |
-| 1000 queries/day | ~$18-25 |
-| Idle | $0 |
-
-T4 GPU at ~$0.59/hr is only billed during active inference + brief warmup. CPU containers are negligible.
-
-## Troubleshooting
-
-**Cold start fails on `LlamaServer`**: check the binary path in `modal_serve/serve.py`. The official image's binary is at `/app/llama-server`; if upstream changes, run `modal shell gazet::LlamaServer` and `which llama-server`.
-
-**`Api` cannot reach `LlamaServer`**: confirm `modal.Cls.from_name(...).serve.web_url` returns a non-empty string. The first deploy registers URLs; redeploys keep them stable.
-
-**Streamlit websocket errors**: `@modal.web_server` supports websockets natively; if a proxy issue appears, raise `startup_timeout` and check `modal logs gazet`.
-
-**Model not found**: the path in `serve.py` is `/models/checkpoints/qwen35-fientune-v3/ckpt-q4_k_m.gguf`. Verify the volume layout matches.

modal_serve/serve.py

@@ -48,7 +48,8 @@ llama_image = (
     image=llama_image,
     gpu="T4",
     volumes={"/models": gazet_vol},
-    scaledown_window=120,
+    scaledown_window=300,
+    min_containers=1,
     max_containers=2,
     timeout=600,
 )
@@ -82,6 +83,7 @@ api_image = (
     image=api_image,
     volumes={"/data": data_vol},
     scaledown_window=300,
+    min_containers=1,
     max_containers=3,
     timeout=300,
 )
@@ -108,12 +110,15 @@ demo_image = (
     .pip_install_from_pyproject("pyproject.toml", optional_dependencies=["demo"])
     .add_local_python_source("gazet")
     .add_local_file("gazet_demo.py", "/root/gazet_demo.py")
+    .add_local_file("assets/gazet-logo.svg", "/root/assets/gazet-logo.svg")
+    .add_local_file("assets/ds-logo-pos.svg", "/root/assets/ds-logo-pos.svg")
 )
 
 
 @app.cls(
     image=demo_image,
     scaledown_window=600,
+    min_containers=1,
     max_containers=3,
     timeout=600,
 )