Hello World
In this tutorial, you are building a simple demo application running on the Seaplane platform. While this implementation is complete overkill for the use case. It demonstrates in an easy-to-understand example how you can use Seaplane to build data science pipelines and experiments.
The application is available on /hello and takes a user's name as input and
responds with hello world <name>.
As you will see in the implementation below, the app is broken up into two
@task components each adding one word to the string. The first task adds the
word world the second task adds the word hello. To learn more about tasks
have a look at our documentation.
Once deployed, the Seaplane platform sets up and scales all the required infrastructure, including:
- Two containerized workloads
- An API gateway to handle the API request
- Data streams connecting all individual components
To follow along you need access to the Seaplane platform. You can sign up for
the beta here. Make sure you
have the seaplane package installed on your machine by running pip3 install seaplane in your terminal.
If you prefer to skip to the end, you can clone the finished project from our demos repository on GitHub.
Creating the project​
As a first step, you are creating the project by running seaplane init hello-world. This creates the basic project structure and files.
Delete the contents of main.py for now. You are replacing it with the hello
world code during this tutorial.
hello-world/
├── hello-world/
│ └── main.py
├── .env
└── pyproject.toml
World Task​
The first task takes the user input and pre-pends the word World, leaving us
with world <name>. In this tutorial, you are adding all tasks and the app in
one file main.py. For larger projects, we recommend creating a new file for
every individual task and importing it in main.py
from seaplane import task
@task(type='compute', id='world-task')
def world(data):
s = "World " + data['name']
return {"string" : s}
Let's unpack what we did here. We create a new @task of type compute. Once
deployed, Seaplane turns this task into a self-contained, auto-scaling
containerized workload.
The data object in the world() function contains the JSON object from the
API call; we will see later how this works once we wire everything together in
the @app component.
We extract the name and pre-pend it with the word world. Finally, we return a
JSON object which is sent to the next step in the pipeline.
Want to learn more about tasks? Take a look at the documentation here.
Hello Task​
The second task in our pipeline pre-pends the word Hello to the string,
leaving us with Hello World <name>.
from seaplane import task
@task(type='compute', id='hello-task')
def hello(data):
s = "hello " + data['string']
return {"string" : s}
Let's unpack again what we did here. We created a new compute task. The data
object in the hello() function contains the output of the world task. We
will see in the next section how this all ties together. Inside the function, we
retrieve the current string from the data object and pre-pend it with Hello.
Finally, we return the entire string from the function. This output will ultimately go back to the user.
The Application​
With both our tasks created, we can tie it all together in the @app component.
The application defines the flow of the data, how it's accessible and what
should happen to the output. Want to learn more about apps? Have a look at our
documentation here
from seaplane import app, start
@app(path='/hello', method=['POST', 'GET'], id='hello-world')
def hello_world(body):
string = world(body)
return hello(string)
start()
The code above creates our application and makes it available at the /hello
endpoint. Which translates to
<tenant-id>.on.cplane.cloud/hello-world/<version>/hello.
It wires the tasks together. The world task receives the user input from the
API, performs its computation and sends its result to the hello task. The
output of the hello task is returned to the user.
Deploying​
To deploy your application open the .env file in your root project directory.
Replace sp-your-api-key with your Seaplane API key which you can get from the
Flightdeck
Open a terminal and navigate to the root of your Seaplane project. Run poetry install to install all required packages including Seaplane.
Run seaplane deploy to start the deployment of your application. Once
deployed, we can query our API using cURL as follows.
curl -X POST -H 'Content-Type: application/json' \
--header "Authorization: Bearer $(curl https://flightdeck.cplane.cloud/identity/token --request POST --header "Authorization: Bearer <YOUR-API-KEY>")" \
-d '{"input" : [{"name": "<YOUR-NAME>"}]}' https://carrier.cplane.cloud/apps/hello-world/latest/hello
Returning the following JSON object
{"id":"<YOUR-BATCH-ID>","status":"processing"}
Replace <API-KEY> with your Seaplane API key. Replace <YOUR-NAME> with any
string but for the sake of the demo your name ;).
This creates a new batch processing request on Seaplane. By default POST
requests are treated as batches. You can get the result of the processed batch
i.e the output by running a GET request with the batch ID as follows.
curl -X GET \
--header "Authorization: Bearer $(curl https://flightdeck.cplane.cloud/identity/token --request POST --header "Authorization: Bearer <YOUR-API-KEY>")" \
https://carrier.cplane.cloud/apps/hello-world/latest/hello/request/<YOUR-BATCH-ID>
Returning the following JSON object
{"id":"<YOUR-BATCH-ID>","output":["{\"string\": \"hello World <YOUR-NAME>\"}"],"status":"completed"}
And that is all there is to it. You now have your first pipeline deployed in Seaplane. As mentioned before this kind of setup is complete overkill for a hello world application. But you can imagine how powerful it becomes if you replace the tasks with a pre-processing task, a model inference task and a post-processing task. You can start building data-driven APIs in minutes without ever having to think about the underlying infrastructure.
Sign up for our beta here if you want to try it yourself!