pymlsapi 0.1.0__py3-none-any.whl

pymlsapi/models/__init__.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from pymlsapi.models.common import InteriorStyle, JobStatus, RoomType, SocialPlatform
+from pymlsapi.models.content import (
+    ContentGenerationResponse,
+    GeneratedContentBundle,
+    InstagramContent,
+    SocialPlatformBundle,
+    VideoScriptContent,
+)
+from pymlsapi.models.intelligence import (
+    FinancialFlag,
+    InvestorInsights,
+    LlmIntelligence,
+    PropertyIntelligence,
+    SystemCondition,
+    SystemsAndCapex,
+)
+from pymlsapi.models.listings import (
+    Address,
+    AgentInfo,
+    BaseListing,
+    Coordinates,
+    IngestJob,
+    ListingMetadata,
+    PropertyFeatures,
+    PropertySpecifications,
+)
+from pymlsapi.models.studio import (
+    AdCreativesResult,
+    ArchitecturalRenderResult,
+    CustomStudioResult,
+    DeclutterResult,
+    DeStageEmptyResult,
+    ExteriorEnhanceResult,
+    FloorPlanAnalysisResponse,
+    HouseTourResult,
+    Render3dResult,
+    ReplaceFurnitureResult,
+    ReplaceMaterialResult,
+    RestyleResult,
+    SocialPublishResult,
+    StagingResult,
+    StudioJob,
+    TwilightResult,
+    UploadResult,
+    UpscaleResult,
+    VideoEnhanceResult,
+    VideoTransitionResult,
+    VideoWalkthroughResult,
+    WallColorsResult,
+)
+
+__all__ = [
+    "AdCreativesResult",
+    "Address",
+    "AgentInfo",
+    "ArchitecturalRenderResult",
+    "BaseListing",
+    "ContentGenerationResponse",
+    "Coordinates",
+    "CustomStudioResult",
+    "DeStageEmptyResult",
+    "DeclutterResult",
+    "ExteriorEnhanceResult",
+    "FinancialFlag",
+    "FloorPlanAnalysisResponse",
+    "GeneratedContentBundle",
+    "HouseTourResult",
+    "IngestJob",
+    "InstagramContent",
+    "InteriorStyle",
+    "InvestorInsights",
+    "JobStatus",
+    "ListingMetadata",
+    "LlmIntelligence",
+    "PropertyFeatures",
+    "PropertyIntelligence",
+    "PropertySpecifications",
+    "Render3dResult",
+    "ReplaceFurnitureResult",
+    "ReplaceMaterialResult",
+    "RestyleResult",
+    "RoomType",
+    "SocialPlatform",
+    "SocialPlatformBundle",
+    "SocialPublishResult",
+    "StagingResult",
+    "StudioJob",
+    "SystemCondition",
+    "SystemsAndCapex",
+    "TwilightResult",
+    "UploadResult",
+    "UpscaleResult",
+    "VideoEnhanceResult",
+    "VideoScriptContent",
+    "VideoTransitionResult",
+    "VideoWalkthroughResult",
+    "WallColorsResult",
+]

pymlsapi/models/common.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class InteriorStyle(str, Enum):
+    MODERN = "modern"
+    LUXURY = "luxury"
+    SCANDINAVIAN = "scandinavian"
+    JAPANDI = "japandi"
+    INDUSTRIAL = "industrial"
+    BOHEMIAN = "bohemian"
+    MINIMALIST = "minimalist"
+    COASTAL = "coastal"
+    MID_CENTURY_MODERN = "mid_century_modern"
+    ART_DECO = "art_deco"
+    FARMHOUSE = "farmhouse"
+    MEDITERRANEAN = "mediterranean"
+    CONTEMPORARY = "contemporary"
+    RUSTIC = "rustic"
+    TRANSITIONAL = "transitional"
+    FRENCH_COUNTRY = "french_country"
+    HOLLYWOOD_REGENCY = "hollywood_regency"
+    ECLECTIC = "eclectic"
+    ZEN = "zen"
+    BAUHAUS = "bauhaus"
+    VICTORIAN = "victorian"
+    TROPICAL = "tropical"
+    MODERN_CRAFTSMAN = "modern_craftsman"
+    SOUTHWESTERN = "southwestern"
+    WABI_SABI = "wabi_sabi"
+    SHABBY_CHIC = "shabby_chic"
+    CHALET = "chalet"
+    URBAN_LOFT = "urban_loft"
+    CUSTOM = "custom"
+
+
+class RoomType(str, Enum):
+    LIVING_ROOM = "living_room"
+    BEDROOM = "bedroom"
+    PRIMARY_BEDROOM = "primary_bedroom"
+    DINING_ROOM = "dining_room"
+    KITCHEN = "kitchen"
+    BATHROOM = "bathroom"
+    PATIO = "patio"
+    OUTDOOR_PATIO = "outdoor_patio"
+    HOME_OFFICE = "home_office"
+    ENTRYWAY = "entryway"
+    BASEMENT = "basement"
+    COMMERCIAL_LOBBY = "commercial_lobby"
+
+
+class SocialPlatform(str, Enum):
+    INSTAGRAM = "instagram"
+    FACEBOOK = "facebook"
+    LINKEDIN = "linkedin"
+    X_TWITTER = "x_twitter"
+    TIKTOK = "tiktok"
+    YOUTUBE = "youtube"
+
+
+class JobStatus(str, Enum):
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"

