shahar1 commented on code in PR #76157:
URL: https://github.com/apache/airflow/pull/76157#discussion_r4619775335


##########
providers/databricks/src/airflow/providers/databricks/operators/genie.py:
##########
@@ -0,0 +1,356 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Operators for asking Databricks Genie spaces questions as standalone 
tasks."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections.abc import Sequence
+from datetime import timedelta
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+from airflow.providers.common.compat.sdk import AirflowFailException, 
BaseOperator, ResumableJobMixin, conf
+from airflow.providers.databricks.hooks.genie import (
+    _PENDING_STATUSES,
+    DatabricksGenieError,
+    DatabricksGenieHook,
+    _truncate_result,
+)
+from airflow.providers.databricks.triggers.genie import 
DatabricksGenieMessageTrigger
+
+if TYPE_CHECKING:
+    from airflow.providers.common.compat.sdk import Context
+
+GenieMessageRef = dict[str, str]
+
+_NOT_FOUND = "NOT_FOUND"
+_STALE = "STALE"
+
+
+class DatabricksGenieOperator(ResumableJobMixin, BaseOperator):
+    """
+    Ask a Databricks Genie space one question and return a bounded, structured 
answer.
+
+    The operator submits the question once, persists the Genie conversation 
and message IDs to task
+    state before waiting, then polls (or defers) until the message finishes. A 
retry after a worker
+    crash or timeout reconnects to the stored message instead of asking again.
+
+    Genie has no idempotency key, so a submission whose outcome is unknown (a 
timeout, a connection
+    error or a 5xx response) cannot be told apart from one that was never 
received. The operator fails
+    without retrying in that case and the next try refuses to submit again; 
set ``conversation_id`` and
+    ``message_id`` to attach to the message you found, or 
``resubmit_unconfirmed=True`` to ask again.
+
+    .. seealso::
+        For more information on how to use this operator, take a look at the 
guide:
+        :ref:`howto/operator:DatabricksGenieOperator`
+
+    :param space_id: Genie space ID. (templated)
+    :param question: Question to ask. Required unless ``message_id`` is set. 
(templated)
+    :param databricks_conn_id: Databricks connection. Defaults to 
``databricks_default``. (templated)
+    :param conversation_id: Existing conversation to ask the question in. The 
operator never deletes it.
+        Defaults to ``None``, which starts a new conversation. An empty string 
means ``None``. (templated)
+    :param message_id: Existing message to wait for instead of asking a 
question. Requires
+        ``conversation_id``. An empty string means ``None``. (templated)
+    :param polling_period_seconds: Seconds between status checks. Defaults to 
``5``.
+    :param timeout: Maximum seconds to wait for the answer in one try. Timing 
out does not cancel the
+        message; the next try reconnects to it. Defaults to ``1800``.
+    :param resubmit_unconfirmed: Ask the question again even though an earlier 
submission's outcome is
+        unknown and may have created a message. Defaults to ``False``.
+    :param databricks_retry_limit: Attempts for each Genie read. Submissions 
are never retried.
+        Defaults to ``3``.
+    :param databricks_retry_delay: Minimum seconds between read attempts. 
Defaults to ``1``.
+    :param deferrable: Release the worker while waiting. Defaults to 
``[operators] default_deferrable``,
+        with a fallback of ``False``.
+    :param durable: When ``True`` (the default), the Genie message IDs are 
persisted to task state
+        before waiting so a retry reconnects instead of asking again. Requires 
Airflow 3.3+; on earlier
+        versions every try asks the question again.
+    """
+
+    template_fields: Sequence[str] = (
+        "space_id",
+        "question",
+        "databricks_conn_id",
+        "conversation_id",
+        "message_id",
+    )
+    ui_color = "#1CB1C2"
+    external_id_key = "databricks_genie_message"
+
+    def __init__(
+        self,
+        *,
+        space_id: str,
+        question: str | None = None,
+        databricks_conn_id: str = "databricks_default",
+        conversation_id: str | None = None,
+        message_id: str | None = None,
+        polling_period_seconds: float = 5,
+        timeout: float = 1800,
+        resubmit_unconfirmed: bool = False,
+        databricks_retry_limit: int = 3,
+        databricks_retry_delay: float = 1,
+        deferrable: bool = conf.getboolean("operators", "default_deferrable", 
fallback=False),
+        durable: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # Named here (not left to **kwargs) so default_args reaches it on 
every supported Airflow version.
+        if durable is not None:
+            kwargs["durable"] = durable
+        super().__init__(**kwargs)
+        if polling_period_seconds <= 0:
+            raise ValueError("polling_period_seconds must be positive")
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        self.space_id = space_id
+        self.question = question
+        self.databricks_conn_id = databricks_conn_id
+        self.conversation_id = conversation_id
+        self.message_id = message_id
+        self.polling_period_seconds = polling_period_seconds
+        self.timeout = timeout
+        self.resubmit_unconfirmed = resubmit_unconfirmed
+        self.databricks_retry_limit = databricks_retry_limit
+        self.databricks_retry_delay = databricks_retry_delay
+        self.deferrable = deferrable
+        self._result: dict[str, Any] | None = None
+
+    @cached_property
+    def hook(self) -> DatabricksGenieHook:
+        return DatabricksGenieHook(
+            self.databricks_conn_id,
+            retry_limit=self.databricks_retry_limit,
+            retry_delay=self.databricks_retry_delay,
+            caller=type(self).__name__,
+            poll_interval=self.polling_period_seconds,
+        )
+
+    @property
+    def _submission_key(self) -> str:
+        return f"{self.external_id_key}_submission"
+
+    def _fingerprint(self) -> str:
+        """Identify the question so a retry never reconnects to an answer for 
a different one."""
+        material = "\x1f".join((self.space_id, self.conversation_id or "", 
self.question or ""))
+        return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+    def _task_state_store(self, context: Context) -> Any:
+        return context.get("task_state_store") if self.durable else None
+
+    def _validate(self) -> None:
+        self.conversation_id = self.conversation_id or None
+        self.message_id = self.message_id or None
+        self.hook._validate_space_id(self.space_id)
+        if self.message_id is not None:
+            if self.conversation_id is None:
+                raise ValueError("message_id requires conversation_id")
+        elif not isinstance(self.question, str) or not self.question.strip():
+            raise ValueError("question must be a non-empty string unless 
message_id is set")
+
+    def execute(self, context: Context) -> dict[str, Any]:
+        self._validate()
+        if self.message_id is None:
+            return self.execute_resumable(context)
+        ref = {
+            "space_id": self.space_id,
+            "conversation_id": self.conversation_id,
+            "message_id": self.message_id,
+            "fingerprint": self._fingerprint(),
+        }
+        self.log.info(
+            "Attaching to Genie message %s in conversation %s", 
self.message_id, self.conversation_id
+        )
+        if (store := self._task_state_store(context)) is not None:
+            store.set(self.external_id_key, ref)
+            store.delete(self._submission_key)
+        return self.poll_until_complete(ref, context)
+
+    def submit_job(self, context: Context) -> Any:
+        store = self._task_state_store(context)
+        if store is not None:
+            if store.get(self._submission_key) and not 
self.resubmit_unconfirmed:
+                raise AirflowFailException(
+                    "An earlier try submitted this Genie question but 
Databricks never confirmed the "
+                    "outcome, so a message may already exist. Inspect the 
Genie space, then set "
+                    "conversation_id and message_id to attach to it, or set 
resubmit_unconfirmed=True "
+                    "to ask again."
+                )
+            store.set(self._submission_key, {"fingerprint": 
self._fingerprint()})

Review Comment:
   **minor** — the marker stores a fingerprint that nothing reads.
   
   `submit_job` only checks that the marker exists 
(`store.get(self._submission_key)`), so a try whose templated question changed 
is still refused with "An earlier try submitted this Genie question", while the 
stored-message path (`get_job_status`) does compare fingerprints. Either 
compare the marker's fingerprint here and let a different question through, or 
store a plain flag so the two paths do not look like they behave the same.



##########
providers/databricks/tests/unit/databricks/operators/test_genie.py:
##########
@@ -0,0 +1,562 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+from __future__ import annotations
+
+import json
+from unittest import mock
+
+import pytest
+
+from airflow.providers.common.compat.sdk import AirflowFailException, 
TaskDeferred
+from airflow.providers.databricks.hooks.genie import DatabricksGenieError, 
DatabricksGenieHook
+from airflow.providers.databricks.operators.genie import 
DatabricksGenieOperator
+from airflow.providers.databricks.triggers.genie import 
DatabricksGenieMessageTrigger
+
+from tests_common.test_utils.version_compat import AIRFLOW_V_3_3_PLUS
+
+SPACE_ID = "space/1"
+CONVERSATION_ID = "conversation-1"
+MESSAGE_ID = "message-1"
+QUESTION = "How many orders were placed last week?"
+START = "spaces/space%2F1/start-conversation"
+FOLLOW_UP = f"spaces/space%2F1/conversations/{CONVERSATION_ID}/messages"
+MESSAGE = 
f"spaces/space%2F1/conversations/{CONVERSATION_ID}/messages/{MESSAGE_ID}"
+ATTACHMENT_RESULT = f"{MESSAGE}/attachments/attachment-1/query-result"
+KEY = DatabricksGenieOperator.external_id_key
+SUBMISSION_KEY = f"{KEY}_submission"
+
+durable_only = pytest.mark.skipif(
+    not AIRFLOW_V_3_3_PLUS, reason="task_state_store (durable execution) 
requires Airflow 3.3+"
+)
+
+
+def message(status: str, **fields) -> dict:
+    return {"conversation_id": CONVERSATION_ID, "message_id": MESSAGE_ID, 
"status": status, **fields}
+
+
+COMPLETED = message(
+    "COMPLETED",
+    attachments=[
+        {"text": {"content": "There were 42 orders."}},
+        {
+            "attachment_id": "attachment-1",
+            "query": {"title": "Orders", "query": "SELECT count(*) FROM 
orders"},
+        },
+    ],
+)
+QUERY_RESULT = {
+    "statement_response": {
+        "manifest": {"schema": {"columns": [{"name": "count"}]}, 
"total_row_count": 1},
+        "result": {"data_array": [["42"]]},
+    }
+}
+EXPECTED_RESULT = {
+    "space_id": SPACE_ID,
+    "conversation_id": CONVERSATION_ID,
+    "message_id": MESSAGE_ID,
+    "status": "COMPLETED",
+    "answer": "There were 42 orders.",
+    "queries": [{"title": "Orders", "query": "SELECT count(*) FROM orders"}],
+    "query_results": [{"columns": ["count"], "rows": [["42"]], 
"total_row_count": 1, "truncated": False}],
+}
+
+
+class FakeStore:
+    """Dict-backed task state store that records the order of operations."""
+
+    def __init__(self, journal: list, data: dict | None = None) -> None:
+        self.journal = journal
+        self.data = dict(data or {})
+
+    def get(self, key, default=None):
+        return self.data.get(key, default)
+
+    def set(self, key, value, *, retention=None):
+        self.journal.append(("set", key))
+        self.data[key] = value
+
+    def delete(self, key):
+        self.journal.append(("delete", key))
+        self.data.pop(key, None)
+
+
+class FakeGenie:
+    """Replay Genie responses per (method, endpoint) and record every 
request."""
+
+    def __init__(self, journal: list) -> None:
+        self.journal = journal
+        self.responses: dict[tuple[str, str], list] = {}
+        self.bodies: list = []
+
+    def add(self, method: str, endpoint: str, *responses) -> None:
+        self.responses.setdefault((method, endpoint), []).extend(responses)
+
+    def __call__(self, hook, method, endpoint, *, body=None, retry_read, 
deadline=None):
+        self.journal.append((method, endpoint))
+        if method == "POST":
+            assert retry_read is False
+            self.bodies.append(body)
+        else:
+            assert retry_read is True
+        queue = self.responses.get((method, endpoint))
+        assert queue, f"unexpected {method} {endpoint}"
+        response = queue.pop(0) if len(queue) > 1 else queue[0]
+        if isinstance(response, BaseException):
+            raise response
+        return response
+
+    def calls(self, method: str) -> list:
+        return [call for call in self.journal if call[0] == method]
+
+
[email protected]
+def journal():
+    return []
+
+
[email protected]
+def genie(journal):
+    fake = FakeGenie(journal)
+    with mock.patch.object(DatabricksGenieHook, "_request", autospec=True, 
side_effect=fake):
+        yield fake
+
+
[email protected]
+def sleep():
+    with mock.patch("airflow.providers.databricks.operators.genie.time.sleep", 
autospec=True) as sleep:
+        yield sleep
+
+
+def make_operator(**kwargs) -> DatabricksGenieOperator:
+    kwargs.setdefault("space_id", SPACE_ID)
+    kwargs.setdefault("question", QUESTION)
+    kwargs.setdefault("deferrable", False)
+    return DatabricksGenieOperator(task_id="ask_genie", 
polling_period_seconds=2, **kwargs)
+
+
+def stored_ref(**overrides) -> dict:
+    ref = {
+        "space_id": SPACE_ID,
+        "conversation_id": CONVERSATION_ID,
+        "message_id": MESSAGE_ID,
+        "fingerprint": make_operator()._fingerprint(),
+    }
+    ref.update(overrides)
+    return ref
+
+
+def answered(genie: FakeGenie, *statuses: str, post: str = START) -> None:
+    genie.add("POST", post, {"conversation_id": CONVERSATION_ID, "message_id": 
MESSAGE_ID})
+    genie.add("GET", MESSAGE, *[message(status) for status in statuses], 
COMPLETED)
+    genie.add("GET", ATTACHMENT_RESULT, QUERY_RESULT)
+
+
[email protected](("field", "value"), [("polling_period_seconds", 0), 
("timeout", -1)])
+def test_invalid_wait_options(field, value):
+    with pytest.raises(ValueError, match="must be positive"):
+        DatabricksGenieOperator(task_id="ask", space_id=SPACE_ID, 
question=QUESTION, **{field: value})
+
+
[email protected](
+    ("kwargs", "match"),
+    [
+        ({"space_id": " "}, "space ID must be a non-empty string"),
+        ({"question": " "}, "question must be a non-empty string"),
+        ({"question": None}, "question must be a non-empty string"),
+        ({"message_id": MESSAGE_ID}, "message_id requires conversation_id"),
+    ],
+)
+def test_invalid_request(genie, kwargs, match):
+    with pytest.raises(ValueError, match=match):
+        make_operator(**kwargs).execute({})
+    assert genie.journal == []
+
+
+def test_template_fields():
+    assert set(DatabricksGenieOperator.template_fields) == {
+        "space_id",
+        "question",
+        "databricks_conn_id",
+        "conversation_id",
+        "message_id",
+    }
+
+
+def test_hook_configuration():
+    op = make_operator(databricks_conn_id="genie", databricks_retry_limit=5, 
databricks_retry_delay=2)
+    assert op.hook.databricks_conn_id == "genie"
+    assert op.hook.retry_limit == 5
+    assert op.hook.retry_delay == 2
+    assert op.hook.poll_interval == 2
+
+
+def test_asks_new_conversation_and_waits(genie, sleep):
+    answered(genie, "SUBMITTED", "EXECUTING_QUERY")
+
+    assert make_operator(durable=False).execute({}) == EXPECTED_RESULT
+
+    assert genie.calls("POST") == [("POST", START)]
+    assert genie.bodies == [{"content": QUESTION, "enable_visualization": 
False}]
+    assert genie.calls("GET").count(("GET", MESSAGE)) == 3
+    assert sleep.call_count == 2
+
+
[email protected]("empty", ["", None])
+def test_empty_optional_ids_start_new_conversation(genie, empty):
+    answered(genie)
+    make_operator(conversation_id=empty, message_id=empty, 
durable=False).execute({})
+    assert genie.calls("POST") == [("POST", START)]
+
+
+def test_asks_follow_up_in_existing_conversation(genie):
+    answered(genie, post=FOLLOW_UP)
+    assert make_operator(conversation_id=CONVERSATION_ID, 
durable=False).execute({}) == EXPECTED_RESULT
+    assert genie.calls("POST") == [("POST", FOLLOW_UP)]
+
+
+def test_accepts_message_id_under_id_key(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, "id": 
MESSAGE_ID})
+    genie.add("GET", MESSAGE, COMPLETED)
+    genie.add("GET", ATTACHMENT_RESULT, QUERY_RESULT)
+    assert make_operator(durable=False).execute({})["message_id"] == MESSAGE_ID
+
+
[email protected](
+    ("status", "match"),
+    [
+        ("FAILED", "could not answer message message-1: no warehouse"),
+        ("CANCELLED", "ended with status CANCELLED"),
+        ("QUERY_RESULT_EXPIRED", "ended with status QUERY_RESULT_EXPIRED"),
+        ("SOMETHING_NEW", "unknown message status: 'SOMETHING_NEW'"),
+    ],
+)
+def test_remote_terminal_failure(genie, status, match):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message(status, error={"error": "no warehouse"}))
+    with pytest.raises(DatabricksGenieError, match=match):
+        make_operator(durable=False).execute({})
+
+
+def test_failed_message_without_detail(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message("FAILED", error="boom"))
+    with pytest.raises(DatabricksGenieError, match="could not answer message 
message-1: boom"):
+        make_operator(durable=False).execute({})
+
+
+def test_synchronous_timeout(genie, sleep):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message("ASKING_AI"))
+    with (
+        mock.patch(
+            "airflow.providers.databricks.operators.genie.time.monotonic",
+            autospec=True,
+            side_effect=[0, 5, 11],
+        ),
+        pytest.raises(DatabricksGenieError, match="Timed out after 10 seconds 
.* reconnects to it"),
+    ):
+        make_operator(durable=False, timeout=10).execute({})
+    sleep.assert_called_once_with(2)
+
+
+def test_result_is_bounded(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message("COMPLETED", attachments=[{"text": 
{"content": "x" * 200_000}}]))
+
+    result = make_operator(durable=False).execute({})
+
+    assert result["truncated"] is True
+    assert result["message_id"] == MESSAGE_ID
+    assert len(json.dumps(result, separators=(",", ":")).encode()) <= 48 * 1024
+
+
+def test_defers_with_ids_only(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message("SUBMITTED"))
+    op = make_operator(durable=False, deferrable=True, 
databricks_conn_id="genie", timeout=60)
+
+    with pytest.raises(TaskDeferred) as deferred:
+        op.execute({})
+
+    trigger = deferred.value.trigger
+    assert isinstance(trigger, DatabricksGenieMessageTrigger)
+    assert trigger.serialize()[1] == {
+        "space_id": SPACE_ID,
+        "conversation_id": CONVERSATION_ID,
+        "message_id": MESSAGE_ID,
+        "databricks_conn_id": "genie",
+        "polling_period_seconds": 2,
+        "retry_limit": 3,
+        "retry_delay": 1,
+    }
+    assert deferred.value.method_name == "execute_complete"
+    assert deferred.value.timeout.total_seconds() == 60
+    assert deferred.value.kwargs == {"ref": stored_ref()}
+
+
+def test_deferrable_does_not_defer_completed_message(genie):
+    answered(genie)
+    assert make_operator(durable=False, deferrable=True).execute({}) == 
EXPECTED_RESULT
+
+
+def test_execute_complete_fetches_result_on_worker(genie):
+    genie.add("GET", MESSAGE, COMPLETED)
+    genie.add("GET", ATTACHMENT_RESULT, QUERY_RESULT)
+    event = {"status": "success", "conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID}
+
+    assert make_operator().execute_complete({}, event, ref=stored_ref()) == 
EXPECTED_RESULT
+
+
+def test_execute_complete_raises_for_failed_message(genie):
+    genie.add("GET", MESSAGE, message("CANCELLED"))
+    event = {"status": "success", "conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID}
+    with pytest.raises(DatabricksGenieError, match="ended with status 
CANCELLED"):
+        make_operator().execute_complete({}, event, ref=stored_ref())
+
+
+def test_execute_complete_rejects_pending_message(genie):
+    genie.add("GET", MESSAGE, message("ASKING_AI"))
+    event = {"status": "success", "conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID}
+    with pytest.raises(DatabricksGenieError, match="has not completed yet"):
+        make_operator().execute_complete({}, event, ref=stored_ref())
+
+
[email protected](("status_code", "expected"), [(503, 503), ("503", 
None), (None, None)])
+def test_execute_complete_error_event(genie, status_code, expected):
+    event = {
+        "status": "error",
+        "conversation_id": CONVERSATION_ID,
+        "message_id": MESSAGE_ID,
+        "error_type": "api_error",
+        "status_code": status_code,
+    }
+    with pytest.raises(DatabricksGenieError, match=r"failed \(api_error\)") as 
err:
+        make_operator().execute_complete({}, event, ref=stored_ref())
+    assert err.value.status_code == expected
+    assert genie.journal == []
+
+
[email protected](
+    "event",
+    [
+        None,
+        {},
+        {"status": "unknown", "conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID},
+        {"status": "success", "conversation_id": "other", "message_id": 
MESSAGE_ID},
+        {"status": "success", "conversation_id": CONVERSATION_ID, 
"message_id": "other"},
+    ],
+)
+def test_execute_complete_invalid_event(genie, event):
+    with pytest.raises(DatabricksGenieError, match="invalid event"):
+        make_operator().execute_complete({}, event, ref=stored_ref())
+
+
[email protected]("status_code", [None, 500, 503])
+def test_unconfirmed_submission_fails_without_retry(genie, status_code):
+    genie.add("POST", START, DatabricksGenieError("unknown outcome", 
status_code=status_code))
+    with pytest.raises(AirflowFailException, match="unknown outcome"):
+        make_operator(durable=False).execute({})
+
+
+def test_accepted_submission_without_ids_fails_without_retry(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID})
+    with pytest.raises(AirflowFailException, match="returned no conversation 
or message ID"):
+        make_operator(durable=False).execute({})
+
+
[email protected]("status_code", [400, 401, 403, 404, 429])
+def test_rejected_submission_is_retryable(genie, status_code):
+    genie.add("POST", START, DatabricksGenieError("rejected", 
status_code=status_code))
+    with pytest.raises(DatabricksGenieError, match="rejected") as err:
+        make_operator(durable=False).execute({})
+    assert not isinstance(err.value, AirflowFailException)
+
+
+def test_attach_to_existing_message_without_store(genie):
+    genie.add("GET", MESSAGE, COMPLETED)
+    genie.add("GET", ATTACHMENT_RESULT, QUERY_RESULT)
+    op = make_operator(question=None, conversation_id=CONVERSATION_ID, 
message_id=MESSAGE_ID)
+    assert op.execute({}) == EXPECTED_RESULT
+    assert genie.calls("POST") == []
+
+
+def test_on_kill_leaves_message_running(genie):
+    make_operator().on_kill()
+    assert genie.journal == []
+
+
+@durable_only
+class TestDurable:
+    @staticmethod
+    def run(op, store) -> dict:
+        return op.execute({"ti": mock.MagicMock(stats_tags={}), 
"task_state_store": store})

Review Comment:
   **minor** — unspec'd mock.
   
   > Flag any `mock.Mock()` or `mock.MagicMock()` without `spec` or `autospec`. 
Unspec'd mocks silently accept any attribute access, hiding real bugs.
   
   The mixin only reads `ti.stats_tags`, so a spec'd mock or a small stand-in 
object with that one attribute works here.



##########
providers/databricks/tests/unit/databricks/operators/test_genie.py:
##########
@@ -0,0 +1,562 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+from __future__ import annotations
+
+import json
+from unittest import mock
+
+import pytest
+
+from airflow.providers.common.compat.sdk import AirflowFailException, 
TaskDeferred
+from airflow.providers.databricks.hooks.genie import DatabricksGenieError, 
DatabricksGenieHook
+from airflow.providers.databricks.operators.genie import 
DatabricksGenieOperator
+from airflow.providers.databricks.triggers.genie import 
DatabricksGenieMessageTrigger
+
+from tests_common.test_utils.version_compat import AIRFLOW_V_3_3_PLUS
+
+SPACE_ID = "space/1"
+CONVERSATION_ID = "conversation-1"
+MESSAGE_ID = "message-1"
+QUESTION = "How many orders were placed last week?"
+START = "spaces/space%2F1/start-conversation"
+FOLLOW_UP = f"spaces/space%2F1/conversations/{CONVERSATION_ID}/messages"
+MESSAGE = 
f"spaces/space%2F1/conversations/{CONVERSATION_ID}/messages/{MESSAGE_ID}"
+ATTACHMENT_RESULT = f"{MESSAGE}/attachments/attachment-1/query-result"
+KEY = DatabricksGenieOperator.external_id_key
+SUBMISSION_KEY = f"{KEY}_submission"
+
+durable_only = pytest.mark.skipif(
+    not AIRFLOW_V_3_3_PLUS, reason="task_state_store (durable execution) 
requires Airflow 3.3+"
+)
+
+
+def message(status: str, **fields) -> dict:
+    return {"conversation_id": CONVERSATION_ID, "message_id": MESSAGE_ID, 
"status": status, **fields}
+
+
+COMPLETED = message(
+    "COMPLETED",
+    attachments=[
+        {"text": {"content": "There were 42 orders."}},
+        {
+            "attachment_id": "attachment-1",
+            "query": {"title": "Orders", "query": "SELECT count(*) FROM 
orders"},
+        },
+    ],
+)
+QUERY_RESULT = {
+    "statement_response": {
+        "manifest": {"schema": {"columns": [{"name": "count"}]}, 
"total_row_count": 1},
+        "result": {"data_array": [["42"]]},
+    }
+}
+EXPECTED_RESULT = {
+    "space_id": SPACE_ID,
+    "conversation_id": CONVERSATION_ID,
+    "message_id": MESSAGE_ID,
+    "status": "COMPLETED",
+    "answer": "There were 42 orders.",
+    "queries": [{"title": "Orders", "query": "SELECT count(*) FROM orders"}],
+    "query_results": [{"columns": ["count"], "rows": [["42"]], 
"total_row_count": 1, "truncated": False}],
+}
+
+
+class FakeStore:
+    """Dict-backed task state store that records the order of operations."""
+
+    def __init__(self, journal: list, data: dict | None = None) -> None:
+        self.journal = journal
+        self.data = dict(data or {})
+
+    def get(self, key, default=None):
+        return self.data.get(key, default)
+
+    def set(self, key, value, *, retention=None):
+        self.journal.append(("set", key))
+        self.data[key] = value
+
+    def delete(self, key):
+        self.journal.append(("delete", key))
+        self.data.pop(key, None)
+
+
+class FakeGenie:
+    """Replay Genie responses per (method, endpoint) and record every 
request."""
+
+    def __init__(self, journal: list) -> None:
+        self.journal = journal
+        self.responses: dict[tuple[str, str], list] = {}
+        self.bodies: list = []
+
+    def add(self, method: str, endpoint: str, *responses) -> None:
+        self.responses.setdefault((method, endpoint), []).extend(responses)
+
+    def __call__(self, hook, method, endpoint, *, body=None, retry_read, 
deadline=None):
+        self.journal.append((method, endpoint))
+        if method == "POST":
+            assert retry_read is False
+            self.bodies.append(body)
+        else:
+            assert retry_read is True
+        queue = self.responses.get((method, endpoint))
+        assert queue, f"unexpected {method} {endpoint}"
+        response = queue.pop(0) if len(queue) > 1 else queue[0]
+        if isinstance(response, BaseException):
+            raise response
+        return response
+
+    def calls(self, method: str) -> list:
+        return [call for call in self.journal if call[0] == method]
+
+
[email protected]
+def journal():
+    return []
+
+
[email protected]
+def genie(journal):
+    fake = FakeGenie(journal)
+    with mock.patch.object(DatabricksGenieHook, "_request", autospec=True, 
side_effect=fake):
+        yield fake
+
+
[email protected]
+def sleep():
+    with mock.patch("airflow.providers.databricks.operators.genie.time.sleep", 
autospec=True) as sleep:
+        yield sleep
+
+
+def make_operator(**kwargs) -> DatabricksGenieOperator:
+    kwargs.setdefault("space_id", SPACE_ID)
+    kwargs.setdefault("question", QUESTION)
+    kwargs.setdefault("deferrable", False)
+    return DatabricksGenieOperator(task_id="ask_genie", 
polling_period_seconds=2, **kwargs)
+
+
+def stored_ref(**overrides) -> dict:
+    ref = {
+        "space_id": SPACE_ID,
+        "conversation_id": CONVERSATION_ID,
+        "message_id": MESSAGE_ID,
+        "fingerprint": make_operator()._fingerprint(),
+    }
+    ref.update(overrides)
+    return ref
+
+
+def answered(genie: FakeGenie, *statuses: str, post: str = START) -> None:
+    genie.add("POST", post, {"conversation_id": CONVERSATION_ID, "message_id": 
MESSAGE_ID})
+    genie.add("GET", MESSAGE, *[message(status) for status in statuses], 
COMPLETED)
+    genie.add("GET", ATTACHMENT_RESULT, QUERY_RESULT)
+
+
[email protected](("field", "value"), [("polling_period_seconds", 0), 
("timeout", -1)])
+def test_invalid_wait_options(field, value):
+    with pytest.raises(ValueError, match="must be positive"):
+        DatabricksGenieOperator(task_id="ask", space_id=SPACE_ID, 
question=QUESTION, **{field: value})
+
+
[email protected](
+    ("kwargs", "match"),
+    [
+        ({"space_id": " "}, "space ID must be a non-empty string"),
+        ({"question": " "}, "question must be a non-empty string"),
+        ({"question": None}, "question must be a non-empty string"),
+        ({"message_id": MESSAGE_ID}, "message_id requires conversation_id"),
+    ],
+)
+def test_invalid_request(genie, kwargs, match):
+    with pytest.raises(ValueError, match=match):
+        make_operator(**kwargs).execute({})
+    assert genie.journal == []
+
+
+def test_template_fields():
+    assert set(DatabricksGenieOperator.template_fields) == {
+        "space_id",
+        "question",
+        "databricks_conn_id",
+        "conversation_id",
+        "message_id",
+    }
+
+
+def test_hook_configuration():
+    op = make_operator(databricks_conn_id="genie", databricks_retry_limit=5, 
databricks_retry_delay=2)
+    assert op.hook.databricks_conn_id == "genie"
+    assert op.hook.retry_limit == 5
+    assert op.hook.retry_delay == 2
+    assert op.hook.poll_interval == 2
+
+
+def test_asks_new_conversation_and_waits(genie, sleep):
+    answered(genie, "SUBMITTED", "EXECUTING_QUERY")
+
+    assert make_operator(durable=False).execute({}) == EXPECTED_RESULT
+
+    assert genie.calls("POST") == [("POST", START)]
+    assert genie.bodies == [{"content": QUESTION, "enable_visualization": 
False}]
+    assert genie.calls("GET").count(("GET", MESSAGE)) == 3
+    assert sleep.call_count == 2
+
+
[email protected]("empty", ["", None])
+def test_empty_optional_ids_start_new_conversation(genie, empty):
+    answered(genie)
+    make_operator(conversation_id=empty, message_id=empty, 
durable=False).execute({})
+    assert genie.calls("POST") == [("POST", START)]
+
+
+def test_asks_follow_up_in_existing_conversation(genie):
+    answered(genie, post=FOLLOW_UP)
+    assert make_operator(conversation_id=CONVERSATION_ID, 
durable=False).execute({}) == EXPECTED_RESULT
+    assert genie.calls("POST") == [("POST", FOLLOW_UP)]
+
+
+def test_accepts_message_id_under_id_key(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, "id": 
MESSAGE_ID})
+    genie.add("GET", MESSAGE, COMPLETED)
+    genie.add("GET", ATTACHMENT_RESULT, QUERY_RESULT)
+    assert make_operator(durable=False).execute({})["message_id"] == MESSAGE_ID
+
+
[email protected](
+    ("status", "match"),
+    [
+        ("FAILED", "could not answer message message-1: no warehouse"),
+        ("CANCELLED", "ended with status CANCELLED"),
+        ("QUERY_RESULT_EXPIRED", "ended with status QUERY_RESULT_EXPIRED"),
+        ("SOMETHING_NEW", "unknown message status: 'SOMETHING_NEW'"),
+    ],
+)
+def test_remote_terminal_failure(genie, status, match):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message(status, error={"error": "no warehouse"}))
+    with pytest.raises(DatabricksGenieError, match=match):
+        make_operator(durable=False).execute({})
+
+
+def test_failed_message_without_detail(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message("FAILED", error="boom"))
+    with pytest.raises(DatabricksGenieError, match="could not answer message 
message-1: boom"):
+        make_operator(durable=False).execute({})
+
+
+def test_synchronous_timeout(genie, sleep):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message("ASKING_AI"))
+    with (
+        mock.patch(
+            "airflow.providers.databricks.operators.genie.time.monotonic",
+            autospec=True,
+            side_effect=[0, 5, 11],
+        ),
+        pytest.raises(DatabricksGenieError, match="Timed out after 10 seconds 
.* reconnects to it"),
+    ):
+        make_operator(durable=False, timeout=10).execute({})
+    sleep.assert_called_once_with(2)
+
+
+def test_result_is_bounded(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message("COMPLETED", attachments=[{"text": 
{"content": "x" * 200_000}}]))
+
+    result = make_operator(durable=False).execute({})
+
+    assert result["truncated"] is True
+    assert result["message_id"] == MESSAGE_ID
+    assert len(json.dumps(result, separators=(",", ":")).encode()) <= 48 * 1024
+
+
+def test_defers_with_ids_only(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID})
+    genie.add("GET", MESSAGE, message("SUBMITTED"))
+    op = make_operator(durable=False, deferrable=True, 
databricks_conn_id="genie", timeout=60)
+
+    with pytest.raises(TaskDeferred) as deferred:
+        op.execute({})
+
+    trigger = deferred.value.trigger
+    assert isinstance(trigger, DatabricksGenieMessageTrigger)
+    assert trigger.serialize()[1] == {
+        "space_id": SPACE_ID,
+        "conversation_id": CONVERSATION_ID,
+        "message_id": MESSAGE_ID,
+        "databricks_conn_id": "genie",
+        "polling_period_seconds": 2,
+        "retry_limit": 3,
+        "retry_delay": 1,
+    }
+    assert deferred.value.method_name == "execute_complete"
+    assert deferred.value.timeout.total_seconds() == 60
+    assert deferred.value.kwargs == {"ref": stored_ref()}
+
+
+def test_deferrable_does_not_defer_completed_message(genie):
+    answered(genie)
+    assert make_operator(durable=False, deferrable=True).execute({}) == 
EXPECTED_RESULT
+
+
+def test_execute_complete_fetches_result_on_worker(genie):
+    genie.add("GET", MESSAGE, COMPLETED)
+    genie.add("GET", ATTACHMENT_RESULT, QUERY_RESULT)
+    event = {"status": "success", "conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID}
+
+    assert make_operator().execute_complete({}, event, ref=stored_ref()) == 
EXPECTED_RESULT
+
+
+def test_execute_complete_raises_for_failed_message(genie):
+    genie.add("GET", MESSAGE, message("CANCELLED"))
+    event = {"status": "success", "conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID}
+    with pytest.raises(DatabricksGenieError, match="ended with status 
CANCELLED"):
+        make_operator().execute_complete({}, event, ref=stored_ref())
+
+
+def test_execute_complete_rejects_pending_message(genie):
+    genie.add("GET", MESSAGE, message("ASKING_AI"))
+    event = {"status": "success", "conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID}
+    with pytest.raises(DatabricksGenieError, match="has not completed yet"):
+        make_operator().execute_complete({}, event, ref=stored_ref())
+
+
[email protected](("status_code", "expected"), [(503, 503), ("503", 
None), (None, None)])
+def test_execute_complete_error_event(genie, status_code, expected):
+    event = {
+        "status": "error",
+        "conversation_id": CONVERSATION_ID,
+        "message_id": MESSAGE_ID,
+        "error_type": "api_error",
+        "status_code": status_code,
+    }
+    with pytest.raises(DatabricksGenieError, match=r"failed \(api_error\)") as 
err:
+        make_operator().execute_complete({}, event, ref=stored_ref())
+    assert err.value.status_code == expected
+    assert genie.journal == []
+
+
[email protected](
+    "event",
+    [
+        None,
+        {},
+        {"status": "unknown", "conversation_id": CONVERSATION_ID, 
"message_id": MESSAGE_ID},
+        {"status": "success", "conversation_id": "other", "message_id": 
MESSAGE_ID},
+        {"status": "success", "conversation_id": CONVERSATION_ID, 
"message_id": "other"},
+    ],
+)
+def test_execute_complete_invalid_event(genie, event):
+    with pytest.raises(DatabricksGenieError, match="invalid event"):
+        make_operator().execute_complete({}, event, ref=stored_ref())
+
+
[email protected]("status_code", [None, 500, 503])
+def test_unconfirmed_submission_fails_without_retry(genie, status_code):
+    genie.add("POST", START, DatabricksGenieError("unknown outcome", 
status_code=status_code))
+    with pytest.raises(AirflowFailException, match="unknown outcome"):
+        make_operator(durable=False).execute({})
+
+
+def test_accepted_submission_without_ids_fails_without_retry(genie):
+    genie.add("POST", START, {"conversation_id": CONVERSATION_ID})
+    with pytest.raises(AirflowFailException, match="returned no conversation 
or message ID"):
+        make_operator(durable=False).execute({})
+
+
[email protected]("status_code", [400, 401, 403, 404, 429])
+def test_rejected_submission_is_retryable(genie, status_code):
+    genie.add("POST", START, DatabricksGenieError("rejected", 
status_code=status_code))
+    with pytest.raises(DatabricksGenieError, match="rejected") as err:
+        make_operator(durable=False).execute({})
+    assert not isinstance(err.value, AirflowFailException)
+
+
+def test_attach_to_existing_message_without_store(genie):
+    genie.add("GET", MESSAGE, COMPLETED)
+    genie.add("GET", ATTACHMENT_RESULT, QUERY_RESULT)
+    op = make_operator(question=None, conversation_id=CONVERSATION_ID, 
message_id=MESSAGE_ID)
+    assert op.execute({}) == EXPECTED_RESULT
+    assert genie.calls("POST") == []
+
+
+def test_on_kill_leaves_message_running(genie):

Review Comment:
   **nit** — this tests `BaseOperator.on_kill`; the operator does not define 
one.
   
   > Tests for pre-existing logic or standard-library/third-party functions are 
padding; missing tests for changed behaviour are gaps.
   
   The docs already say Genie has no cancel API, so the test can go.



##########
providers/databricks/src/airflow/providers/databricks/operators/genie.py:
##########
@@ -0,0 +1,356 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Operators for asking Databricks Genie spaces questions as standalone 
tasks."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections.abc import Sequence
+from datetime import timedelta
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+from airflow.providers.common.compat.sdk import AirflowFailException, 
BaseOperator, ResumableJobMixin, conf
+from airflow.providers.databricks.hooks.genie import (
+    _PENDING_STATUSES,
+    DatabricksGenieError,
+    DatabricksGenieHook,
+    _truncate_result,
+)
+from airflow.providers.databricks.triggers.genie import 
DatabricksGenieMessageTrigger
+
+if TYPE_CHECKING:
+    from airflow.providers.common.compat.sdk import Context
+
+GenieMessageRef = dict[str, str]
+
+_NOT_FOUND = "NOT_FOUND"
+_STALE = "STALE"
+
+
+class DatabricksGenieOperator(ResumableJobMixin, BaseOperator):
+    """
+    Ask a Databricks Genie space one question and return a bounded, structured 
answer.
+
+    The operator submits the question once, persists the Genie conversation 
and message IDs to task
+    state before waiting, then polls (or defers) until the message finishes. A 
retry after a worker
+    crash or timeout reconnects to the stored message instead of asking again.
+
+    Genie has no idempotency key, so a submission whose outcome is unknown (a 
timeout, a connection
+    error or a 5xx response) cannot be told apart from one that was never 
received. The operator fails
+    without retrying in that case and the next try refuses to submit again; 
set ``conversation_id`` and
+    ``message_id`` to attach to the message you found, or 
``resubmit_unconfirmed=True`` to ask again.
+
+    .. seealso::
+        For more information on how to use this operator, take a look at the 
guide:
+        :ref:`howto/operator:DatabricksGenieOperator`
+
+    :param space_id: Genie space ID. (templated)
+    :param question: Question to ask. Required unless ``message_id`` is set. 
(templated)
+    :param databricks_conn_id: Databricks connection. Defaults to 
``databricks_default``. (templated)
+    :param conversation_id: Existing conversation to ask the question in. The 
operator never deletes it.
+        Defaults to ``None``, which starts a new conversation. An empty string 
means ``None``. (templated)
+    :param message_id: Existing message to wait for instead of asking a 
question. Requires
+        ``conversation_id``. An empty string means ``None``. (templated)
+    :param polling_period_seconds: Seconds between status checks. Defaults to 
``5``.
+    :param timeout: Maximum seconds to wait for the answer in one try. Timing 
out does not cancel the
+        message; the next try reconnects to it. Defaults to ``1800``.
+    :param resubmit_unconfirmed: Ask the question again even though an earlier 
submission's outcome is
+        unknown and may have created a message. Defaults to ``False``.
+    :param databricks_retry_limit: Attempts for each Genie read. Submissions 
are never retried.
+        Defaults to ``3``.
+    :param databricks_retry_delay: Minimum seconds between read attempts. 
Defaults to ``1``.
+    :param deferrable: Release the worker while waiting. Defaults to 
``[operators] default_deferrable``,
+        with a fallback of ``False``.
+    :param durable: When ``True`` (the default), the Genie message IDs are 
persisted to task state
+        before waiting so a retry reconnects instead of asking again. Requires 
Airflow 3.3+; on earlier
+        versions every try asks the question again.
+    """
+
+    template_fields: Sequence[str] = (
+        "space_id",
+        "question",
+        "databricks_conn_id",
+        "conversation_id",
+        "message_id",
+    )
+    ui_color = "#1CB1C2"
+    external_id_key = "databricks_genie_message"
+
+    def __init__(
+        self,
+        *,
+        space_id: str,
+        question: str | None = None,
+        databricks_conn_id: str = "databricks_default",
+        conversation_id: str | None = None,
+        message_id: str | None = None,
+        polling_period_seconds: float = 5,
+        timeout: float = 1800,
+        resubmit_unconfirmed: bool = False,
+        databricks_retry_limit: int = 3,
+        databricks_retry_delay: float = 1,
+        deferrable: bool = conf.getboolean("operators", "default_deferrable", 
fallback=False),
+        durable: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # Named here (not left to **kwargs) so default_args reaches it on 
every supported Airflow version.
+        if durable is not None:
+            kwargs["durable"] = durable
+        super().__init__(**kwargs)
+        if polling_period_seconds <= 0:
+            raise ValueError("polling_period_seconds must be positive")
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        self.space_id = space_id
+        self.question = question
+        self.databricks_conn_id = databricks_conn_id
+        self.conversation_id = conversation_id
+        self.message_id = message_id
+        self.polling_period_seconds = polling_period_seconds
+        self.timeout = timeout
+        self.resubmit_unconfirmed = resubmit_unconfirmed
+        self.databricks_retry_limit = databricks_retry_limit
+        self.databricks_retry_delay = databricks_retry_delay
+        self.deferrable = deferrable
+        self._result: dict[str, Any] | None = None
+
+    @cached_property
+    def hook(self) -> DatabricksGenieHook:
+        return DatabricksGenieHook(
+            self.databricks_conn_id,
+            retry_limit=self.databricks_retry_limit,
+            retry_delay=self.databricks_retry_delay,
+            caller=type(self).__name__,
+            poll_interval=self.polling_period_seconds,
+        )
+
+    @property
+    def _submission_key(self) -> str:
+        return f"{self.external_id_key}_submission"
+
+    def _fingerprint(self) -> str:
+        """Identify the question so a retry never reconnects to an answer for 
a different one."""
+        material = "\x1f".join((self.space_id, self.conversation_id or "", 
self.question or ""))
+        return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+    def _task_state_store(self, context: Context) -> Any:
+        return context.get("task_state_store") if self.durable else None
+
+    def _validate(self) -> None:
+        self.conversation_id = self.conversation_id or None
+        self.message_id = self.message_id or None
+        self.hook._validate_space_id(self.space_id)
+        if self.message_id is not None:
+            if self.conversation_id is None:
+                raise ValueError("message_id requires conversation_id")
+        elif not isinstance(self.question, str) or not self.question.strip():
+            raise ValueError("question must be a non-empty string unless 
message_id is set")
+
+    def execute(self, context: Context) -> dict[str, Any]:
+        self._validate()
+        if self.message_id is None:
+            return self.execute_resumable(context)
+        ref = {
+            "space_id": self.space_id,
+            "conversation_id": self.conversation_id,
+            "message_id": self.message_id,
+            "fingerprint": self._fingerprint(),
+        }
+        self.log.info(
+            "Attaching to Genie message %s in conversation %s", 
self.message_id, self.conversation_id
+        )
+        if (store := self._task_state_store(context)) is not None:
+            store.set(self.external_id_key, ref)
+            store.delete(self._submission_key)
+        return self.poll_until_complete(ref, context)
+
+    def submit_job(self, context: Context) -> Any:
+        store = self._task_state_store(context)
+        if store is not None:
+            if store.get(self._submission_key) and not 
self.resubmit_unconfirmed:
+                raise AirflowFailException(
+                    "An earlier try submitted this Genie question but 
Databricks never confirmed the "
+                    "outcome, so a message may already exist. Inspect the 
Genie space, then set "
+                    "conversation_id and message_id to attach to it, or set 
resubmit_unconfirmed=True "
+                    "to ask again."
+                )
+            store.set(self._submission_key, {"fingerprint": 
self._fingerprint()})
+
+        space = quote(self.space_id, safe="")
+        if self.conversation_id is None:
+            endpoint = f"spaces/{space}/start-conversation"
+        else:
+            endpoint = 
f"spaces/{space}/conversations/{quote(self.conversation_id, safe='')}/messages"
+        try:
+            created = self.hook._request(
+                "POST",
+                endpoint,
+                body={"content": self.question, "enable_visualization": False},
+                retry_read=False,
+            )
+        except DatabricksGenieError as err:
+            if err.status_code is not None and err.status_code < 500:
+                # Databricks rejected the request, so nothing was created and 
a retry may submit again.
+                if store is not None:
+                    store.delete(self._submission_key)
+                raise
+            raise AirflowFailException(str(err)) from err
+
+        conversation_id = created.get("conversation_id")
+        message_id = created.get("message_id") or created.get("id")
+        if not isinstance(conversation_id, str) or not isinstance(message_id, 
str):
+            raise AirflowFailException(
+                "Genie accepted the question but returned no conversation or 
message ID; "
+                "the question will not be asked again."
+            )
+        ref = {
+            "space_id": self.space_id,
+            "conversation_id": conversation_id,
+            "message_id": message_id,
+            "fingerprint": self._fingerprint(),
+        }
+        self.log.info("Asked Genie message %s in conversation %s", message_id, 
conversation_id)
+        if store is not None:
+            # Persist before dropping the marker so no crash can lose both.
+            store.set(self.external_id_key, ref)
+            store.delete(self._submission_key)
+        return ref
+
+    def _message_path(self, ref: GenieMessageRef) -> str:
+        return (
+            f"spaces/{quote(ref['space_id'], safe='')}/conversations/"
+            f"{quote(ref['conversation_id'], 
safe='')}/messages/{quote(ref['message_id'], safe='')}"
+        )
+
+    def _get_message(self, ref: GenieMessageRef, deadline: float | None = 
None) -> dict[str, Any]:
+        return self.hook._request("GET", self._message_path(ref), 
retry_read=True, deadline=deadline)
+
+    def get_job_status(self, external_id: Any, context: Context) -> str:
+        if not isinstance(external_id, dict) or external_id.get("fingerprint") 
!= self._fingerprint():
+            self.log.warning("Stored Genie message was for a different 
question; asking again")
+            return _STALE
+        try:
+            message = self._get_message(external_id)
+        except DatabricksGenieError as err:
+            if err.status_code == 404:
+                return _NOT_FOUND
+            raise
+        return str(message.get("status"))

Review Comment:
   **major** — an unknown or missing status on reconnect asks the question 
again.
   
   `get_job_status` returns whatever Genie sent, including `"None"` when the 
response has no `status`. `ResumableJobMixin.get_resume_decision` submits a new 
job whenever `is_job_active` and `is_job_succeeded` are both false, so any 
status that is neither in `_PENDING_STATUSES` nor `COMPLETED` counts as 
terminal here. `_check_message` raises on an unknown status, but this path does 
not: if Genie adds a new in-progress status, try 1 fails with "unknown message 
status" and every later try posts the question again while the first message is 
still running.
   
   Could `get_job_status` raise for a status outside the known pending and 
terminal sets, so only `FAILED` / `CANCELLED` / `QUERY_RESULT_EXPIRED` / 404 / 
a changed fingerprint lead to a new submission? A durable test for that case 
would pin it.



##########
providers/databricks/src/airflow/providers/databricks/hooks/genie.py:
##########
@@ -0,0 +1,466 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Hook for Databricks Genie conversations."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote, urlsplit
+
+import requests
+from requests.auth import HTTPBasicAuth
+from tenacity import RetryError
+
+from airflow.providers.common.compat.sdk import (
+    AirflowException,
+    AirflowOptionalProviderFeatureException,
+)
+from airflow.providers.databricks.hooks.databricks_base import 
BaseDatabricksHook
+
+if TYPE_CHECKING:
+    from airflow.providers.common.ai.managed_agents.base import (
+        BaseManagedAgentHook,
+        ManagedAgentCapabilities,
+        ManagedAgentRef,
+        ManagedAgentRequest,
+        ManagedAgentResponse,
+    )
+else:
+    try:
+        from airflow.providers.common.ai.managed_agents.base import (
+            BaseManagedAgentHook,
+            ManagedAgentCapabilities,
+            ManagedAgentRef,
+            ManagedAgentRequest,
+            ManagedAgentResponse,
+        )
+    except ImportError:
+
+        def _needs_common_ai(*args: Any, **kwargs: Any) -> Any:
+            raise AirflowOptionalProviderFeatureException(
+                "Databricks Genie managed-agent integration needs the 
'common.ai' extra of the "
+                "Databricks provider: pip install 
'apache-airflow-providers-databricks[common.ai]'."
+            )
+
+        class BaseManagedAgentHook:
+            """Stand-in for the optional Common AI contract."""
+
+            agent = _needs_common_ai
+
+        ManagedAgentCapabilities = ManagedAgentRef = ManagedAgentRequest = 
ManagedAgentResponse = (
+            _needs_common_ai
+        )
+
+
+_MAX_RESPONSE_BYTES = 1024 * 1024
+_MAX_RESULT_BYTES = 48 * 1024
+_MAX_RESULT_ROWS = 100
+_POLL_INTERVAL_SECONDS = 1.0
+_PENDING_STATUSES = frozenset(
+    {
+        "FETCHING_METADATA",
+        "FILTERING_CONTEXT",
+        "ASKING_AI",
+        "PENDING_WAREHOUSE",
+        "EXECUTING_QUERY",
+        "SUBMITTED",
+    }
+)
+
+
+class DatabricksGenieError(AirflowException):
+    """A Genie request failed or returned a result that could not be used."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> 
None:
+        super().__init__(message)
+        # AirflowException declares status_code as HTTPStatus; Genie keeps the 
raw code or None.
+        self.status_code = status_code  # type: ignore[assignment]
+
+
+class DatabricksGenieHook(BaseDatabricksHook, BaseManagedAgentHook):
+    """
+    Consult a Genie space using the Databricks Workspace REST API.
+
+    The Databricks connection supplies authentication. Genie start/send 
requests are sent once:
+    their outcome may be unknown after a timeout or server error, so the hook 
never retries them.
+    Message and query-result reads use the hook's configured retry policy.
+    """
+
+    agent_platform = "databricks.genie"
+
+    def __init__(self, *args: Any, poll_interval: float = 
_POLL_INTERVAL_SECONDS, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        if poll_interval <= 0:
+            raise ValueError("poll_interval must be greater than zero")
+        self.poll_interval = poll_interval
+
+    @staticmethod
+    def _validate_space_id(space_id: str) -> None:
+        if not isinstance(space_id, str) or not space_id.strip():
+            raise ValueError("A Databricks Genie space ID must be a non-empty 
string.")
+
+    def resolve_agent(self, agent: str) -> ManagedAgentRef:
+        self._validate_space_id(agent)
+        return ManagedAgentRef(platform=self.agent_platform, name=agent)
+
+    def get_agent_capabilities(self, agent: str) -> ManagedAgentCapabilities:
+        self.resolve_agent(agent)
+        return ManagedAgentCapabilities(sessions=True, structured_output=True)
+
+    def invoke_agent(self, agent: str, request: ManagedAgentRequest) -> 
ManagedAgentResponse:
+        self.resolve_agent(agent)
+        if request.vendor_options:
+            raise ValueError(
+                f"Databricks Genie does not support vendor_options: 
{sorted(request.vendor_options)}"
+            )
+        prompt = request.prompt if request.prompt is not None else 
_messages_to_prompt(request.as_messages())
+        timeout = request.timeout if request.timeout is not None else 
self.timeout_seconds
+        result = self.consult(agent, prompt, 
conversation_id=request.session_id, timeout=timeout)
+        return ManagedAgentResponse(
+            text=json.dumps(result, ensure_ascii=False, separators=(",", ":")),
+            raw=result,
+            structured=result,
+            session_id=result["conversation_id"],
+            trace_ref=result["message_id"],
+        )
+
+    def consult(
+        self,
+        space_id: str,
+        prompt: str,
+        *,
+        conversation_id: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Submit one question and return a bounded, structured Genie 
result."""
+        self._validate_space_id(space_id)
+        if not prompt.strip():
+            raise ValueError("A Genie question must not be empty.")
+        if timeout is not None and timeout <= 0:
+            raise ValueError("timeout must be greater than zero")
+        if conversation_id is not None and not conversation_id.strip():
+            raise ValueError("conversation_id must not be empty")
+
+        deadline = time.monotonic() + (timeout if timeout is not None else 
self.timeout_seconds)
+        space = quote(space_id, safe="")
+        if conversation_id is None:
+            endpoint = f"spaces/{space}/start-conversation"
+            body = {"content": prompt, "enable_visualization": False}
+        else:
+            conversation = quote(conversation_id, safe="")
+            endpoint = f"spaces/{space}/conversations/{conversation}/messages"
+            body = {"content": prompt, "enable_visualization": False}
+
+        created = self._request("POST", endpoint, body=body, retry_read=False, 
deadline=deadline)
+        resolved_conversation_id = created.get("conversation_id")
+        message_id = created.get("message_id") or created.get("id")
+        if not isinstance(resolved_conversation_id, str) or not 
isinstance(message_id, str):
+            raise DatabricksGenieError(
+                "Genie accepted the consultation but returned no conversation 
or message ID; "
+                "the request will not be repeated."
+            )
+
+        while True:
+            message = self._request(
+                "GET",
+                
f"spaces/{space}/conversations/{quote(resolved_conversation_id, 
safe='')}/messages/"
+                f"{quote(message_id, safe='')}",
+                retry_read=True,
+                deadline=deadline,
+            )
+            status = message.get("status")
+            if status == "COMPLETED":
+                break
+            if status == "FAILED":
+                error = message.get("error") or {}
+                detail = error.get("error") if isinstance(error, dict) else 
str(error)
+                raise DatabricksGenieError(
+                    f"Genie could not answer the question: {detail or 'unknown 
error'}"
+                )
+            if status in {"CANCELLED", "QUERY_RESULT_EXPIRED"}:
+                raise DatabricksGenieError(f"Genie consultation ended with 
status {status}.")
+            if status not in _PENDING_STATUSES:
+                raise DatabricksGenieError(f"Genie returned an unknown message 
status: {status!r}.")
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise DatabricksGenieError(
+                    f"Timed out waiting for Genie message {message_id}; "
+                    f"conversation {resolved_conversation_id} "
+                    "is available to inspect."
+                )
+            time.sleep(min(self.poll_interval, remaining))
+
+        structured = self._summarize_result(
+            space_id, space, resolved_conversation_id, message_id, message, 
deadline
+        )
+        return _truncate_result(structured)
+
+    def _summarize_result(
+        self,
+        space_id: str,
+        space_path: str,
+        conversation_id: str,
+        message_id: str,
+        message: dict[str, Any],
+        deadline: float,
+    ) -> dict[str, Any]:
+        attachments = message.get("attachments") or []
+        answers: list[str] = []
+        queries: list[dict[str, Any]] = []
+        query_results: list[dict[str, Any]] = []
+        for attachment in attachments:
+            if not isinstance(attachment, dict):
+                continue
+            text_attachment = attachment.get("text")
+            if isinstance(text_attachment, dict) and 
isinstance(text_attachment.get("content"), str):
+                answers.append(text_attachment["content"])
+            query = attachment.get("query")
+            if isinstance(query, dict):
+                queries.append(
+                    {
+                        key: query[key]
+                        for key in ("title", "query", "description", 
"query_result_metadata")
+                        if key in query
+                    }
+                )
+                attachment_id = attachment.get("attachment_id")
+                if isinstance(attachment_id, str) and attachment_id:
+                    response = self._request(
+                        "GET",
+                        f"spaces/{space_path}/conversations/"
+                        f"{quote(conversation_id, safe='')}/messages/"
+                        f"{quote(message_id, safe='')}/attachments/"
+                        f"{quote(attachment_id, safe='')}/query-result",
+                        retry_read=True,
+                        deadline=deadline,
+                    )
+                    query_results.append(_summarize_query_result(response))
+        result: dict[str, Any] = {
+            "space_id": space_id,
+            "conversation_id": conversation_id,
+            "message_id": message_id,
+            "status": message.get("status"),
+            "answer": "\n\n".join(answers),
+        }
+        if queries:
+            result["queries"] = queries
+        if query_results:
+            result["query_results"] = query_results
+        return result
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        body: dict[str, Any] | None = None,
+        retry_read: bool,
+        deadline: float | None = None,
+    ) -> dict[str, Any]:
+        """Call one Genie endpoint; only GET requests are eligible for 
transport retries."""
+        url = self._endpoint_url(f"api/2.0/genie/{endpoint}")
+        parsed_url = urlsplit(url)
+        is_loopback = parsed_url.hostname in {"localhost", "127.0.0.1", "::1"}
+        if parsed_url.scheme != "https" and not is_loopback:
+            raise DatabricksGenieError(
+                "Databricks Genie requires HTTPS so connection credentials are 
not sent in cleartext."
+            )
+        headers = {**self.user_agent_header, **self._get_aad_headers()}
+        token = self._get_token()
+        auth = None

Review Comment:
   **minor** (this file comes from the first Genie hook PR, so the fix belongs 
there) — a matching `.netrc` entry replaces the bearer token.
   
   With a token, `_request` sets the `Authorization` header and passes 
`auth=None`. `requests` then applies a matching `.netrc` entry and overwrites 
the header with Basic auth. `BaseDatabricksHook._do_api_call` passes 
`_TokenAuth(token)` for this reason; the same would work here.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to