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 PhariaKernel. 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 the Kernel and locally. To test against the DevCsi, we require two more environment variables (optionally one more for tracing):

# .env

# The address of the PhariaKernel instance you are using, e.g. https://pharia-kernel.your-pharia.domain (replace the `your-pharia.domain` part in all examples)
PHARIA_KERNEL_ADDRESS=

# A token to authenticate against PhariaAI, can be retrieved from the PhariaStudio frontend (https://pharia-studio.your-pharia.domain)
PHARIA_AI_TOKEN=

# The address of the PhariaStudio instance you are using, e.g. https://pharia-studio.your-pharia.domain (replace the `your-pharia.domain` part in all examples)
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

The DevCsi can export traces to any OpenTelemetry compatible backend like Langfuse. Simply set the corresponding environment variables:

# .env
OTEL_EXPORTER_OTLP_ENDPOINT=https://cloud.langfuse.com/api/public/otel/v1/traces
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_STRING}"

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 PhariaKernel 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

# The PhariaKernel supports arbiratry OCI registries to deploy Skills to. See https://pharia-skill.readthedocs.io/en/stable/03-core_concepts.html#namespaces for more details.
# If you are unsure what value to set here, check with the operator of your PhariaAI instance what registries your PhariaKernel is configured with.
# e.g. registry.gitlab.{your-domain} for a gitlab registry, but could also be a GitHub or any other registry that is configured for your PhariaKernel.
SKILL_REGISTRY=

# The repository you want to deploy your Skill to.
# e.g. engineering/your-team/skills
SKILL_REPOSITORY=

# The `pharia-skill` CLI tool uses basic auth to authenticate against the Skill registry.
# In case you are using a token as a password, the value of `SKILL_REGISTRY_USER` can be anything, e.g. `dummy`.
SKILL_REGISTRY_USER=
# A token that has read and write access to the registry you want to publish your Skill to.
SKILL_REGISTRY_TOKEN=

To publish your Skill, run:

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

6. Deploying

To know which Skills to serve, the PhariaKernel watches a list of configured namespaces. These can be toml files hosted on a server. Check with your operator where this configuration file for the namespace that you deployed to in the previous step is hosted. Then, update the configuration file 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 the PhariaKernel. You can reference the OpenAPI documentation at https://pharia-kernel.yourpharia.domain/api-docs to construct your request. You need to provide the name of the namespace that you have previously deployed your Skill to. If unsure, check with your operator. 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"}'