@msm-core/pipeline

The product is the standard and the pipeline. The models inside are interchangeable commodities.

@msm-core/pipeline is a pluggable AI pipeline that routes user messages through three layers — translate → brain → validate — returning a typed trace with every layer's output, confidence, and latency.

The brain is a single-pass agent that classifies, reasons, and decides in one step. The pipeline never runs tools — it tells the agent what to do, and the agent loop handles execution.

User Message
     ↓
[1] Translation       — normalize language (Gulf Arabic → English bilingual)
     ↓
[2] Brain             — classify + reason + decide: respond / use_tool / escalate / clarify / delegate
     ↓
  action = "use_tool"?
  → return early (action_required: true)
  → agent executes tool and calls pipeline again with tool_results[]

  action = "respond" / "escalate" / "clarify" / "delegate"
     ↓
[3] Validation        — policy checks, safety, quality gate
     ↓
Outbound Translation  — translate response back to user's language (if needed)
     ↓
Final Output

Install

npm install @msm-core/pipeline

Quick Start

import { createPipeline } from "@msm-core/pipeline";

const pipeline = await createPipeline("./examples/food-commerce-gulf-dummy.yaml");

const trace = await pipeline.run({ raw: "ابي اطلب برغر وبيبسي", modality: "text" });

console.log(trace.payload.brain?.action);         // "respond"
console.log(trace.payload.final_output?.text);    // Arabic response
console.log(trace.entries.map(e => e.name));      // ["translation","brain","validation","outbound_translation"]

Three-Layer Architecture

| Layer | Role | Provider | |---|---|---| | translation | Detect language, normalize to English for downstream processing | dummy, ollama, or custom | | brain | Single-pass classify + reason + decide (@msm-core/brain) | dummy (throws), ollama, or custom | | validation | Policy/safety gate — pass, flag, or block the response | dummy, ollama, or custom |

The brain wraps @msm-core/brain (createBrain()), which is backed by @msm-core/nemo HDC classification + an Ollama LLM for reasoning.

Brain Actions

import { STANDARD_ACTIONS } from "@msm-core/pipeline";

STANDARD_ACTIONS.USE_TOOL   // "use_tool"  — return early, agent runs the tool
STANDARD_ACTIONS.RESPOND    // "respond"   — generate + validate response
STANDARD_ACTIONS.CLARIFY    // "clarify"   — ask user for more info
STANDARD_ACTIONS.ESCALATE   // "escalate"  — hand off to human agent
STANDARD_ACTIONS.DELEGATE   // "delegate"  — pass to another agent

Only "use_tool" has special pipeline behavior — it short-circuits validation and returns action_required: true. Every other action is terminal: the pipeline proceeds to validation and returns a final response.

Custom actions are supported — declare any string value; the pipeline treats everything that is not "use_tool" as terminal.

Agent Loop Pattern

The pipeline is a single-pass brain. Tool execution happens outside in the agent loop:

import {
  createPipeline,
  STANDARD_ACTIONS,
  type MSMInput,
} from "@msm-core/pipeline";

const pipeline = await createPipeline("./examples/food-commerce-gulf-dummy.yaml");

let input: MSMInput = { raw: userMessage, modality: "text" };

while (true) {
  const trace = await pipeline.run(input);
  const brain = trace.payload.brain;

  if (brain?.action === STANDARD_ACTIONS.USE_TOOL) {
    const result = await myToolRunner(brain.tool_name!, brain.tool_params!);
    input = {
      raw: userMessage,
      modality: "text",
      tool_results: [{ tool_name: brain.tool_name!, status: "ok", output: result }],
    };
    continue;
  }

  return trace.payload.final_output?.text;
}

Manifests

A manifest is a YAML file that declares the full pipeline for a domain:

# examples/food-commerce-gulf-dummy.yaml
msm_version: "1.0"
manifest_id: "food-commerce-gulf-dummy-v1"
domain: "food-commerce"
region: "gulf-arabic"
created: "2026-04-12"

