Complete

Our complete-endpoint is the basic interface to our models. You can send a prompt, which can be any combination of texts and images, to generate a (text) completion. If the concepts of prompting and completion are new to you, please refer to this section in our documentation.

Code Example Text

import os
from aleph_alpha_client import Client, Prompt, CompletionRequest
# If you are using a Windows machine, you must install the python-dotenv package and run the two below lines as well.
# from dotenv import load_dotenv
# load_dotenv()

client = Client(token=os.getenv("AA_TOKEN"))
prompt_text = """Write a short text about dogs.

### Response:"""

params = {
    "prompt": Prompt.from_text(prompt_text),
    "maximum_tokens": 100,
}
request = CompletionRequest(**params)
response = client.complete(request=request, model="luminous-supreme-control")
completion = response.completions[0].completion

print(
    f"""Prompt: {prompt_text}
Completion: {completion.strip()}"""
)
# prints:
# Prompt: Write a short text about dogs.

# ### Response:
# Completion: Dogs are man's best friend. They are known for their loyalty, intelligence, and ability to be trained for a variety of tasks. Dogs have been domesticated for thousands of years and have been used for hunting, herding, and as guard dogs. They come in a variety of sizes, shapes, and colors and are popular pets around the world.

tip

For security reasons, we recommend that you do not use your token directly in your code. Instead, save it in a file named ".env" with the following entry:

AA_TOKEN=your_token

You can then easily import your token as shown in the coding example above.

Code Example Image + Text

You can also generate a completion for a combination of texts and images!

import os
from aleph_alpha_client import Client, Prompt, Image, CompletionRequest
# If you are using a Windows machine, you must install the python-dotenv package and run the two below lines as well.
# from dotenv import load_dotenv
# load_dotenv()

client = Client(token=os.getenv("AA_TOKEN"))

path_prompt_image = "path/to/image"
prompt_image = Image.from_image_source(path_prompt_image)

prompt_text = "The items in this room are:"

params = {
    "prompt": Prompt(items=[
        prompt_image,
        prompt_text
    ]),
    "maximum_tokens": 18,
    "stop_sequences": ["."]
}

request = CompletionRequest(**params)
response = client.complete(request=request, model="luminous-base")
completion = response.completions[0].completion

print(
    f"""Prompt: {prompt_text}
Completion: {completion.strip()}"""
)
# prints:
# Prompt: The items in this room are:
# Completion: desk, chair, bed, guitar, lamp, and shelf

tip

Image data can also be loaded from local files or even byte objects.

Code Examples Attention Manipulation

You can apply attention manipulation to text as well as multimodal inputs. In the following example, we demonstrate how to manipulate the attention paid to an input sequence. To do so, you need to find the parts of the string that you want to manipulate. You must then pass those substrings to the TextControl-class and specify how you want to manipulate the attention. A factor below 1 suppresses the attention paid to the substring, while all values above 1 amplify the attention. Finally, you pass your attention manipulations to the Prompt-class.

import os
from aleph_alpha_client import Client, CompletionRequest, Prompt, TextControl
import re

# If you are using a Windows machine, you must install the python-dotenv package and run the two below lines as well.
# from dotenv import load_dotenv
# load_dotenv()

client = Client(token=os.getenv("AA_TOKEN"))
prompt_text = """I bought a game and a party hat. Tonight I will"""

matching_string = re.search("game", prompt_text)

begin_match = matching_string.regs[0][0]
end_match = matching_string.regs[0][1]

control_suppress = TextControl(
    start=begin_match, length=end_match - begin_match, factor=0.1
)

control_amplify = TextControl(
    start=begin_match, length=end_match - begin_match, factor=14
)

controls = [control_suppress, control_amplify]

