nouri-App/HOME_ASSISTANT.md

Home Assistant

Nouri stellt für Home Assistant eine kleine token-geschützte JSON-API bereit. Sie ist für Sprachbefehle wie diese gedacht:

• Füge Erbsen auf die Einkaufsliste hinzu
• Füge Erbsen mit Hinweis TK auf die Einkaufsliste hinzu
• Füge Blumenerde als Einkaufsartikel hinzu
• Füge Skyr als Lebensmittel hinzu

Nouri konfigurieren

Setze in der Nouri-Umgebung:

NOURI_HA_TOKEN=<langes-zufälliges-token>
NOURI_HA_USER_ID=<optionale-nouri-user-id>

NOURI_HA_USER_ID ist optional. Ohne diesen Wert nutzt Nouri zuerst den ersten aktiven Admin und danach den ersten aktiven Nutzer.

Lokal zum Testen:

export NOURI_HA_TOKEN='ein-langes-zufälliges-token'
flask --app wsgi run --debug

Auf Cloudron:

cloudron env set --app <nouri-app> NOURI_HA_TOKEN='ein-langes-zufälliges-token'
cloudron restart --app <nouri-app>

Home Assistant vorbereiten

Lege in Home Assistant in secrets.yaml diese Werte an:

nouri_ha_token: ein-langes-zufälliges-token
nouri_url: https://deine-nouri-domain.example.org

Wenn Home Assistant lokal auf Nouri zugreift, nimm die aus Home Assistant erreichbare Adresse, zum Beispiel:

nouri_url: http://192.168.178.50:5000

127.0.0.1 funktioniert nur, wenn Home Assistant und Nouri im selben Prozess- oder Container-Kontext laufen.

Eintrag hinzufügen

POST /api/home-assistant/shopping
Authorization: Bearer <NOURI_HA_TOKEN>
Content-Type: application/json

{
  "name": "Erbsen",
  "note": "TK"
}

Wenn Nouri den Eintrag kennt, wird er direkt auf die Einkaufsliste gesetzt. note landet im bestehenden Feld Einkaufshinweis.

Wenn Nouri den Eintrag nicht kennt, kommt eine Rückfrage-Antwort:

{
  "ok": true,
  "status": "needs_confirmation",
  "name": "Erbsen",
  "note": "TK",
  "options": ["food", "shopping"],
  "message": "Erbsen kenne ich noch nicht. Soll ich es als Lebensmittel oder Einkaufsartikel anlegen?"
}

Rückfrage bestätigen

POST /api/home-assistant/shopping/confirm
Authorization: Bearer <NOURI_HA_TOKEN>
Content-Type: application/json

{
  "name": "Erbsen",
  "note": "TK",
  "create_as": "food"
}

Mögliche Werte für create_as:

• food für Lebensmittel
• shopping für reine Einkaufsartikel

Alternativ kann der erste Endpoint mit confirm_create: true verwendet werden:

{
  "name": "Blumenerde",
  "create_as": "shopping",
  "confirm_create": true
}

REST Commands

Trage in configuration.yaml ein:

rest_command:
  nouri_shopping:
    url: "{{ url }}/api/home-assistant/shopping"
    method: post
    headers:
      X-Nouri-Token: !secret nouri_ha_token
      Content-Type: "application/json"
    payload: >
      {
        "name": "{{ name }}",
        "note": "{{ note | default('') }}",
        "create_as": "{{ create_as | default('') }}",
        "confirm_create": {{ confirm_create | default(false) | tojson }}
      }

  nouri_shopping_confirm:
    url: "{{ url }}/api/home-assistant/shopping/confirm"
    method: post
    headers:
      X-Nouri-Token: !secret nouri_ha_token
      Content-Type: "application/json"
    payload: >
      {
        "name": "{{ name }}",
        "note": "{{ note | default('') }}",
        "create_as": "{{ create_as }}"
      }

Danach Home Assistant neu starten oder die YAML-Konfiguration neu laden.

Manuell testen

In Home Assistant:

1. Öffne Entwicklerwerkzeuge.
2. Öffne Aktionen.
3. Wähle rest_command.nouri_shopping.
4. Nutze zum Testen:

url: !secret nouri_url
name: Erbsen
note: TK

Wenn Erbsen in Nouri existiert, wird es auf die Einkaufsliste gesetzt. Wenn nicht, antwortet Nouri mit needs_confirmation.

Assist-Sprachsätze

Minimal in configuration.yaml:

conversation:
  intents:
    NouriShopping:
      - "füge {name} auf die einkaufsliste hinzu"
      - "füge {name} mit hinweis {note} auf die einkaufsliste hinzu"
      - "füge {name} als lebensmittel hinzu"
      - "füge {name} als einkaufsartikel hinzu"

Dazu ein Intent Script:

intent_script:
  NouriShopping:
    action:
      - action: rest_command.nouri_shopping
        data:
          url: !secret nouri_url
          name: "{{ name }}"
          note: "{{ note | default('') }}"
          create_as: >
            {% if 'lebensmittel' in text | default('') | lower %}food{% elif 'einkaufsartikel' in text | default('') | lower %}shopping{% else %}{% endif %}
          confirm_create: false
        response_variable: nouri_response
      - stop: "Nouri Antwort"
        response_variable: nouri_response
    speech:
      text: >
        {{ action_response.content.message }}

Rückfrage-Logik

Der erste Schritt ist damit fertig: bekannte Lebensmittel oder Einkaufsartikel landen direkt auf der Nouri-Einkaufsliste.

Wenn Nouri mit needs_confirmation antwortet, muss Home Assistant im nächsten Schritt nachfragen:

Soll ich das als Lebensmittel oder als Einkaufsartikel anlegen?

Danach ruft Home Assistant /api/home-assistant/shopping/confirm mit create_as: food oder create_as: shopping auf. Diese zweite Stufe kann je nach Setup über Assist, eine Automation, eine mobile Benachrichtigung oder später über Alexa umgesetzt werden.