Quick start guide: building PhariaAI applications

Prerequisites

  • Your installed PhariaAI is version 0.52.4 or higher.

  • Support for custom Skills is enabled, with a default namespace named app. Also, you need to have credentials for the OCI registry.

  • Support for custom applications is enabled, and you have the credentials for the OCI registry.

  • You have enabled the following: PhariaAssistant, PhariaOS, PhariaEngine, PhariaStudio; and you have the URLs to access them.

  • You have the following tools:

    • Node.js version 20.0 or higher

    • pnpm version 9.1 or higher

    • uv installed locally

Create an application with the PhariaAI CLI

When you create a custom application using the PhariaAI CLI, the generated application includes the following:

  • an application UI

  • an application service

  • an application Skill

To do this, run the command below in your terminal:

npx @aleph-alpha/pharia-ai-cli create
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, do the following to install dependencies and start each component (UI, service, Skill) in separate terminal sessions:

1. Application UI

To get a token, see: Get an authorisation token. 
cd <your-app-name>/ui
pnpm install
# Set your PhariaAI user token in <your-app-name>/ui/.env.
pnpm run dev

2. 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

3. 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

Done!

You now have your first custom 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.

But we need to do one more thing…​

Publish your Skill to be served by PhariaEngine

At this point, API calls from the application service to the PhariaAI Skill will fail. This is because the Skill must be served through PhariaEngine. To resolve this, you 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 admin for the location of this file) by adding the new Skill entry. Once updated, your PhariaAI application is ready for use!

Previewing and registering your application

Before using pharia-ai-cli commands shown below, ensure all necessary environment variables are configured correctly in <your-app-name>/.env.

Before registering 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 Previewing your applications in developer mode 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, you need to register it:

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

Limiting access to your application

You can limit visibility of your application in PhariaAssistant by providing a project ID in the register command:

cd <your-app-folder>
npx @aleph-alpha/pharia-ai-cli register --project <PROJECT ID>

The project ID can be found in the URL bar when you access the project in PhariaStudio:

PhariaStudio - project ID in URL

If an application is registered without setting a project ID, then it is visible to all users of PhariaAssistant.

Finally, to publish and deploy the application, use the following command:

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

Access to applications can be managed in PhariaStudio as explained in Manage access to the application.

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
PhariaAssistant caches some responses in the backend for up to 10 minutes. Therefore, you may still be able to see your application in PhariaAssistant for a few minutes after you undeploy it. You can avoid this by logging out of and back into PhariaAssistant; this refreshes the cached data.

Next steps

To learn more about developing PhariaAI applications, you can explore these resources: