Upload 6 files

README.md

@@ -1,13 +1,68 @@
----
-title: Exercise 3
-emoji: 🐢
-colorFrom: pink
-colorTo: pink
+---
+title: Apartment
+emoji: 🏠
+colorFrom: red
+colorTo: gray
 sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
+sdk_version: 6.13.0
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Apartment Predictor (Numeric Model + LLM)
+
+This Space demonstrates the Week 2 AI Applications pattern:
+
+- natural language apartment wishes
+- structured extraction (`rooms`, `area_m2`, `town`)
+- reuse of an existing pickled random forest model
+- LLM explanation of the result
+
+Because the data is Swiss, students should write prompts in German so town names like `Zürich` match the dataset more reliably.
+
+## Student workflow
+
+- Build logic in notebook (`week2/ai_applications_exercise2.ipynb`)
+- Reuse the provided saved model file `random_forest_regression.pkl`
+- Implement TODOs in `app_student.py` (any LLM provider is allowed)
+- Promote finished code to `app.py` for deployment
+- Deploy the app to Hugging Face Spaces
+- Complete `documentation.md`
+
+## What To Submit
+
+Your submission for this exercise should include:
+
+- a working deployed app on Hugging Face Spaces
+- your finished code files
+- a completed `documentation.md`
+
+In `documentation.md`, document what you built, how your prompts work, how you tested the app, and what happened during deployment.
+
+You must also include **2 screenshots** from your app:
+
+- 2 different example inputs
+- visible extracted JSON
+- visible prediction
+- visible final explanation text
+
+## LLM policy in this exercise
+
+- LLM usage is mandatory.
+- No fallback path is allowed for extraction/explanation.
+- Errors should stay visible so issues can be debugged.
+
+## Reference solution details
+
+- `app.py` is an OpenAI-based reference implementation.
+- It expects `OPENAI_API_KEY` (and optional `OPENAI_MODEL`).
+
+## Required files
+
+- `app.py`
+- `app_student.py`
+- `requirements.txt`
+- `random_forest_regression.pkl`
+- `bfs_municipality_and_tax_data.csv`
+
+See `NOTEBOOK_TO_APP.md` for the transfer checklist.

app.py

