feat: Introduce sandbox attach functionality for existing facilities

- Added `sandbox_attach.py` to implement the `seed_existing_facility` function, allowing seed data to be attached to existing facilities without creating duplicates.
- Enhanced `DemoSeedRunner` to resolve geo organization from the run or profile, improving flexibility in seed execution.
- Implemented error handling to ensure only superusers can initiate the seed run.
- Created unit tests in `test_sandbox_attach.py` to validate the new functionality and ensure proper error handling and execution flow.
- Updated `seed_runs.py` with a new `create_attached_seed_run` function to facilitate the creation of seed runs for existing facilities.

Author: yash-learner

src/care_demo_facility_setup/services/runner.py

@@ -24,15 +24,25 @@ def __init__(self, run: SeedRun):
         self.run = run
         self.pack = load_seed_pack(run.pack_slug)
         profile = load_profile(run.pack_slug, run.profile_slug)
+        geo_organization = self._resolve_geo_organization(run, profile)
         self.context = SeedContext(
             client=CareSeedClient(run.requested_by),
             artifacts=SeedArtifactStore(run),
-            geo_organization=profile["geo_organization_external_id"],
+            geo_organization=geo_organization,
             run=run,
             pack=self.pack,
             profile=profile,
         )
 
+    @staticmethod
+    def _resolve_geo_organization(run: SeedRun, profile: dict) -> str:
+        """Prefer caller-injected geo (attach/sandbox); fall back to profile."""
+        payload = run.request_payload or {}
+        geo = payload.get("geo_organization_external_id") or profile.get("geo_organization_external_id")
+        if not geo:
+            raise SeedRunExecutionError("No geo_organization_external_id on the seed run or profile.")
+        return str(geo)
+
     def execute(self):
         if self.run.status in {
             SeedRunStatus.SUCCEEDED,
@@ -48,6 +58,13 @@ def execute(self):
         self._mark_run(SeedRunStatus.RUNNING, started=True)
         try:
             for step_definition in get_executable_seed_step_definitions(self.pack["manifest"]):
+                step = self._get_step(step_definition.key)
+                # Attach mode (and any pre-completed step) must not re-run.
+                if step.status in {
+                    SeedRunStepStatus.SUCCEEDED,
+                    SeedRunStepStatus.SKIPPED,
+                }:
+                    continue
                 self._execute_seed_step(step_definition)
         except Exception as exc:
             self._mark_pending_steps_skipped("Skipped because an earlier step failed.")

src/care_demo_facility_setup/services/sandbox_attach.py

@@ -0,0 +1,200 @@
+"""Programmatic attach-to-existing-facility entrypoint for sandbox callers.
+
+Seeds pack content onto a facility that already exists (e.g. Experience sandbox
+shell). Does not create a second facility. Runs DemoSeedRunner.execute()
+synchronously — never enqueue_seed_run / .delay().
+"""
+
+from __future__ import annotations
+
+from care_demo_facility_setup.models import SeedRun, SeedRunStatus, SeedRunStepStatus
+from care_demo_facility_setup.services.runner import DemoSeedRunner
+from care_demo_facility_setup.services.seed_errors import SeedRunExecutionError
+from care_demo_facility_setup.services.seed_packs import DEFAULT_PACK_SLUG
+from care_demo_facility_setup.services.seed_runs import create_attached_seed_run
+
+# Clearer panel keys than raw step keys (title-case still works either way).
+_SUMMARY_KEYS = {
+    "inventory_items": "product_knowledges",
+}
+
+_STAT_LABELS = {
+    "created": "created",
+    "attached": "attached",
+    "reused": "reused",
+    "products_received": "received",
+    "transferred": "transferred",
+    "categories_created": "categories",
+    "departments_created": "departments",
+    "departments_reused": "departments reused",
+    "locations_created": "locations",
+    "healthcare_services_created": "services",
+    "op_closed": "OP",
+    "ip_in_progress": "IP",
+    "emergency": "emergency",
+    "beds_assigned": "beds",
+}
+
+
+def seed_existing_facility(
+    *,
+    facility_external_id: str,
+    geo_organization_external_id: str,
+    requested_by,
+    pack_slug: str = DEFAULT_PACK_SLUG,
+    profile_slug: str = "local",
+) -> SeedRun:
+    """Attach pack seed data to an existing facility and execute synchronously.
+
+    Returns the SeedRun on SUCCEEDED. Raises SeedRunExecutionError (or the
+    underlying step exception) on failure so the sandbox task can mark the job
+    failed.
+    """
+    if not requested_by or not getattr(requested_by, "is_superuser", False):
+        raise SeedRunExecutionError("Seed run must be requested by a superuser.")
+
+    run = create_attached_seed_run(
+        facility_external_id=str(facility_external_id),
+        geo_organization_external_id=str(geo_organization_external_id),
+        requested_by=requested_by,
+        pack_slug=pack_slug,
+        profile_slug=profile_slug,
+    )
+    DemoSeedRunner(run).execute()
+    run.refresh_from_db()
+    if run.status != SeedRunStatus.SUCCEEDED:
+        raise SeedRunExecutionError(run.error or "Attached seed run did not succeed.")
+    return run
+
+
+def _is_int(value) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _join_parts(parts: list[str]) -> str | None:
+    return " · ".join(parts) if parts else None
+
+
+def _format_stats_summary(key: str, stats) -> str | None:
+    """Build a short labeled string from step stats when message is absent."""
+    if stats is True or stats is None or stats == {}:
+        return None
+    if isinstance(stats, bool):
+        return None
+    if _is_int(stats):
+        return str(stats)
+    if not isinstance(stats, dict):
+        return None
+
+    if key in {"inventory_items", "product_knowledges"}:
+        created = stats.get("created")
+        received = stats.get("products_received")
+        transferred = stats.get("transferred")
+        parts = []
+        if _is_int(created):
+            parts.append(f"{created} product knowledges")
+        if _is_int(received):
+            parts.append(f"{received} received")
+        if _is_int(transferred):
+            parts.append(f"{transferred} transferred")
+        if parts:
+            return _join_parts(parts)
+
+    if key == "clinical_visits":
+        created = stats.get("created")
+        if _is_int(created):
+            breakdown = []
+            for stat_key, label in (
+                ("op_closed", "OP"),
+                ("ip_in_progress", "IP"),
+                ("emergency", "emergency"),
+            ):
+                value = stats.get(stat_key)
+                if _is_int(value) and value:
+                    breakdown.append(f"{value} {label}")
+            if breakdown:
+                return f"{created} ({', '.join(breakdown)})"
+            return str(created)
+
+    if key == "facility":
+        attached = stats.get("attached")
+        created = stats.get("created")
+        parts = []
+        if _is_int(attached) and attached:
+            parts.append(f"{attached} attached")
+        if _is_int(created) and created:
+            parts.append(f"{created} created")
+        if parts:
+            return ", ".join(parts)
+        if _is_int(attached):
+            return "attached" if attached else "0 attached"
+        if _is_int(created):
+            return f"{created} created"
+
+    if key == "facility_foundation":
+        parts = []
+        for stat_key, label in (
+            ("departments_created", "departments"),
+            ("departments_reused", "departments reused"),
+            ("locations_created", "locations"),
+            ("healthcare_services_created", "services"),
+        ):
+            value = stats.get(stat_key)
+            if _is_int(value) and value:
+                parts.append(f"{value} {label}")
+        if parts:
+            return _join_parts(parts)
+
+    if key == "questionnaires":
+        created = stats.get("created")
+        reused = stats.get("reused")
+        parts = []
+        if _is_int(created):
+            parts.append(f"{created} created")
+        if _is_int(reused):
+            parts.append(f"{reused} reused")
+        if parts:
+            return ", ".join(parts)
+
+    parts = []
+    for stat_key, value in stats.items():
+        if not _is_int(value):
+            continue
+        label = _STAT_LABELS.get(stat_key, stat_key.replace("_", " "))
+        parts.append(f"{value} {label}")
+    return _join_parts(parts)
+
+
+def _step_summary(step) -> str | None:
+    """Human-readable value for one succeeded seed step."""
+    message = getattr(step, "message", None)
+    if isinstance(message, str) and message.strip():
+        return message.strip()
+    return _format_stats_summary(step.key, getattr(step, "stats", None))
+
+
+def summarize_seed_run(run: SeedRun) -> dict:
+    """Map SeedRun steps into readable summaries for the Experience sandbox panel.
+
+    Values are short strings (or rarely plain ints) derived from each step's
+    seeder ``message`` when present, otherwise from labeled ``stats``. Debug
+    identifiers live under ``_meta`` (Experience skips ``_`` keys). Failed
+    steps are omitted.
+    """
+    loaded: dict = {
+        "_meta": {
+            "seed_run_id": str(run.external_id),
+            "pack_slug": run.pack_slug,
+            "profile_slug": run.profile_slug,
+        },
+    }
+    for step in run.steps.all().order_by("order"):
+        if step.key == "validate":
+            continue
+        status = step.status.value if hasattr(step.status, "value") else step.status
+        if status != SeedRunStepStatus.SUCCEEDED:
+            continue
+        summary = _step_summary(step)
+        if summary is not None:
+            loaded[_SUMMARY_KEYS.get(step.key, step.key)] = summary
+    return loaded

src/care_demo_facility_setup/services/seed_runs.py

@@ -1,15 +1,24 @@
 from __future__ import annotations
 
+from care.emr.models.organization import Organization
+from care.facility.models import Facility
 from django.db import transaction
 from django.utils import timezone
 
 from care_demo_facility_setup.models import (
     SeedRun,
+    SeedRunArtifact,
     SeedRunStatus,
     SeedRunStep,
     SeedRunStepStatus,
 )
-from care_demo_facility_setup.services.seed_packs import SeedPackError, load_seed_pack
+from care_demo_facility_setup.services.seed_errors import SeedRunExecutionError
+from care_demo_facility_setup.services.seed_packs import (
+    DEFAULT_PACK_SLUG,
+    SeedPackError,
+    load_profile,
+    load_seed_pack,
+)
 from care_demo_facility_setup.services.seed_step_registry import SeedStepRegistryError, get_seed_step_definitions
 from care_demo_facility_setup.services.seed_validation import validate_seed_request
 
@@ -143,3 +152,121 @@ def enqueue_seed_run(run_external_id: str):
             error=f"Could not enqueue seed run: {exc}",
             finished_date=timezone.now(),
         )
