Concepts

PhariaEngine is a very powerful tool, and it can seem quite complex in the beginning. However, much of the power behind it can be explained by a few important concepts.

Terms in italic are also defined in this article.


Skill

A Skill is the fundamental building block of PhariaEngine. Each Skill encapsulates a discrete unit of business or AI logic. It is a user-defined, stateless function that adheres to strict input/output schemas defined using Pydantic models. This ensures type safety, validation, and clear documentation of the Skill’s contract.

Unlike traditional serverless or Function as a Service (FaaS) functions, Skills are designed to operate within PhariaEngine’s orchestration layer. They interact with the broader system through the Cognitive System Interface (CSI) which exposes AI-native capabilities like LLM inference, vector search, and authenticated data access. This abstraction allows Skills to focus purely on business logic while delegating infrastructure concerns to PhariaEngine.

When a given Skill is to be executed, and how, is determined by PhariaEngine. This allows the engineer to focus on the business and AI logic of each Skill.

WebAssembly (WASM) component

When you build a Skill, it is compiled to a WebAssembly (WASM) component using componentize-py. This tool resolves the imports of a Skill module, so any package you import in your Skill is also included in the component.

Note, however, that non-native dependencies (for example, NumPy, which is written in C) only work if the wheels for WASI targets are available at build-time. For Pydantic, our SDK resolves this for you.

Cognitive System Interface (CSI)

Similarly to how an operating system provides functionality to applications, the Cognitive System Interface (CSI) is the set of functions provided to the user code when it is run within the PhariaEngine environment.

The functionality of the CSI is focused around the needs of AI methodology, such as LLM inference, vector search, and data access.

By providing a common interface to these tools, it allows the user code to describe the intended interaction and outcome in its own code, and PhariaEngine manages the complexity of providing it.

For example, authentication is not part of the CSI interface, but it is handled by PhariaEngine, which authenticates all CSI calls with the token provided in the request. To make this interface available at development time, the SDK provides a DevCSI.

Testing

When Skills are run in PhariaEngine, the CSI is provided via an application binary interface. This interface is defined in the WASM Interface Type (WIT) language.

For development and debugging, Skills can also run in a local Python environment. The CSI, which is available to the Skill at runtime, can be substituted with a DevCSI which is backed by HTTP requests against a running instance of PhariaEngine. In this way, developers can write tests, step through their Python code, and inspect the state of variables.

Tracing

PhariaEngine automatically traces Skills and all interactions with the CSI (however, logs are currently not available). When developing Skills, the developer does not need to worry about setting up tracing.

PhariaEngine can be configured to export traces to an OpenTelemetry-compatible backend. At development time, the DevCSI can be configured to export traces to PhariaStudio, where you can visualise them.

Namespaces

PhariaEngine uses namespaces to group Skills. Namespaces are configured by the operator of PhariaEngine, who needs to specify the following:

  • An Open Container Initiative (OCI) registry from which Skills can be loaded. (Although Skills are technically not containers, we still publish them as OCI images to a registry.)

  • A namespace configuration. This is a toml file which is typically checked into a git repository.

Namespaces allow teams to deploy their Skills in a self-service way. Permissions for the registry and the namespace configuration can be configured in such a way that only team members can deploy Skills to the namespace.

To make a Skill available in PhariaEngine, it needs to meet two criteria:

  • the Skill must be deployed as a component to an OCI registry

  • the Skill must be configured in the namespace configuration

For reference, you can view pharia-kernel.namespaces in the values.yaml of your deployment. For the deployment, configure the pharia-skill CLI tool with environment variables to point to the correct registry for the namespace you want to deploy to.