Upload 12 files

ADDING_A_MUNICIPALITY.md

@@ -0,0 +1,70 @@
+# Adding a municipality (worked example: City of Houston)
+
+Two things are needed. Only the **second** one makes reviews actually work.
+
+## 1. Config — framing (5 minutes)
+
+`jurisdictions/houston.yaml` is already included as a starter. It sets the city name,
+region, the code/bylaw framework names findings must cite, and disables the dated
+transition logic (Houston has no Calgary-style rezoning revert).
+
+After this step the tool *speaks* Houston: report titles, personas, framework names.
+It cannot yet cite a single Houston rule.
+
+## 2. Skills — the grounded rules (the real work)
+
+Reviews are only as good as the distilled knowledge. Create folders under `skills/`
+whose `SKILL.md` frontmatter declares the jurisdiction:
+
+```
+skills/houston-development/SKILL.md
+---
+name: houston-development
+jurisdiction: houston          # <-- REQUIRED, or it will load for every city
+track: development
+track_label: "Chapter 42 development review"
+track_scope: "a Houston development application subject to Code of Ordinances Chapter 42"
+description: "..."
+---
+```
+
+`jurisdiction:` is what keeps cities apart. Skills tagged `calgary` never load for a
+Houston review and vice-versa — verified by test. A skill with **no** `jurisdiction:`
+loads for every municipality (use only for genuinely universal content).
+
+### Turning your Houston documents into skills
+
+You said you have the documents. **Do not drop the raw PDFs into `knowledge/`.** That
+was tested here with a 674-page code PDF and it made results *worse*: 38% of its pages
+were image-only, the relevant clauses were scattered across 600 pages, and the router
+spent its budget on chunks that didn't match. Reviews improved only after clauses were
+distilled into structured tables.
+
+For each rule you want the tool to enforce, add a row:
+
+| Rule | Clause | As written |
+|---|---|---|
+| Minimum lot size, single-family | Ch. 42-181 | "..." |
+
+Put those in `skills/houston-development/references/*.md`. The grounded-citation rule
+then lets findings cite `Ch. 42-181` because that exact string is in the knowledge.
+Anything not distilled will be reported as an information gap instead of a guess —
+which is the correct behaviour, not a failure.
+
+### Sanity check
+
+```bash
+python - <<'PY'
+import engine as eng
+print("houston skills:", [s.name for s in eng.load_knowledge(".", jurisdiction="houston")[0]])
+print("calgary skills:", [s.name for s in eng.load_knowledge(".", jurisdiction="calgary")[0]])
+PY
+```
+
+Until Houston skills exist, `get_review_kit(municipality="houston")` returns an explicit
+"no review skills configured yet" message rather than pretending it can review.
+
+## 3. Optional — remove Calgary
+
+If this deployment is Houston-only, delete `skills/alberta-suites`,
+`skills/calgary-*`, and `jurisdictions/calgary.yaml`. Nothing else references them.

engine.py

@@ -60,6 +60,7 @@ class Skill:
     track: str = "suites"
     track_label: str = ""
     track_scope: str = ""
+    jurisdiction: str = ""
 
 
 def _read_text(path: Path) -> str:
@@ -153,9 +154,18 @@ def _frontmatter_desc(md: str) -> str:
     return ""
 
 
-def load_knowledge(base_dir, uploaded=None) -> tuple[list[Skill], list[Source]]:
-    """uploaded: list of (filename, bytes) from Streamlit uploads."""
+def load_knowledge(base_dir, uploaded=None,
+                   jurisdiction: str = "") -> tuple[list[Skill], list[Source]]:
+    """Load skills + drop-folder knowledge.
+
+    uploaded: list of (filename, bytes) from Streamlit uploads.
+    jurisdiction: when set, only load skills whose SKILL.md frontmatter declares a
+        matching `jurisdiction:` (comma-separated list allowed), plus skills that
+        declare none (treated as universal). This lets one deployment hold several
+        municipalities' knowledge without a Calgary review pulling in Houston rules.
+    """
     base = Path(base_dir)
+    want = jurisdiction.strip().lower()
     skills: list[Skill] = []
     for skill_dir in sorted((base / "skills").glob("*")):
         smd = skill_dir / "SKILL.md"
