You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In this tutorial, you will learn how to use natural functions in Ballerina Integrator, which allow the function to contain instructions in natural language.
4
-
Such a function is evaluated at runtime with a call to an LLM. The example uses a natural function to analyze blog content to suggest a category and rate it based on predefined criteria.
3
+
In this tutorial, you will create and use a natural function using the Ballerina Integrator. A natural function allows the logic of the function to be described in natural language and is executed at runtime with a call to a Large Language Model (LLM), with the natural language instructions as the prompt.
4
+
The tutorial uses a natural function to analyze blog content to suggest a suitable category and rate it on a scale of 1 to 10 based on specified criteria.
5
5
6
6
???+ tip "Natural Programming"
7
-
To learn more about Ballerina natural programming library module, see [natural programming](https://central.ballerina.io/ballerinax/np).
7
+
To learn more about natural programming and natural functions, see [Natural Language is Code: A hybrid approach with Natural Programming](https://blog.ballerina.io/posts/2025-04-26-introducing-natural-programming/).
8
8
9
9
10
10
## Implementation
11
11
Follow the steps below to implement the integration.
12
12
13
-
### Step 1: Create a new integration project.
13
+
### Step 1: Create a new integration project
14
14
1. Click on the Ballerina Integrator icon on the sidebar.
15
15
2. Click on the **`Create New Integration`** button.
16
-
3. Enter the project name as `NaturalProgramming`.
16
+
3. Enter `BlogReviewer` as the project name.
17
17
4. Select Project Directory and click on the **`Select Location`** button.
18
18
5. Click on the **`Create New Integration`** button to create the integration project.
19
19
20
20
### Step 2: Define Types
21
21
1. Click on the **`Add Artifacts`** button and select **`Type`** in the **`Other Artifacts`** section.
22
22
2. Click on **`+ Add Type`** to add a new type.
23
-
3. Add the **`Record Name`** as `Blog` and paste the following JSON payload. Select **`Is Closed Record`** and click on the **`Import`** button.
23
+
3. Use `Blog` as the **`Name`**. Then click on the **`JSON`** button and paste the following JSON payload. Tick **`Is Closed`** and click on the **`Import`** button. Then click the **`Save`** button.
24
+
24
25
```json
25
26
{
26
27
"title": "Tips for Growing a Beautiful Garden",
27
28
"content": "Spring is the perfect time to start your garden. Begin by preparing your soil with organic compost and ensure proper drainage. Choose plants suitable for your climate zone, and remember to water them regularly. Don't forget to mulch to retain moisture and prevent weeds."
28
29
}
29
30
```
30
-
4. Add another type with the **`Record Name`** as `Review` and paste the following JSON payload. Select **`Is Closed Record`** and click on the **`Import`** button.
31
+
32
+
4. Add another type with `Review` as the **`Name`** and paste the following JSON payload. Select **`Is Closed`** and click on the **`Import`** button. Then click the **`Save`** button.
33
+
31
34
```json
32
35
{
33
-
"name": "Gardening",
36
+
"suggestedCategory": "Gardening",
34
37
"rating": 5
35
38
}
36
39
```
40
+
37
41
5. The types are now available in the project. `Blog` and `Review` are the types that represent the blog content and review respectively.
3. Click on the **`Edit`** button to add the function logic.
54
-
4. Add the following prompt to the function and click on the **`Save`** button.
48
+
2. Use `reviewBlog` as the name of the function. Then click the **`Add Parameter`** button to add a parameter of type `Blog` named `blog`. Use `Review` as the return type and convert it to nilable type using type operators. Then click on the **`Create`** button.
3. Click on the **`Edit`** button to specify the requirement in natural language (i.e., the prompt).
53
+
4. Use the following prompt and click on the **`Save`** button. Note how interpolations refer to the `blog` parameter.
54
+
55
55
```plaintext
56
56
You are an expert content reviewer for a blog site that
57
57
categorizes posts under the following categories: "Gardening", "Sports", "Health", "Technology", "Travel"
@@ -72,36 +72,52 @@ Follow the steps below to implement the integration.
72
72
Title: ${blog.title}
73
73
Content: ${blog.content}
74
74
```
75
-
76
-
### Step 5: Update the resource method
77
-
1. The service will have a default resource named `greeting` with the **`GET`** method. Click on three dots appear in front of the `/convert` service resource and select **`Edit`** from menu.
78
-
2. Then click the edit button in front of `/greeting` resource.
79
-
3. Change the resource HTTP method to **`POST`**.
80
-
4. Change the resource name as `review`.
81
-
5. Add a payload parameter named `blog` to the resource of type `Blog`.
82
-
6. Change the 201 response return type to `Review`.
83
-
7. Click on the **`Save`** button to update the resource with the specified configurations.
6. The service will have a default resource named `greeting` with the **`GET`** method. Click on the three dots that appear in front of the `/blogs` service and select **`Edit`** from the menu.
89
+
7. Then click the **`Edit`** button in front of `/greeting` resource.
90
+
8. Change the resource HTTP method to **`POST`**.
91
+
9. Change the resource name to `review`.
92
+
10. Click on **`Add Payload`** and specify `blog` as the name and `Blog` as the type.
93
+
11. Change the 201 response return type to `Review`.
94
+
12. Click on the **`Save`** button to update the resource with the specified configurations.
9. The resource implementation is now complete. The function `reviewBlog` is called with the blog content as input and the review is returned as the response.
100
+
2. Hover over the arrow after start and click the ➕ button to add a new action to the resource.
101
+
3. Select **`Call Natural Function`** from the node panel.
102
+
4. Select the `reviewBlog` function from the suggestions.
103
+
5. For the **`Blog`** parameter, use `blog` as the argument and click on the **`Save`** button.
8. The resource implementation is now complete. The function `reviewBlog` is called with the `blog` content as input, and the `review` is returned as the response.
98
113
99
-
### Step 7: Configure model for natural function
100
-
1. Press `Ctrl + Shift + P` on Windows and Linux, or `shift + ⌘ + P` on a Mac and type `>Ballerina: Configure default model for natural functions` to configure the default model for natural functions.
1. Press `Ctrl + Shift + P` on Windows and Linux, or `Shift + ⌘ + P` on a Mac, and type `>Ballerina: Configure default model for natural functions (Experimental)` to configure the default model for natural functions.
Since this integration involves an LLM (Large Language Model) call, the response values may not always be identical across different executions.
@@ -110,18 +126,14 @@ Follow the steps below to implement the integration.
110
126
2. The integration will start and the service will be available at `http://localhost:9090/blogs`.
111
127
3. Click on the **`Try it`** button to open the embedded HTTP client.
112
128
4. Enter the blog content in the request body and click on the ▶️ button to send the request.
129
+
113
130
```json
114
131
{
115
132
"title": "The Healthy Maven",
116
133
"content": "For those who want a 360-degree approach to self-care, with advice for betterment in the workplace, home, gym, and on the go, look no further. The Healthy Maven offers recipes for every type of meal under the sun (salads, sides, soups, and more), DIY tips (you’ll learn how to make your own yoga mat spray), and quick workouts. If you like where all this is going, there’s a supplementary podcast run by blogger Davida with guest wellness experts."
117
134
}
118
135
```
119
-
5. The response will be a review of the blog content with the category and rating.
120
-
```json
121
-
{
122
-
"name": "Health",
123
-
"rating": 8
124
-
}
125
-
```
126
-
6. The blog content is analyzed by the natural function to suggest a category and rate it based on predefined criteria.
0 commit comments