Merge branch '27-osl-ai-documentation-additions' into 'develop'

# OSL AI

<figure>

  <img src="../images/ai/osl_ai.png" alt="OSL AI architecture">

  <figcaption>Figure 1. OSL AI architecture</figcaption>

</figure>

OpenSlice introduces a dedicated AI layer that brings conversational and agentic capabilities on top of the existing NaaS and Service Orchestration functionalities. The goal is to let stakeholders, like operators, developers, and end customers interact with OpenSlice through natural language, and to let OpenSlice itself use AI agents to support orchestration decisions.

The OSL AI layer is built around four concepts:

- **MCP Server**: exposes OpenSlice functionalities as tools that any MCP-compatible AI assistant can call

- **MCP Backend**: OpenSlice's own native agent, integrating local LLMs and the MCP Server, and offering agentic capabilities to the rest of the platform

- **OSL Assistant**: the AI assistant embedded in the OpenSlice UI, giving users a chat-based way to interact with the platform

- **Agentic Orchestration**: the ability for the Service Orchestrator to delegate complex orchestration decisions to cognitive agents *(Beta)*

Each of these is described below.

## MCP Server

The OpenSlice MCP Server implements a [Model Context Protocol](https://modelcontextprotocol.io/) endpoint on top of OpenSlice's existing TMF-based service and product management stack. It is a standalone component that translates MCP tool invocations into calls against OpenSlice's internal catalog, ordering, and inventory subsystems, and returns the results in the structured format MCP clients expect.

Functionally, the exposed tool set is organized around six operational domains:

- **Service catalog management**: listing published service catalogs and their categories, resolving service specification references within a category, retrieving full service and resource specification details, and searching across published service specifications

- **Service order management**: submitting a service order against a given specification, with optional characteristics, and querying the resulting order's status and details

- **Service instance management**: retrieving a service instance's state, characteristics, and supporting services/resources, and updating a running instance's characteristics

- **Product catalog management**: the product-side equivalent of catalog management: listing published product catalogs and categories, resolving product offerings within a category, and retrieving full offering or product specification details, including search

- **Product order management**: submitting an order covering one or more product offerings, each with its own characteristics, and querying the resulting order's status and details

- **Resource management**:  retrieving a resource instance's status and characteristics

The interface is protocol-based rather than client-specific, sp any MCP-compatible client can consume it. The same endpoint serves any conforming client without additional integration work on OpenSlice's side.

## MCP Backend

The OpenSlice MCP Backend is OSL's native agent, keeping AI usage frugal and sovereign by using locally deployed, open-source models over external, cloud-hosted ones.

The MCP Backend is a **generic agent**: it is not bound to any single frontend or consumer. It is exposed as a REST interface, so any client capable of issuing HTTP requests can integrate against it, like external chatbots or OSL AI Assistant.

Architecturally, the MCP Backend combines three capabilities:

* **LLM inference**: via [Ollama](https://ollama.com/), giving it access to a selection of locally deployed, open-source models

* **Tool-calling against the OpenSlice MCP Server**: the MCP Backend operates as an MCP client itself, invoking the catalog, ordering, instance, and resource tools the MCP Server exposes, rather than reasoning in isolation

* **Session-level memory**: conversational state is retained across a session, so a caller does not need to resupply context already established earlier in the interaction

In addition to its REST interface, the MCP Backend connects to the OpenSlice Service Bus, which extends its agentic capabilities to other OpenSlice components rather than restricting them to HTTP-based callers. 

<figure>

  <img src="../images/ai/osl_ai_mcpbe.png" alt="MCP Server and MCP Backend architecture">

  <figcaption>Figure 2. MCP Server and MCP Backend architecture</figcaption>

</figure>

## OSL Assistant

The OSL Assistant is the AI assistant natively embedded in the OpenSlice UI, giving users a chat based entry point into the platform alongside the existing portal views.

The OSL Assistant does not integrate with LLMs or OpenSlice tools directly. It is a client of the MCP Backend, which supplies both:

* **LLM inference**: with priority given to locally deployed models, for sovereignty and efficiency

* **Tool access via the OpenSlice MCP Server**: the catalog, ordering, instance, and resource tools the MCP Server exposes

Authentication is end to end rather than assistant local: the user authenticates through the same login as the rest of the OpenSlice UI, and that authentication context is propagated from the UI, through the MCP Backend, to the MCP Server. As a result, the assistant never operates with its own, separate identity; every action it takes on the user's behalf is scoped to that user's existing permissions.

The OSL Assistant also keeps session level memory, retaining conversational context for the duration of a session so the user does not need to restate information already given earlier in the conversation.

<figure>

  <img src="../images/ai/osl_ai_assistant.png" alt="OSL Assistant Question">

  <figcaption>Figure 3. OSL Assistant question</figcaption>

</figure>

<figure>

  <img src="../images/ai/osl_ai_assistant_answer.png" alt="OSL Assistant Answer">

  <figcaption>Figure 4. OSL Assistant answer</figcaption>

</figure>

## Agentic Orchestration

> **Beta feature**

    Agentic Orchestration is an early, beta capability. It is functional but has not yet undergone the same level of testing and hardening as the rest of the OSL AI layer, and its behavior may still change in upcoming releases.

Orchestration decisions within OpenSlice are made in one of three ways, corresponding to increasing levels of autonomy as defined by the TM Forum Levels of Autonomy model:

* **Predefined, repetitive orchestration flows**: modeled as business process diagrams (L1, Assisted Operation)

* **User-defined, rule-based orchestration flows**: no-code, injectable directly into the orchestration flow (L2, Partial Autonomous)

* **Agent-powered orchestration**: driven by cognitive agents with tool-calling capabilities (L3 to L4, Conditional to Highly Autonomous)

Agentic Orchestration is what makes the third option available to the Service Orchestrator: rather than always following a fixed process or a static rule set, individual orchestration steps can be delegated to an agent capable of reasoning over the available context and acting on it.

### Delivery mechanism

Agents connect to the OpenSlice Service Bus, each advertising a name and listening on its own queue, and integrate an LLM with, optionally, tool-calling capabilities via MCP Servers. The MCP Backend is itself a native OpenSlice agent.

The OpenSlice Orchestrator (OSOM) can call any of these agents throughout the orchestration lifecycle, communicating with them over the Service Bus whenever a step calls for an agent-driven decision rather than a predefined or rule-based one. This allows a single workflow to combine orchestration styles: routine steps continue through predefined or no-code flows, while steps that require contextual judgement are handed off to an agent, local or remote, OSL-native or third-party, connected to the Service Bus.

<figure>

  <img src="../images/ai/osl_ai_agentic_orchestration.png" alt="Agentic Orchestration concept">

  <figcaption>Figure 5. Agentic Orchestration concept</figcaption>

</figure>

<figure>

  <img src="../images/ai/osl_ai_agentic_orch_concept.png" alt="Agentic Orchestration Architecture">

  <figcaption>Figure 6. Agentic Orchestration architecture</figcaption>

</figure>

* A Custom Resource (CR) to TMF bridge (CRIDGE) microservice which interfaces with Kubernetes

* A Metrics Retrieval Component (METRICO) which interfaces with external monitoring tools, retrieving and injecting desired metrics into OpenSlice orchestration pipeline

* A pool of several controllers (e.g., Sylva, Camara, 3GPP, gitops, etc.), offered as optionally enabled addons

* An AI layer, integrating the built-in MCP Server and open-source LLMs, which interfaces and interworks with the rest components

* An AI layer consisting of two microservices: an MCP Server, which exposes OpenSlice's service/product catalog browsing, ordering, and instance management capabilities as standardized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools accessible by any MCP-compatible AI client and an MCP Backend, a generic AI agent that connects an open-source LLM to those tools to autonomously fulfill user requests and power the chat-based AI assistant embedded in the UI

* A Message Bus used by all microservices to exchange messages either via message Queues or via publish/subscribe Topics

* An Authentication Server implementing Oauth2 authentication scheme

* A microservice that is capable to interface with an issue management system (e.g. it raises an issue to all related stakeholders - CSPs, NOPs, CSCs - that a new Service Order is requested)