Skip to main content

PhariaAI applications quick start guide

Creating a PhariaAI application​

tip

Prerequisites:

This section explains how to create a PhariaAI application using the PhariaAI CLI. The generated application includes the following:

  • a PhariaAI application UI
  • a PhariaAI application service
  • a PhariaAI application skill

Run the command below in your terminal:

npx @aleph-alpha/pharia-ai-cli create
info

To see all options supported for a certain pharia-ai-cli command, execute npx @aleph-alpha/pharia-ai-cli <COMMAND> --help

You are prompted to provide a new app name and select a template:

✔ Please provide a new app name › <your-app-name>
✔ Please select a template › base / summary / qa

Once the application is created, follow these instructions to install dependencies and start each component (UI, service, skill) in separate terminal sessions.

PhariaAI application UI:​

info

To get a token, see: How to obtain a Bearer token in Pharia Studio

cd <your-app-name>/ui
pnpm install
# Set your Pharia AI user token in <your-app-name>/ui/.env.
pnpm run dev

PhariaAI application service:​

cd <your-app-name>/service
# Ensure your local Python version matches the one specified in pyproject.toml (e.g., pyenv install x.x.x && pyenv local x.x.x; see https://github.com/pyenv/pyenv)
# Verify that any missing environment variables are set in <your-app-name>/service/.env
uv sync --dev
uv run dev

PhariaAI application skill:​

cd <your-app-name>/skill
# Ensure your local Python version matches the one specified in pyproject.toml
set -a && source ../.env
uv sync --dev
info

Congratulations! You now have your first PhariaAI application up and running. To see your application in action, simply visit the application UI URL. The user interface is already set up to communicate with the application service, and the application service is configured to work with the application skill.

warning

At this point, API calls from the application service to the PhariaAI skill will fail. This is because the skill needs to be served through a PhariaEngine. To resolve this, you'll need to publish the skill so that it can be served through your PhariaEngine instance.

To publish the skill to the registry:

# Update the registry values in <your-app-name>/.env as needed, then run the following commands:
cd <your-app-name>/skill
set -a && source ../.env
uv sync --dev
uv run pharia-skill build <skill-name>
uv run pharia-skill publish <skill-name>

After publishing, update your namespace.toml file (ask your PhariaAI Operator for the location of this file) by adding the new skill entry. Once updated, your PhariaAI application is ready for use!

Previewing and deploying your application​

info

Before using any pharia-ai-cli command below, make sure all necessary environment variables are configured correctly in <your-app-name>/.env.

When you're ready to deploy your PhariaAI application, first preview it locally using PhariaAssistant:

cd <your-app-name>
npx @aleph-alpha/pharia-ai-cli preview

This command starts the application locally. Copy the preview URL and follow the instructions in How to use developer mode in PhariaAssistant to add the URL to the Developer Mode Server URL list in PhariaAssistant. Your application then appears in PhariaAssistant's left sidebar.

To make your application available in PhariaAI, first register it:

cd <your-app-name>
npx @aleph-alpha/pharia-ai-cli register

You can optionally label your application, which provides more options when filtering the list of registered applications with the PhariaOS API.

npx @aleph-alpha/pharia-ai-cli register --labels "chat,marketing"
note

As of version 0.28.1 of the PhariaAI CLI, updating your application's labels is not possible after registration. Instead, updating is only possible directly with the PhariaOS API.

Limiting access to your application​

You can limit visibility of your application in PhariaAssistant by providing a project id during the register command. The project id is available by accessing the project in PhariaStudio, in the URL bar.

pharia-studio-project-id-url.png

Access to applications can be managed in PhariaStudio as explained in Manage access to applications. If an application is registered without setting a project id, then it will be visible to all users of PhariaAssistant.

npx @aleph-alpha/pharia-ai-cli register --project <PROJECT ID>

Hiding your application from PhariaAssistant​

You can hide your application from the PhariaAssistant sidebar by providing the --headless option to the register command. This is useful for applications that offer only a service backend without any graphical user interface.

npx @aleph-alpha/pharia-ai-cli register --headless
info

Assistant only displays applications that include the "assistant" label. The PhariaAI CLI applies this label by default, unless the --headless option is specified.

note

As of version 0.28.1 of the PhariaAI CLI, updating the display option of your application is not possible after registration. Instead, updating is only possible directly with the PhariaOS API.

Deploying your application​

To finally deploy your application, run the following commands:

cd <your-app-name>
npx @aleph-alpha/pharia-ai-cli publish
npx @aleph-alpha/pharia-ai-cli deploy

Undeploying your application​

If you want to undeploy your application execute the following command

cd <your-app-name>
npx @aleph-alpha/pharia-ai-cli undeploy
info

PhariaAssistant caches certain responses in the backend for up to 10 minutes. Hence, you might still be able to see your application in PhariaAssistant for a few minutes after you undeployed it. This mechanism can be circumvented by logging out from and back into PhariaAssistant, which will refresh cached data.

If you encounter any issues, see the Troubleshooting section.

Next steps​

To learn more about PhariaAI applications, explore these resources: