finder-enrichment-orchestrator-api-client 0.1.0

Lightweight API client for the Finder Enrichment Orchestrator service

Finder Enrichment Orchestrator API Client

A lightweight Python package for interacting with the Finder Enrichment Orchestrator API. This client provides synchronous methods for enriching listings, descriptions, images, and floorplans.

Features

• Simple: Easy-to-use interface for enrichment operations
• Synchronous: Immediate processing without background jobs
• Type-safe: Full Pydantic model support for requests and responses
• Configurable: Support for both environment variables and direct configuration
• Comprehensive: Support for all enrichment operations (listings, descriptions, images, floorplans)

Installation

pip install finder-enrichment-orchestrator-api-client

Quick Start

Basic Usage

from finder_enrichment_orchestrator_api_client import OrchestratorAPIClient

# Initialize with environment variables
client = OrchestratorAPIClient()

# Or initialize with direct configuration
client = OrchestratorAPIClient(
    base_url="http://localhost:3100",
    api_key="your-api-key-here"
)

# Enrich a single listing
result = client.enrich_listing(listing_id="123")
if result.status == "success":
    print(f"Enriched listing: {result.enriched_listing_id}")
    print(f"Processing time: {result.processing_time_seconds}s")
else:
    print(f"Error: {result.error_message}")

Batch Enrichment

# Enrich multiple listings
batch_result = client.enrich_listings(listing_ids=["123", "456", "789"])

print(f"Total processed: {batch_result.total_processed}")
print(f"Successful: {batch_result.total_successful}")
print(f"Failed: {batch_result.total_failed}")

for result in batch_result.results:
    print(f"Listing {result.original_listing_id}: {result.status}")

Description Enrichment

# Enrich a listing's description
result = client.enrich_description(listing_id="123")
if result.status == "success":
    print(f"Description output: {result.description_output}")
    print(f"Model used: {result.model}")

Image Enrichment

# Enrich all images for a listing
result = client.enrich_listing_images(listing_id="123")
print(f"Processed {result.image_count} images")

for image_result in result.results:
    print(f"Image {image_result.original_image_id}: {image_result.status}")

# Enrich a single image
image_result = client.enrich_image(image_id="456")
if image_result.status == "success":
    print(f"Image analytics: {image_result.image_analytics_output}")

Floorplan Enrichment

# Enrich a single floorplan
result = client.enrich_floorplan(floorplan_id="789")
if result.status == "success":
    print(f"Floorplan analytics: {result.floorplan_analytics_output}")
    print(f"Analytics run ID: {result.analytics_run_id}")

Environment Variables

The client uses the following environment variables by default:

# Base URL for the orchestrator API (default: http://localhost:3100)
export ORCHESTRATOR_BASE_URL="https://your-orchestrator-api.com"

# API key for authentication (required)
export ORCHESTRATOR_API_KEY="your-api-key-here"

You can also set these in a .env file:

ORCHESTRATOR_BASE_URL=http://localhost:3100
ORCHESTRATOR_API_KEY=your-api-key-here

API Reference

OrchestratorAPIClient

Initialization

client = OrchestratorAPIClient(
    base_url: Optional[str] = None,  # Default: ORCHESTRATOR_BASE_URL env var
    api_key: Optional[str] = None,    # Default: ORCHESTRATOR_API_KEY env var
    api_prefix: str = "/api",         # API path prefix
    default_timeout_seconds: float = 30.0  # Request timeout
)

Methods

Listing Enrichment

• enrich_listing(listing_id: str, *, timeout_seconds: Optional[float] = None) -> EnrichmentResult

  Enrich a single listing synchronously.

• enrich_listings(listing_ids: List[str], *, timeout_seconds: Optional[float] = None) -> BatchEnrichmentResult

  Enrich multiple listings in a batch.

Description Enrichment

• enrich_description(listing_id: str, *, timeout_seconds: Optional[float] = None) -> DescriptionAnalysisResult

  Enrich a listing's description.

Image Enrichment

• enrich_listing_images(listing_id: str, *, timeout_seconds: Optional[float] = None) -> BatchImageAnalysisResult

  Enrich all images for a listing.

• enrich_image(image_id: str, *, timeout_seconds: Optional[float] = None) -> ImageAnalysisResult

  Enrich a single image.

Floorplan Enrichment

• enrich_floorplan(floorplan_id: str, *, timeout_seconds: Optional[float] = None) -> FloorplanAnalysisResult

  Enrich a single floorplan.

Response Models

All methods return Pydantic models with the following common fields:

• status: "success", "failed", or "timeout"
• error_message: Error description (if applicable)
• processing_time_seconds: Time taken for processing
• timestamp: When the operation completed

See the individual model classes for specific fields:

• EnrichmentResult
• BatchEnrichmentResult
• DescriptionAnalysisResult
• ImageAnalysisResult
• BatchImageAnalysisResult
• FloorplanAnalysisResult
• BatchFloorplanAnalysisResult

Error Handling

from finder_enrichment_orchestrator_api_client import OrchestratorAPIClient
import requests

client = OrchestratorAPIClient()

try:
    result = client.enrich_listing(listing_id="123")
    if result.status == "success":
        print("Success!")
    else:
        print(f"Processing failed: {result.error_message}")
except requests.HTTPError as e:
    print(f"HTTP error: {e}")
except ValueError as e:
    print(f"Invalid response: {e}")

Development

Setup

# Clone the repository
git clone https://github.com/giacomokavanagh/finder-enrichment-orchestrator.git
cd finder-enrichment-orchestrator/src/finder_enrichment_orchestrator_api_client

# Install in development mode
pip install -e ".[dev]"

Testing

# Run tests
pytest

# Run tests with coverage
pytest --cov=finder_enrichment_orchestrator_api_client

Code Formatting

# Format code
black .
isort .

# Check style
flake8

Building

# Install build dependencies
pip install build twine

# Build the package
python -m build

# Upload to PyPI
twine upload dist/*

License

MIT License

Support

For issues and questions, please visit the GitHub Issues page.