pymlsapi/models/content.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class InstagramContent(BaseModel):
+    hook_above_fold: Optional[str] = None
+    caption: str
+    carousel_prompt: Optional[str] = None
+    call_to_action: Optional[str] = None
+    hashtags: List[str] = Field(default_factory=list)
+    character_count: Optional[int] = None
+
+
+class FacebookContent(BaseModel):
+    headline: Optional[str] = None
+    post_copy: str
+    link_preview: Optional[Dict[str, str]] = None
+    hashtags: List[str] = Field(default_factory=list)
+
+
+class LinkedInContent(BaseModel):
+    post_copy: str
+    hashtags: List[str] = Field(default_factory=list)
+
+
+class XTwitterContent(BaseModel):
+    single_tweet: Optional[str] = None
+    thread: List[str] = Field(default_factory=list)
+
+
+class TikTokContent(BaseModel):
+    caption: str
+    on_screen_hook_text: Optional[str] = None
+    call_to_action_cue: Optional[str] = None
+    sound_recommendation: Optional[str] = None
+    hashtags: List[str] = Field(default_factory=list)
+
+
+class YouTubeContent(BaseModel):
+    video_title_options: List[str] = Field(default_factory=list)
+    description: Optional[str] = None
+    tags: List[str] = Field(default_factory=list)
+    shorts: Optional[Dict[str, str]] = None
+
+
+class SocialPlatformBundle(BaseModel):
+    instagram: Optional[InstagramContent] = None
+    facebook: Optional[FacebookContent] = None
+    linkedin: Optional[LinkedInContent] = None
+    x_twitter: Optional[XTwitterContent] = None
+    tiktok: Optional[TikTokContent] = None
+    youtube: Optional[YouTubeContent] = None
+
+
+class VideoScriptScene(BaseModel):
+    second_range: str
+    visual: str
+    voiceover: str
+
+
+class VideoScriptContent(BaseModel):
+    duration_seconds: int = 30
+    format: str = "vertical_9_16"
+    hook: str
+    scenes: List[VideoScriptScene] = Field(default_factory=list)
+
+
+class EmailBlastContent(BaseModel):
+    subject_lines: List[str] = Field(default_factory=list)
+    preview_text: Optional[str] = None
+    body_html: Optional[str] = None
+    body_markdown: Optional[str] = None
+
+
+class GeneratedContentBundle(BaseModel):
+    social: Optional[SocialPlatformBundle] = None
+    email_blast: Optional[EmailBlastContent] = None
+    video_script: Optional[VideoScriptContent] = None
+    flyer_bullets: Optional[List[str]] = None
+    mls_remarks: Optional[str] = None
+    investor_pitch: Optional[Dict[str, Any]] = None
+
+
+class ContentGenerationResponse(BaseModel):
+    mls_id: str
+    tone: str
+    target_audience: Optional[str] = None
+    generated_at: Optional[str] = None
+    content: GeneratedContentBundle = Field(default_factory=GeneratedContentBundle)