+
+
+@transaction.atomic
+def create_attached_seed_run(
+    *,
+    facility_external_id: str,
+    geo_organization_external_id: str,
+    requested_by,
+    pack_slug: str = DEFAULT_PACK_SLUG,
+    profile_slug: str = "local",
+) -> SeedRun:
+    """Create a SeedRun that attaches pack content to an existing facility.
+
+    Skips host/profile geo validation: the caller supplies geo and facility ids.
+    Pre-stores ``facility:main`` and marks the facility step succeeded so
+    FacilitySeeder is never called. Standalone ``create_seed_run`` is unchanged.
+    """
+    try:
+        pack = load_seed_pack(pack_slug)
+        profile = load_profile(pack_slug, profile_slug)
+    except SeedPackError as exc:
+        raise SeedRunExecutionError(str(exc)) from exc
+
+    if not Organization.objects.filter(
+        external_id=geo_organization_external_id,
+        org_type="govt",
+    ).exists():
+        raise SeedRunExecutionError("geo_organization_external_id does not match an existing govt organization.")
+
+    try:
+        facility = Facility.objects.get(external_id=facility_external_id)
+    except Facility.DoesNotExist as exc:
+        raise SeedRunExecutionError(f"Facility {facility_external_id} does not exist.") from exc
+
+    facility_ref = pack.get("facility", {}).get("ref", "facility:main")
+    manifest = pack["manifest"]
+    now = timezone.now()
+    request_payload = {
+        "pack_slug": pack_slug,
+        "profile_slug": profile_slug,
+        "dry_run": False,
+        "attach_existing_facility": True,
+        "facility_external_id": str(facility_external_id),
+        "geo_organization_external_id": str(geo_organization_external_id),
+    }
+    summary = {
+        "pack_slug": manifest["slug"],
+        "pack_name": manifest["name"],
+        "pack_version": manifest["version"],
+        "profile_slug": profile["slug"],
+        "profile_name": profile["name"],
+        "counts": manifest.get("counts", {}),
+        "geo_organization_external_id": str(geo_organization_external_id),
+        "facility_external_id": str(facility_external_id),
+        "attach_existing_facility": True,
+        "resource_categories": profile.get("resource_categories", {}),
+    }
+
+    run = SeedRun.objects.create(
+        pack_slug=pack_slug,
+        profile_slug=profile_slug,
+        dry_run=False,
+        requested_by=requested_by,
+        request_payload=request_payload,
+        summary=summary,
+        status=SeedRunStatus.QUEUED,
+        error="",
+    )
+
+    facility_step = None
+    for index, step_definition in enumerate(_planned_steps_for_pack(pack_slug), start=1):
+        if step_definition.key == "validate":
+            status = SeedRunStepStatus.SUCCEEDED
+            message = "Attach-mode validation passed (geo and facility injected)."
+            started = now
+            finished = now
+            stats = summary.get("counts", {})
+        elif step_definition.key == "facility":
+            status = SeedRunStepStatus.SUCCEEDED
+            message = f"Attached existing facility {facility.name}"
+            started = now
+            finished = now
+            stats = {"created": 0, "attached": 1}
+        else:
+            status = SeedRunStepStatus.PENDING
+            message = ""
+            started = None
+            finished = None
+            stats = {}
+
+        step = SeedRunStep.objects.create(
+            run=run,
+            order=index,
+            key=step_definition.key,
+            title=step_definition.title,
+            status=status,
+            message=message,
+            stats=stats,
+            started_date=started,
+            finished_date=finished,
+        )
+        if step_definition.key == "facility":
+            facility_step = step
+
+    SeedRunArtifact.objects.create(
+        run=run,
+        step=facility_step,
+        ref=facility_ref,
+        resource_type="Facility",
+        resource_external_id=facility.external_id,
+        slug=getattr(facility, "slug", "") or "",
+        payload={
+            "id": str(facility.external_id),
+            "name": facility.name,
+            "attached": True,
+        },
+    )
+    return run