UN-2946 [FEAT] Prompt Studio lookups bridge, executor hook, and IDE wiring (OSS side)

.gitignore

@@ -653,7 +653,11 @@ docker/*.env
 !docker/sample*.env
 docker/public_tools.json
 docker/proxy_overrides.yaml
-docker/compose.override.yaml
+docker/compose.*.yaml
+# ``docker/compose.debug.yaml`` is checked-in tooling — keep it out of the
+# broader ``compose.*.yaml`` ignore so a delete + recreate doesn't make it
+# look untracked, and so teammates can spot it.
+!docker/compose.debug.yaml
 docker/workflow_data/
 
 # Tool development
@@ -696,6 +700,12 @@ CLAUDE.md
 CONTRIBUTION_GUIDE.md
 .mcp.json
 
+# Codex
+AGENTS.md
+
+# Pi
+.pi/
+
 # Windsurf
 .qodo
 .windsurfrules

backend/prompt_studio/lookup_utils.py

@@ -0,0 +1,171 @@
+"""Shared utility for lookup operations. No-ops in OSS.
+
+Only the absence of ``pluggable_apps.lookups`` itself is treated as
+"cloud not installed"; an ImportError from a transitive dependency
+re-raises so we don't silently degrade to a no-op on a real bug.
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_CLOUD_LOOKUP_MODULES = {
+    # OSS images lack the parent ``pluggable_apps`` package, so include it.
+    "pluggable_apps",
+    "pluggable_apps.lookups",
+    "pluggable_apps.lookups.execution",
+    "pluggable_apps.lookups.output_enrichment",
+    "pluggable_apps.lookups.staleness",
+    "pluggable_apps.lookups.validation",
+    "pluggable_apps.lookups.models",
+}
+
+try:
+    from pluggable_apps.lookups import execution as _execution
+    from pluggable_apps.lookups import output_enrichment as _output_enrichment
+    from pluggable_apps.lookups import staleness as _staleness
+    from pluggable_apps.lookups import validation as _validation
+    from pluggable_apps.lookups.models import LookupOutputResult as _LookupOutputResult
+
+    LOOKUPS_AVAILABLE = True
+except ImportError as e:
+    if e.name not in _CLOUD_LOOKUP_MODULES:
+        raise
+    LOOKUPS_AVAILABLE = False
+
+
+def get_lookup_config(prompt) -> dict | None:
+    """Return lookup config for a prompt, or None if lookups are unavailable."""
+    if not LOOKUPS_AVAILABLE:
+        return None
+    return _execution.build_lookup_config_for_prompt(prompt)
+
+
+def get_lookup_configs_for_tool(tool, prompts=None) -> list[dict] | None:
+    """Return lookup configs for a tool (single pass), or None in OSS.
+
+    ``prompts`` scopes validation to the run's prompts so unrelated
+    incomplete assignments on the tool don't block it.
+    """
+    if not LOOKUPS_AVAILABLE:
+        return None
+    return _execution.build_lookup_configs_for_tool(tool, prompts=prompts)
+
+
+def get_multi_var_lookups_for_tool(tool, prompt_ids=None) -> list[str]:
+    """Return names of multi-variable lookups linked to the tool, [] in OSS.
+
+    ``prompt_ids`` scopes the check so a run is only blocked when the
+    multi-var lookup is actually used by it.
+    """
+    if not LOOKUPS_AVAILABLE:
+        return []
+    _, names = _execution.has_multi_var_lookups(tool, prompt_ids=prompt_ids)
+    return names
+
+
+def persist_lookup_output(prompt_output, prompt_lookup: dict) -> None:
+    """Persist lookup enrichment result. No-op in OSS."""
+    if not LOOKUPS_AVAILABLE:
+        return
+    lookup_meta = prompt_lookup.get("meta", {})
+    lookup_id = lookup_meta.get("lookup_id")
+    if not lookup_id:
+        return
+    defaults = {
+        "lookup_definition_id": lookup_id,
+        "output": prompt_lookup.get("enriched", ""),
+    }
+    version_id = lookup_meta.get("version_id")
+    if version_id:
+        defaults["version_id"] = version_id
+    _LookupOutputResult.objects.update_or_create(
+        prompt_output=prompt_output,
+        defaults=defaults,
+    )
+
+
+def enrich_prompt_output(prompt_output, data: dict) -> dict:
+    """Let cloud plugins enrich serialized prompt output with lookup data.
+
+    No-op in OSS.
+    """
+    if not LOOKUPS_AVAILABLE:
+        return data
+    return _output_enrichment.enrich_with_lookup_output(prompt_output, data)
+
+
+def validate_lookups_for_export(prompts) -> tuple[dict, str | None]:
+    """Validate lookup assignments before export. Returns ({}, None) in OSS."""
+    if not LOOKUPS_AVAILABLE:
+        return {}, None
+    return _validation.validate_lookups_for_export(prompts)
+
+
+def get_latest_lookup_mutation_for_tool(tool):
+    """Max ``modified_at`` across lookup-related records linked to the tool
+    (version, reference file, assignment) — feeds the staleness banner.
+    None if unavailable or nothing linked.
+    """
+    if not LOOKUPS_AVAILABLE:
+        return None
+    return _staleness.get_latest_lookup_mutation_for_tool(tool)
+
+
+def get_original_value_if_enriched(
+    metadata: dict, prompt_key: str
+) -> tuple[Any, dict] | None:
+    """Return ``(original_value, prompt_lookup_dict)`` if ``prompt_key`` was
+    enriched, or ``None`` otherwise.
+
+    Pure metadata-shape check — safe to call even when LOOKUPS_AVAILABLE
+    is False (returns None because the shape won't match).
+    """
+    if not isinstance(metadata, dict):
+        return None
+    lookup_outputs = metadata.get("lookup_outputs") or {}
+    prompt_lookup = lookup_outputs.get(prompt_key)
+    if isinstance(prompt_lookup, dict) and "original" in prompt_lookup:
+        return prompt_lookup.get("original"), prompt_lookup
+    return None
+
+
+def attach_combined_output_enrichment(result: dict, enriched_by_key: dict) -> None:
+    """Stamp the combined-output payload with enriched-output metadata.
+
+    Key name stays cloud-side so the FE-plugin shape can evolve without
+    coordinating with OSS.
+    """
+    if not LOOKUPS_AVAILABLE:
+        return
+    _output_enrichment.attach_combined_output_enrichment(result, enriched_by_key)
+
+
+def extract_prompt_output_enrichment(item) -> dict | None:
+    """Pick enriched-output data off a serialized prompt-output row.
+
+    Returns a plugin-opaque dict (FE-only) or None when no enrichment
+    is present / plugin missing.
+    """
+    if not LOOKUPS_AVAILABLE:
+        return None
+    return _output_enrichment.extract_prompt_output_enrichment(item)
+
+
+def get_lookup_validation_for_tool(tool) -> dict:
+    """Pre-emptive lookup validation for FE Export / Deploy gating.
+
+    Returns an "always ok" payload in OSS so the FE gate is a no-op.
+    """
+    if not LOOKUPS_AVAILABLE:
+        return {
+            "ok": True,
+            "draft_lookups": [],
+            "multi_var_lookups": [],
+            "incomplete_lookups": [],
+            "single_pass_enabled": bool(
+                getattr(tool, "single_pass_extraction_mode", False)
+            ),
+        }
+    return _validation.get_lookup_validation_for_tool(tool)

backend/prompt_studio/prompt_studio_core_v2/migrations/0007_customtool_last_exported_at.py

@@ -0,0 +1,21 @@
+# Generated by Django 4.2.1 on 2026-04-21 20:20
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("prompt_studio_core_v2", "0006_add_custom_data_to_customtool"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="customtool",
+            name="last_exported_at",
+            field=models.DateTimeField(
+                blank=True,
+                db_comment="Timestamp of the last successful export; NULL if never exported since the field was introduced.",
+                null=True,
+            ),
+        ),
+    ]

backend/prompt_studio/prompt_studio_core_v2/models.py

@@ -161,6 +161,15 @@ class CustomTool(DefaultOrganizationMixin, BaseModel):
         db_comment="Flag to share this custom tool with all users in the organization",
     )
 
+    # NULL on pre-feature tools; populated on first successful export.
+    # Drives staleness checks (e.g. lookup-change banner) without requiring
+    # a data backfill.
+    last_exported_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        db_comment="Timestamp of the last successful export; NULL if never exported since the field was introduced.",
+    )
+
     objects = CustomToolModelManager()
 
     def delete(self, organization_id=None, *args, **kwargs):

backend/prompt_studio/prompt_studio_core_v2/prompt_studio_helper.py

@@ -14,12 +14,17 @@
 from django.db import transaction
 from django.db.models.manager import BaseManager
 from plugins import get_plugin
+from rest_framework.exceptions import APIException
 from rest_framework.request import Request
 from utils.file_storage.constants import FileStorageKeys
 from utils.file_storage.helpers.prompt_studio_file_helper import PromptStudioFileHelper
 from utils.local_context import StateStore
 
 from backend.celery_service import app as celery_app
+from prompt_studio.lookup_utils import (
+    get_lookup_config,
+    get_lookup_configs_for_tool,
+)
 from prompt_studio.prompt_profile_manager_v2.models import ProfileManager
 from prompt_studio.prompt_profile_manager_v2.profile_manager_helper import (
     ProfileManagerHelper,
@@ -387,6 +392,9 @@ def _build_prompt_output(
         if webhook_enabled:
             output[TSPKeys.POSTPROCESSING_WEBHOOK_URL] = webhook_url
 
+        if lookup_config := get_lookup_config(prompt):
+            output["lookup_config"] = lookup_config
+
         output[TSPKeys.EVAL_SETTINGS] = {}
         output[TSPKeys.EVAL_SETTINGS][TSPKeys.EVAL_SETTINGS_EVALUATE] = prompt.evaluate
         output[TSPKeys.EVAL_SETTINGS][TSPKeys.EVAL_SETTINGS_MONITOR_LLM] = [monitor_llm]
@@ -798,6 +806,9 @@ def build_fetch_response_payload(
         if webhook_enabled:
             output[TSPKeys.POSTPROCESSING_WEBHOOK_URL] = webhook_url
 
+        if lookup_config := get_lookup_config(prompt):
+            output["lookup_config"] = lookup_config
+
         output[TSPKeys.EVAL_SETTINGS] = {}
         output[TSPKeys.EVAL_SETTINGS][TSPKeys.EVAL_SETTINGS_EVALUATE] = prompt.evaluate
         output[TSPKeys.EVAL_SETTINGS][TSPKeys.EVAL_SETTINGS_MONITOR_LLM] = [monitor_llm]
@@ -1166,6 +1177,10 @@ def build_single_pass_payload(
             TSPKeys.SIMILARITY_TOP_K: default_profile.similarity_top_k,
         }
 
+        lookup_configs = get_lookup_configs_for_tool(tool, prompts=prompts)
+        if lookup_configs:
+            tool_settings["lookup_configs"] = lookup_configs
+
         for p in prompts:
             if not p.prompt:
                 raise EmptyPromptError()
@@ -1607,6 +1622,9 @@ def _execute_single_prompt(
                 is_single_pass=False,
                 profile_manager_id=profile_manager_id,
             )
+        except APIException:
+            # Validation responses are user-facing; DRF renders them as-is.
+            raise
         except Exception as e:
             logger.error(
                 f"[{tool.tool_id}] Error while fetching response for "
@@ -1672,6 +1690,9 @@ def _execute_prompts_in_single_pass(
                 document_id=document_id,
                 is_single_pass=True,
             )
+        except APIException:
+            # Validation responses are user-facing; DRF renders them as-is.
+            raise
         except Exception as e:
             logger.error(
                 f"[{tool.tool_id}] Error while fetching single pass response: {e}"
@@ -1911,6 +1932,8 @@ def _fetch_response(
         output[TSPKeys.ENABLE_POSTPROCESSING_WEBHOOK] = webhook_enabled
         if webhook_enabled:
             output[TSPKeys.POSTPROCESSING_WEBHOOK_URL] = webhook_url
+        if lookup_config := get_lookup_config(prompt):
+            output["lookup_config"] = lookup_config
         # Eval settings for the prompt
         output[TSPKeys.EVAL_SETTINGS] = {}
         output[TSPKeys.EVAL_SETTINGS][TSPKeys.EVAL_SETTINGS_EVALUATE] = prompt.evaluate

backend/prompt_studio/prompt_studio_core_v2/urls.py

@@ -66,6 +66,10 @@
 
 prompt_studio_task_status = PromptStudioCoreView.as_view({"get": "task_status"})
 
+prompt_studio_lookup_validation = PromptStudioCoreView.as_view(
+    {"get": "lookup_validation"}
+)
+
 
 urlpatterns = format_suffix_patterns(
     [
@@ -165,5 +169,10 @@
             prompt_studio_task_status,
             name="prompt-studio-task-status",
         ),
+        path(
+            "prompt-studio/<uuid:pk>/lookup-validation/",
+            prompt_studio_lookup_validation,
+            name="prompt-studio-lookup-validation",
+        ),
     ]
 )