pymlsapi/models/intelligence.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class SystemCondition(BaseModel):
+    age_years: Optional[int] = None
+    material: Optional[str] = None
+    condition: Optional[str] = None
+    estimated_replacement_horizon: Optional[str] = None
+    confidence: Optional[float] = None
+
+
+class StormProtection(BaseModel):
+    has_impact_windows: bool = False
+    has_impact_doors: bool = False
+    insurance_premium_impact: Optional[str] = None
+
+
+class SystemsAndCapex(BaseModel):
+    roof: Optional[SystemCondition] = None
+    hvac: Optional[SystemCondition] = None
+    water_heater: Optional[SystemCondition] = None
+    appliances: Optional[Dict[str, Any]] = None
+    storm_protection: Optional[StormProtection] = None
+
+
+class RentRange(BaseModel):
+    low: float = 0.0
+    median: float = 0.0
+    high: float = 0.0
+
+
+class InvestorInsights(BaseModel):
+    estimated_monthly_rent: RentRange = Field(default_factory=RentRange)
+    estimated_gross_yield_pct: float = 0.0
+    hoa_present: bool = False
+    rental_restrictions: Optional[str] = None
+    tenant_suitability: Optional[str] = None
+
+
+class FinancialFlag(BaseModel):
+    type: str
+    severity: str
+    summary: str
+    explanation: str
+
+
+class LlmIntelligence(BaseModel):
+    systems_and_capex: SystemsAndCapex = Field(default_factory=SystemsAndCapex)
+    investor_insights: InvestorInsights = Field(default_factory=InvestorInsights)
+    financial_flags: List[FinancialFlag] = Field(default_factory=list)
+    property_strengths: List[str] = Field(default_factory=list)
+    watch_items: List[str] = Field(default_factory=list)
+
+
+class PropertyIntelligence(BaseModel):
+    mls_id: str
+    parcel_id: Optional[str] = None
+    summary: Dict[str, Any] = Field(default_factory=dict)
+    public_records: Dict[str, Any] = Field(default_factory=dict)
+    llm_derived_intelligence: Optional[LlmIntelligence] = None
+    generated_at: Optional[str] = None

pymlsapi/models/listings.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Address(BaseModel):
+    street: str
+    city: str
+    state: str
+    zip: str
+    county: Optional[str] = None
+    country: Optional[str] = None
+    formatted: str
+
+
+class Coordinates(BaseModel):
+    latitude: float
+    longitude: float
+
+
+class PropertySpecifications(BaseModel):
+    beds: int
+    baths_full: float
+    baths_half: float = 0.0
+    sqft: int
+    lot_sqft: Optional[int] = None
+    year_built: Optional[int] = None
+    stories: Optional[int] = None
+    property_type: str
+    parking_spaces: Optional[int] = None
+    garage: Optional[bool] = None
+
+
+class PropertyFeatures(BaseModel):
+    heating: List[str] = Field(default_factory=list)
+    cooling: List[str] = Field(default_factory=list)
+    appliances: List[str] = Field(default_factory=list)
+    flooring: List[str] = Field(default_factory=list)
+    roof_type: Optional[str] = None
+    water_source: Optional[str] = None
+    sewer: Optional[str] = None
+    view: List[str] = Field(default_factory=list)
+
+
+class AgentInfo(BaseModel):
+    name: str
+    phone: Optional[str] = None
+    email: Optional[str] = None
+    license: Optional[str] = None
+    brokerage: Optional[str] = None
+
+
+class ListingMetadata(BaseModel):
+    days_on_market: Optional[int] = None
+    listed_date: Optional[str] = None
+    mls_board: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+class BaseListing(BaseModel):
+    source: str = "cache"
+    mls_id: str
+    status: str
+    price: float
+    currency: str = "USD"
+    price_per_sqft: Optional[float] = None
+    address: Address
+    coordinates: Optional[Coordinates] = None
+    specifications: PropertySpecifications
+    features: PropertyFeatures = Field(default_factory=PropertyFeatures)
+    photos: List[str] = Field(default_factory=list)
+    photo_count: int = 0
+    agent: Optional[AgentInfo] = None
+    description: str = ""
+    meta: Optional[ListingMetadata] = None
+
+
+class IngestJob(BaseModel):
+    job_id: Optional[str] = Field(None, alias="jobId")
+    mls_id: Optional[str] = Field(None, alias="mlsId")
+    status: str
+    step: Optional[str] = None
+    status_url: Optional[str] = Field(None, alias="statusUrl")
+    lookup_url: Optional[str] = Field(None, alias="lookupUrl")
+    progress_percentage: Optional[int] = 0
+    error: Optional[str] = None
+    result: Optional[Any] = None
+
+    model_config = ConfigDict(populate_by_name=True)

