@cloudgrid-io/mcp 0.13.0 → 0.15.0

package/src/corpus/templates/semantic-search/cloudgrid.yaml

@@ -0,0 +1,217 @@
+# ============================================================================
+# cloudgrid.yaml — Complete Example
+# ============================================================================
+#
+# This file shows EVERY field the platform supports, with comments explaining
+# each one. It is a reference — no real project would use all of these at once.
+#
+# STANDARD: every CloudGrid template ships its cloudgrid.yaml in THIS full form.
+# Uncomment ONLY the fields the archetype needs (always: name + services; plus
+# needs: for runtime apps). Leave everything else commented. Comments are
+# ignored by the parser, so the file deploys to exactly the active fields.
+#
+# Only two fields are required: name and services. Everything else is optional.
+# Full docs: docs/cloudgrid-yaml-reference.md
+# ============================================================================
+
+
+# ─── IDENTITY ───────────────────────────────────────────────────────────────
+
+# Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
+# Must start and end with a letter or digit.
+# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+name: semantic-search
+
+# One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
+# description: Hybrid semantic + keyword search over your documents
+
+# Single emoji or short text shown as the entity icon. Max 64 chars.
+# icon: "🔎"
+
+# Entity type: 'app' (default) or 'agent'. An agent is an app with an agent: block.
+# kind: app
+
+
+# ─── NETWORKING ─────────────────────────────────────────────────────────────
+
+# Whether this entity serves public HTTP traffic.
+# true = public URL + Ingress (default). false = internal only.
+# expose: true
+
+# Additional domain names this entity serves on (the platform URL is always active).
+# custom_domains:
+#   - orders.example.com
+#   - shop.example.com
+
+
+# ─── HEALTH PROBE (entity-level override) ──────────────────────────────────
+
+# Override the default health check for the entire entity.
+# probe:
+#   path: /healthz               # HTTP path to probe (default: /).
+#   expected: "<500"             # '<500' (default), '200', '2xx'.
+
+
+# ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
+
+# Slack notification to the org's default channel on deploy failure.
+# true = notify (default), false = silent.
+# notify: true
+
+
+# ─── SCALING ────────────────────────────────────────────────────────────────
+
+# Replica scaling intent.
+#   'auto'  — platform decides from the grid tier (default).
+#   'alert' — single-replica, emit a SPOF warning at plug time.
+#   1-10    — explicit replica count, clamped to the grid max.
+# scale: auto
+
+
+# ─── INFRASTRUCTURE NEEDS ──────────────────────────────────────────────────
+#
+# Declare infrastructure; the platform provisions it and injects connection
+# details as env vars. Nine needs: database, cache, kv, queue, pubsub, vector,
+# object_storage, disk, ai. Simplest form is `true`.
+#
+# needs:
+#   # database — MongoDB. Injects DATABASE_MONGODB_URL (+ legacy MONGODB_URL).
+#   #   true | pool | dedicated | { tier: external, secret: MY_DB }
+#   database: true
+#   # cache — Redis, LRU eviction (derived data). Injects CACHE_REDIS_URL (+ REDIS_URL).
+#   #   true | redis | { engine: external, secret: MY_REDIS_URL }
+#   cache: true
+#   # kv — Redis, no eviction (durable: flags, idempotency). Injects KV_REDIS_URL.
+#   kv: true
+#   # queue — Redis job-queue substrate (BullMQ). Injects QUEUE_REDIS_URL.
+#   queue: true
+#   # pubsub — Redis broadcast pub/sub. Injects PUBSUB_REDIS_URL.
+#   pubsub: true
+#   # vector — pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+ PGVECTOR_URL).
+#   #   true | pgvector | { engine: pgvector, dim: 1536 }
+#   #   NOT USED HERE — pgvector runtime role-grant is blocked (platform #1545).
+#   #   This template stores embeddings in the Mongo `chunks` collection and
+#   #   cosine-ranks in-app instead. Swap to `vector: pgvector` once #1545 lands.
+#   vector: pgvector
+#   # object_storage — GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET, _GCS_REGION.
+#   #   true | { size: 10Gi }
+#   object_storage: true
+#   # disk — persistent FS mount (PVC). Injects DISK_PATH. Pins to 1 replica.
+#   #   true | { size: 1Gi, mount: /var/data }  (forbidden: /proc /sys /dev)
+#   #   Use with SOURCE_TYPE=local to read documents from the mount.
+#   disk: true
+#   # ai — AI Gateway via @cloudgrid-io/ai. Injects AI_GATEWAY_URL. true | false.
+#   ai: true
+
+
+# ─── INTER-ENTITY COMMUNICATION ────────────────────────────────────────────
+
+# Entities this app calls (outbound). Service-account token injected per pair.
+# calls:
+#   - org:atomic/billing-api
+
+# Inbound caller policy — who can call YOUR entity.
+# callers:
+#   policy: auto                 # 'auto' | 'manual' (default).
+#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   fallback: deny               # 'deny' (default) | 'warn'.
+#   # allowed_apps:              # required only when scope: explicit
+#   #   - org:atomic/frontend
+
+
+# ─── VAULT ──────────────────────────────────────────────────────────────────
+
+# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# The source + embeddings secrets can also be stored directly with
+# `grid secrets set KEY=VALUE` — see AGENTS.md.
+# vault:
+#   EMBEDDINGS_API_KEY: embeddings-api-key
+#   DROPBOX_REFRESH_TOKEN: dropbox-refresh-token
+
+
+# ─── CONNECTORS AND HOOKS ──────────────────────────────────────────────────
+
+# connectors:
+#   - id: team-slack
+#     target: org                # 'system' | 'org'.
+#     channel: "#deploys"
+# hooks:
+#   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created
+#     via: team-slack
+#     template: "Deploy failed for {entity_name}: {error}"
+#     channel: "#alerts"
+# triggers:
+#   - from: team-slack
+#     event: message
+#     channel: "#support"
+#     route: /webhooks/slack
+
+
+# ─── LOCAL DEVELOPMENT ──────────────────────────────────────────────────────
+
+# Config for `grid dev`. Redact fields in dev data snapshots.
+# dev:
+#   snapshot:
+#     mask:
+#       - users.email
+#       - users.phone
+
+
+# ─── AGENT METADATA ────────────────────────────────────────────────────────
+
+# An agent is an app with kind: agent (above) and an agent: block.
+# agent:
+#   purpose: Sync customer data from external CRM every night
+#   schedule: "0 2 * * *"
+#   trigger: webhook
+
+
+# ─── PRIVATE RESOURCE AUTO-DEPENDENCIES ────────────────────────────────────
+
+# When true (default), private resources are auto-injected as depends_on.
+# auto_depends_on_private_requires: true
+
+
+# ─── SERVICES (REQUIRED) ───────────────────────────────────────────────────
+#
+# At least one service is required. Key = service name (slug rules).
+# Types: node, nextjs, python, static, cron.
+#
+services:
+  # React (Vite) built to static assets, served at the root.
+  web:
+    type: static
+    path: /
+    build:
+      command: npm run build
+      output: dist
+    node_version: "22"
+  # Python FastAPI backend — hybrid search, answer mode, manager admin.
+  # Entry: services/backend/src/main.py (uvicorn app.main:app).
+  backend:
+    type: python
+    path: /backend
+  # A scheduled `type: cron` refresh service is a follow-up — a Python cron
+  # entity is currently blocked on platform issue #1585. Until it lands, use the
+  # manager "Refresh now" endpoint (POST /backend/admin/refresh). See AGENTS.md.
+  # refresh:
+  #   type: cron
+  #   schedule: "0 3 * * *"
+  #   timezone: UTC
+  #   run: job
+  #   source:
+  #     path: services/refresh
+# CloudGrid managed Mongo → injects DATABASE_MONGODB_URL (+ legacy MONGODB_URL).
+# NO `needs: vector` — pgvector runtime role-grant is still blocked (#1545);
+# embeddings live in the Mongo `chunks` collection and are cosine-ranked in-app.
+needs:
+  database: true
+
+
+# ============================================================================
+# NOTES
+# - NOT here: org:/entity_id: (→ .cloudgrid/link.json), secrets (→ grid secrets set),
+#   Dockerfile (platform generates from services.*.type).
+# - Deploy: grid plug   |   Local with grid resources: grid dev
+# - Full reference: docs/cloudgrid-yaml-reference.md  |  CLI: docs/cli-reference.md
+# ============================================================================