@@ -167,10 +177,16 @@ def load_knowledge(base_dir, uploaded=None) -> tuple[list[Skill], list[Source]]:
         def _fm_key(key: str, default: str = "") -> str:
             m = re.search(rf'^{key}:\s*"?(.*?)"?\s*$', fm_text, flags=re.M)
             return m.group(1).strip() if m else default
+        skill_jur = _fm_key("jurisdiction")
+        if want and skill_jur:
+            allowed = {j.strip().lower() for j in skill_jur.split(",") if j.strip()}
+            if want not in allowed:
+                continue  # belongs to a different municipality
         sk = Skill(skill_dir.name, md, _frontmatter_desc(md),
                    track=_fm_key("track", "suites"),
                    track_label=_fm_key("track_label"),
-                   track_scope=_fm_key("track_scope"))
+                   track_scope=_fm_key("track_scope"),
+                   jurisdiction=skill_jur)
         seen_keys: set[str] = set()
         for ref in sorted(skill_dir.rglob("*")):
             if not ref.is_file() or ref.name.lower() == "skill.md":

mcp_server.py

@@ -43,6 +43,15 @@ mcp = FastMCP("crossbeam-plan-review", stateless_http=True)
 
 
 # ── helpers ────────────────────────────────────────────────────────────────
+def _slug(slug: str = "") -> str:
+    """Resolve the active municipality slug (falls back to the first configured)."""
+    choices = list_jurisdictions(BASE_DIR)
+    if slug and slug in choices:
+        return slug
+    real = [s for s in choices if not s.startswith("_") and s != "default"]
+    return real[0] if real else ""
+
+
 def _jur(slug: str = ""):
     choices = list_jurisdictions(BASE_DIR)
     if slug and slug in choices:
@@ -58,9 +67,14 @@ def _resolve_key(provider: str, api_key: str) -> str:
     return os.environ.get(env, "") if env else ""
 
 
-def _load(track_id: str = ""):
-    skills, loose = eng.load_knowledge(BASE_DIR)
+def _load(track_id: str = "", municipality: str = ""):
+    """Load knowledge scoped to a municipality so multiple cities can coexist."""
+    skills, loose = eng.load_knowledge(BASE_DIR, jurisdiction=_slug(municipality))
     tracks = eng.discover_tracks(skills)
+    if not tracks:
+        # A configured municipality with no skills yet (e.g. a freshly added city).
+        # Return an explicit empty track rather than crashing on next(iter({})).
+        return skills, loose, {}, {"label": "unconfigured", "scope": "", "skills": []}
     if track_id and track_id in tracks:
         tr = tracks[track_id]
     else:
@@ -89,7 +103,7 @@ def list_municipalities() -> dict:
 def list_review_tracks(municipality: str = "") -> dict:
     """List available review tracks/types (e.g. suites, multi-residential, institutional)
     and the models available for the LLM-backed tools."""
