Overview

Constellab allows you to develop and deploy custom applications, ranging from simple interactive plots or dashboards to visualize results, to full-fledged applications within the Constellab environment. These applications help present data or outcomes in a scenario effectively. You can also explore real-life examples in the Community Applications section.

Supported Technologies

Streamlit

Streamlit is a popular Python package for quickly building data applications. It is favored for developing simple dashboards as it is powerful and efficient in visualizing results. Streamlit is easy to learn and only requires knowledge of Python, eliminating the need for frontend development skills. However, it has limitations in interface customization.

More information on Streamlit can be found here: Streamlit Official Site.

Reflex

Reflex is a fast-growing project that allows developers to build frontend and backend applications using Python, all in one place. It offers high customization options but is more challenging to learn. Having knowledge in both frontend and backend development is recommended for using Reflex efficiently.

More information on Reflex can be found here: Reflex Official Site.

Developing app

There are three methods for building an application in Constellab, each catering to different needs and levels of complexity:

Streamlit Agent

• Technology Supported: Streamlit
• Description: This method is ideal for developing simple applications directly from Constellab. Applications created using this method are easily shareable and maintainable with community agents. It supports virtual environment.
• Use Case: Suitable for quick and straightforward app development without the need for complex package handling.

Click here to learn more about Streamlit agent.

Task app in Your Brick

• Technologies Supported: Streamlit, Reflex
• Description: This method is meant for developing advanced applications and integrating them into your brick. In this scenario, a custom task is created to generate the application. It provides more flexibility and customization. It supports virtual environment.
• Use Case: Ideal for developers who need to build more complex applications, taking advantage of a real development environment and support multi-files.

Click here to learn more about Task app.

Deployment in Constellab

When deploying an application in Constellab, the platform handles various aspects such as deployment, security, and app cleanup. This ensures that developers can focus on building their applications without worrying about these operational details.

Develop a task app in you brick

Task apps provide a method to develop applications within your brick. They are particularly useful for creating complex, multi-file applications but can also be used for simpler apps if you prefer working in an IDE rather than using an agent.

Initialize the task app

To initialize a task app, use the CLI generate command to create an empty Streamlit or Reflex app. The following commands will generate the necessary structure:

• For Streamlit : gws streamlit generate my_app. More info here
• For Reflex : gws reflex generate my_app. More info here

Upon execution, a new folder is created in the current directory with the following structure :

• generate_my_app.py: This file contains the task that generates the app. An AppResource is created as the output of this task, which is used to open the app in Constellab.
• _my_app folder: This folder contains the app code and starts with an underscore ("_") to ensure it is not loaded at lab start.main.py or rconfig.py: The main application file. For Streamlit apps, this will be main.py. For Reflex apps, it will be rconfig.py.dev_config.json: This file contains configuration settings to run the app in development mode.

Run the app in development mode.

To test your application in development mode, you need to have the dev_config.json file located in your app folder. This file is crucial for simulating the application environment. Follow these steps to run your app:  

• Run the Development Command: Use the following command to run your app in dev mode. Substitute [path_to_config.json] with the path to your dev_config.json file.
• For Streamlit:gws streamlit run-dev [path_to_config.json]
• For Reflex:gws reflex run-dev [path_to_config.json]
• Access the App: The command will output a message with the URL where your app is hosted. Open this URL in a web browser to view your application.

Detail of the dev_config.json file.

Here's a breakdown of the configuration settings:

• app_dir_path
• Type: String
• Description: The path to the folder containing your app's main file. It is best to use a relative path from the dev_config.json file.
• source_ids
• Type: List[string]
• Description: A list of resource IDs to simulate real usage. Resources must be defined in the dev environment. To get a resource ID, access the resource in the Constellab dev environment and find the ID in the URL or under Resource info. If the resources do not exist, run the task to generate the application and utilize the resource from the generated StreamlitResource. The order here must match the order in your application code.
• params
• Type: Dict
• Description: Parameters to pass to the app. Keys should match those defined in the Streamlit or Reflex Resource. For instance, "title" must correspond to streamlit_resource.set_param('title', title).
• env_type
• Type: 'NONE' | 'CONDA' | 'MAMBA' | 'PIP'
• Description: Specifies the environment type to run the app. Defaults to 'NONE', which means the lab environment is used.
• env_file_path
• Type: String
• Description: If using an environment type other than 'NONE', provide the path to the environment file (YAML or TXT). Using a relative path from the dev_config.json file is recommended.

The generate task

The generate_my_app.py file contains the necessary task to configure and create the AppResource. This allows you to pass inputs, configure the app, and provide the app code for deployment in Constellab.  

Here is an example of the generate task for streamlit app.

from gws_core import (ConfigParams, AppConfig, AppType, OutputSpec,
                      OutputSpecs, StreamlitResource, Task, TaskInputs,
                      TaskOutputs, app_decorator, task_decorator, 
                      InputSpecs, ConfigSpecs)

@task_decorator("GenerateStreamlitShowcaseApp", human_name="Generate streamlit showcase app",
                short_description="App that showcases Constellab components for streamlit",
                style=StreamlitResource.copy_style())