layers:
  translation:
    provider: dummy
    model: "dummy-translation-v1"
    version: "1.0.0"
    fine_tuned: false
    mode: "translated"

  brain:
    provider: ollama
    model: "qwen2.5:3b"
    version: "1.0.0"
    fine_tuned: false

  validation:
    provider: dummy
    model: "dummy-validation-v1"
    version: "1.0.0"
    fine_tuned: false

hooks:
  content_safety:
    provider: content-safety-provider
    point: "before:validation"
    fine_tuned: false

Load any manifest:

const pipeline = await createPipeline("./examples/healthcare-triage.yaml");

Available examples:

examples/
├── food-commerce-gulf-dummy.yaml    ← Gulf food ordering, offline (runs now)
├── food-commerce-gulf-ollama.yaml   ← Gulf food ordering, real Ollama (runs now)
├── healthcare-triage.yaml           ← Medical triage
├── sports-booking.yaml              ← Sports facility booking
├── legal-compliance.yaml            ← Legal/contract review
├── banking-support.yaml             ← Gulf banking support
├── education-tutoring.yaml          ← AI tutoring
├── ecommerce-retail.yaml            ← Gulf e-commerce
└── kader-booking-ollama.yaml        ← Kader booking system

Extensibility

Register a custom provider

import { LayerRegistry, createPipeline } from "@msm-core/pipeline";

const registry = new LayerRegistry();

registry.register("brain", "my-provider", (config) => ({
  name: "brain",
  async process(payload) {
    return {
      model_id: config.model,
      model_ver: config.version ?? "1.0",
      latency_ms: 0,
      confidence: 0.95,
      status: "ok",
      action: "respond",
      response_text: "Hello from my brain",
    };
  },
}));

const pipeline = await createPipeline(manifest, { registry });

Swap a layer at runtime

pipeline.swap("validation", myStrictValidationLayer);

Add hooks

pipeline.addHook({
  name: "audit-logger",
  point: "after:brain",
  async process(payload) {
    await auditLog(payload.brain);
    return { model_id: "audit", model_ver: "1.0", latency_ms: 0, confidence: 1, status: "ok", data: {} };
  },
});

Hook points: before:translation, after:translation, before:brain, after:brain, before:validation, after:validation.

Freeze the pipeline

pipeline.freeze(); // subsequent swap() or addHook() calls throw

Running Locally

git clone https://github.com/msm-core/pipeline.git
cd pipeline
pnpm install

pnpm demo           # dummy models, zero setup
pnpm demo:ollama    # real Ollama (requires: ollama pull qwen2.5:3b)

pnpm server         # HTTP server on http://localhost:3000/api/run
npm test
npm run build

Docker

docker compose up

HTTP API

curl -X POST http://localhost:3000/api/run \
  -H "Content-Type: application/json" \
  -d '{"text": "ابي اطلب برغر وبيبسي"}'

Trace Output

{
  trace_id: "uuid",
  session_id: "uuid",
  payload: {
    input:        { raw, modality, tools?, tool_results? },
    translation?: TranslationOutput,
    brain?:       BrainOutput,      // action, response_text, tool_name, tool_params, reasoning
    validation?:  ValidationOutput, // passed, quality_score, policy_violations, action
    final_output: { text, trace_id, action_required }
  },
  entries: LayerTraceEntry[],       // one per layer/hook: model_id, latency_ms, status
  pipeline_status: "ok" | "failed"
}

Why Not LangChain / LlamaIndex?

| | LangChain / LlamaIndex | @msm-core/pipeline | |--|--|--| | Core idea | Orchestrate one LLM | Replace LLM with specialized layers | | Model coupling | Tied to provider APIs | Any model behind a standard contract | | Swap a model | Change code + prompts | Change one line in manifest YAML | | Language support | Depends on the LLM | Dedicated Translation Layer | | Auditability | Prompt chains | Per-layer trace with confidence scores | | Cost | LLM pricing | 10–20x cheaper (small specialized models) |

Related Packages

| Package | Role | |---|---| | @msm-core/brain | Brain layer — HDC classify + LLM reason | | @msm-core/nemo | HDC text classification (English + Arabic) | | @msm-core/cst | CST tokenizer — vocabulary and morphology |

License

MIT