API Reference

Packages

• orama.trirematics.io/v1

orama.trirematics.io/v1

Package v1 contains API Schema definitions for the orama v1 API group

Resource Types

• AIFabric
• AIFabricList
• CompositionModel
• CompositionModelList
• Element
• ElementList

AIFabric

AIFabric is the Schema for the AIFabric API

Appears in:

• AIFabricList

Field	Description	Default	Validation
apiVersion string	orama.trirematics.io/v1
kind string	AIFabric
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: {} Optional: {}
spec AIFabricSpec	Spec is the desired state of the AIFabric
status AIFabricStatus	Status is the observed state of the AIFabric

AIFabricList

AIFabricList contains a list of AIFabric

Field	Description	Default	Validation
apiVersion string	orama.trirematics.io/v1
kind string	AIFabricList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: {} Optional: {}
items AIFabric array	Items is the list of AIFabric objects.

AIFabricSpec

AIFabricSpec defines the desired state of AIFabric.

Appears in:

• AIFabric

Field	Description	Default	Validation
mcp MCPServer array	The MCP Servers deployed by the AIFabric, exposing tools for the Agents in the AIFabric.		MinItems: 1 Optional: {}
llms LLM array	The LLMs used by the agents of the AIFabric.		MinItems: 1 Optional: {}
agents Agent array	The agents deployed by the AIFabric.		MinItems: 1 Optional: {}
imagePullSecrets LocalObjectReference array	ImagePullSecrets is a list of references to secrets for pulling images for the AIFabric components.		MinItems: 1 Optional: {}
telemetry Telemetry	Telemetry defines how the internal agents of the AIFabric export their OpenTelemetry traces. Unset disables telemetry.		Optional: {}

AIFabricStatus

AIFabricStatus is the current observed state of the AIFabric

Appears in:

• AIFabric

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the AIFabric's current state. Known types are: "Available", "Degraded", "Progressing".		Optional: {}
elements string array	List of Elements associated to the AIFabric.		Optional: {}
ready boolean	Readiness of the AIFabric, equals to a logical AND between the readiness of the Elements. Unset until the first reconciliation writes it.		Optional: {}

Agent

Agent defines an agent in the AIFabric.

Appears in:

• AIFabricSpec

Field	Description	Default	Validation
name NameTag	The name of the agent		MaxLength: 63 MinLength: 1 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Required: {}
type ApplicationType	The type of the agent (internal or external).	internal	Enum: [external internal] Required: {}
external ExternalAgentDesc	External holds configuration for external agents.		Optional: {}
internal InternalAgentDesc	Internal holds configuration for internal agents.		Optional: {}
chattable boolean	Chattable tells whether the agent is intended to be used directly by a human. Defaults to: - nil (treated as false) for "sink" agents. - true for all other agent roles and external agents.		Optional: {}

AgentRole

Underlying type: string

AgentRole defines the role of an internal agent in a multi-agent system.

Validation:

• Enum: [none sink supervisor worker]

Appears in:

• InternalAgentDesc

Field	Description
sink	The agent is considered a dependency of all the "worker" agents
supervisor	The agent has all the "worker" agents as dependencies.
worker	The agent is considered a dependency of any "supervisor" agent and has all the "sink" agents as dependencies.
none	The agent does not have any implicit dependency.

ApplicationType

Underlying type: string

Validation:

• Enum: [external internal]

Appears in:

• Agent
• MCPServer

Field	Description
external	The application is deployed outside of the cluster
internal	The application is deployed inside the cluster

CompositionModel

CompositionModel is the Schema for the compositionmodels API

Appears in:

• CompositionModelList

Field	Description	Default	Validation
apiVersion string	orama.trirematics.io/v1
kind string	CompositionModel
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.		Optional: {}
deploymentModes object (keys:NameTag, values:Model)
spec CompositionModelSpec	Spec of the CompositionModel		Required: {}
status CompositionModelStatus	NOT USED

CompositionModelList

CompositionModelList contains a list of CompositionModel

Field	Description	Default	Validation
apiVersion string	orama.trirematics.io/v1
kind string	CompositionModelList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items CompositionModel array

CompositionModelSpec

CompositionModelSpec defines the desired state of CompositionModel

Appears in:

• CompositionModel

Field	Description	Default	Validation
provider string			MaxLength: 31 Required: {}
version string			Required: {}

CompositionModelStatus

CompositionModelStatus defines the observed state of CompositionModel

Appears in:

• CompositionModel

Element

Element is the Schema for the elements API

Appears in:

• ElementList

Field	Description	Default	Validation
apiVersion string	orama.trirematics.io/v1
kind string	Element
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ObjectMeta	Refer to Kubernetes API documentation for fields of metadata.
spec ElementSpec	The desired state of the Element
status ElementStatus	The observed state of the Element

ElementList

ElementList contains a list of Element

Field	Description	Default	Validation
apiVersion string	orama.trirematics.io/v1
kind string	ElementList
kind string	Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds		Optional: {}
apiVersion string	APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources		Optional: {}
metadata ListMeta	Refer to Kubernetes API documentation for fields of metadata.
items Element array