class GenerateStreamlitShowcaseApp(Task):
    """
    Task that generates a streamlit app.
    """
    
    input_specs = InputSpecs({
        'resource': InputSpec(Resource)
    })

    output_specs = OutputSpecs({
        'streamlit_app': OutputSpec(StreamlitResource)
    })

    config_specs = ConfigSpecs({
        'my_param': InputSpec(StrParam,)
    })


    def run(self, params: ConfigParams, inputs: TaskInputs) -> TaskOutputs:
        """ Run the task """

        streamlit_app = StreamlitResource()

        # pass the task input resource to the reflex app
        task_input = inputs.get('resource')
        streamlit_app.add_resource(task_input, create_new_resource=False)

        # pass the task parameter to the streamlit app
        task_param = params.get('my_param')
        streamlit_app.set_param('my_param', task_param)

        # set the app config
        streamlit_app.set_app_config(MyAppAppConfig())

        # set the authentication requirement
        # by default, the app requires authentication so this line is optional
        streamlit_app.set_requires_authentication(True)

        # name the resource
        streamlit_app.set_name("Streamlit Showcase App")

        return {"streamlit_app": streamlit_app}

Inputs

To pass inputs to your AppResource, use the add_resource method. These input resources will be accessible within the app code. You can add any resource type except ResourceSet.

Recommendation: Add pre-computed data to avoid heavy computations in the app code, as this can slow down the application.

To access the input from the app code, it depends on the app technology (streamlit or reflex), please check the corresponding documentation. 

Config

You can customize your application by passing parameters to generate a pre-configured application. This is useful for purposes such as limiting access to certain data.

• To set parameters, use the set_param or set_params methods. These parameters will be available within the application code, enabling dynamic configuration.

To access the params from the app code, it depends on the app technology (streamlit or reflex), please check the corresponding documentation. 

Configure the app code

Provide the code for your Streamlit or Reflex app using one of the two methods below:

Provide an AppConfig (Recommended)

Use the set_app_config method to specify the configuration of your app. An AppConfig object, extended and decorated with @app_decorator, must include:

• get_app_folder_path: This method returns the path to the app folder (relative to the current file). This ensures that the latest version of the code is used when running the app.
• get_shell_proxy (Optional): Override this method to return a PipShellProxy, CondaShellProxy, or MambaShellProxy if you wish to run the app in a virtual environment. The environment must include the necessary app packages (e.g., Streamlit or Reflex).

from gws_core import (AppConfig, AppType, app_decorator, 
                      ShellProxy, MambaShellProxy)


@app_decorator("MyAppAppConfig", app_type=AppType.STREAMLIT,
               human_name="Generate MyApp app")
class MyAppAppConfig(AppConfig):

    # retrieve the path of the app folder, relative to this file
    # the app code folder starts with a underscore to avoid being loaded when the brick is loaded
    def get_app_folder_path(self):
        return self.get_app_folder_from_relative_path(__file__, "_my_app")
    
    def get_shell_proxy(self) -> ShellProxy:
      """
      Can be overrided to provide a custom virtual environment. 
      Do not override to use default environment
      """
        return MambaShellProxy.from_env_str("""
name: my_test_env
channels:
  - conda-forge
dependencies:
  - pip
  - pip:
    - streamlit==1.45.1
""")

Provide a Folder (Not Recommended)

You can call set_static_folder and provide the path to the folder containing your app code. This approach is not recommended because:

• A copy of the code is stored in the AppResource.
• This may generate strange behavior.
• The code remains frozen and will not update unless the resource is deleted and re-generated.

Utilizing AppConfig allows for better management and updating of your application within Constellab, thereby making it the preferred method for configuring app code.

Configure the authentication

Generated apps in Constellab are designed to require user authentication by default. This authentication process is seamless and invisible to users, ensuring that access control is maintained without impacting user experience. However, you may wish to disable authentication for certain scenarios, such as when developing a community app. In this case, call the set_requires_authentication method of the AppResource.

# disable authentication
streamlit_app.set_requires_authentication (False)

Use brick classes in app

In an application running in a normal environment (without a virtual environment), the GWS environment is automatically loaded. This allows you to work with classes from your brick such as resources, tasks, and databases. With this loaded environment, you can create real-time applications and generate scenarios or notes with ease.

Below is an example of a Streamlit application that creates an empty scenario when a button is clicked. The application automatically authenticates the user, ensuring that the scenario is marked as created by the user who clicked the button.

import streamlit as st
from gws_core import ScenarioProxy, Logger, User, CurrentUserService

# Your Streamlit app code here
st.title("Create scenario app")

if st.button("Create scenario"):
    st.write("Creating scenario")
    Logger.info("Creating scenario from streamlit app")
    # Call ScenarioProxy to create the scenario
    scenario_proxy = ScenarioProxy(title="Super streamlit")
else:
    st.write("No creating")
  

• Automatic User Authentication: The app authenticates the user automatically, linking scenario creation to the user performing the action.

• Real-time Interaction: The direct interaction with the database allows creating real-time applications and scenarios seamlessly.