---
title: "Pipeline architecture"
manual: "AI Assistant"
version: "main"
source: "Developers/Architecture/PipelineArchitecture.rst"
rendered: "2026-10-03T14:54:45+00:00"
---

# Pipeline architecture {#pipeline-architecture}

The pipeline is the central runtime abstraction of the assistant. It executes a
sequence of configured steps against a request context.

## Core classes {#core-classes}

-   **`Madj2k\AiCore\Assistant\Pipeline\Pipeline`**

    Executes configured steps.

-   **`Madj2k\AiCore\Assistant\Pipeline\Processor\ProcessorInterface`**

    Common interface for all pipeline processors.

-   **`Madj2k\AiCore\Assistant\Pipeline\Registry\ProcessorRegistry`**

    Resolves processors by identifier.

-   **`Madj2k\AiCore\Assistant\Prompt\PromptBuilder`**

    Builds LLM messages from profile prompts, step prompts, history and context.

-   **`Madj2k\AiCore\Assistant\Context\Context`**

    Shared state object for one assistant request.

## Processor responsibilities {#processor-responsibilities}

Processors must stay generic. Project-specific instructions belong into database
records. A processor should read step configuration and context, execute its
technical task and write results back into context.

## LLM processors {#llm-processors}

LLM-based processors should call the AI provider through the configured
`AiConnection` and `AiConnectorRegistry`. They should not instantiate provider
clients directly.

## Streaming execution {#streaming-execution}

`Madj2k\AiCore\Assistant\Pipeline\Pipeline` can run in synchronous mode
through `run()` or in streaming mode through `runStream()`. In streaming
mode the pipeline forwards streamed chunks to the callback passed by the caller.

A processor can participate in streaming by implementing
`Madj2k\AiCore\Assistant\Pipeline\Processor\ProcessorStreamingInterface`
in addition to `ProcessorInterface`. If a streaming callback is available and
the processor implements that interface, the pipeline calls `processStream()`.
Otherwise it falls back to the regular `process()` method.

## Prompt context builders {#prompt-context-builders}

Prompt context is assembled through
`Madj2k\AiCore\Assistant\Prompt\Context\Registry\ContextBuilderRegistry`.
The registry collects all tagged context builders that support the current
processor type and returns sorted `PromptSection` objects. This keeps prompt
context construction extensible without hard-coding every section in one
processor.

## Pipeline tracing {#pipeline-tracing}

Processors can emit trace events for started steps, finished steps, LLM requests,
LLM responses, retrieval results and errors. Traces are essential for debugging
pipeline behaviour.