@@ -0,0 +1,319 @@
+import json
+import os
+import pickle
+from pathlib import Path
+
+import gradio as gr
+import numpy as np
+import pandas as pd
+from openai import OpenAI
+
+MODEL_PATH = Path("random_forest_regression.pkl")
+DATA_PATH = Path("bfs_municipality_and_tax_data.csv")
+
+# Hugging Face Secrets / local environment variables
+# Required secret on Hugging Face: OPENAI_API_KEY
+# Optional variable/secret: OPENAI_MODEL, e.g. gpt-4.1-mini
+LLM_API_KEY = os.getenv("OPENAI_API_KEY", "")
+LLM_MODEL = os.getenv("OPENAI_MODEL", "gpt-4.1-mini")
+
+
+def load_model_and_data():
+    if not MODEL_PATH.exists():
+        raise FileNotFoundError(
+            f"Missing model file: {MODEL_PATH}. Upload random_forest_regression.pkl to the same folder as app.py."
+        )
+    if not DATA_PATH.exists():
+        raise FileNotFoundError(
+            f"Missing data file: {DATA_PATH}. Upload bfs_municipality_and_tax_data.csv to the same folder as app.py."
+        )
+
+    with open(MODEL_PATH, "rb") as model_file:
+        loaded_model = pickle.load(model_file)
+
+    bfs_data = pd.read_csv(DATA_PATH, sep=",", encoding="utf-8")
+    bfs_data["tax_income"] = (
+        bfs_data["tax_income"].astype(str).str.replace("'", "", regex=False).astype(float)
+    )
+
+    return loaded_model, bfs_data
+
+
+model, df_bfs_data = load_model_and_data()
+
+town_to_row = {
+    str(row["bfs_name"]).strip().lower(): row
+    for _, row in df_bfs_data.iterrows()
+}
+valid_towns = list(df_bfs_data["bfs_name"].sort_values().unique())
+
+
+def match_town(user_town: str):
+    """Match user town text to the canonical bfs_name in the CSV."""
+    if not user_town:
+        return None
+
+    query = str(user_town).strip().lower()
+    if not query:
+        return None
+
+    # 1) Exact lower-case match
+    if query in town_to_row:
+        return town_to_row[query]["bfs_name"]
+
+    # 2) Relaxed contains matching
+    matches = []
+    for town in valid_towns:
+        town_lower = str(town).strip().lower()
+        if query == town_lower:
+            return town
+        if query in town_lower or town_lower in query:
+            matches.append(town)
+
+    # Avoid silently choosing between ambiguous towns
+    if len(matches) == 1:
+        return matches[0]
+
+    return None
+
+
+def call_llm_json(system_prompt: str, user_prompt: str) -> str:
+    """Call OpenAI and require a JSON object response."""
+    if not LLM_API_KEY:
+        raise RuntimeError(
+            "OPENAI_API_KEY is missing. Add it in Hugging Face under Settings -> Variables and secrets."
+        )
+    if not LLM_MODEL:
+        raise RuntimeError("OPENAI_MODEL is missing. Example value: gpt-4.1-mini")
+
+    client = OpenAI(api_key=LLM_API_KEY)
+
+    response = client.responses.create(
+        model=LLM_MODEL,
+        input=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+        text={"format": {"type": "json_object"}},
+    )
+
+    return response.output_text
+
+
+def parse_json_response(raw: str, required_keys: tuple[str, ...]) -> dict:
+    cleaned = (raw or "").strip()
+
+    if not cleaned:
+        raise ValueError("LLM returned an empty response instead of JSON.")
+
+    try:
+        parsed = json.loads(cleaned)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"LLM did not return valid JSON. Received: {cleaned[:300]}"
+        ) from exc
+
+    missing_keys = [key for key in required_keys if key not in parsed]
+    if missing_keys:
+        raise ValueError(
+            f"LLM JSON is missing required keys: {', '.join(missing_keys)}."
+        )
+
+    return parsed
+
+
+def extract_preferences(user_text: str) -> dict:
+    """Extract rooms, area_m2 and town from German free text using an LLM."""
+    if not user_text or not user_text.strip():
+        raise ValueError(
+            "Bitte gib einen Wohnungswunsch mit Zimmeranzahl, Fläche und Ort ein."
+        )
+
+    system_prompt = """
+Du bist ein Extraktionssystem für Schweizer Wohnungswünsche.
+
+Extrahiere aus dem Nutzereingabetext exakt diese Informationen:
+- rooms: Anzahl Zimmer als Zahl, zum Beispiel 3.5
+- area_m2: Wohnfläche in Quadratmetern als Zahl, zum Beispiel 85
+- town: Schweizer Gemeinde / Ort als String, zum Beispiel "Winterthur"
+
+Antworte ausschliesslich mit gültigem JSON.
+Keine Markdown-Codeblöcke.
+Keine Erklärungen.
+Keine zusätzlichen Schlüssel.
+Wenn ein Wert fehlt, verwende null.
+
+Erwartetes Format:
+{"rooms": 3.5, "area_m2": 85, "town": "Winterthur"}
+"""
+
+    user_prompt = f"""
+Extrahiere rooms, area_m2 und town aus folgendem deutschen Wohnungswunsch:
+
+{user_text}
+"""
+
+    raw = call_llm_json(system_prompt, user_prompt)
+    parsed = parse_json_response(raw, required_keys=("rooms", "area_m2", "town"))
+
+    rooms = parsed["rooms"]
+    area_m2 = parsed["area_m2"]
+    town = parsed["town"]
+
+    if rooms is None or area_m2 is None or town is None:
+        raise ValueError("Bitte gib Zimmeranzahl, Wohnfläche in m2 und Ort an.")
+
+    try:
+        rooms = float(rooms)
+        area_m2 = float(area_m2)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            "Zimmeranzahl und Wohnfläche müssen als Zahlen erkannt werden."
+        ) from exc
+
+    if rooms <= 0:
+        raise ValueError("Die Zimmeranzahl muss grösser als 0 sein.")
+    if area_m2 <= 0:
+        raise ValueError("Die Wohnfläche muss grösser als 0 sein.")
+
+    canonical_town = match_town(town)
+    if canonical_town is None:
+        raise ValueError(
+            f"Ort '{town}' wurde nicht eindeutig in den BFS-Daten gefunden. "
+            "Bitte verwende einen gültigen Schweizer Gemeindenamen aus dem Datensatz."
+        )
+
+    return {
+        "rooms": rooms,
+        "area_m2": area_m2,
+        "town": canonical_town,
+    }
+
+
+def predict_apartment_price(rooms: float, area_m2: float, town: str) -> float:
+    """Predict monthly rent with exactly these model features:
+    [rooms, area_m2, pop, pop_dens, frg_pct, emp, tax_income]
+    """
+    canonical_town = match_town(town)
+    if canonical_town is None:
+        raise ValueError(f"Ort '{town}' wurde nicht gefunden.")
+
+    row = town_to_row[canonical_town.lower()]
+
+    features = np.array(
+        [[
+            float(rooms),
+            float(area_m2),
+            float(row["pop"]),
+            float(row["pop_dens"]),
+            float(row["frg_pct"]),
+            float(row["emp"]),
+            float(row["tax_income"]),
+        ]]
+    )
+
+    prediction = model.predict(features)[0]
+    return round(float(prediction), 2)
+
+
+def generate_explanation(preferences: dict, prediction: float) -> str:
+    """Generate a concise German explanation with one uncertainty note using an LLM."""
+    system_prompt = """
+Du bist ein hilfreicher Assistent für Wohnungsmietpreise in der Schweiz.
+
+Deine Aufgabe:
+Erkläre die gegebene Modellschätzung kurz und verständlich auf Deutsch.
+
+Wichtige Regeln:
+- Verwende die angegebene Prediction.
+- Berechne keinen neuen Preis.
+- Erfinde keine zusätzlichen Daten.
+- Erwähne Zimmeranzahl, Fläche und Ort.
+- Füge einen kurzen Unsicherheitshinweis hinzu.
+- Sage, dass es sich um eine Schätzung handelt.
+- Antworte ausschliesslich mit gültigem JSON.
+- Verwende exakt den Schlüssel "answer".
+
+Erwartetes Format:
+{"answer": "Für eine 3.5-Zimmer-Wohnung mit 85 m2 in Winterthur schätzt das Modell die Monatsmiete auf rund 2800 CHF. Die Schätzung ist unsicher, weil Faktoren wie Zustand, Mikrolage und Ausstattung nicht direkt berücksichtigt werden."}
+"""
+
+    user_prompt = f"""
+Wohnungsdaten:
+{json.dumps(preferences, ensure_ascii=False)}
+
+Modellschätzung der monatlichen Miete in CHF:
+{prediction}
+
+Formuliere eine kurze deutsche Antwort.
+"""
+
+    raw = call_llm_json(system_prompt, user_prompt)
+    parsed = parse_json_response(raw, required_keys=("answer",))
+
+    answer = parsed["answer"]
+    if not answer:
+        raise ValueError("LLM explanation returned an empty answer.")
+
+    return str(answer)
+
+
+def run_pipeline(user_text: str):
+    """End-to-end app pipeline."""
+    try:
+        preferences = extract_preferences(user_text)
+        prediction = predict_apartment_price(
+            rooms=preferences["rooms"],
+            area_m2=preferences["area_m2"],
+            town=preferences["town"],
+        )
+        final_answer = generate_explanation(
+            preferences=preferences,
+            prediction=prediction,
+        )
+        return preferences, prediction, final_answer
+
+    except Exception as exc:
+        return (
+            {
+                "error": str(exc),
+                "hint": "Bitte gib Zimmeranzahl, Wohnfläche in m2 und einen Schweizer Ort an.",
+            },
+            None,
+            f"Fehler: {exc}",
+        )
+
+
+with gr.Blocks(title="Apartment Wishes -> Prediction") as demo:
+    gr.Markdown(
+        """
+        # Apartment Predictor
+
+        Beschreibe den Wohnungswunsch bitte auf Deutsch.
+
+        Beispiel:  
+        **"Ich suche eine 3.5-Zimmer-Wohnung mit etwa 85 m2 in Winterthur."**
+        """
+    )
+
+    user_text = gr.Textbox(
+        label="Wohnungswunsch",
+        lines=4,
+        placeholder="Beschreibe Zimmer, Fläche in m2 und Ort auf Deutsch...",
+    )
+
+    submit = gr.Button("Schätzen")
+
+    extracted = gr.JSON(label="Extrahierte Eingaben")
+    price = gr.Number(label="Geschätzte Monatsmiete (CHF)")
+    response = gr.Textbox(label="Antwort", lines=6)
+
+    submit.click(
+        fn=run_pipeline,
+        inputs=[user_text],
+        outputs=[extracted, price, response],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

app_student.py

@@ -0,0 +1,319 @@
+import json
+import os
+import pickle
+from pathlib import Path
+
+import gradio as gr
+import numpy as np
+import pandas as pd
+from openai import OpenAI
+
+MODEL_PATH = Path("random_forest_regression.pkl")
+DATA_PATH = Path("bfs_municipality_and_tax_data.csv")
+
+# Hugging Face Secrets / local environment variables
+# Required secret on Hugging Face: OPENAI_API_KEY
+# Optional variable/secret: OPENAI_MODEL, e.g. gpt-4.1-mini
+LLM_API_KEY = os.getenv("OPENAI_API_KEY", "")
+LLM_MODEL = os.getenv("OPENAI_MODEL", "gpt-4.1-mini")
+
+
+def load_model_and_data():
+    if not MODEL_PATH.exists():
+        raise FileNotFoundError(
+            f"Missing model file: {MODEL_PATH}. Upload random_forest_regression.pkl to the same folder as app.py."
+        )
+    if not DATA_PATH.exists():
+        raise FileNotFoundError(
+            f"Missing data file: {DATA_PATH}. Upload bfs_municipality_and_tax_data.csv to the same folder as app.py."
+        )
+
+    with open(MODEL_PATH, "rb") as model_file:
+        loaded_model = pickle.load(model_file)
+
+    bfs_data = pd.read_csv(DATA_PATH, sep=",", encoding="utf-8")
+    bfs_data["tax_income"] = (
+        bfs_data["tax_income"].astype(str).str.replace("'", "", regex=False).astype(float)
+    )
+
+    return loaded_model, bfs_data
+
+
+model, df_bfs_data = load_model_and_data()
+
+town_to_row = {
+    str(row["bfs_name"]).strip().lower(): row
+    for _, row in df_bfs_data.iterrows()
+}
+valid_towns = list(df_bfs_data["bfs_name"].sort_values().unique())
+
+
+def match_town(user_town: str):
+    """Match user town text to the canonical bfs_name in the CSV."""
+    if not user_town:
+        return None
+
+    query = str(user_town).strip().lower()
+    if not query:
+        return None
+
+    # 1) Exact lower-case match
+    if query in town_to_row:
+        return town_to_row[query]["bfs_name"]
+
+    # 2) Relaxed contains matching
+    matches = []
+    for town in valid_towns:
+        town_lower = str(town).strip().lower()
+        if query == town_lower:
+            return town
+        if query in town_lower or town_lower in query:
+            matches.append(town)
+
+    # Avoid silently choosing between ambiguous towns
+    if len(matches) == 1:
+        return matches[0]
+
+    return None
+
+
+def call_llm_json(system_prompt: str, user_prompt: str) -> str:
+    """Call OpenAI and require a JSON object response."""
+    if not LLM_API_KEY:
+        raise RuntimeError(
+            "OPENAI_API_KEY is missing. Add it in Hugging Face under Settings -> Variables and secrets."
+        )
+    if not LLM_MODEL:
+        raise RuntimeError("OPENAI_MODEL is missing. Example value: gpt-4.1-mini")
+
+    client = OpenAI(api_key=LLM_API_KEY)
+
+    response = client.responses.create(
+        model=LLM_MODEL,
+        input=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ],
+        text={"format": {"type": "json_object"}},
+    )
+
+    return response.output_text
+
+
+def parse_json_response(raw: str, required_keys: tuple[str, ...]) -> dict:
+    cleaned = (raw or "").strip()
+
+    if not cleaned:
+        raise ValueError("LLM returned an empty response instead of JSON.")
+
+    try:
+        parsed = json.loads(cleaned)
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"LLM did not return valid JSON. Received: {cleaned[:300]}"
+        ) from exc
+
+    missing_keys = [key for key in required_keys if key not in parsed]
+    if missing_keys:
+        raise ValueError(
+            f"LLM JSON is missing required keys: {', '.join(missing_keys)}."
+        )
+
+    return parsed
+
+
+def extract_preferences(user_text: str) -> dict:
+    """Extract rooms, area_m2 and town from German free text using an LLM."""
+    if not user_text or not user_text.strip():
+        raise ValueError(
+            "Bitte gib einen Wohnungswunsch mit Zimmeranzahl, Fläche und Ort ein."
+        )
+
+    system_prompt = """
+Du bist ein Extraktionssystem für Schweizer Wohnungswünsche.
+
+Extrahiere aus dem Nutzereingabetext exakt diese Informationen:
+- rooms: Anzahl Zimmer als Zahl, zum Beispiel 3.5
+- area_m2: Wohnfläche in Quadratmetern als Zahl, zum Beispiel 85
+- town: Schweizer Gemeinde / Ort als String, zum Beispiel "Winterthur"
+
+Antworte ausschliesslich mit gültigem JSON.
+Keine Markdown-Codeblöcke.
+Keine Erklärungen.
+Keine zusätzlichen Schlüssel.
+Wenn ein Wert fehlt, verwende null.
+
+Erwartetes Format:
+{"rooms": 3.5, "area_m2": 85, "town": "Winterthur"}
+"""
+
+    user_prompt = f"""
+Extrahiere rooms, area_m2 und town aus folgendem deutschen Wohnungswunsch:
+
+{user_text}
+"""
+
+    raw = call_llm_json(system_prompt, user_prompt)
+    parsed = parse_json_response(raw, required_keys=("rooms", "area_m2", "town"))
+
+    rooms = parsed["rooms"]
+    area_m2 = parsed["area_m2"]
+    town = parsed["town"]
+
+    if rooms is None or area_m2 is None or town is None:
+        raise ValueError("Bitte gib Zimmeranzahl, Wohnfläche in m2 und Ort an.")
+
+    try:
+        rooms = float(rooms)
+        area_m2 = float(area_m2)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            "Zimmeranzahl und Wohnfläche müssen als Zahlen erkannt werden."
+        ) from exc
+
+    if rooms <= 0:
+        raise ValueError("Die Zimmeranzahl muss grösser als 0 sein.")
+    if area_m2 <= 0:
+        raise ValueError("Die Wohnfläche muss grösser als 0 sein.")
+
+    canonical_town = match_town(town)
+    if canonical_town is None:
+        raise ValueError(
+            f"Ort '{town}' wurde nicht eindeutig in den BFS-Daten gefunden. "
+            "Bitte verwende einen gültigen Schweizer Gemeindenamen aus dem Datensatz."
+        )
+
+    return {
+        "rooms": rooms,
+        "area_m2": area_m2,
+        "town": canonical_town,
+    }
+
+
+def predict_apartment_price(rooms: float, area_m2: float, town: str) -> float:
+    """Predict monthly rent with exactly these model features:
+    [rooms, area_m2, pop, pop_dens, frg_pct, emp, tax_income]
+    """
+    canonical_town = match_town(town)
+    if canonical_town is None:
+        raise ValueError(f"Ort '{town}' wurde nicht gefunden.")
+
+    row = town_to_row[canonical_town.lower()]
+
+    features = np.array(
+        [[
+            float(rooms),
+            float(area_m2),
+            float(row["pop"]),
+            float(row["pop_dens"]),
+            float(row["frg_pct"]),
+            float(row["emp"]),
+            float(row["tax_income"]),
+        ]]
+    )
+
+    prediction = model.predict(features)[0]
+    return round(float(prediction), 2)
+
+
+def generate_explanation(preferences: dict, prediction: float) -> str:
+    """Generate a concise German explanation with one uncertainty note using an LLM."""
+    system_prompt = """
+Du bist ein hilfreicher Assistent für Wohnungsmietpreise in der Schweiz.
+
+Deine Aufgabe:
+Erkläre die gegebene Modellschätzung kurz und verständlich auf Deutsch.
+
+Wichtige Regeln:
+- Verwende die angegebene Prediction.
+- Berechne keinen neuen Preis.
+- Erfinde keine zusätzlichen Daten.
+- Erwähne Zimmeranzahl, Fläche und Ort.
+- Füge einen kurzen Unsicherheitshinweis hinzu.
+- Sage, dass es sich um eine Schätzung handelt.
+- Antworte ausschliesslich mit gültigem JSON.
+- Verwende exakt den Schlüssel "answer".
+
+Erwartetes Format:
+{"answer": "Für eine 3.5-Zimmer-Wohnung mit 85 m2 in Winterthur schätzt das Modell die Monatsmiete auf rund 2800 CHF. Die Schätzung ist unsicher, weil Faktoren wie Zustand, Mikrolage und Ausstattung nicht direkt berücksichtigt werden."}
+"""
+
+    user_prompt = f"""
+Wohnungsdaten:
+{json.dumps(preferences, ensure_ascii=False)}
+
+Modellschätzung der monatlichen Miete in CHF:
+{prediction}
+
+Formuliere eine kurze deutsche Antwort.
+"""
+
+    raw = call_llm_json(system_prompt, user_prompt)
+    parsed = parse_json_response(raw, required_keys=("answer",))
+
+    answer = parsed["answer"]
+    if not answer:
+        raise ValueError("LLM explanation returned an empty answer.")
+
+    return str(answer)
+
+
+def run_pipeline(user_text: str):
+    """End-to-end app pipeline."""
+    try:
+        preferences = extract_preferences(user_text)
+        prediction = predict_apartment_price(
+            rooms=preferences["rooms"],
+            area_m2=preferences["area_m2"],
+            town=preferences["town"],
+        )
+        final_answer = generate_explanation(
+            preferences=preferences,
+            prediction=prediction,
+        )
+        return preferences, prediction, final_answer
+
+    except Exception as exc:
+        return (
+            {
+                "error": str(exc),
+                "hint": "Bitte gib Zimmeranzahl, Wohnfläche in m2 und einen Schweizer Ort an.",
+            },
+            None,
+            f"Fehler: {exc}",
+        )
+
+
+with gr.Blocks(title="Apartment Wishes -> Prediction") as demo:
+    gr.Markdown(
+        """
+        # Apartment Predictor
+
+        Beschreibe den Wohnungswunsch bitte auf Deutsch.
+
+        Beispiel:  
+        **"Ich suche eine 3.5-Zimmer-Wohnung mit etwa 85 m2 in Winterthur."**
+        """
+    )
+
+    user_text = gr.Textbox(
+        label="Wohnungswunsch",
+        lines=4,
+        placeholder="Beschreibe Zimmer, Fläche in m2 und Ort auf Deutsch...",
+    )
+
+    submit = gr.Button("Schätzen")
+
+    extracted = gr.JSON(label="Extrahierte Eingaben")
+    price = gr.Number(label="Geschätzte Monatsmiete (CHF)")
+    response = gr.Textbox(label="Antwort", lines=6)
+
+    submit.click(
+        fn=run_pipeline,
+        inputs=[user_text],
+        outputs=[extracted, price, response],
+    )
+
+
+if __name__ == "__main__":
+    demo.launch()

