<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->

# Purpose of this module
This module provides a simple dataflow to provide a caption for images using openai.

# Configuration Options

This module has the following configuration options:
1. `include_embeddings={True, False}` -- whether to include embeddings in the output. Defaults to `False`

This module can be called with the following inputs, when `include_embeddings=False`:
- `image_url` The url of the image to caption (can be locally stored or remotely stored). If locally stored, this will be encoded in base64. If remotely store,d the URL will be sent to openAI (so it has to be publicly accessible)
- `additional_prompt` Optional, defaults to `None`. This is an additional prompt that will be added to the end of the prompt. Examples include:
  - "Please make this caption overly dramatic and comical"
  - "Please make this caption very concise"
- `descriptiveness` One of [None, "somewhat", "very", "extremely", "obsessively"], used to create the prompt.
  - If None, the prompt will be "Please provide a caption of the following image"
  - If provided, the prompt will be "Please provide a caption of the following image. The caption should be {descriptiveness} descriptive"
- `max_tokens` Max number of tokens to use for openAI
- `additional_metadata` Optional, defaults to `None`. If provided, this will be added to the metadata dict returned at the end.

In addition, this module can be called with the following inputs, when `include_embeddings=True`:
- `embeddings_model` Optional, defaults to "text-embeddings-ada-002", if caption_embeddings is on the blocking path

Note that you must have `OPENAI_API_KEY` set in your environment for this to work.

This also accepts the following overrides:
- `core_prompt` The prompt to use, overrides the default prompt or "Please provide a caption for this image"

Note that this has two modes:

1. (`include_embeddings=False`, or not specified) Just quries the caption for the image. You can request `generated_caption`, which will give embeddings for the caption.
2. (`include_embeddings=True`): also gets the caption for the image, and the embeddings the caption. This requires `caption_embeddings` to be one of the variables called.

If you want all the metadata about this run wrapped up in a dictionary (say, to save externally), you can request `metadata` which will return a dict with the following keys:

When `include_embeddings=False`:
- `original_image_url`: original, provide image URL -- if this has been converted to base64 this will be the original path
- `generated_caption`: caption generated by the captioning model
- `caption_model`: the model used to generate the caption
- `caption_prompt`: the prompt used to generate the caption
- `**additional_metadata`: any additional metadata passed in
- `execution_time`: current time when this is generated, in ISO format

If `include_embeddings=True`, you will get the above, as well as:
- `caption_embeddings`: embeddings for the caption
- `embeddings_model`: the model used to generate the embeddings

# Limitations
We may consider breaking this into multiple DAGs at some point, as it does two separate pieces.
For now, however, it has some basic capabilities.
