finder-enrichment-orchestrator-api-client 0.1.0
Lightweight API client for the Finder Enrichment Orchestrator service
Requires Python: >=3.8

# 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

```bash
pip install finder-enrichment-orchestrator-api-client
```

## Quick Start

### Basic Usage

```python
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

```python
# 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

```python
# 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

```python
# 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

```python
# 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:

```bash
# 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

```python
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

```python
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

```bash
# 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

```bash
# Run tests
pytest

# Run tests with coverage
pytest --cov=finder_enrichment_orchestrator_api_client
```

### Code Formatting

```bash
# Format code
black .
isort .

# Check style
flake8
```

### Building

```bash
# 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](https://github.com/giacomokavanagh/finder-enrichment-orchestrator/issues) page.