Metadata-Version: 2.4
Name: AppWrapper
Version: 0.3.0
Summary: Library for Superb-AI Apps
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.0.0
Requires-Dist: boto3>=1.13.4
Requires-Dist: pydantic>=2.0.0
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: summary

# AppWrapper

A Python library that wraps Superb AI app functions. Used as a decorator, it automatically handles the full lifecycle of app tasks: downloading input files, executing the function, validating results, uploading outputs, and reporting status.

## Installation

```bash
pip install AppWrapper
```

## Quick Start

### Normal Mode (Production)

Communicates with the TOAD backend service. Required environment variables are automatically injected.

```python
from app_wrapper import AppWrapper

@AppWrapper()
def my_app():
    # Your app logic here
    return {"type": "link", "url": "https://example.com/result"}
```

### Local Mode

Test locally using direct AWS credentials without TOAD communication.

```python
from app_wrapper import AppWrapper

@AppWrapper(
    LOCAL_MODE=True,
    AWS_ACCESS_KEY_ID="your-access-key",
    AWS_SECRET_ACCESS_KEY="your-secret-key",
    AWS_DEFAULT_REGION="ap-northeast-2",
)
def my_app():
    return {"type": "link", "url": "https://example.com/result"}
```

## Result Format

App functions must return one of the following two types.

### Link Type

Returns an external URL as the result.

```python
{"type": "link", "url": "https://example.com/result"}
```

### Download Type

Uploads a local file to S3 and delivers it as the result.

```python
{"type": "download", "file_path": "/path/to/output/file.json"}
```

## S3 File Download

Download additional S3 files within your app function.

```python
from app_wrapper import AppWrapper

AppWrapper.download_from_s3(
    bucket="my-bucket",
    key="path/to/file.csv",
    download_path="/tmp/file.csv",
)
```

## Environment Variables

Environment variables required in normal mode. These are automatically injected in production.

| Variable | Description |
|---|---|
| `TOAD_HOST` | TOAD backend service host URL |
| `TENANT_ID` | Tenant ID |
| `TASK_ID` | Task ID |
| `MAIN_APP_ID` | Main app ID |
| `POD_FILE_PATH` | Input file download path |
| `APP_INPUT_FILES` | List of input file S3 paths (Python list format string) |

In local mode, pass AWS credentials directly to the `AppWrapper` constructor.

| Parameter | Description | Default |
|---|---|---|
| `AWS_ACCESS_KEY_ID` | AWS Access Key | `""` |
| `AWS_SECRET_ACCESS_KEY` | AWS Secret Key | `""` |
| `AWS_DEFAULT_REGION` | AWS Region | `ap-northeast-2` |

## Architecture

```
app_wrapper/
├── __init__.py          # Public exports
├── app_wrapper.py       # AppWrapper - decorator & orchestrator
├── s3_client.py         # S3Client - S3 download/upload operations
├── status_manager.py    # StatusManager - task status & log reporting
├── result_schema.py     # Pydantic models for result validation
└── task_status.py       # Status enum (Complete, Processing, Failed, ...)
```

## Dependencies

- `requests>=2.0.0`
- `boto3>=1.13.4`
- `pydantic>=2.0.0`
