How to enable teams to ship custom skills

For operators

Skills are organized into namespaces to allow development teams to deploy in self-service. Each namespace is associated with:

1. An OCI repository from which to load skills. Popular choices include GitLab Container Registries, GitHub Container Registries, and JFrog Artifactory.
2. A namespace configuration file that lists the skills that are deployed. (This is typically a TOML file checked into a Git repository owned by the corresponding team.)

We recommend the operators to set up the app namespace, which is referenced in the official tutorials. This is configured using the values from the PhariaAI Helm chart.

The following is an example configuration based on the fictional GitLab instance https://gitlab.acme.com and the OCI registries registry.acme.com:

pharia-kernel:
  namespaces:
    # The Namespace name can be specified in camelCase, and is converted to kebab-case when deployed.
    app:
      # The URL to the corresponding Namespace configuration TOML file.
      # Changes in this file will be automatically applied
      configUrl: "https://gitlab.acme.com/api/v4/projects/123/repository/files/namespace.toml/raw?ref=main"
      # The Container Registry that backs the skill registry for this Namespace
      registry: "registry.acme.com"
      # The base repository in `registry` that backs the skill registry for this Namespace
      # This composes the final repository for each skill e.g. ${baseRepository}/${skillName}
      baseRepository: "app/skills"
  env:
    secret:
      # The access token for `configUrl`
      NAMESPACES__APP__CONFIG_ACCESS_TOKEN:
        name: my-secrets
        key: myConfigAccessToken
      # The user name for accessing `registry`
      NAMESPACES__APP__REGISTRY_USER:
        name: my-secrets
        key: myRegistryUser
      # The password or access token for accessing `registry`
      NAMESPACES__APP__REGISTRY_PASSWORD:
        name: my-secrets
        key: myRegistryAccessToken

With the configuration above, the OCI registry and the configuration file is specified for each namespace in pharia-kernel.namespaces. The credentials to access the namespace configuration file and the OCI registry are specified via pharia-kernel.env.secret.

Additional namespaces can be set up as necessary, for example, if requested by a fictional "Awesome AI Team".

The following is an example configuration with the additional namespace awesome-ai-team:

pharia-kernel:
  namespaces:
    app:
      configUrl: "https://gitlab.acme.com/api/v4/projects/123/repository/files/namespace.toml/raw?ref=main"
      registry: "registry.acme.com"
      baseRepository: "app/skills"
    awesomeAiTeam:
      configUrl: "https://gitlab.my-namespace.com/api/v4/projects/123/repository/files/namespace.toml/raw?ref=main"
      registry: "registry.my-namespace.com"
      baseRepository: "my-namespace"
  env:
    secret:
      NAMESPACES__APP__CONFIG_ACCESS_TOKEN:
        name: my-secrets
        key: myConfigAccessToken
      NAMESPACES__APP__REGISTRY_USER:
        name: my-secrets
        key: myRegistryUser
      NAMESPACES__APP__REGISTRY_PASSWORD:
        name: my-secrets
        key: myRegistryAccessToken
      NAMESPACES__AWESOME_AI_TEAM__CONFIG_ACCESS_TOKEN:
        name: my-namespace-secrets
        key: myNamespaceConfigAccessToken
      NAMESPACES__AWESOME_AI_TEAM__REGISTRY_USER:
        name: my-namespace-secrets
        key: myNamespaceRegistryUser
      NAMESPACES__AWESOME_AI_TEAM__REGISTRY_PASSWORD:
        name: my-namespace-secrets
        key: myNamespaceRegistryAccessToken

For PhariaAI Helm chart versions up to 1.250600.2

In older PhariaAI Helm chart versions, a list is required for defining env:

pharia-kernel:
  env:
    - name: NAMESPACES__APP__CONFIG_ACCESS_TOKEN
      valueFrom:
        secretKeyRef:
          name: my-secrets
          key: myConfigAccessToken
    - name: NAMESPACES__APP__REGISTRY_USER
      valueFrom:
        secretKeyRef:
          name: my-secrets
          key: myRegistryUser
    - name: NAMESPACES__APP__REGISTRY_PASSWORD
      valueFrom:
        secretKeyRef:
          name: my-secrets
          key: myRegistryAccessToken

For version 1.250700.0 onwards, both list and map are allowed, but it's recommended to use the streamlined format for configuring secrets:

pharia-kernel:
  env:
    secret:
      NAMESPACES__APP__CONFIG_ACCESS_TOKEN:
        name: my-secrets
        key: myConfigAccessToken
      NAMESPACES__APP__REGISTRY_USER:
        name: my-secrets
        key: myRegistryUser
      NAMESPACES__APP__REGISTRY_PASSWORD:
        name: my-secrets
        key: myRegistryAccessToken

For developers

The namespace configuration TOML file facilitates developer self-service.

Skills

After publishing the skills to the associated OCI repository, the developers can deploy them by updating the namespace config.

In the following example, the skills foo and bar are now deployed. The skill tag is optional, which defaults to latest:

skills = [
    { name = "foo", tag = "1.0.1" },
    { name = "bar" },
]

Native tools

PhariaEngine offers native tools that are built-in and optionally configurable for each namespace.

Currently, the available tools are add, subtract, and saboteur, which are intended for testing during skill development:

native-tools = [ "add", "subtract", "saboteur" ]

MCP servers

PhariaEngine allows additional tools to be provided via the Model Context Protocol (MCP).

All MCP servers that use Streamable HTTP transport and do not require authentication can be configured for each namespace:

mcp-servers = [
    "https://gitmcp.io/Aleph-Alpha/pharia-kernel-sdk-py",
    "http://mcp-fetch.pharia-ai.svc.cluster.local:8000/mcp"
]