-    _, _, tracks, _ = _load()
+    _, _, tracks, _ = _load("", municipality)
     return {
         "tracks": [{"id": t, "label": v["label"], "scope": v["scope"]}
                    for t, v in tracks.items()],
@@ -100,11 +114,132 @@ def list_review_tracks(municipality: str = "") -> dict:
 @mcp.tool()
 def list_knowledge(municipality: str = "") -> dict:
     """Show the knowledge base (skills + reference files) the reviews are grounded in."""
-    skills, loose = eng.load_knowledge(BASE_DIR)
+    skills, loose = eng.load_knowledge(BASE_DIR, jurisdiction=_slug(municipality))
     return {"manifest": eng.knowledge_manifest(skills, loose)}
 
 
 # ── Flow 3: plan review ─────────────────────────────────────────────────────
+# ═══════════════════════════════════════════════════════════════════════════
+#  CLIENT-SIDE TOOLS — no API key required.
+#
+#  When the caller is itself an LLM (ChatGPT, Claude, Gemini, HuggingChat), it
+#  makes no sense for this server to call ANOTHER model: you would pay twice and
+#  wait twice. These tools instead hand the agent everything it needs — the
+#  grounded knowledge, the review rules, the output schema, and deterministic
+#  document extraction — and the agent's own model does the reasoning.
+#
+#  Use the *_with_llm tools further below only for non-LLM callers (n8n, scripts,
+#  cron) that have no model of their own.
+# ═══════════════════════════════════════════════════════════════════════════
+
+@mcp.tool()
+def extract_document(pdf_base64: str = "", max_pages: int = 15,
+                     include_images: bool = False) -> dict:
+    """Extract text (and optionally page images) from a PDF or DXF. NO API KEY NEEDED.
+
+    Deterministic parsing via PyMuPDF/ezdxf — no LLM involved. Returns per-page text
+    so an agent can read a plan set or letter it cannot otherwise open. Set
+    include_images=true to also get base64 JPEGs of each page for vision models
+    (omitted by default because they are large)."""
+    if not pdf_base64:
+        return {"error": "Provide pdf_base64 (base64-encoded PDF or DXF bytes)."}
+    try:
+        data = base64.b64decode(pdf_base64)
+    except Exception as exc:  # noqa: BLE001
+        return {"error": f"pdf_base64 is not valid base64: {exc}"}
+    try:
+        b64s, texts, total, dims = eng.file_to_pages("upload.pdf", data, max_pages=max_pages)
+    except Exception as exc:  # noqa: BLE001
+        return {"error": str(exc)}
+    out = {"total_pages": total, "pages_extracted": len(texts),
+           "pages": [{"page": i + 1, "sheet_id": eng.guess_sheet_id(t) or "", "text": t}
+                     for i, t in enumerate(texts)]}
+    if include_images:
+        out["page_images_base64_jpeg"] = b64s
+    return out
+
+
+@mcp.tool()
+def get_review_kit(municipality: str = "", review_track: str = "suites",
+                   application_date: str = "") -> dict:
+    """Everything needed to REVIEW a plan set yourself. NO API KEY NEEDED.
+
+    Returns the jurisdiction framing, the grounded knowledge base for the chosen
+    track, the critical review rules (scope gate, grounded-citation rule, category
+    discipline), and the JSON output schema.
+
+    Recommended agent workflow:
+      1. extract_document(pdf_base64=...)   → the plan text/images
+      2. get_review_kit(municipality=..., review_track=...)  → rules + knowledge
+      3. YOUR model produces the findings, obeying `critical_rules` and citing ONLY
+         clause numbers that appear verbatim in `knowledge`.
+    """
+    jur = _jur(municipality)
+    _, _, tracks, tr = _load(review_track, municipality)
+    if not tracks:
+        return {"error": f"No review skills are configured for '{jur.place}' yet.",
+                "municipality": jur.place,
+                "how_to_fix": ("Add skill folders under skills/ whose SKILL.md frontmatter "
+                               f"declares `jurisdiction: {_slug(municipality)}` (plus track, "
+                               "track_label, track_scope). Until then this municipality has "
+                               "framing but no grounded rules, so no review can be performed."),
+                "frameworks": {"safety": jur.safety_framework,
+                               "land_use": jur.landuse_framework}}
+    knowledge = "\n\n".join(
+        [f"=== {sk.name}/SKILL.md ===\n{sk.skill_md}" for sk in tr["skills"]] +
+        [f"=== {s.key} ===\n{s.content}" for sk in tr["skills"] for s in sk.sources])
+    rules = eng.build_critical_rules(tr["label"], tr["scope"],
+                                     ", ".join(v["label"] for v in tracks.values()), jur)
+    trans = f" (assess against {jur.transition_label})" if jur.transition_label else ""
+    return {
+        "municipality": jur.place,
+        "review_track": {"id": review_track, "label": tr["label"], "scope": tr["scope"]},
+        "frameworks": {"safety": jur.safety_framework, "land_use": jur.landuse_framework},
+        "project_framing": (f"Municipality: {jur.place}\nReview type: {tr['label']}\n"
+                            f"Intended application date: {application_date or 'not stated'}{trans}"),
+        "critical_rules": rules,
+        "knowledge": knowledge,
+        "output_schema": eng.REVIEW_SYSTEM_TMPL.split("OUTPUT:", 1)[-1].strip(),
+        "note": ("Cite ONLY clause/section numbers that appear verbatim in `knowledge`. "
+                 "If a rule is real but its number is not present, name the reference file "
+                 "instead or record an information gap — never invent a number."),
+    }
+
+
+@mcp.tool()
+def get_corrections_kit(municipality: str = "") -> dict:
+    """Everything needed to INTERPRET a corrections letter yourself. NO API KEY NEEDED.
+
+    Returns the grounded knowledge, the honesty rules, and the output schema for
+    turning a municipal corrections/Detailed-Review letter into an item-by-item
+    analysis and a draft response.
+
+    The honesty rule is the important part: a draft response must NEVER claim a
+    correction has been resolved. Every resolution belongs to the applicant and is
+    represented by an [APPLICANT: ...] placeholder."""
+    jur = _jur(municipality)
+    skills, _ = eng.load_knowledge(BASE_DIR)
+    sk = [x for t in eng.discover_tracks(skills).values() for x in t["skills"]]
+    knowledge = "\n\n".join(
+        [f"=== {x.name}/SKILL.md ===\n{x.skill_md}" for x in sk] +
+        [f"=== {s.key} ===\n{s.content}" for x in sk for s in x.sources])
+    system = eng.CORRECTIONS_SYSTEM_TMPL.format(knowledge="<knowledge supplied separately>",
+                                                **eng._jur_fields(jur))
+    return {
+        "municipality": jur.place,
+        "frameworks": {"safety": jur.safety_framework, "land_use": jur.landuse_framework},
+        "rules_and_schema": system,
+        "knowledge": knowledge,
+        "honesty_rule": ("NEVER state or imply a correction has been resolved. Every "
+                         "resolution is an [APPLICANT: ...] placeholder the applicant fills in."),
+    }
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+#  SERVER-SIDE TOOLS — these DO call an LLM provider (need an API key).
+#  Use them from non-LLM callers: n8n, scripts, schedulers.
+# ═══════════════════════════════════════════════════════════════════════════
+
 @mcp.tool()
 def review_plan_set(
     pdf_base64: str,
@@ -128,7 +263,7 @@ def review_plan_set(
     if not key:
         return {"error": f"No API key for {provider}. Pass api_key or set the env var."}
     jur = _jur(municipality)
-    skills_all, loose, tracks, tr = _load(review_track)
+    skills_all, loose, tracks, tr = _load(review_track, municipality)
     skills = tr["skills"]
     data = base64.b64decode(pdf_base64)
     b64s, texts, total, dims = eng.file_to_pages("upload.pdf", data, max_pages=max_pages)
@@ -170,7 +305,7 @@ def analyze_corrections_letter(
     if not key:
         return {"error": f"No API key for {provider}. Pass api_key or set the env var."}
     jur = _jur(municipality)
-    skills, loose = eng.load_knowledge(BASE_DIR)
+    skills, loose = eng.load_knowledge(BASE_DIR, jurisdiction=_slug(municipality))
     sk = [x for t in eng.discover_tracks(skills).values() for x in t["skills"]]
     sources = [s for x in sk for s in x.sources]
     data = base64.b64decode(letter_base64)
@@ -204,7 +339,7 @@ def generate_checklist(
     if not key:
         return {"error": f"No API key for {provider}. Pass api_key or set the env var."}
     jur = _jur(municipality)
-    _, _, tracks, tr = _load(review_track)
+    _, _, tracks, tr = _load(review_track, municipality)
     result = eng.run_checklist(provider, model, key, tr["skills"],
                                {"label": tr["label"], "scope": tr["scope"]},
                                project_desc=project_description, base_url=base_url, jur=jur)
@@ -224,7 +359,16 @@ async def _landing(request):
 
     choices = list_jurisdictions(BASE_DIR)
     muns = ", ".join(s for s in choices if not s.startswith("_") and s != "default") or "—"
+    # HF Spaces terminates TLS at its proxy, so request.base_url reports http://
+    # inside the container. Emitting that URL makes clients (e.g. HuggingChat)
+    # reject it as insecure — honour the forwarded proto and default to https.
     base = str(request.base_url).rstrip("/")
+    proto = request.headers.get("x-forwarded-proto", "")
+    host = request.headers.get("host", "")
+    if proto:
+        base = f"{proto}://{host}"
+    elif base.startswith("http://") and not host.startswith(("localhost", "127.0.0.1")):
+        base = "https://" + base[len("http://"):]
     rows = "".join(
         f"<tr><td><code>{n}</code></td><td>{d}</td></tr>" for n, d in [
             ("list_municipalities", "Configured jurisdictions + their frameworks"),