ElementSpec

ElementSpec defines the desired state of Element.

Appears in:

• Element

Field	Description	Default	Validation
model Model	The model used by the Element.		Required: {}
elementConfig string	The configuration file for the Element		Optional: {}
imagePullSecrets LocalObjectReference array	List of references to secrets used to pull images for the Element.		MinItems: 1 Optional: {}
shadowService string	The name to assign to the service associated to the Element's deployment.		Required: {}
env EnvVar array	List of environment variables for the Element's deployment.		Optional: {}
dependencies string array	List of names of the Elements on which this Element depends.		Optional: {}

ElementStatus

ElementStatus defines the observed state of Element.

Appears in:

• Element

Field	Description	Default	Validation
conditions Condition array	Conditions represent the latest available observations of the Element's current state. Known types are: "Available", "Degraded", "Progressing".		Optional: {}
ready boolean	The readiness of the Element's deployment. Unset until the first reconciliation writes it.		Optional: {}

ExternalAgentDesc

Underlying type: ExternalAppDesc

ExternalAgentDesc defines an external agent

Appears in:

• Agent

Field	Description	Default	Validation
baseUrl string	The url where the service is reachable		Required: {}
authHeadersSecretRef LocalObjectReference	The HTTP headers used for authenticating requests (optional). Each key represents the header name and its corresponding value.		Optional: {}
timeoutSeconds integer	The timeout for requests to the external service		Optional: {}

ExternalAppDesc

ExternalAppDesc defines an external application

Appears in:

• ExternalAgentDesc
• ExternalMCPDesc

Field	Description	Default	Validation
baseUrl string	The url where the service is reachable		Required: {}
authHeadersSecretRef LocalObjectReference	The HTTP headers used for authenticating requests (optional). Each key represents the header name and its corresponding value.		Optional: {}
timeoutSeconds integer	The timeout for requests to the external service		Optional: {}

ExternalEndpoint

ExternalEndpoint defines an endpoint in terms of URL and auth headers

Appears in:

• ExternalAppDesc
• LLM

Field	Description	Default	Validation
baseUrl string	The url where the service is reachable		Required: {}
authHeadersSecretRef LocalObjectReference	The HTTP headers used for authenticating requests (optional). Each key represents the header name and its corresponding value.		Optional: {}

ExternalMCPDesc

Underlying type: ExternalAppDesc

ExternalMCPDesc defines an external MCP server

Appears in:

• MCPServer

Field	Description	Default	Validation
baseUrl string	The url where the service is reachable		Required: {}
authHeadersSecretRef LocalObjectReference	The HTTP headers used for authenticating requests (optional). Each key represents the header name and its corresponding value.		Optional: {}
timeoutSeconds integer	The timeout for requests to the external service		Optional: {}

FullModelName

Underlying type: string

FullModelName is an aliased string type for the general format of particular deployment-mode in the context of a composition-model, separated by a slash. Each of the parts is a NameTag and the length requirements match the one of the FullNameTag. The first part is the composition-model and the second part is the deployment-mode much like a directory structure.

Validation:

• MaxLength: 127
• MinLength: 3
• Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?\/[a-z0-9]([-a-z0-9]*[a-z0-9])?$)

Appears in:

• InternalAgentDesc
• InternalAppDesc

InternalAgentDesc

InternalAgentDesc defines an internal agent

Appears in:

• Agent