pymlsapi/models/studio.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class StudioJob(BaseModel):
+    job_id: str
+    status: str
+    progress_percentage: int = 0
+    current_step: Optional[str] = None
+    status_url: Optional[str] = None
+    result: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    created_at: Optional[str] = None
+    completed_at: Optional[str] = None
+
+
+class StagingResult(BaseModel):
+    staged_photo_url: str
+    before_after_comparison_url: Optional[str] = None
+    room_type: Optional[str] = None
+    style: Optional[str] = None
+    staging_manifest: List[str] = Field(default_factory=list)
+
+
+class DeclutterResult(BaseModel):
+    decluttered_photo_url: str
+    before_after_comparison_url: Optional[str] = None
+    items_removed: List[str] = Field(default_factory=list)
+
+
+class TwilightResult(BaseModel):
+    enhanced_photo_url: str
+    before_after_comparison_url: Optional[str] = None
+    mode: Optional[str] = None
+
+
+class DeStageEmptyResult(BaseModel):
+    empty_photo_url: str
+    before_after_comparison_url: Optional[str] = None
+    flooring_restored: Optional[str] = None
+
+
+class RestyleResult(BaseModel):
+    restyled_photo_url: str
+    before_after_comparison_url: Optional[str] = None
+    target_style: Optional[str] = None
+
+
+class ReplaceFurnitureResult(BaseModel):
+    result_photo_url: str
+    target_furniture: Optional[str] = None
+
+
+class ReplaceMaterialResult(BaseModel):
+    result_photo_url: str
+    surface_type: Optional[str] = None
+    material_applied: Optional[str] = None
+
+
+class SwatchItem(BaseModel):
+    color_name: str
+    hex: str
+    image_url: str
+
+
+class WallColorsResult(BaseModel):
+    comparison_grid_3x3_url: str
+    swatch_results: List[SwatchItem] = Field(default_factory=list)
+
+
+class ExteriorEnhanceResult(BaseModel):
+    enhanced_photo_url: str
+    enhancements_applied: List[str] = Field(default_factory=list)
+
+
+class UpscaleResult(BaseModel):
+    upscaled_image_url: str
+    target_resolution: Optional[str] = None
+    scale_factor: int = 4
+
+
+class RoomCloseup(BaseModel):
+    room_name: str
+    image_url: str
+
+
+class Render3dResult(BaseModel):
+    isometric_3d_dollhouse_url: str
+    thumbnail_url: Optional[str] = None
+    room_renders: List[RoomCloseup] = Field(default_factory=list)
+
+
+class SpatialSummary(BaseModel):
+    total_rooms_detected: int = 0
+    stories: int = 1
+    layout_type: Optional[str] = None
+
+
+class FloorPlanAnalysisResponse(BaseModel):
+    style: Optional[str] = None
+    spatial_summary: SpatialSummary = Field(default_factory=SpatialSummary)
+    rooms: List[Dict[str, Any]] = Field(default_factory=list)
+    isometric_3d_prompt: Optional[str] = None
+    render_3d_url: Optional[str] = None
+
+
+class ArchitecturalRenderResult(BaseModel):
+    rendered_image_url: str
+    source_type: Optional[str] = None
+
+
+class CreativePlacement(BaseModel):
+    placement: str
+    image_url: str
+    aspect_ratio: Optional[str] = None
+
+
+class AdCreativesCompliance(BaseModel):
+    fair_housing_passed: bool = True
+    flags: List[str] = Field(default_factory=list)
+
+
+class AdCreativesResult(BaseModel):
+    mls_id: Optional[str] = None
+    creatives: Dict[str, CreativePlacement] = Field(default_factory=dict)
+    compliance: AdCreativesCompliance = Field(default_factory=AdCreativesCompliance)
+
+
+class SocialPublishResult(BaseModel):
+    status: str
+    destinations_dispatched: List[str] = Field(default_factory=list)
+    results: Dict[str, Any] = Field(default_factory=dict)
+
+
+class MasteredVideo(BaseModel):
+    aspect_ratio: str
+    url: str
+
+
+class VideoEnhanceResult(BaseModel):
+    mastered_videos: List[MasteredVideo] = Field(default_factory=list)
+
+
+class VideoWalkthroughResult(BaseModel):
+    video_url: str
+    duration_seconds: Optional[float] = None
+
+
+class VideoTransitionResult(BaseModel):
+    video_url: str
+    transition_type: Optional[str] = None
+
+
+class HouseTourResult(BaseModel):
+    video_tour_url: str
+    rooms_included: List[str] = Field(default_factory=list)
+
+
+class CustomStudioResult(BaseModel):
+    output_url: str
+    prompt_used: str
+
+
+class UploadResult(BaseModel):
+    url: str
+    filename: Optional[str] = None
+    content_type: Optional[str] = None
+    bytes: Optional[int] = None