package/src/corpus/templates/semantic-search/index.md

@@ -0,0 +1,97 @@
+# Template: semantic-search (CloudGrid-native document search)
+
+A deployable, domain-agnostic **document search** app — index a folder of
+documents (PDF/DOCX/TXT/MD), then search by keyword, by meaning, and by metadata,
+with a grounded answer mode and a manager admin. Two services: a React (Vite)
+static frontend at `/` and a FastAPI backend at `/backend`, backed by
+grid-shared Mongo. This template ships **real, runnable code** — read `AGENTS.md`,
+adapt the naming/metadata to your domain, then deploy.
+
+**Hybrid search** = Mongo `$text` (lexical) + in-app NumPy cosine over chunk
+embeddings (semantic) + metadata filters, blended and aggregated to the document
+level with a best-passage highlight.
+
+**Key rules (proven by a live build — do not regress these):**
+
+1. **Every service's code lives under `services/<name>/`.** `path:` in
+   `cloudgrid.yaml` is the URL mount, NOT the filesystem path. The `web` service
+   → `services/web/`; the `backend` service → `services/backend/`.
+2. **Read the Mongo URL LAZILY** — `os.environ.get("DATABASE_MONGODB_URL") or
+   os.environ.get("MONGODB_URL")` inside `get_client()`, never at import time.
+3. **Health is green with NO secrets set.** No secret is read at import time;
+   every secret is gated inside a function. `GET /backend/health` needs only Mongo.
+4. **`@app.on_event("startup")` calls `db.ensure_indexes()`** so the chunks
+   `$text` index exists at boot — `$text` returns `[]` on an empty catalog rather
+   than raising `IndexNotFound` (a 500). The `$text` query is also guarded in
+   `except OperationFailure` as belt-and-suspenders.
+5. **No `needs: vector`** — pgvector runtime role-grant is blocked (#1545), so
+   embeddings live in the Mongo `chunks` collection (a float array) and are
+   cosine-ranked in-app. **No active cron** — a Python `type: cron` refresh is
+   blocked (#1585); ship the manager "Refresh now" endpoint and add cron later.
+
+## File tree
+
+```
+cloudgrid.yaml                                 # name + services(web static+build, backend python) + needs:{database:true}
+services/web/                                  # React + Vite static frontend (LTR, neutral)
+  package.json  vite.config.js  index.html
+  src/main.jsx  App.jsx  api.js  styles.css
+  src/components/SearchView.jsx ManagerLogin.jsx Settings.jsx Dashboard.jsx
+services/backend/                              # FastAPI backend, mounted at /backend
+  requirements.txt
+  src/main.py                                  # uvicorn entry (reads PORT; no secret at import)
+  src/app/
+    main.py                                    # routes + startup ensure_indexes()
+    config.py                                  # lazy secret gating (SOURCE_TYPE, EMBEDDINGS_*, ...)
+    db.py                                       # lazy Mongo; ensure_indexes(); collections documents+chunks
+    search.py                                   # hybrid: $text + cosine + metadata, blended to doc level
+    indexing.py                                 # discover -> extract -> chunk -> embed -> store (incremental)
+    source.py                                   # pluggable adapter: dropbox | local | url
+    embeddings.py                               # one config point (OpenAI-compatible)
+    answer.py                                   # grounded answer + citations (extractive fallback)
+    auth.py                                     # manager session auth (MANAGER_PASSWORD_HASH)
+```
+
+## cloudgrid.yaml (active fields)
+
+```yaml
+# On disk this file is the full-annotated reference (templates/_cloudgrid.yaml.reference)
+# with EVERY field present as a comment; only the fields below are uncommented.
+name: semantic-search
+services:
+  web:
+    type: static
+    path: /
+    build:
+      command: npm run build
+      output: dist
+    node_version: "22"
+  backend:
+    type: python
+    path: /backend
+needs:
+  database: true
+```
+
+> **Capability:** the need is `database: true` — the deployer provisions Mongo and
+> injects `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`). NO `needs: vector`
+> (#1545) and NO active cron (#1585). `requires:` is the deprecated v1 alias —
+> don't mix it with `needs:`.
+
+## Configure + deploy
+
+1. `grid init semantic-search` — creates the entity + `.cloudgrid/link.json`.
+2. `grid secrets set EMBEDDINGS_API_KEY=sk-…` plus the source secrets
+   (`SOURCE_TYPE` + Dropbox/local/url config) and `MANAGER_PASSWORD_HASH`
+   (sha256 hex of the manager password). See `AGENTS.md`.
+3. (Optional) `grid dev` to run locally against the injected dev Mongo.
+4. `grid plug` to deploy — a runtime deploy is **async**: poll status until live,
+   then sign in as manager and hit "Refresh now" to index the source.
+
+## Adapt it
+
+- Rename the `collection` / `date` metadata to your domain in
+  `services/backend/src/app/indexing.py` (`_parse_metadata`).
+- Add a source adapter: subclass `Source` in `source.py`, return it from
+  `get_source()`, gate its secrets in `config.py`.
+- Point embeddings at any OpenAI-compatible provider via `EMBEDDINGS_BASE_URL`.

package/src/corpus/templates/semantic-search/services/backend/requirements.txt

@@ -0,0 +1,7 @@
+fastapi==0.111.0
+uvicorn[standard]==0.30.1
+pymongo==4.8.0
+numpy==1.26.4
+httpx==0.27.0
+pypdf==4.2.0
+python-docx==1.1.2

package/src/corpus/templates/semantic-search/services/backend/src/app/answer.py

@@ -0,0 +1,90 @@
+"""Grounded answer mode.
+
+Composes an answer from the indexed documents ONLY, with citations back to the
+documents used. No outside knowledge. Toggleable from Settings. If the answer LLM
+is not configured, it falls back to an extractive answer (the top passages
+themselves), still grounded and cited — never crashes.
+"""
+from __future__ import annotations
+
+import httpx
+
+from . import config, search
+
+
+def _answer_enabled_from_db() -> bool:
+    from . import db
+
+    doc = db.settings().find_one({"_id": "features"}) or {}
+    return bool(doc.get("answer_mode_enabled", True))
+
+
+def compose_answer(question: str) -> dict:
+    """Return a grounded answer + the documents cited. Extractive fallback if no LLM."""
+    if not _answer_enabled_from_db():
+        return {"answer": None, "citations": [], "note": "Answer mode is disabled."}
+
+    hits = search.search(question, mode="hybrid", limit=5)
+    passages = hits["results"]
+    if not passages:
+        return {
+            "answer": None,
+            "citations": [],
+            "note": "No indexed material matches this question.",
+        }
+
+    citations = [
+        {"document_id": p["document_id"], "title": p["title"], "collection": p["collection"]}
+        for p in passages
+    ]
+
+    # Grounded generation only if the LLM key is present; otherwise return an
+    # extractive answer built from the retrieved passages.
+    key = config.embeddings_api_key()
+    if not key:
+        extractive = "\n\n".join(
+            f"- {p['title']}: {p['best_passage']}" for p in passages[:3]
+        )
+        return {
+            "answer": extractive,
+            "citations": citations,
+            "mode": "extractive",
+            "note": "Grounded generation unavailable (no API key) — showing "
+                    "the most relevant source passages instead.",
+        }
+
+    context = "\n\n".join(
+        f"[{i+1}] {p['title']}:\n{p['best_passage']}" for i, p in enumerate(passages)
+    )
+    system = (
+        "You answer strictly and only from the provided document passages. "
+        "Cite sources as [n]. If the passages do not contain the answer, say so. "
+        "Never use outside knowledge."
+    )
+    try:
+        resp = httpx.post(
+            f"{config.embeddings_base_url()}/chat/completions",
+            headers={"Authorization": f"Bearer {key}"},
+            json={
+                "model": config.answer_model(),
+                "messages": [
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": f"Question: {question}\n\nSources:\n{context}"},
+                ],
+                "temperature": 0.2,
+            },
+            timeout=60.0,
+        )
+        resp.raise_for_status()
+        text = resp.json()["choices"][0]["message"]["content"]
+        return {"answer": text, "citations": citations, "mode": "generated", "note": None}
+    except Exception as exc:  # noqa: BLE001 - degrade to extractive, never crash
+        extractive = "\n\n".join(
+            f"- {p['title']}: {p['best_passage']}" for p in passages[:3]
+        )
+        return {
+            "answer": extractive,
+            "citations": citations,
+            "mode": "extractive",
+            "note": f"Generation failed ({exc}); showing source passages.",
+        }

package/src/corpus/templates/semantic-search/services/backend/src/app/auth.py

@@ -0,0 +1,65 @@
+"""Server-side manager session auth.
+
+Admin functions are enforced on the server, not just hidden in the UI. Sessions
+are opaque tokens stored in Mongo. The password is compared against
+MANAGER_PASSWORD_HASH (sha256 hex). If no hash is configured, admin login is
+refused (never open by default) — but the app still starts and search stays
+public.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import secrets
+
+from fastapi import Header, HTTPException
+
+from . import config, db
+
+SESSION_TTL_HOURS = 12
+
+
+def _hash(password: str) -> str:
+    return hashlib.sha256(password.encode("utf-8")).hexdigest()
+
+
+def login(password: str) -> str:
+    configured = config.manager_password_hash()
+    if not configured:
+        raise HTTPException(
+            status_code=503,
+            detail="Manager auth is not configured (MANAGER_PASSWORD_HASH unset).",
+        )
+    if not secrets.compare_digest(_hash(password), configured):
+        raise HTTPException(status_code=401, detail="Invalid password.")
+    token = secrets.token_urlsafe(32)
+    db.get_db().sessions.insert_one({
+        "_id": token,
+        "created_at": dt.datetime.now(dt.timezone.utc),
+        "expires_at": dt.datetime.now(dt.timezone.utc) + dt.timedelta(hours=SESSION_TTL_HOURS),
+    })
+    return token
+
+
+def require_manager(authorization: str | None = Header(default=None)) -> str:
+    """FastAPI dependency: validate the Bearer session token."""
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="Manager session required.")
+    token = authorization.split(" ", 1)[1].strip()
+    session = db.get_db().sessions.find_one({"_id": token})
+    if not session:
+        raise HTTPException(status_code=401, detail="Invalid session.")
+    if session["expires_at"] < dt.datetime.now(dt.timezone.utc):
+        db.get_db().sessions.delete_one({"_id": token})
+        raise HTTPException(status_code=401, detail="Session expired.")
+    return token
+
+
+def change_password(current: str, new: str) -> str:
+    """Self-contained password change. Returns the NEW hash for the manager to
+    store as the MANAGER_PASSWORD_HASH secret (we never persist the plaintext or
+    the secret ourselves)."""
+    configured = config.manager_password_hash()
+    if configured and not secrets.compare_digest(_hash(current), configured):
+        raise HTTPException(status_code=401, detail="Current password is incorrect.")
+    return _hash(new)

package/src/corpus/templates/semantic-search/services/backend/src/app/config.py

@@ -0,0 +1,110 @@
+"""Central configuration and secret gating.
+
+CRITICAL CloudGrid rule: NEVER read a secret at module import time. Every value
+here is resolved lazily inside a function, so the process starts and passes
+`GET /backend/health` even when NO secret is set. Search and indexing degrade
+gracefully (empty results + a clear "not indexed / missing secret" note) rather
+than crashing.
+
+The Mongo connection is the ONLY hard dependency for health, and it is injected
+automatically by CloudGrid (`needs: database`) as DATABASE_MONGODB_URL.
+
+Two pluggable config points:
+  - SOURCE_TYPE  selects the document-source adapter (dropbox | local | url).
+  - EMBEDDINGS_* selects the embeddings provider (OpenAI-compatible by default).
+"""
+from __future__ import annotations
+
+import os
+
+
+# ── Mongo (injected by the grid — the only health-critical config) ──────────
+
+def mongo_url() -> str | None:
+    """Injected by CloudGrid `needs: database`. Never set by hand."""
+    return os.environ.get("DATABASE_MONGODB_URL") or os.environ.get("MONGODB_URL")
+
+
+# ── Embeddings (one config point, gated) ─────────────────────────────────────
+
+def embeddings_api_key() -> str | None:
+    return os.environ.get("EMBEDDINGS_API_KEY")
+
+
+def embeddings_model() -> str:
+    # Changing the model changes vector dimensions and requires a full reindex.
+    return os.environ.get("EMBEDDINGS_MODEL", "text-embedding-3-small")
+
+
+def embeddings_base_url() -> str:
+    # Any OpenAI-compatible endpoint. Default is OpenAI.
+    return os.environ.get("EMBEDDINGS_BASE_URL", "https://api.openai.com/v1")
+
+
+def embeddings_configured() -> bool:
+    return bool(embeddings_api_key())
+
+
+def answer_model() -> str:
+    return os.environ.get("ANSWER_MODEL", "gpt-4o-mini")
+
+
+# ── Source adapter (one config point, gated) ─────────────────────────────────
+
+def source_type() -> str:
+    """dropbox | local | url. Selects the document-source adapter."""
+    return os.environ.get("SOURCE_TYPE", "dropbox")
+
+
+def dropbox_config() -> dict[str, str | None]:
+    return {
+        "app_key": os.environ.get("DROPBOX_APP_KEY"),
+        "app_secret": os.environ.get("DROPBOX_APP_SECRET"),
+        "refresh_token": os.environ.get("DROPBOX_REFRESH_TOKEN"),
+        "folder_path": os.environ.get("DROPBOX_FOLDER_PATH", ""),
+    }
+
+
+def local_source_path() -> str:
+    """Directory the local adapter reads. Point at a `needs: disk` mount
+    (DISK_PATH) or a bundled folder."""
+    return os.environ.get("LOCAL_SOURCE_PATH", os.environ.get("DISK_PATH", ""))
+
+
+def url_source_manifest() -> str | None:
+    """A newline- or comma-separated list of document URLs the url adapter
+    fetches. Set as a secret or plain env var."""
+    return os.environ.get("URL_SOURCE_MANIFEST")
+
+
+def source_configured() -> bool:
+    st = source_type()
+    if st == "dropbox":
+        c = dropbox_config()
+        return bool(c["app_key"] and c["app_secret"] and c["refresh_token"])
+    if st == "local":
+        return bool(local_source_path())
+    if st == "url":
+        return bool(url_source_manifest())
+    return False
+
+
+# ── Manager auth (gated) ──────────────────────────────────────────────────────
+
+def manager_password_hash() -> str | None:
+    """A sha256 hex digest of the manager password. Compared server-side."""
+    return os.environ.get("MANAGER_PASSWORD_HASH")
+
+
+def manager_auth_configured() -> bool:
+    return bool(manager_password_hash())
+
+
+# ── Search blend weights ─────────────────────────────────────────────────────
+
+def semantic_weight() -> float:
+    return float(os.environ.get("SEMANTIC_WEIGHT", "0.55"))
+
+
+def keyword_weight() -> float:
+    return float(os.environ.get("KEYWORD_WEIGHT", "0.45"))

package/src/corpus/templates/semantic-search/services/backend/src/app/db.py

@@ -0,0 +1,89 @@
+"""Lazy MongoDB access.
+
+The client and connection string are resolved LAZILY (inside get_client), never
+at module top level — so importing this module never touches the network and
+never requires the env var to exist. CloudGrid injects DATABASE_MONGODB_URL at
+runtime from `needs: database`.
+
+Collections:
+  documents  — one row per source document (title, collection tag, date, ...).
+  chunks     — one embeddable passage per document (content + embedding array).
+  settings   — feature flags, synonyms, catalog metadata (last_refresh).
+  usage_events, index_reports, sessions — telemetry / admin.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pymongo import ASCENDING, MongoClient, TEXT
+from pymongo.database import Database
+
+from . import config
+
+_client: Optional[MongoClient] = None
+
+
+def get_client() -> MongoClient:
+    global _client
+    if _client is None:
+        uri = config.mongo_url()
+        if not uri:
+            raise RuntimeError(
+                "DATABASE_MONGODB_URL is not set. CloudGrid injects it "
+                "automatically from `needs: database` — run with `grid dev` "
+                "locally or deploy with `grid plug`. Do not set it by hand."
+            )
+        # Short server-selection timeout so health checks fail fast, not hang.
+        _client = MongoClient(uri, serverSelectionTimeoutMS=3000)
+    return _client
+
+
+def get_db() -> Database:
+    # Default DB name comes from the connection-string path segment the grid injects.
+    return get_client().get_default_database()
+
+
+def ping() -> bool:
+    """True if Mongo is reachable. Used by /backend/health."""
+    get_client().admin.command("ping")
+    return True
+
+
+def ensure_indexes() -> None:
+    """Create the indexes the search relies on. Safe to call repeatedly.
+
+    Called at FastAPI startup so the chunks $text index exists before any query
+    — without it, `$text` raises IndexNotFound (a 500) on an empty catalog.
+    """
+    db = get_db()
+    # Text index on chunk content for lexical / $text search.
+    db.chunks.create_index([("content", TEXT)], name="chunks_content_text")
+    db.chunks.create_index([("document_id", ASCENDING)], name="chunks_document_id")
+    # Metadata filter indexes on documents.
+    db.documents.create_index([("date", ASCENDING)], name="documents_date")
+    db.documents.create_index([("collection", ASCENDING)], name="documents_collection")
+    db.documents.create_index(
+        [("source_filename", ASCENDING)], name="documents_source_filename", unique=True
+    )
+
+
+# ── Collection accessors ─────────────────────────────────────────────────────
+
+def documents():
+    return get_db().documents
+
+
+def chunks():
+    return get_db().chunks
+
+
+def settings():
+    return get_db().settings
+
+
+def events():
+    return get_db().usage_events
+
+
+def index_reports():
+    return get_db().index_reports