for control in controls:
    params = {
        "prompt": Prompt.from_text(prompt_text, controls=[control]),
        "stop_sequences": ["\n", "."],
        "maximum_tokens": 16,
    }
    request = CompletionRequest(**params)
    response = client.complete(request=request, model="luminous-supreme")
    completion = response.completions[0].completion
    print(
        f"""Prompt: {prompt_text}
Completion: {completion.strip()}"""
    )

# prints:
# Prompt: I bought a game and a party hat. Tonight I will
# Completion: be wearing the hat and drinking a beer
# Prompt: I bought a game and a party hat. Tonight I will
# Completion: be playing games with my friends

It is also possible to put multiple attention manipulations for multiple substrings into the same prompt.

import os
from aleph_alpha_client import Client, CompletionRequest, Prompt, TextControl
import re

# If you are using a Windows machine, you must install the python-dotenv package and run the two below lines as well.
# from dotenv import load_dotenv
# load_dotenv()

client = Client(token=os.getenv("AA_TOKEN"))

prompt_text = """I bought a game and a movie. Tonight I will"""

matching_string_game = re.search("game", prompt_text)

matching_string_movie = re.search("movie", prompt_text)

begin_match_game = matching_string_game.regs[0][0]
end_match_game = matching_string_game.regs[0][1]

begin_match_movie = matching_string_movie.regs[0][0]
end_match_movie = matching_string_movie.regs[0][1]

control_game = TextControl(
    start=begin_match_game,
    length=end_match_game - begin_match_game,
    factor=0.1,
)

control_movie = TextControl(
    start=begin_match_movie, length=end_match_movie - begin_match_movie, factor=5
)

params = {
    "prompt": Prompt.from_text(
        prompt_text, controls=[control_game, control_movie]
    ),
    "stop_sequences": ["\n", "."],
    "maximum_tokens": 16,
}
request = CompletionRequest(**params)
response = client.complete(request=request, model="luminous-supreme")
completion = response.completions[0].completion
print(
    f"""Prompt: {prompt_text}
Completion: {completion.strip()}"""
)

# prints:
# Prompt: I bought a game and a movie. Tonight I will
# Completion: be watching the movie

Finally, you can even manipulate the attention on images you input to our multimodal models. It is important to note that our model does not see the image you pass in. If no other cropping is specified, we do the largest possible center crop.

In this example, we want the model to pay attention to the guitar in the image of our object detection example in the Multimodality section. Without any attention manipulation, the completion correctly returned the items in the room.

The items in this room are: desk, bed, computer, lamp, bookshelf, and guitar.

Now we amplify the attention paid to the guitar. To do so we have to define a bounding box and it's location. All coordinates of the bounding box are logical coordinates (between 0 and 1) and relative to the entire image. If you would like to know more, please refer to our Read the Docs. Our models work with square images. Non-square images are center-cropped by default before going to the model (you can specify a custom cropping if you want). Since control coordinates are relative to the entire image, all or a portion of your control may be outside the "model visible area".

import os
from aleph_alpha_client import Client, CompletionRequest, Prompt, Image, ImageControl

# If you are using a Windows machine, you must install the python-dotenv package and run the two below lines as well.
# from dotenv import load_dotenv
# load_dotenv()

client = Client(token=os.getenv("AA_TOKEN"))

prompt_image_path = "/path/to/image"

control = ImageControl(left=0.17, top=0.43, width=0.13, height=0.33, factor=10)
image_prompt = Image.from_image_source(prompt_image_path, controls=[control])

prompt_text = "The items in this room are:"
params = {
    "prompt": Prompt(items=[image_prompt, prompt_text]),
    "maximum_tokens": 3,
    "stop_sequences": ["\n", "."],
}
request = CompletionRequest(**params)
response = client.complete(request=request, model="luminous-extended")
completion = response.completions[0].completion

print(
    f"""Prompt: {prompt_text}
Completion: {completion.strip()}"""
)

# prints:
# Prompt: The items in this room are:
# Completion: a guitar

The items in this room are: a guitar

If you need more information on the parameters you can use, please checkout our HTTP API.