Abstract
Gemini 2.5 Pro Experimental enabled automated cargo ship stowage planning via prompt engineering, overcoming prior model limitations. This eliminates the need for complex algorithms, demonstrating AI’s potential in logistics.
Introduction
Recently, I encountered a practical business challenge: automating stowage planning through AI. Specifically, I received a request to generate optimal container loading plans for cargo ships, a task traditionally requiring significant manual effort and domain expertise. In initial tests, prior to the release of Gemini 2.5, I found that existing models struggled to effectively handle the complexities of this problem, including constraints like weight distribution, container dimensions, and destination sequencing. However, with the release of Gemini 2.5, I observed a significant improvement in the model’s capabilities. Utilizing the Gemini 2.5 Pro Experimental model, I successfully demonstrated the generation of viable stowage plans using only carefully crafted prompts. This breakthrough eliminates the need for complex, custom-built algorithms or extensive training datasets. The successful implementation involved providing the model with key parameters such as container dimensions, weights, destination ports, and ship capacity. This report details the methodology, prompt engineering, and results of my attempt to create automated stowage planning using Gemini 2.5 Pro Experimental, highlighting its potential to revolutionize logistics and shipping operations.
Usage
1. Get API key
In order to use the scripts in this report, please use your API key. Ref This API key is used to access the Gemini API.
2. Main script
I used Python for testing this. The main script is very simple as follows. The function createPrompt() returns the value of contents, including the prompt. This function is shown in the next section.
import json
from google import genai
from google.genai.types import Part
contents = createPrompt()
client = genai.Client(api_key="###") # Please set your API key.
response = client.models.generate_content(
model="models/gemini-2.5-pro-exp-03-25",
contents=contents,
config={"response_mime_type": "application/json"},
)
print(response.text)
3. Prompt
The function createPrompt() is as follows.
def createPrompt():
# Please set the file name with the path of the file which are used as the reference data.
ref_file_name = "./sampleRefFile.pdf"
with open(ref_file_name, "rb") as f:
ref_file = f.read()
json_schema_for_stowage_area = {
"description": "JSON schema for cart.",
"type": "object",
"properties": {
"xWidth": {
"type": "number",
"description": "Width of cart. Unit is meter. This is the direction of the x-axis.",
},
"yLength": {
"type": "number",
"description": "Length of cart. This cart is moved to the yLength direction. Unit is meter. This is the direction of the y-axis.",
},
"maxWeight": {
"type": "number",
"description": "Maximum loading capacity of cart. Unit is kilogram.",
},
"directionOfTravel": {
"type": "string",
"description": "Direction of travel.",
},
},
"required": ["xWidth", "yLength", "maxWeight", "directionOfTravel"],
}
json_schema_for_containers = {
"description": "JSON schema for containers. Each ID is required to be used with jsonSchemaForOutput.",
"type": "array",
"items": {
"type": "object",
"properties": {
"xWidth": {
"type": "number",
"description": "Width of container. Unit is meter.",
},
"yLength": {
"type": "number",
"description": "Length of container. Unit is meter. Unit is meter.",
},
"zHeight": {
"type": "number",
"description": "Height of container. Unit is meter.",
},
"weight": {
"type": "number",
"description": "Weight of container. Unit is kilogram.",
},
"id": {
"type": "string",
"description": "This value is ID of container. you are required to use this ID when you place it.",
},
},
"required": ["xWidth", "yLength", "zHeight", "weight", "id"],
},
}
json_schema_for_output = {
"description": "JSON schema for output data. The origin of the coordinates of both cart and container is in the bottom corner",
"type": "object",
"properties": {
"containers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordicate. Unit is meter.",
},
"y": {
"type": "number",
"description": "Y coordicate. Unit is meter.",
},
"z": {
"type": "number",
"description": "Z coordicate. Unit is meter.",
},
"rotate90": {
"type": "boolean",
"description": "When this container is required to rotate 90 degrees, set 'true'.",
},
"id": {
"type": "string",
"description": "ID of container. This ID is required to be corresponding to the ID of 'Containers'.",
},
},
"required": ["x", "y", "z", "rotate90", "id"],
},
},
"centerOfGravity": {
"type": "object",
"description": "Calculated the center of gravity.",
"properties": {
"x": {
"type": "number",
"description": "X coordicate. Unit is meter.",
},
"y": {
"type": "number",
"description": "Y coordicate. Unit is meter.",
},
"z": {
"type": "number",
"description": "Z coordicate. Unit is meter.",
},
},
"required": ["x", "y", "z"],
},
"required": ["containers", "centerOfGravity"],
},
}
json_schema_for_error = {
"description": "JSON schema for error. When all containers cannot be put, return it as the error message by including the reason for the error.",
"type": "object",
"properties": {
"errorMessage": {"type": "string", "description": "Error message."},
"required": ["errorMessage"],
},
}
prompts = [
f"Return the suitable loading plan for the containers on the platform. In order to achieve this, please run the following steps.",
f"1. Understand the following containers and platform.",
f"Containers",
f"<Containers>{json.dumps(containers)}</Containers>",
f'JSON schema of "Container" is as follows.',
f"<jsonSchemaForContainers>{json.dumps(json_schema_for_containers)}</jsonSchemaForContainers>",
f"Platform",
f"<Platform>{json.dumps(stowage_area)}</Platform>",
f'JSON schema of "Platform" is as follows.',
f"<jsonSchemaForPlatform>{json.dumps(json_schema_for_stowage_area)}</jsonSchemaForPlatform>",
f"All containers are required to be put. If all containers cannot be put, return <JSONSchemaForError>{json.dumps(json_schema_for_error)}</JSONSchemaForError>.",
f"Condition of loading plan.",
f"<ConditionOfLoadingPlan>",
f"Loading surface: Rectangular, flat",
f"Loading restrictions: None (not considered this time)",
f"Loading plan",
f"The loading plan shows the placement of containers in coordinates. For example, if the center of the platform is the origin (0, 0), and the x-axis corresponds to the length and the y-axis corresponds to the width, it will look like this:",
f"Must not create gaps between containers.",
f"Heavier containers are required to be put on the bottom. Lighter conteiners are required to put on the heavy containers",
f"</ConditionOfLoadingPlan>",
f'2. Return the result using the following JSON schema. Consider "IMPORTANT".',
f"<JSONSchemaForOutputFormat>{json.dumps(json_schema_for_output)}</JSONSchemaForOutputFormat>",
f'<IMPORTANT>Think of a result by following the uploaded file "{ref_file_name}".</IMPORTANT>',
]
return [
"\n".join(prompts),
Part.from_bytes(data=ref_file, mime_type="application/pdf"),
]
Here, the file ./sampleRefFile.pdf is as follows. I used this data as the reference data for outputting values.
3. Testing
Sample 1
About the values of stowage_area and containers, when the following values are used,
stowage_area = {
"xWidth": 3,
"yLength": 6,
"maxWeight": 100,
"directionOfTravel": "yLength",
}
containers = [
{"xWidth": 3, "yLength": 3, "zHeight": 1, "weight": 9, "id": "sample1"},
{"xWidth": 3, "yLength": 3, "zHeight": 1, "weight": 9, "id": "sample2"},
{"xWidth": 2, "yLength": 3, "zHeight": 1, "weight": 6, "id": "sample3"},
{"xWidth": 2, "yLength": 3, "zHeight": 1, "weight": 6, "id": "sample4"},
{"xWidth": 2, "yLength": 3, "zHeight": 1, "weight": 6, "id": "sample5"},
]
The following result is obtained.
{
"containers": [
{ "x": 0, "y": 0, "z": 0, "rotate90": false, "id": "sample1" },
{ "x": 0, "y": 3, "z": 0, "rotate90": false, "id": "sample2" },
{ "x": 0, "y": 0, "z": 1, "rotate90": true, "id": "sample3" },
{ "x": 0, "y": 2, "z": 1, "rotate90": true, "id": "sample4" },
{ "x": 0, "y": 4, "z": 1, "rotate90": true, "id": "sample5" }
],
"centerOfGravity": { "x": 1.5, "y": 3, "z": 1 }
}
When this result is showin as 3D image, it becomes as follows.
Sample 2
About the values of stowage_area and containers, when the following values are used,
stowage_area = { xWidth: 3, yLength: 3, maxWeight: 100, directionOfTravel: "yLength" }
containers = [
{ xWidth: 2, yLength: 3, zHeight: 1, weight: 1, id: "sample1" },
{ xWidth: 1, yLength: 3, zHeight: 1, weight: 1, id: "sample2" },
{ xWidth: 2, yLength: 2, zHeight: 1, weight: 1, id: "sample3" },
{ xWidth: 1, yLength: 1, zHeight: 1, weight: 2, id: "sample4" },
{ xWidth: 1, yLength: 2, zHeight: 1, weight: 2, id: "sample5" },
{ xWidth: 2, yLength: 1, zHeight: 1, weight: 2, id: "sample6" },
]
The following result is obtained.
{
"containers": [
{ "x": 0, "y": 0, "z": 0, "rotate90": false, "id": "sample6" },
{ "x": 2, "y": 0, "z": 0, "rotate90": false, "id": "sample4" },
{ "x": 0, "y": 1, "z": 0, "rotate90": false, "id": "sample5" },
{ "x": 1, "y": 1, "z": 0, "rotate90": false, "id": "sample3" },
{ "x": 0, "y": 0, "z": 1, "rotate90": false, "id": "sample1" },
{ "x": 2, "y": 0, "z": 1, "rotate90": false, "id": "sample2" }
],
"centerOfGravity": { "x": 1.5, "y": 1.222, "z": 0.722 }
}
When this result is showin as 3D image, it becomes as follows.
Sample 3
About the values of stowage_area and containers, when the following values are used,
stowage_area = { xWidth: 6, yLength: 10, maxWeight: 100, directionOfTravel: "yLength" }
containers = [
{ xWidth: 3, yLength: 5, zHeight: 1, weight: 1, id: "sample1" },
{ xWidth: 3, yLength: 6, zHeight: 1, weight: 1, id: "sample2" },
{ xWidth: 3, yLength: 3, zHeight: 1, weight: 1, id: "sample3" },
{ xWidth: 2, yLength: 3, zHeight: 1, weight: 1, id: "sample4" },
{ xWidth: 2, yLength: 6, zHeight: 1, weight: 1, id: "sample5" },
{ xWidth: 3, yLength: 3, zHeight: 1, weight: 2, id: "sample6" },
{ xWidth: 3, yLength: 3, zHeight: 1, weight: 2, id: "sample7" },
{ xWidth: 3, yLength: 3, zHeight: 1, weight: 2, id: "sample8" },
{ xWidth: 3, yLength: 3, zHeight: 1, weight: 2, id: "sample9" },
{ xWidth: 3, yLength: 4, zHeight: 1, weight: 2, id: "sample10" },
{ xWidth: 3, yLength: 4, zHeight: 1, weight: 2, id: "sample11" },
]
The following result is obtained.
{
"containers": [
{ "x": 0, "y": 0, "z": 0, "rotate90": false, "id": "sample10" },
{ "x": 3, "y": 0, "z": 0, "rotate90": false, "id": "sample11" },
{ "x": 0, "y": 4, "z": 0, "rotate90": false, "id": "sample6" },
{ "x": 3, "y": 4, "z": 0, "rotate90": false, "id": "sample7" },
{ "x": 0, "y": 7, "z": 0, "rotate90": false, "id": "sample8" },
{ "x": 3, "y": 7, "z": 0, "rotate90": false, "id": "sample9" },
{ "x": 0, "y": 0, "z": 1, "rotate90": true, "id": "sample2" },
{ "x": 0, "y": 3, "z": 1, "rotate90": true, "id": "sample5" },
{ "x": 0, "y": 5, "z": 1, "rotate90": false, "id": "sample1" },
{ "x": 3, "y": 5, "z": 1, "rotate90": false, "id": "sample3" },
{ "x": 3, "y": 8, "z": 1, "rotate90": true, "id": "sample4" }
],
"centerOfGravity": { "x": 3.088, "y": 5.441, "z": 0.794 }
}
When this result is showin as 3D image, it becomes as follows.
Summary
- Demonstrated the feasibility of automating cargo ship stowage planning using Gemini 2.5 Pro Experimental through prompt engineering.
- Successfully generated viable stowage plans by providing key parameters like container dimensions, weights, destination ports, and ship capacity via prompts.