└── sinapsis-cli ├── sinapsis_cli_tutorial.md └── sinapsis_cli_tutorial.pdf /sinapsis-cli/sinapsis_cli_tutorial.md: -------------------------------------------------------------------------------- 1 | # Sinapsis CLI 2 | 3 | The sinapsis CLI offers a mechanism to easily execute Sinapsis Agent definitions from a unix shell. Additionally, it includes functionalities to display useful information such as a Template attribute names, example Agent defintions for specified Templates or the list of all the installed templates in the current workspace. 4 | 5 | 6 | ## Initial steps 7 | 8 | Please follow the installation process described in the [Sinapsis Installation](https://github.com/Sinapsis-ai/sinapsis?tab=readme-ov-file#installation) section. 9 | 10 | ## Available commands 11 | A summary of the available CLI commands and usage can be consulted in the 12 | [Sinapsis Quickstart](https://github.com/Sinapsis-ai/sinapsis?tab=readme-ov-file#quickstart) section. 13 | 14 | 15 | ## Usage 16 | 17 | To verify the installation process was successful, please execute the following command: 18 | 19 | ```bash 20 | sinapsis 21 | ``` 22 | If everything was correctly installed, the below welcome message should be displayed in the unix console: 23 | ```bash 24 | Welcome to Sinapsis CLI. Please run 'sinapsis -h' to obtain information about available commands. 25 | ``` 26 | Add the flag `-h` or `--help` after the `sinapsis` command to get detailed information about sinapsis usage and available options 27 | ```bash 28 | sinapsis -h 29 | ``` 30 | Output: 31 | ```bash 32 | usage: sinapsis [-h] {run,info} ... 33 | 34 | Sinapsis CLI 35 | 36 | options: 37 | -h, --help show this help message and exit 38 | 39 | subcommands: 40 | CLI commands: run, help 41 | 42 | {run,info} 43 | run Run a Sinapsis agent with a yaml config file 44 | info Get information about one or all Sinapsis template 45 | ``` 46 | 47 | ## Sinapsis run 48 | Sinapsis CLI provide the command `sinapsis run` to execute Agent definitions declared in a config file. Detailed usage information can be obtained using the `--help` or `-h` flags as follows 49 | ```bash 50 | sinapsis run -h 51 | ``` 52 | This will produce the following usage example 53 | ```bash 54 | usage: sinapsis run [-h] [--enable-profiler] agent_config 55 | 56 | positional arguments: 57 | agent_config 58 | 59 | options: 60 | -h, --help show this help message and exit 61 | --enable-profiler Run agent in profiling mode 62 | ``` 63 | 64 | For instance, to run the [hello_world_agent](https://github.com/Sinapsis-ai/sinapsis/blob/main/src/sinapsis/configs/hello_world_agent.yml) config file use 65 | ```bash 66 | sinapsis run src/sinapsis/configs/hello_world_agent.yml 67 | ``` 68 | Output: 69 | ```bash 70 | 2025-02-24 @ 14:44:31:663 | DEBUG | hello_world_agent:__instantiate_templates:113 - Initialized template: InputTemplate 71 | 2025-02-24 @ 14:44:31:665 | DEBUG | hello_world_agent:__instantiate_templates:113 - Initialized template: HelloWorld 72 | 2025-02-24 @ 14:44:31:665 | DEBUG | hello_world_agent:__instantiate_templates:113 - Initialized template: DisplayHelloWorld 73 | 2025-02-24 @ 14:44:31:665 | DEBUG | hello_world_agent:_log_agent_execution_order:128 - Execution Order 74 | 2025-02-24 @ 14:44:31:665 | DEBUG | hello_world_agent:_log_agent_execution_order:131 - Order: <<0>>, template name: <> 75 | 2025-02-24 @ 14:44:31:665 | DEBUG | hello_world_agent:_log_agent_execution_order:131 - Order: <<1>>, template name: <> 76 | 2025-02-24 @ 14:44:31:665 | DEBUG | hello_world_agent:_log_agent_execution_order:131 - Order: <<2>>, template name: <> 77 | 2025-02-24 @ 14:44:31:665 | INFO | hello_world_agent:_lazy_init:66 - Agent and templates initialized 78 | 2025-02-24 @ 14:44:31:665 | INFO | hello_world_agent:signal_block_if_needed:167 - Signaling block mode for HelloWorld no: 2/3 79 | 2025-02-24 @ 14:44:31:666 | INFO | hello_world_agent:signal_block_if_needed:167 - Signaling block mode for DisplayHelloWorld no: 3/3 80 | 81 | Hello, this is my first template! 82 | 83 | 2025-02-24 @ 14:44:31:666 | INFO | hello_world_agent:all_templates_finished:208 - All templates returned finished, stopping execution... 84 | 2025-02-24 @ 14:44:31:666 | DEBUG | .../sinapsis_core/cli/run_agent_from_config.py:run_agent_from_config:47 - result: DataContainer(container_id=a360a..., images=[], audios=[], texts=[TextPacket(content='Hello, this is my first template!', id='e86...', source='HelloWorld', modified_by_templates=['HelloWorld'], embedding=[], generic_data={}, annotations=None)], time_series=[], binary_data=[], generic_data={}) 85 | ``` 86 | ### Enable profiler 87 | Additionally, to get the profiling times of the executed Agent and Templates the `optional` flag `--enable-profiler` can be used. For example, the following command 88 | ```bash 89 | sinapsis run src/sinapsis/configs/hello_world_agent.yml --enable-profiler 90 | ``` 91 | will display the following execution times and statistics in the output console 92 | ```bash 93 | 2025-02-24 @ 14:49:07:502 | INFO | hello_world_agent:print_stats:77 - template: HelloWorld, average_time: 0.030, median: 0.030, num_executions: 1 94 | 2025-02-24 @ 14:49:07:502 | INFO | hello_world_agent:print_stats:84 - Agent times: 0.174 median: 0.174 95 | ``` 96 | 97 | ## Sinapsis info 98 | Sinapis CLI offers through the `sinapsis info` command, a funtionality to display detailed information regarding Template Attributes, example Agent configs for specified Templates and the list of all the installed Templates in the working environment. 99 | 100 | To display the `sinapsis info` command example of usage and all the available options use the `--help` or `-h` flags 101 | ```bash 102 | sinapsis info -h 103 | ``` 104 | Output: 105 | ```bash 106 | usage: sinapsis info [-h] [--template TEMPLATE_NAME] [--all] [--all-template-names] [--example-template-config TEMPLATE_NAME] 107 | 108 | options: 109 | -h, --help show this help message and exit 110 | --template TEMPLATE_NAME Template name to display info for 111 | --all Get info about all Sinapsis templates 112 | --all-template-names Display all template names 113 | --example-template-config TEMPLATE_NAME 114 | Display an example config for the specified template 115 | ``` 116 | ### Display Template information 117 | Use 118 | ```bash 119 | sinapsis info --template TEMPLATE_NAME 120 | ``` 121 | to display the following information: 122 | * Path to the installed Template. 123 | * Brief description of Template. 124 | * Description of Template attributes. 125 | 126 | For example, to display the `HelloWorld` Template information run 127 | 128 | ```bash 129 | sinapsis info --template HelloWorld 130 | ``` 131 | Output: 132 | ```bash 133 | /path/to/sinapsis/templates/hello_world.py 134 | 135 | HelloWorld: This template simply adds a text packet to our data container. The data container 136 | is `sent` to any subsequent templates in our Agent. 137 | 138 | HelloWorld attributes: 139 | display_text : default: Hello World 140 | ``` 141 | 142 | ### Display ALL Templates info 143 | Use the following command to display Template information for ALL the templates installed in the working environment: 144 | ```bash 145 | sinapsis info --all 146 | ``` 147 | Output: 148 | ```bash 149 | ---------------------------------------------------------------------- 150 | /path/to/sinapsis/templates/display_hello_world.py 151 | 152 | DisplayHelloWorld: This template simply logs all the text packets received in a data container. 153 | It is meant to be used for illustration purposes and in combination with 154 | HelloWorld template. 155 | 156 | DisplayHelloWorld attributes: 157 | 158 | ---------------------------------------------------------------------- 159 | /path/to/sinapsis/templates/hello_world.py 160 | 161 | HelloWorld: This template simply adds a text packet to our data container. The data container 162 | is `sent` to any subsequent templates in our Agent. 163 | 164 | HelloWorld attributes: 165 | display_text : default: Hello World 166 | 167 | ---------------------------------------------------------------------- 168 | ``` 169 | ### Display ALL Template names 170 | Use 171 | ```bash 172 | sinapsis info --all-template-names 173 | ``` 174 | to display a list with all the available Template names installed in the working environment. By default, when installing Sinapsis the following templates should be displayed: 175 | ```bash 176 | CopyDataContainer 177 | DisplayHelloWorld 178 | HelloWorld 179 | InputTemplate 180 | MergeDataFlow 181 | OutputTemplate 182 | SplitDataFlow 183 | TransferDataContainer 184 | ``` 185 | ### Display example template config 186 | The ```sinapis info``` command offers the option to build and display an example Agent config for an specified Template name using the ```--example_template_config``` flag as follows: 187 | ```bash 188 | sinapsis info --example-template-config TEMPLATE_NAME 189 | ``` 190 | For example, to display an Agent config for the ```HelloWorld``` template use: 191 | ```bash 192 | sinapsis info --example-template-config HelloWorld 193 | ``` 194 | Output: 195 | ```bash 196 | agent: 197 | name: my_test_agent 198 | templates: 199 | - template_name: InputTemplate 200 | class_name: InputTemplate 201 | attributes: {} 202 | - template_name: HelloWorld 203 | class_name: HelloWorld 204 | template_input: InputTemplate 205 | attributes: 206 | display_text: Hello World 207 | ``` 208 | 209 | 210 | -------------------------------------------------------------------------------- /sinapsis-cli/sinapsis_cli_tutorial.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Sinapsis-AI/sinapsis-tutorials/861f6ef9addb12aebb197b015dafc3c6341f547a/sinapsis-cli/sinapsis_cli_tutorial.pdf --------------------------------------------------------------------------------