Field	Description	Default	Validation
model FullModelName	Model is the CompositionModel and deployment mode of the application.		MaxLength: 127 MinLength: 3 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?\/[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Required: {}
annotations object (keys:string, values:string)	Annotations to add to the Element created for the application. Takes precedence over other annotations with the same key which are defined by the model. Annotations matching "env.orama.t9s.io/VAR_NAME" are parsed as Element environment variables.		Optional: {}
labels object (keys:string, values:string)	Labels to add to the Element created for the application.		Optional: {}
llm NameTag	LLM is the name of the LLM the agent must use.		MaxLength: 63 MinLength: 1 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Required: {}
role AgentRole	Role is the role of the agent in a multi-agent system. The role determines the following implicit dependencies between agents: - "sink": the agent is considered a dependency of all the "worker" agents. - "supervisor": the agent has all the "worker" agents as dependencies. - "worker": the agent is considered a dependency of any "supervisor" agent and has all the "sink" agents as dependencies. - "none": the agent does not have any implicit dependency. Role-based dependencies can only be extended with additional explicit dependencies specified in the dedicated field. Role-based dependencies cannot be overridden or removed.	worker	Enum: [none sink supervisor worker]
mcpServers NameTag array	MCPServers is a list of MCP Servers the agent can use.		MaxLength: 63 MinLength: 1 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Optional: {}
dependencies NameTag array	Dependencies is a list of Agent names to which this Agent can send requests. The name must be defined either in the list of agents or in the list of external applications with kind "agent".		MaxLength: 63 MinLength: 1 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Optional: {}

InternalAppDesc

InternalAppDesc defines an internal application

Appears in:

• InternalAgentDesc
• InternalMCPDesc

Field	Description	Default	Validation
model FullModelName	Model is the CompositionModel and deployment mode of the application.		MaxLength: 127 MinLength: 3 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?\/[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Required: {}
annotations object (keys:string, values:string)	Annotations to add to the Element created for the application. Takes precedence over other annotations with the same key which are defined by the model. Annotations matching "env.orama.t9s.io/VAR_NAME" are parsed as Element environment variables.		Optional: {}
labels object (keys:string, values:string)	Labels to add to the Element created for the application.		Optional: {}

InternalMCPDesc

Underlying type: InternalAppDesc

InternalMCPDesc defines an internal MCP server

Appears in:

• MCPServer

Field	Description	Default	Validation
model FullModelName	Model is the CompositionModel and deployment mode of the application.		MaxLength: 127 MinLength: 3 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?\/[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Required: {}
annotations object (keys:string, values:string)	Annotations to add to the Element created for the application. Takes precedence over other annotations with the same key which are defined by the model. Annotations matching "env.orama.t9s.io/VAR_NAME" are parsed as Element environment variables.		Optional: {}
labels object (keys:string, values:string)	Labels to add to the Element created for the application.		Optional: {}

LLM

LLM defines how to reach a large language model (LLM) service.

Appears in:

• AIFabricSpec

Field	Description	Default	Validation
name NameTag	Name is the name of the LLM service.		MaxLength: 63 MinLength: 1 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Required: {}
provider ModelProviderName	ModelProvider is the provider of the language model.		Enum: [anthropic deepseek nvidia ollama openai] Required: {}
model string	ModelName is the name of the language model to use.		Required: {}
apiKeySecretRef SecretKeySelector	ApiKeySecretRef is a reference to a Secret containing the API key. The Secret should already exist in the target namespace.		Optional: {}
endpoint ExternalEndpoint	The endpoint where the LLM is reachable		Optional: {}
reasoningEffort string	ReasoningEffort is how much the model reasons before answering, e.g. "low". The accepted values depend on the provider.		Optional: {}
serviceTier string	ServiceTier is the processing tier of the requests, e.g. "flex". The accepted values depend on the provider.		Optional: {}

MCPServer

MCPServer defines an MCP server exposing tools for the agents in the AIFabric.

Appears in:

• AIFabricSpec

Field	Description	Default	Validation
name NameTag	The name of the MCP server.		MaxLength: 63 MinLength: 1 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Required: {}
type ApplicationType	The type of the MCP server (internal or external).	internal	Enum: [external internal] Required: {}
external ExternalMCPDesc	External holds configuration for external MCP servers.		Optional: {}
internal InternalMCPDesc	Internal holds configuration for internal MCP servers.		Optional: {}

Model

Model defines a deployment mode for the CompositionModel

Appears in:

• CompositionModel
• ElementSpec

Field	Description	Default	Validation
name NameTag	The name of the model.		MaxLength: 63 MinLength: 1 Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$) Required: {}
vendor string	The vendor of the model, preferably defined with three alphanumeric lower case characters.		Required: {}
kind string	The kind of the model.		Required: {}
imageTag string	The image tag for the deployment's container of an element with this model.		Required: {}
args string array	Args to the container.		Optional: {}
command string array	Entrypoint array. The container ENTRYPOINT is used when this is not specified.		Optional: {}
readinessProbe Probe	Readiness probe to consider the Element available.		Optional: {}
resources ResourceRequirements	Resource requirements for the container of the workload		Optional: {}
rules PolicyRule array	The rbac rules for an element with this model		Optional: {}
clusterRules PolicyRule array	The rbac rules granted cluster-wide to an element with this model		Optional: {}
env EnvVar array	The environment for the deployment of an element with this model		Optional: {}

ModelProviderName

Underlying type: string

Validation:

• Enum: [anthropic deepseek nvidia ollama openai]

Appears in:

• LLM

Field	Description
anthropic
deepseek
nvidia
ollama
openai

NameTag

Underlying type: string

NameTag is an aliased string type for the general format of names used all over Athena repository with a limited character-set and length.

Validation:

• MaxLength: 63
• MinLength: 1
• Pattern: (^[a-z0-9]([-a-z0-9]*[a-z0-9])?$)

Appears in:

• Agent
• CompositionModel
• InternalAgentDesc
• LLM
• MCPServer
• Model

Telemetry

Telemetry defines how the internal agents of the AIFabric export their OpenTelemetry traces, over OTLP/HTTP to a collector. Leaving it unset disables telemetry entirely.

Appears in:

• AIFabricSpec

Field	Description	Default	Validation
endpoint string	The base URL of the OTLP/HTTP collector, e.g. "http://phoenix:6006". The "/v1/traces" path is appended by the agent runtime, so it must not be part of this value.		Required: {}
projectName string	The project the traces are filed under in the telemetry backend (the "openinference.project.name" resource attribute). Every agent of the AIFabric shares it: a distributed trace is reconstructed within a single project, so agents exporting to different projects would fragment the traces of the same conversation. Defaults to the name of the AIFabric.		Optional: {}