documentation.md

@@ -0,0 +1,204 @@
+# Documentation
+## Week 2: Apartment Predictor (Saved Regression Model + LLM Workflow)
+
+This file documents the apartment prediction application that combines a saved regression model with an LLM workflow.
+
+---
+
+## 1. Project Summary
+
+The app accepts a German free-text apartment request, for example: "Ich suche eine 3.5-Zimmer-Wohnung mit 85 m2 in Winterthur." An LLM extracts the structured parameters `rooms`, `area_m2`, and `town` from the text. The app then uses a saved random forest regression model to estimate the monthly rent in CHF. A second LLM step turns the numeric prediction into a short German explanation with an uncertainty note.
+
+---
+
+## 2. Files Used
+
+| File | Purpose |
+|------|---------|
+| `ai_applications_exercise2.ipynb` | Notebook work and testing during the exercise |
+| `app_student.py` | Student implementation with completed TODOs |
+| `app.py` | Final deployable Gradio app for Hugging Face Spaces |
+| `random_forest_regression.pkl` | Saved regression model used for numeric prediction |
+| `bfs_municipality_and_tax_data.csv` | Municipality features used for prediction |
+| `requirements.txt` | Python dependencies for the Space |
+| `README.md` | Hugging Face Space configuration and project summary |
+| `documentation.md` | Written documentation for the submission |
+| `screenshot1.png` | First screenshot from the running app |
+| `screenshot2.png` | Second screenshot from the running app |
+
+---
+
+## 3. Numeric Prediction Part
+
+### 3.1 Reused Model
+
+**Which saved model did you use?**  
+`random_forest_regression.pkl`
+
+**What does the model predict?**  
+The model predicts the estimated monthly rent of an apartment in CHF. The prediction is based on apartment size information and municipality-level data.
+
+**Which input features are used for prediction?**
+
+The model input uses the seven features in this exact order:
+
+1. `rooms`
+2. `area_m2`
+3. `pop`
+4. `pop_dens`
+5. `frg_pct`
+6. `emp`
+7. `tax_income`
+
+### 3.2 Prediction Logic
+
+The user provides `rooms`, `area_m2`, and `town` in natural language. The LLM extracts these values as JSON. Python then matches the extracted town name to the canonical `bfs_name` in `bfs_municipality_and_tax_data.csv`. The app reads the municipality values `pop`, `pop_dens`, `frg_pct`, `emp`, and `tax_income` from the matching CSV row. These values are combined with `rooms` and `area_m2` into a NumPy array and passed to the saved regression model.
+
+---
+
+## 4. LLM Extraction Part
+
+### 4.1 Goal
+
+The first LLM step extracts structured model inputs from a German apartment request. It must return the number of rooms, the apartment area in square meters, and the town name.
+
+### 4.2 Prompt Design
+
+The extraction prompt tells the LLM that it is an extraction system for Swiss apartment wishes. The prompt requires strict JSON and explicitly lists the required keys: `rooms`, `area_m2`, and `town`. It also tells the model not to return Markdown, explanations, or additional keys. If a value is missing, the LLM is instructed to use `null`.
+
+### 4.3 Expected Output Format
+
+```json
+{"rooms": 3.5, "area_m2": 85, "town": "Winterthur"}
+```
+
+### 4.4 Validation
+
+The app validates the LLM output with `parse_json_response`. This function checks that the response is not empty, that it is valid JSON, and that all required keys are present. The app also converts `rooms` and `area_m2` to numbers and checks that they are greater than zero. The extracted town is matched against the BFS municipality data before the prediction is made.
+
+---
+
+## 5. LLM Explanation Part
+
+### 5.1 Goal
+
+The second LLM step generates a short natural-language answer in German. It explains the model prediction to the user. The LLM should not calculate a new price; it should use the prediction value that was produced by the regression model.
+
+### 5.2 Prompt Design
+
+The explanation prompt includes the structured preferences and the predicted rent. The prompt instructs the LLM to write in German, mention the number of rooms, area, and town, and include a short uncertainty note. The answer is also required to be valid JSON with the key `answer`.
+
+### 5.3 Expected Output Format
+
+```json
+{"answer": "Für eine 3.5-Zimmer-Wohnung mit 85 m2 in Winterthur schätzt das Modell die Monatsmiete auf rund 2800 CHF. Die Schätzung ist unsicher, weil Faktoren wie Zustand, Mikrolage und Ausstattung nicht direkt berücksichtigt werden."}
+```
+
+---
+
+## 6. End-to-End Pipeline
+
+1. The user enters a German apartment request.
+2. The LLM extracts `rooms`, `area_m2`, and `town` as JSON.
+3. Python validates the JSON and converts the numeric values.
+4. Python matches the town name to the BFS municipality data.
+5. The app builds the seven-feature model input.
+6. The saved random forest regression model predicts the monthly rent.
+7. The second LLM step generates a short German explanation.
+8. The Gradio app returns the extracted JSON, the predicted rent, and the final explanation text.
+
+---
+
+## 7. Test Cases
+
+| Test Input | Extracted Output Correct? | Prediction Returned? | Explanation Returned? | Notes |
+|------------|----------------------------|----------------------|-----------------------|-------|
+| `Ich suche eine 3.5-Zimmer-Wohnung mit 85 m2 in Winterthur.` | Yes | Yes | Yes | The app extracted the apartment size and town and returned a German explanation. |
+| `Wie viel kostet ungefähr eine 2-Zimmer-Wohnung mit 55 Quadratmetern in Zürich?` | Yes | Yes | Yes | The LLM extracted `rooms`, `area_m2`, and `town`; the model returned a rent estimate. |
+| `Ich interessiere mich für eine 4.5 Zimmer Wohnung mit 110 m2 in Bern.` | Yes | Yes | Yes | The app handled another Swiss city and produced the full output pipeline. |
+
+---
+
+## 8. Errors and Problems
+
+**Problem:** The app failed locally with `FileNotFoundError: random_forest_regression.pkl`.  
+**Cause:** The saved model file was not in the same folder as `app.py`.  
+**Fix:** I added `random_forest_regression.pkl` to the project folder before running and deploying the app.
+
+**Problem:** The LLM could return invalid or incomplete JSON.  
+**Cause:** LLM output is not guaranteed unless the prompt and API response format are strict.  
+**Fix:** The app uses JSON mode and validates the response with `parse_json_response`.
+
+**Problem:** Invalid or ambiguous town names may not match the BFS CSV.  
+**Cause:** The model requires municipality-level features from the CSV.  
+**Fix:** The app first tries exact town matching and then relaxed contains matching. Ambiguous or missing towns return a visible error.
+
+**Problem:** The Space may fail if the API key is missing.  
+**Cause:** The LLM steps require an OpenAI API key.  
+**Fix:** I added `OPENAI_API_KEY` as a Hugging Face Space Secret.
+
+---
+
+## 9. Deployment Notes
+
+### 9.1 Files included
+
+The Hugging Face Space contains:
+
+- `app.py`
+- `app_student.py`
+- `README.md`
+- `requirements.txt`
+- `documentation.md`
+- `bfs_municipality_and_tax_data.csv`
+- `random_forest_regression.pkl`
+- `screenshot1.png`
+- `screenshot2.png`
+
+### 9.2 Secrets / Environment Variables
+
+The app requires this Hugging Face Secret:
+
+- `OPENAI_API_KEY`
+
+Optional:
+
+- `OPENAI_MODEL`, for example `gpt-4.1-mini`
+
+### 9.3 Deployment Result
+
+The Space was deployed as a Gradio application. After uploading all required files and setting the OpenAI API key, the app started successfully and returned the extracted JSON, the predicted rent, and the final German explanation.
+
+### 9.4 Screenshots
+
+Add the two screenshots from the running Hugging Face Space here after deployment:
+
+```md
+![Example 1](screenshot1.png)
+
+In this example, the app extracted the apartment request as JSON, predicted the monthly rent, and generated a German explanation.
+
+![Example 2](screenshot2.png)
+
+In this example, a different German apartment request was used. The screenshot shows the extracted JSON, predicted rent, and final answer.
+```
+
+![Example 1](screenshot1.png)
+
+In this example, the app extracted the apartment request as JSON, predicted the monthly rent, and generated a German explanation.
+
+![Example 2](screenshot2.png)
+
+In this example, a different German apartment request was used. The screenshot shows the extracted JSON, predicted rent, and final answer.
+
+---
+
+## 10. Reflection
+
+The combination of a regression model and an LLM worked well because the LLM made the app easier to use with natural German input. The numeric prediction stayed inside the saved model, while the LLM handled text extraction and explanation. The system is still fragile because wrong town names, missing values, or invalid JSON can stop the pipeline. German input is important because the dataset contains Swiss municipality names and the expected users describe apartments in German. In a future version, I would add more apartment features such as floor, building condition, balcony, public transport access, and exact location.
+
+---
+
+## 11. Responsible Use Note
+
+The predicted rent is only an estimate and should not be treated as a guaranteed market price. The model uses a limited set of structured features and does not directly include factors such as apartment condition, exact address, renovation status, balcony, view, or micro-location. The LLM may also extract values incorrectly, so the visible JSON output should always be checked. The app is useful for learning and experimentation, but not for final financial or rental decisions.

requirements.txt

@@ -0,0 +1,5 @@
+openai==2.33.0
+scikit-learn==1.8.0
+numpy
+pandas
+gradio