Skip to main content

Quick Start

In this guide, we’ll go through how you can use our Python SDK to build a simple Skill that does a chat request. The full code can be found here.

Prerequisites

1. Installing the SDK​

The SDK is published on PyPi. We recommend using uv to manage Python dependencies.

We will create an example haiku Skill, but you can use any name you want for your project. Create a new project

uv init haiku && cd haiku

and add the SDK as a dependency:

uv add pharia-skill

2. Writing a Skill​

Now, we are ready to write the Skill. Create a file called haiku.py and add the following code:

# haiku.py
from pharia_skill import Csi, Message, skill
from pydantic import BaseModel


class Input(BaseModel):
   topic: str


class Output(BaseModel):
   haiku: str


@skill
def generate_haiku(csi: Csi, input: Input) -> Output:
   system = Message.system("You are a poet who strictly speaks in haikus.")
   user = Message.user(input.topic)
   response = csi.chat("llama-3.1-8b-instruct", [system, user])
   return Output(haiku=response.message.content.strip())

We first define the input and output type as Pydantic models. Then, we create our entrypoint by decorating a function with @skill. This function must stick to the type signature in the example. The first argument Csi provides the interface for interacting with the outside world, such as the chat request shown in our example.

3. Testing​

The @skill annotation does not modify the annotated function, which allows the test code to inject different variants of CSI. The testing module provides two implementations of CSI for testing:

  • The DevCsi can be used for testing Skill code locally against a running PhariaEngine. See the docstring for how to set it up. It also supports exporting traces to PhariaStudio.
  • The StubCsi can be used as a base class for mock implementation.

See core concepts for more information on differences between running Skills in PhariaEngine and locally. To test against the DevCsi, we require two more environment variables (optionally one more for tracing):

# .env

PHARIA_AI_TOKEN=

PHARIA_KERNEL_ADDRESS=

# The address of the PhariaStudio instance you are using for tracing (optional)
PHARIA_STUDIO_ADDRESS=

Now, create a test_haiku.py file and add the following code:

# test_haiku.py
from haiku import generate_haiku, Input
from pharia_skill.testing import DevCsi


def test_haiku():
   csi = DevCsi()
   # optionally with trace export to Studio (creates the project if it does not exist)
   # csi = DevCsi.with_studio("my-project")
   result = generate_haiku(csi, Input(topic="Oat milk"))
   assert "creamy" in result.haiku or "white" in result.haiku

Install pytest:

uv add pytest --dev

And run the test:

uv run pytest test_haiku.py

4. Building​

You now build your Skill, which produces a haiku.wasm file:

uv run pharia-skill build haiku --no-interactive

Note that without the --no-interactive flag, you will get prompted to optionally publish the Skill.

5. Publishing​

We are ready to publish the Skill to a registry. Make sure you understand which namespaces are configured in the PhariaEngine instance you have access to and which registries they are linked with. For the p-prod instance, we have setup a playground to deploy to. Make sure to set the required environment variables:

# .env

SKILL_REGISTRY_USER=
SKILL_REGISTRY_TOKEN=
SKILL_REGISTRY=registry.gitlab.aleph-alpha.de
SKILL_REPOSITORY=engineering/pharia-kernel-playground/skills

To publish your Skill, run:

uv run pharia-skill publish haiku.wasm --name custom_name

6. Deploying​

To know which Skills to serve, PhariaEngine watches a list of configured namespaces. These can be toml files hosted on a server. If deploying to the playground , simply update the namespace.toml file in the GitLab UI and add your Skill:

# namespace.toml
skills = [
    { name = "greet" },
    { name = "haiku", tag = "latest" }
]

7. Invoking via API​

Once your Skill is deployed, you can test it by making an API call to PhariaEngine. You can reference the OpenAPI documentation at https://pharia-kernel.yourpharia.domain/api-docs to construct your request. Here's an example using curl:

curl 'https://pharia-kernel.yourpharia.domain/v1/skills/{namespace}/{name}/run' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $PHARIA_AI_TOKEN" \
  --data '{"topic": "Some text to be a haiku"}'