Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add doc for msg_conversion in dev server #243

Merged
merged 2 commits into from
Nov 7, 2024
Merged

feat: add doc for msg_conversion in dev server #243

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f2053c
feat: add doc for msg_conversion in dev server
leoadonia Nov 7, 2024
a66e290
fix: format
leoadonia Nov 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
219 changes: 193 additions & 26 deletions docs/ten_framework/ten_manager/dev_server_cn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ You will receive a `200 OK` response, with the body containing a JSON object lik
}
```

{% endcode %}
{% endcode %}

## Installed Extension Addons

Expand All @@ -65,7 +65,7 @@ You will receive a `200 OK` response, with the body containing a JSON array like
]
```

{% endcode %}
{% endcode %}

## Available Graphs

Expand All @@ -87,7 +87,7 @@ You will receive a `200 OK` response, with the body containing a JSON array like
]
```

{% endcode %}
{% endcode %}

If an error occurs, such as when the App package is not found, you will receive a `400 Bad Request` response with the body containing `Failed to find any app packages`.

Expand All @@ -98,7 +98,128 @@ Retrieve the list of extensions within a specified graph.
- **Endpoint:** `/api/dev-server/v1/graphs/{graph_id}/nodes`
- **Verb:** GET

You will receive a `200 OK` response, with the body containing a JSON array.
You will receive a `200 OK` response, with the body containing a JSON array. Ex:

{% code title=".json" %}

```json
{
"status": "ok",
"data": [
{
"addon": "addon_a",
"name": "ext_a",
"extension_group": "some_group",
"app": "localhost",
"api": {
"property": {
"foo": {
"type": "string"
}
},
"cmd_in": [
{
"name": "hello",
"property": [
{
"name": "foo",
"attributes": {
"type": "string"
}
}
],
"result": {
"property": [
{
"name": "detail",
"attributes": {
"type": "string"
}
}
]
}
}
],
"data_out": [
{
"name": "hello",
"property": [
{
"name": "bar",
"attributes": {
"type": "Uint8"
}
}
]
}
]
},
"property": {
"foo": "1"
}
},
{
"addon": "addon_b",
"name": "ext_b",
"extension_group": "some_group",
"app": "localhost",
"api": {},
"property": null
}
]
}
```

{% endcode %}

The element type of the `data` array is defined as follows.

| key | value type | required | description |
| :-------------- | :--------: | :------: | :-------------------------------------------------------------------- |
| app | string | N | The uri of the app this extension belongs to, default is 'localhost'. |
| extension_group | string | Y | The extension_group this extension running on. |
| addon | string | Y | The addon used to create this extension. |
| name | string | Y | The extension name. |
| api | object | N | The schema definitions of property and msgs of this extension. |
| property | object | N | The property of this extension. |

> Note that each element in the `data` array is uniquely identified by the combination of `app`, `extension_group`, and `name`.

Definition of the `api` object.

| key | value type | required | description |
| :-------------- | :--------: | :------: | :--------------------------------------- |
| property | object | N | The schema of the property. |
| cmd_in | object | N | The schema of all the `IN` cmd. |
| cmd_out | object | N | The schema of all the `OUT` cmd. |
| data_in | object | N | The schema of all the `IN` data. |
| data_out | object | N | The schema of all the `OUT` data. |
| audio_frame_in | object | N | The schema of all the `IN` audio_frame. |
| audio_frame_out | object | N | The schema of all the `OUT` audio_frame. |
| video_frame_in | object | N | The schema of all the `IN` video_frame. |
| video_frame_out | object | N | The schema of all the `OUT` video_frame. |

> Note that the `cmd`, `data`, `audio_frame`, `video_frame` are four types of TEN msgs.

The format of the `property` is same as the schema definition. The format of `data_in` / `data_out` / `audio_frame_in` / `audio_frame_out` / `video_frame_in` / `video_frame_out` are same as follows.

| key | value type | required | description |
| :-------------------- | :--------: | :------: | :-------------------------------------- |
| name | string | Y | The msg name. |
| property | array | N | The property belongs to this msg. |
| property[].name | string | Y | The property name. |
| property[].attributes | object | Y | The schema definition of this property. |

The format of the `cmd_in` and `cmd_out` are same, and compared with the above `data_in`, there is an additional `result` attribute.

| key | value type | required | description |
| :-------------------- | :--------: | :------: | :------------------------------------------------------------------------------- |
| name | string | Y | The msg name. |
| property | array | N | The property belongs to this msg. |
| property[].name | string | Y | The property name. |
| property[].attributes | object | Y | The schema definition of this property. |
| result | object | N | The schema of the corresponding result of this cmd. |
| result.property | array | Y | The property belongs to this cmd result, the format is same with the `property`. |

## Connections in a Specified Graph

Expand All @@ -107,34 +228,80 @@ Retrieve the list of connections within a specified graph.
- **Endpoint:** `/api/dev-server/v1/graphs/{graph_id}/connections`
- **Verb:** GET

You will receive a `200 OK` response, with the body containing a JSON array like this:
You will receive a `200 OK` response. Ex:

{% code title=".json" %}

```json
[
{
"app": "localhost",
"extension": "simple_http_server_cpp",
"extension_group": "default_extension_group",
"cmd": [
{
"name": "hello_world",
"dest": [
{
"app": "localhost",
"extension": "default_extension_cpp",
"extension_group": "default_extension_group"
}
]
}
]
}
]
{
"status": "ok",
"data": [
{
"app": "localhost",
"extension_group": "some_group",
"extension": "ext_a",
"cmd": [
{
"name": "cmd_1",
"dest": [
{
"app": "localhost",
"extension_group": "some_group",
"extension": "ext_b",
"msg_conversion": {
"type": "per_property",
"rules": [
{
"path": "extra_data",
"conversion_mode": "fixed_value",
"value": "tool_call"
}
],
"keep_original": true
}
}
]
}
]
}
]
}
```

{% endcode %}

The element type of the `data` array is defined as follows.

| key | value type | required | description |
| :-------------- | :--------: | :------: | :---------------------------------------------------------------------------------------------------------------------------- |
| app | string | N | Same as the `app` field in the `nodes`. |
| extension_group | string | Y | Same as the `extension_group` field in the `nodes`. |
| extension | string | Y | Same as the **`name`** field in the `nodes`. |
| cmd | array | N | The msgs will be sent from this extension group by type. The possible values are `cmd`, `data`, `audio_frame`, `video_frame`. |

The element type of the `cmd` array is defined as follows.

| key | value type | required | description |
| :--------------------- | :--------: | :------: | :-------------------------------------------------------------------- |
| name | string | Y | The msg name, must be unique in each msg group. |
| dest | array | Y | The extensions this msg will be sent to. |
| dest[].app | string | N | Same as the `app` field in the `nodes`. |
| dest[].extension_group | string | Y | Same as the `extension_group` field in the `nodes`. |
| dest[].extension | string | Y | Same as the `name` field in the `nodes`. |
| dest[].msg_conversion | object | N | The conversions used to transform the msg before sending to the dest. |

The definition of `msg_conversion` is as follows.

| key | value type | required | description |
| :--------------------- | :--------: | :------: | :------------------------------------------------------------------------- |
| type | string | Y | The possible value is `per_property`. |
| rules | array | Y | The conversion rules. |
| rule[].path | string | Y | The json path of the property this rule will be applied on. |
| rule[].conversion_mode | string | Y | The method of rule, possible values are `fixed_value` and `from_original`. |
| rule[].value | string | N | Required if the conversion_mode is `fixed_value`. |
| rule[].original_path | string | N | Required if the conversion_mode is `from_original`. |
| keep_original | boolean | N | Whether to clone the original property. Default is false. |

## Retrieve Compatible Messages for a Selected Extension

Select a message from an extension and retrieve all other messages from different extensions in the graph that are compatible with it.
Expand All @@ -158,7 +325,7 @@ The input body is a JSON object that represents a request to find compatible pin
}
```

{% endcode %}
{% endcode %}

You will receive a `200 OK` response, with the body containing a JSON array like this:

Expand All @@ -185,7 +352,7 @@ You will receive a `200 OK` response, with the body containing a JSON array like
]
```

{% endcode %}
{% endcode %}

## Update a Graph

Expand Down