pymlsapi 0.1.0__py3-none-any.whl

pymlsapi/resources/studio/custom.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.studio import CustomStudioResult, StudioJob
+from pymlsapi.resources.studio.jobs import AsyncStudioJobsResource, StudioJobsResource
+
+
+class CustomResource:
+    """Synchronous custom multimodal generative studio prompt."""
+
+    def __init__(self, http: HttpClient, jobs: StudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    def generate(
+        self,
+        prompt: str,
+        image_urls: Optional[List[str]] = None,
+        negative_prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {"prompt": prompt}
+        if image_urls:
+            payload["image_urls"] = image_urls
+        if negative_prompt:
+            payload["negative_prompt"] = negative_prompt
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = self._http.post("/v1/studio/custom", json=payload)
+        return StudioJob.model_validate(data)
+
+    def generate_and_wait(
+        self,
+        prompt: str,
+        image_urls: Optional[List[str]] = None,
+        negative_prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> CustomStudioResult:
+        job = self.generate(
+            prompt, image_urls=image_urls, negative_prompt=negative_prompt, webhook_url=webhook_url
+        )
+        completed = self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return CustomStudioResult.model_validate(completed.result or {})
+
+
+class AsyncCustomResource:
+    """Asynchronous custom multimodal generative studio prompt."""
+
+    def __init__(self, http: AsyncHttpClient, jobs: AsyncStudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    async def generate(
+        self,
+        prompt: str,
+        image_urls: Optional[List[str]] = None,
+        negative_prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {"prompt": prompt}
+        if image_urls:
+            payload["image_urls"] = image_urls
+        if negative_prompt:
+            payload["negative_prompt"] = negative_prompt
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = await self._http.post("/v1/studio/custom", json=payload)
+        return StudioJob.model_validate(data)
+
+    async def generate_and_wait(
+        self,
+        prompt: str,
+        image_urls: Optional[List[str]] = None,
+        negative_prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> CustomStudioResult:
+        job = await self.generate(
+            prompt, image_urls=image_urls, negative_prompt=negative_prompt, webhook_url=webhook_url
+        )
+        completed = await self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return CustomStudioResult.model_validate(completed.result or {})

pymlsapi/resources/studio/enhance.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.studio import ExteriorEnhanceResult, StudioJob, UpscaleResult
+from pymlsapi.resources.studio.jobs import AsyncStudioJobsResource, StudioJobsResource
+
+
+class EnhanceResource:
+    """Synchronous exterior curb appeal and 4K upscaling operations."""
+
+    def __init__(self, http: HttpClient, jobs: StudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    def exterior(
+        self,
+        photo_url: str,
+        enhancements: Optional[List[str]] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {"photo_url": photo_url}
+        if enhancements:
+            payload["enhancements"] = enhancements
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = self._http.post("/v1/studio/enhance/exterior", json=payload)
+        return StudioJob.model_validate(data)
+
+    def exterior_and_wait(
+        self,
+        photo_url: str,
+        enhancements: Optional[List[str]] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> ExteriorEnhanceResult:
+        job = self.exterior(photo_url, enhancements=enhancements, webhook_url=webhook_url)
+        completed = self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return ExteriorEnhanceResult.model_validate(completed.result or {})
+
+    def upscale(
+        self,
+        image_url: str,
+        scale_factor: int = 4,
+        enhance_details: bool = True,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {
+            "image_url": image_url,
+            "scale_factor": scale_factor,
+            "enhance_details": enhance_details,
+        }
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = self._http.post("/v1/studio/enhance/upscale", json=payload)
+        return StudioJob.model_validate(data)
+
+    def upscale_and_wait(
+        self,
+        image_url: str,
+        scale_factor: int = 4,
+        enhance_details: bool = True,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> UpscaleResult:
+        job = self.upscale(
+            image_url,
+            scale_factor=scale_factor,
+            enhance_details=enhance_details,
+            webhook_url=webhook_url,
+        )
+        completed = self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return UpscaleResult.model_validate(completed.result or {})
+
+
+class AsyncEnhanceResource:
+    """Asynchronous exterior curb appeal and 4K upscaling operations."""
+
+    def __init__(self, http: AsyncHttpClient, jobs: AsyncStudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    async def exterior(
+        self,
+        photo_url: str,
+        enhancements: Optional[List[str]] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {"photo_url": photo_url}
+        if enhancements:
+            payload["enhancements"] = enhancements
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = await self._http.post("/v1/studio/enhance/exterior", json=payload)
+        return StudioJob.model_validate(data)
+
+    async def exterior_and_wait(
+        self,
+        photo_url: str,
+        enhancements: Optional[List[str]] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> ExteriorEnhanceResult:
+        job = await self.exterior(photo_url, enhancements=enhancements, webhook_url=webhook_url)
+        completed = await self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return ExteriorEnhanceResult.model_validate(completed.result or {})
+
+    async def upscale(
+        self,
+        image_url: str,
+        scale_factor: int = 4,
+        enhance_details: bool = True,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {
+            "image_url": image_url,
+            "scale_factor": scale_factor,
+            "enhance_details": enhance_details,
+        }
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = await self._http.post("/v1/studio/enhance/upscale", json=payload)
+        return StudioJob.model_validate(data)
+
+    async def upscale_and_wait(
+        self,
+        image_url: str,
+        scale_factor: int = 4,
+        enhance_details: bool = True,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> UpscaleResult:
+        job = await self.upscale(
+            image_url,
+            scale_factor=scale_factor,
+            enhance_details=enhance_details,
+            webhook_url=webhook_url,
+        )
+        completed = await self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return UpscaleResult.model_validate(completed.result or {})

pymlsapi/resources/studio/floorplan.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.studio import FloorPlanAnalysisResponse, Render3dResult, StudioJob
+from pymlsapi.resources.studio.jobs import AsyncStudioJobsResource, StudioJobsResource
+
+
+class FloorPlanResource:
+    """Synchronous 2D floor plan blueprint analysis and 3D isometric dollhouse rendering."""
+
+    def __init__(self, http: HttpClient, jobs: StudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    def analyze(
+        self,
+        floorplan_image_url: str,
+        style: Optional[str] = "modern",
+        mls_id: Optional[str] = None,
+        generate_3d_render: bool = False,
+    ) -> FloorPlanAnalysisResponse:
+        """Analyze 2D floorplan geometry, detect rooms, and generate design prompts."""
+        payload: Dict[str, Any] = {
+            "floorplan_image_url": floorplan_image_url,
+            "style": style,
+            "generate_3d_render": generate_3d_render,
+        }
+        if mls_id:
+            payload["mls_id"] = mls_id
+        data = self._http.post("/v1/studio/floorplan/analyze", json=payload)
+        return FloorPlanAnalysisResponse.model_validate(data)
+
+    def render_3d(
+        self,
+        floorplan_image_url: str,
+        style: Optional[str] = "modern",
+        include_room_closeups: bool = True,
+        target_rooms: Optional[List[str]] = None,
+        custom_prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        """Trigger asynchronous 3D isometric dollhouse cutaway model rendering."""
+        payload: Dict[str, Any] = {
+            "floorplan_image_url": floorplan_image_url,
+            "style": style,
+            "include_room_closeups": include_room_closeups,
+        }
+        if target_rooms:
+            payload["target_rooms"] = target_rooms
+        if custom_prompt:
+            payload["custom_prompt"] = custom_prompt
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = self._http.post("/v1/studio/floorplan/render-3d", json=payload)
+        return StudioJob.model_validate(data)
+
+    def render_3d_and_wait(
+        self,
+        floorplan_image_url: str,
+        style: Optional[str] = "modern",
+        include_room_closeups: bool = True,
+        target_rooms: Optional[List[str]] = None,
+        custom_prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 120.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> Render3dResult:
+        """Render 3D isometric dollhouse and auto-poll until complete."""
+        job = self.render_3d(
+            floorplan_image_url=floorplan_image_url,
+            style=style,
+            include_room_closeups=include_room_closeups,
+            target_rooms=target_rooms,
+            custom_prompt=custom_prompt,
+            webhook_url=webhook_url,
+        )
+        completed = self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return Render3dResult.model_validate(completed.result or {})
+
+
+class AsyncFloorPlanResource:
+    """Asynchronous 2D floor plan blueprint analysis and 3D isometric dollhouse rendering."""
+
+    def __init__(self, http: AsyncHttpClient, jobs: AsyncStudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    async def analyze(
+        self,
+        floorplan_image_url: str,
+        style: Optional[str] = "modern",
+        mls_id: Optional[str] = None,
+        generate_3d_render: bool = False,
+    ) -> FloorPlanAnalysisResponse:
+        """Analyze 2D floorplan geometry, detect rooms, and generate design prompts."""
+        payload: Dict[str, Any] = {
+            "floorplan_image_url": floorplan_image_url,
+            "style": style,
+            "generate_3d_render": generate_3d_render,
+        }
+        if mls_id:
+            payload["mls_id"] = mls_id
+        data = await self._http.post("/v1/studio/floorplan/analyze", json=payload)
+        return FloorPlanAnalysisResponse.model_validate(data)
+
+    async def render_3d(
+        self,
+        floorplan_image_url: str,
+        style: Optional[str] = "modern",
+        include_room_closeups: bool = True,
+        target_rooms: Optional[List[str]] = None,
+        custom_prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        """Trigger asynchronous 3D isometric dollhouse cutaway model rendering."""
+        payload: Dict[str, Any] = {
+            "floorplan_image_url": floorplan_image_url,
+            "style": style,
+            "include_room_closeups": include_room_closeups,
+        }
+        if target_rooms:
+            payload["target_rooms"] = target_rooms
+        if custom_prompt:
+            payload["custom_prompt"] = custom_prompt
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = await self._http.post("/v1/studio/floorplan/render-3d", json=payload)
+        return StudioJob.model_validate(data)
+
+    async def render_3d_and_wait(
+        self,
+        floorplan_image_url: str,
+        style: Optional[str] = "modern",
+        include_room_closeups: bool = True,
+        target_rooms: Optional[List[str]] = None,
+        custom_prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 120.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> Render3dResult:
+        """Render 3D isometric dollhouse and auto-poll until complete."""
+        job = await self.render_3d(
+            floorplan_image_url=floorplan_image_url,
+            style=style,
+            include_room_closeups=include_room_closeups,
+            target_rooms=target_rooms,
+            custom_prompt=custom_prompt,
+            webhook_url=webhook_url,
+        )
+        completed = await self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return Render3dResult.model_validate(completed.result or {})

pymlsapi/resources/studio/jobs.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.studio import StudioJob
+from pymlsapi.poller import poll_job_async, poll_job_sync
+
+
+class StudioJobsResource:
+    """Synchronous tracking and polling for Studio AI background jobs."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self, job_id: str) -> StudioJob:
+        """Fetch current status and progress of a Studio job."""
+        data = self._http.get(f"/v1/studio/jobs/{job_id}")
+        return StudioJob.model_validate(data)
+
+    def wait_for(
+        self,
+        job_id: str,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> StudioJob:
+        """Poll job until completion, returning final StudioJob with result."""
+
+        def fetch_job() -> StudioJob:
+            return self.get(job_id)
+
+        def is_done(job: StudioJob) -> bool:
+            return job.status == "completed"
+
+        def is_failed(job: StudioJob) -> bool:
+            return job.status == "failed"
+
+        return poll_job_sync(
+            fetch_fn=fetch_job,
+            is_done_fn=is_done,
+            is_failed_fn=is_failed,
+            timeout_seconds=timeout_seconds,
+            initial_interval=poll_interval,
+            on_progress=on_progress,
+        )
+
+
+class AsyncStudioJobsResource:
+    """Asynchronous tracking and polling for Studio AI background jobs."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def get(self, job_id: str) -> StudioJob:
+        """Fetch current status and progress of a Studio job."""
+        data = await self._http.get(f"/v1/studio/jobs/{job_id}")
+        return StudioJob.model_validate(data)
+
+    async def wait_for(
+        self,
+        job_id: str,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> StudioJob:
+        """Poll job until completion, returning final StudioJob with result."""
+
+        async def fetch_job() -> StudioJob:
+            return await self.get(job_id)
+
+        def is_done(job: StudioJob) -> bool:
+            return job.status == "completed"
+
+        def is_failed(job: StudioJob) -> bool:
+            return job.status == "failed"
+
+        return await poll_job_async(
+            fetch_fn=fetch_job,
+            is_done_fn=is_done,
+            is_failed_fn=is_failed,
+            timeout_seconds=timeout_seconds,
+            initial_interval=poll_interval,
+            on_progress=on_progress,
+        )

pymlsapi/resources/studio/render.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.studio import ArchitecturalRenderResult, StudioJob
+from pymlsapi.resources.studio.jobs import AsyncStudioJobsResource, StudioJobsResource
+
+
+class RenderResource:
+    """Synchronous architectural visualization rendering (CAD / Sketch / SketchUp to photorealism)."""
+
+    def __init__(self, http: HttpClient, jobs: StudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    def architectural(
+        self,
+        source_image_url: str,
+        style: Optional[str] = "modern",
+        prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {"source_image_url": source_image_url, "style": style}
+        if prompt:
+            payload["prompt"] = prompt
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = self._http.post("/v1/studio/render/architectural", json=payload)
+        return StudioJob.model_validate(data)
+
+    def architectural_and_wait(
+        self,
+        source_image_url: str,
+        style: Optional[str] = "modern",
+        prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> ArchitecturalRenderResult:
+        job = self.architectural(
+            source_image_url, style=style, prompt=prompt, webhook_url=webhook_url
+        )
+        completed = self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return ArchitecturalRenderResult.model_validate(completed.result or {})
+
+
+class AsyncRenderResource:
+    """Asynchronous architectural visualization rendering."""
+
+    def __init__(self, http: AsyncHttpClient, jobs: AsyncStudioJobsResource) -> None:
+        self._http = http
+        self._jobs = jobs
+
+    async def architectural(
+        self,
+        source_image_url: str,
+        style: Optional[str] = "modern",
+        prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> StudioJob:
+        payload: Dict[str, Any] = {"source_image_url": source_image_url, "style": style}
+        if prompt:
+            payload["prompt"] = prompt
+        if webhook_url:
+            payload["webhook_url"] = webhook_url
+        data = await self._http.post("/v1/studio/render/architectural", json=payload)
+        return StudioJob.model_validate(data)
+
+    async def architectural_and_wait(
+        self,
+        source_image_url: str,
+        style: Optional[str] = "modern",
+        prompt: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        timeout_seconds: float = 90.0,
+        poll_interval: float = 2.0,
+        on_progress: Optional[Callable[[StudioJob], None]] = None,
+    ) -> ArchitecturalRenderResult:
+        job = await self.architectural(
+            source_image_url, style=style, prompt=prompt, webhook_url=webhook_url
+        )
+        completed = await self._jobs.wait_for(
+            job.job_id,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+        return ArchitecturalRenderResult.model_validate(completed.result or {})

pymlsapi/resources/studio/social.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pymlsapi.async_http import AsyncHttpClient
+from pymlsapi.http import HttpClient
+from pymlsapi.models.studio import SocialPublishResult
+
+
+class SocialResource:
+    """Synchronous direct social network publishing operations."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def publish(
+        self,
+        asset_url: str,
+        destinations: List[str],
+        caption: Optional[str] = None,
+        schedule_time: Optional[str] = None,
+    ) -> SocialPublishResult:
+        payload: Dict[str, Any] = {
+            "asset_url": asset_url,
+            "destinations": destinations,
+        }
+        if caption:
+            payload["caption"] = caption
+        if schedule_time:
+            payload["schedule_time"] = schedule_time
+        data = self._http.post("/v1/studio/social/publish", json=payload)
+        return SocialPublishResult.model_validate(data)
+
+
+class AsyncSocialResource:
+    """Asynchronous direct social network publishing operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def publish(
+        self,
+        asset_url: str,
+        destinations: List[str],
+        caption: Optional[str] = None,
+        schedule_time: Optional[str] = None,
+    ) -> SocialPublishResult:
+        payload: Dict[str, Any] = {
+            "asset_url": asset_url,
+            "destinations": destinations,
+        }
+        if caption:
+            payload["caption"] = caption
+        if schedule_time:
+            payload["schedule_time"] = schedule_time
+        data = await self._http.post("/v1/studio/social/publish", json=payload)
+        return SocialPublishResult.model_validate(data)