pymlsapi/poller.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Callable, Optional, TypeVar
+
+from pymlsapi.errors import JobTimeoutError, StudioJobFailedError
+
+T = TypeVar("T")
+
+
+def poll_job_sync(
+    fetch_fn: Callable[[], Any],
+    is_done_fn: Callable[[Any], bool],
+    is_failed_fn: Callable[[Any], bool],
+    timeout_seconds: float = 90.0,
+    initial_interval: float = 1.5,
+    max_interval: float = 5.0,
+    backoff_multiplier: float = 1.25,
+    on_progress: Optional[Callable[[Any], None]] = None,
+) -> Any:
+    """Poll a job synchronously until it is finished, fails, or times out."""
+    start_time = time.monotonic()
+    current_interval = initial_interval
+
+    while True:
+        job = fetch_fn()
+
+        if on_progress:
+            try:
+                on_progress(job)
+            except Exception:
+                pass
+
+        if is_done_fn(job):
+            return job
+
+        if is_failed_fn(job):
+            job_id = getattr(job, "job_id", getattr(job, "id", "unknown"))
+            error_msg = getattr(job, "error", "Job processing failed on worker")
+            raise StudioJobFailedError(
+                job_id=str(job_id), message=str(error_msg), error_details=job
+            )
+
+        elapsed = time.monotonic() - start_time
+        if elapsed >= timeout_seconds:
+            job_id = getattr(job, "job_id", getattr(job, "id", "unknown"))
+            raise JobTimeoutError(job_id=str(job_id), timeout_seconds=timeout_seconds)
+
+        sleep_time = min(current_interval, timeout_seconds - elapsed)
+        if sleep_time > 0:
+            time.sleep(sleep_time)
+
+        current_interval = min(current_interval * backoff_multiplier, max_interval)
+
+
+async def poll_job_async(
+    fetch_fn: Callable[[], Any],  # async function
+    is_done_fn: Callable[[Any], bool],
+    is_failed_fn: Callable[[Any], bool],
+    timeout_seconds: float = 90.0,
+    initial_interval: float = 1.5,
+    max_interval: float = 5.0,
+    backoff_multiplier: float = 1.25,
+    on_progress: Optional[Callable[[Any], None]] = None,
+) -> Any:
+    """Poll a job asynchronously until it is finished, fails, or times out."""
+    start_time = time.monotonic()
+    current_interval = initial_interval
+
+    while True:
+        job = await fetch_fn()
+
+        if on_progress:
+            try:
+                if asyncio.iscoroutinefunction(on_progress):
+                    await on_progress(job)
+                else:
+                    on_progress(job)
+            except Exception:
+                pass
+
+        if is_done_fn(job):
+            return job
+
+        if is_failed_fn(job):
+            job_id = getattr(job, "job_id", getattr(job, "id", "unknown"))
+            error_msg = getattr(job, "error", "Job processing failed on worker")
+            raise StudioJobFailedError(
+                job_id=str(job_id), message=str(error_msg), error_details=job
+            )
+
+        elapsed = time.monotonic() - start_time
+        if elapsed >= timeout_seconds:
+            job_id = getattr(job, "job_id", getattr(job, "id", "unknown"))
+            raise JobTimeoutError(job_id=str(job_id), timeout_seconds=timeout_seconds)
+
+        sleep_time = min(current_interval, timeout_seconds - elapsed)
+        if sleep_time > 0:
+            await asyncio.sleep(sleep_time)
+
+        current_interval = min(current_interval * backoff_multiplier, max_interval)

pymlsapi/resources/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from pymlsapi.resources.account import AccountResource, AsyncAccountResource
+from pymlsapi.resources.content import AsyncContentResource, ContentResource
+from pymlsapi.resources.intelligence import AsyncIntelligenceResource, IntelligenceResource
+from pymlsapi.resources.listings import AsyncListingsResource, ListingsResource
+from pymlsapi.resources.studio import AsyncStudioResource, StudioResource
+
+__all__ = [
+    "AccountResource",
+    "AsyncAccountResource",
+    "AsyncContentResource",
+    "AsyncIntelligenceResource",
+    "AsyncListingsResource",
+    "AsyncStudioResource",
+    "ContentResource",
+    "IntelligenceResource",
+    "ListingsResource",
+    "StudioResource",
+]