LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
UN-2190 [MISC] Auto-capture execution ID in the API deployment Postman collection (#2031)
Athul8218164826eb
diff --git a/backend/api_v2/postman_collection/constants.py b/backend/api_v2/postman_collection/constants.pyindex 7bcbe988e..117bcad98 100644--- a/backend/api_v2/postman_collection/constants.py+++ b/backend/api_v2/postman_collection/constants.py@@ -6,4 +6,8 @@ class CollectionKey:EXECUTE_PIPELINE_API_KEY = "Process pipeline"STATUS_API_KEY = "Execution status"STATUS_EXEC_ID_DEFAULT = "REPLACE_WITH_EXECUTION_ID"+ EXEC_ID_VARIABLE_NAME = "execution_id"+ # Derive the Postman variable reference from the variable name so the two+ # can never drift apart (-> "{{execution_id}}").+ STATUS_EXEC_ID_VARIABLE = f"{{{{{EXEC_ID_VARIABLE_NAME}}}}}"AUTH_QUERY_PARAM_DEFAULT = "REPLACE_WITH_API_KEY"diff --git a/backend/api_v2/postman_collection/dto.py b/backend/api_v2/postman_collection/dto.pyindex 17a6865ee..1118af3df 100644--- a/backend/api_v2/postman_collection/dto.py+++ b/backend/api_v2/postman_collection/dto.py@@ -1,6 +1,6 @@from abc import ABC, abstractmethodfrom dataclasses import asdict, dataclass, field-from typing import Any+from typing import Any, Literalfrom urllib.parse import urlencode, urljoinfrom django.conf import settings@@ -18,6 +18,24 @@ class HeaderItem:value: str+@dataclass+class ScriptItem:+ exec: list[str]+ type: Literal["text/javascript"] = "text/javascript"+++@dataclass+class EventItem:+ listen: Literal["prerequest", "test"]+ script: ScriptItem+++@dataclass+class VariableItem:+ key: str+ value: str++@dataclassclass FormDataItem:key: str@@ -55,6 +73,7 @@ class RequestItem:class PostmanItem:name: strrequest: RequestItem+ event: list[EventItem] = field(default_factory=list)@dataclass@@ -69,6 +88,12 @@ class APIBase(ABC):def get_form_data_items(self) -> list[FormDataItem]:pass+ def get_collection_variables(self) -> list[VariableItem]:+ """Collection-level variables; only needed when a request+ references them.+ """+ return []+@abstractmethoddef get_api_endpoint(self) -> str:pass@@ -137,20 +162,61 @@ class APIDeploymentDto(APIBase):def _get_status_api_request(self) -> RequestItem:header_list = [HeaderItem(key="Authorization", value=f"Bearer {self.api_key}")]status_query_param = {- "execution_id": CollectionKey.STATUS_EXEC_ID_DEFAULT,+ "execution_id": CollectionKey.STATUS_EXEC_ID_VARIABLE,ApiExecution.INCLUDE_METADATA: "False",ApiExecution.INCLUDE_METRICS: "False",}- status_query_str = urlencode(status_query_param)+ # Keep {{...}} unescaped so Postman resolves the collection variable+ status_query_str = urlencode(status_query_param, safe="{}")abs_api_endpoint = urljoin(settings.WEB_APP_ORIGIN_URL, self.api_endpoint)status_url = urljoin(abs_api_endpoint, "?" + status_query_str)return RequestItem(method=HTTPMethod.GET, header=header_list, url=status_url)+ def get_collection_variables(self) -> list[VariableItem]:+ return [+ VariableItem(+ key=CollectionKey.EXEC_ID_VARIABLE_NAME,+ value=CollectionKey.STATUS_EXEC_ID_DEFAULT,+ )+ ]++ def _get_execute_capture_event(self) -> EventItem:+ """Post-response script that stores the execution_id from the execute+ response into a collection variable, so the status request can use it+ without manual copy-pasting.++ This is Postman's ``test`` hook (the emitted event uses+ ``listen="test"``). It assumes the execute response shape+ ``{"message": {"execution_id": ...}}``; if the body is non-JSON or+ lacks that field it captures nothing and resets the variable to the+ default sentinel so a stale id from a previous run is never reused.+ """+ return EventItem(+ listen="test",+ script=ScriptItem(+ exec=[+ "let response = null;",+ "try {",+ " response = pm.response.json();",+ "} catch (error) {",+ " // Non-JSON response (e.g. gateway error); nothing to capture",+ "}",+ "if (response && response.message && response.message.execution_id) {", # noqa: E501+ f' pm.collectionVariables.set("{CollectionKey.EXEC_ID_VARIABLE_NAME}", response.message.execution_id);', # noqa: E501+ "} else {",+ f' pm.collectionVariables.set("{CollectionKey.EXEC_ID_VARIABLE_NAME}", "{CollectionKey.STATUS_EXEC_ID_DEFAULT}");', # noqa: E501+ ' console.warn("No execution_id in execute response; not reusing a stale value. Status:", pm.response.code);', # noqa: E501+ "}",+ ]+ ),+ )+def get_postman_items(self) -> list[PostmanItem]:postman_item_list = [PostmanItem(name=CollectionKey.EXECUTE_API_KEY,request=self.get_create_api_request(),+ event=[self._get_execute_capture_event()],),PostmanItem(name=CollectionKey.STATUS_API_KEY,@@ -192,6 +258,7 @@ class PipelineDto(APIBase):class PostmanCollection:info: PostmanInfoitem: list[PostmanItem] = field(default_factory=list)+ variable: list[VariableItem] = field(default_factory=list)@classmethoddef create(@@ -228,7 +295,11 @@ class PostmanCollection:)postman_info: PostmanInfo = data_object.get_postman_info()postman_item_list = data_object.get_postman_items()- return cls(info=postman_info, item=postman_item_list)+ return cls(+ info=postman_info,+ item=postman_item_list,+ variable=data_object.get_collection_variables(),+ )def to_dict(self) -> dict[str, Any]:"""Convert PostmanCollection instance to a dict.@@ -237,4 +308,9 @@ class PostmanCollection:dict[str, Any]: PostmanCollection as a dict"""collection_dict = asdict(self)+ # Omit empty event blocks; items without scripts (e.g. pipelines)+ # should not carry an "event" key at all.+ for item in collection_dict.get("item", []):+ if not item.get("event"):+ item.pop("event", None)return collection_dictdiff --git a/backend/api_v2/postman_collection/tests/__init__.py b/backend/api_v2/postman_collection/tests/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/backend/api_v2/postman_collection/tests/test_dto.py b/backend/api_v2/postman_collection/tests/test_dto.pynew file mode 100644index 000000000..b05048fb6--- /dev/null+++ b/backend/api_v2/postman_collection/tests/test_dto.py@@ -0,0 +1,154 @@+"""Regression tests for api_v2.postman_collection.dto — the builder that+turns an API deployment or pipeline into a Postman v2.1 collection.++UN-2190: the execute request gained a post-response capture script and the+status request reuses the captured ``execution_id`` collection variable.+These tests pin the contract so a refactor can't reopen the gaps the+review flagged: the null-event strip, the variable/URL/JS all referencing+the SAME constant, and the status URL keeping ``{{execution_id}}`` literal+(not percent-encoded).++The DTOs are constructed directly (no DB) and only ``WEB_APP_ORIGIN_URL``+is overridden, so the suite is cheap and needs no fixtures.+"""++from __future__ import annotations++import pytest+from django.test import override_settings++from api_v2.postman_collection.constants import CollectionKey+from api_v2.postman_collection.dto import (+ APIDeploymentDto,+ PipelineDto,+ PostmanCollection,+)++WEB_APP_ORIGIN_URL = "https://example.unstract.com"+API_ENDPOINT = "deployment/api/org/my-api/"+API_KEY = "test-api-key"+++def _api_deployment_dto() -> APIDeploymentDto:+ return APIDeploymentDto(+ display_name="My API",+ description="An API deployment",+ api_endpoint=API_ENDPOINT,+ api_key=API_KEY,+ )+++def _pipeline_dto() -> PipelineDto:+ return PipelineDto(+ pipeline_name="My Pipeline",+ api_endpoint=API_ENDPOINT,+ api_key=API_KEY,+ )+++def _build_dict(data_object) -> dict:+ """Mirror PostmanCollection.create without touching the DB.++ Pins WEB_APP_ORIGIN_URL so URL building is deterministic regardless of+ the ambient test settings.+ """+ with override_settings(WEB_APP_ORIGIN_URL=WEB_APP_ORIGIN_URL):+ collection = PostmanCollection(+ info=data_object.get_postman_info(),+ item=data_object.get_postman_items(),+ variable=data_object.get_collection_variables(),+ )+ return collection.to_dict()+++def _item_by_name(collection_dict: dict, name: str) -> dict:+ for item in collection_dict["item"]:+ if item["name"] == name:+ return item+ raise AssertionError(f"item {name!r} not found in collection")+++class TestApiDeploymentCollection:+ def test_execute_item_keeps_populated_event(self) -> None:+ """to_dict keeps the populated execute event and its capture script."""+ collection_dict = _build_dict(_api_deployment_dto())+ execute_item = _item_by_name(collection_dict, CollectionKey.EXECUTE_API_KEY)++ assert "event" in execute_item+ assert execute_item["event"], "execute event must not be stripped"+ script_lines = execute_item["event"][0]["script"]["exec"]+ joined = "\n".join(script_lines)+ # The capture must target the same constant the variable/URL use.+ assert (+ f'pm.collectionVariables.set("{CollectionKey.EXEC_ID_VARIABLE_NAME}"'+ in joined+ )++ def test_capture_script_resets_on_missing_execution_id(self) -> None:+ """The else branch resets to the sentinel so a stale id is never reused."""+ collection_dict = _build_dict(_api_deployment_dto())+ execute_item = _item_by_name(collection_dict, CollectionKey.EXECUTE_API_KEY)+ joined = "\n".join(execute_item["event"][0]["script"]["exec"])++ assert "else" in joined+ assert (+ f'pm.collectionVariables.set("{CollectionKey.EXEC_ID_VARIABLE_NAME}", '+ f'"{CollectionKey.STATUS_EXEC_ID_DEFAULT}")' in joined+ )+ assert "console.warn" in joined++ def test_status_item_has_no_event_key(self) -> None:+ """The status request carries no scripts -> no 'event' key at all."""+ collection_dict = _build_dict(_api_deployment_dto())+ status_item = _item_by_name(collection_dict, CollectionKey.STATUS_API_KEY)+ assert "event" not in status_item++ def test_variable_array_references_the_constant(self) -> None:+ """The collection 'variable' array exposes the exec-id variable."""+ collection_dict = _build_dict(_api_deployment_dto())+ variables = collection_dict["variable"]+ assert any(+ v["key"] == CollectionKey.EXEC_ID_VARIABLE_NAME for v in variables+ )++ def test_status_url_keeps_unencoded_variable_reference(self) -> None:+ """Status URL keeps execution_id={{execution_id}} literal, not %7B-encoded."""+ collection_dict = _build_dict(_api_deployment_dto())+ status_item = _item_by_name(collection_dict, CollectionKey.STATUS_API_KEY)+ url = status_item["request"]["url"]++ assert (+ f"{CollectionKey.EXEC_ID_VARIABLE_NAME}="+ f"{CollectionKey.STATUS_EXEC_ID_VARIABLE}" in url+ )+ assert "%7B" not in url and "%7D" not in url+++class TestCollectionShapeRegression:+ def test_pipeline_carries_no_event_and_empty_variable(self) -> None:+ """PipelineDto: no scripts and no collection variables."""+ collection_dict = _build_dict(_pipeline_dto())+ assert collection_dict["variable"] == []+ for item in collection_dict["item"]:+ assert "event" not in item++ def test_api_deployment_carries_event_and_variable(self) -> None:+ """APIDeploymentDto: execute event present and variable populated."""+ collection_dict = _build_dict(_api_deployment_dto())+ execute_item = _item_by_name(collection_dict, CollectionKey.EXECUTE_API_KEY)+ assert execute_item.get("event")+ assert collection_dict["variable"], "api deployment must expose variables"+++class TestConstantCoupling:+ def test_status_variable_derived_from_name(self) -> None:+ """STATUS_EXEC_ID_VARIABLE must be the {{...}} form of the var name."""+ assert (+ CollectionKey.STATUS_EXEC_ID_VARIABLE+ == f"{{{{{CollectionKey.EXEC_ID_VARIABLE_NAME}}}}}"+ )+ assert CollectionKey.STATUS_EXEC_ID_VARIABLE == "{{execution_id}}"+++if __name__ == "__main__": # pragma: no cover+ raise SystemExit(pytest.main([__file__, "-q"]))diff --git a/backend/api_v2/serializers.py b/backend/api_v2/serializers.pyindex 282adc8a4..58bcd8c17 100644--- a/backend/api_v2/serializers.py+++ b/backend/api_v2/serializers.py@@ -523,6 +523,7 @@ class DeploymentResponseSerializer(Serializer):class APIExecutionResponseSerializer(Serializer):+ execution_id = CharField()execution_status = CharField()status_api = CharField()error = CharField()