brainforge-inference-utils 0.0.1a1__tar.gz

brainforge_inference_utils-0.0.1a1/LICENSE.md

@@ -0,0 +1,21 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Development System
+# All trademark and other rights reserved by their respective owners
+# Copyright 2008-2026 Neongecko.com Inc.
+# BSD-3 License
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+following conditions are met:
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products
+derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

brainforge_inference_utils-0.0.1a1/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: brainforge-inference-utils
+Version: 0.0.1a1
+Summary: Pluggable request/response pipelines for BrainForge LLM inference
+Home-page: https://github.com/NeonGeckoCom/brainforge-inference-utils
+Author: NeonGecko
+Author-email: developers@neon.ai
+License: AGPL-3.0-only
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pydantic~=2.0
+Requires-Dist: neon-data-models>=0.0.3a8,~=0.0.2
+Requires-Dist: fastmcp~=2.3
+Requires-Dist: requests
+Provides-Extra: test
+Requires-Dist: pytest~=8.0; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+# BrainForge Inference Utilities
+
+Pluggable pipelines for shaping BrainForge LLM requests and responses.
+
+This package defines request/response orchestration that attaches to an
+existing inference workflow. Concrete behavior (ambient context, RAG/MCP
+injection, request history validation, citations, response sanitizing,
+safety guardrails, ...) can be implemented as **steps** that plug into one of
+two pipelines:
+
+- **Request pipeline** — runs before generation and shapes the request:
+  injecting informational context, RAG retrieval for host-selected
+  providers, validating and truncating history, etc.
+- **Response pipeline** — runs after generation and shapes the response:
+  citation rewrite, sanitization, guardrails, etc.
+
+Primary generation stays with the host, between the two pipelines. The host
+keeps the `UserTransaction` from the request pipeline until the response is
+ready. A pipeline step may call an inference endpoint to modify the transaction
+(for example citation rewrite) without the host owning those requests.
+
+Both pipelines operate on a `UserTransaction`, which carries the request,
+response, and two per-side context dicts (`request_step_context` and
+`response_step_context`). Requests and responses use the existing
+`neon-data-models` models (`LLMRequest` / `LLMResponse`).
+
+## Concepts
+
+| Concept | Purpose |
+| --- | --- |
+| `UserTransaction` | The request/response pair plus `request_step_context` / `response_step_context` dicts. The host holds this object across generation. |
+| `BrainForgeClient` | Builds pipelines from config and exposes `run_request_pipeline` / `run_response_pipeline` / `supported_request_context`. |
+| `RequestStep` | Shapes `transaction.request` before generation. Declares supported `request_context` keys/values. |
+| `ResponseStep` | Annotates/rewrites `transaction.response` after generation. |
+| `RequestContextOption` | One `request_context` key a step reads, with optional allowed values for hosts to present. |
+| `RequestPipeline` / `ResponsePipeline` | Run an ordered list of steps over a transaction. |
+| `PipelineConfig` / `StepConfig` | Declarative, ordered step lists (see below). |
+
+## Usage sketch
+
+```python
+client = BrainForgeClient(pipeline_config)
+
+options = await client.supported_request_context()
+# e.g. options["rag_providers"].values, options["conversational"].values
+
+transaction = await client.run_request_pipeline(llm_request)
+# host performs generation using transaction.request
+transaction = await client.run_response_pipeline(transaction, llm_response)
+```
+
+Request steps write `transaction.request_step_context[step.id]`. Response steps write
+`transaction.response_step_context[step.id]` and may *read* the request-step context. Those
+namespaces are independent, so the same step id may exist on both sides
+without colliding. Context is available across generation only because the
+same `UserTransaction` is passed back in; this package does not store it
+between calls.
+
+## Design notes
+
+- **Steps are independently defensive.** There is no dependency graph between
+  steps. A step that needs something it does not find (e.g. a citation step with
+  no retrieved sources) reports itself inapplicable via `applicable()` and is
+  skipped with a logged reason, rather than failing the pipeline.
+- **Ordering is explicit.** Step order is exactly the order declared in
+  configuration; the pipeline does not reorder.
+- **Steps may be repeated.** The same step id may appear more than once in a
+  pipeline, including with different `config`. Each appearance is a separate
+  instance and runs in declared order. The pipeline does not merge or
+  de-duplicate entries.
+- **Steps own their context.** Each side has its own dict keyed by step id.
+  A repeated step on the *same* side shares that key; a step id on the request
+  side does not clash with the same id on the response side. Each step is
+  responsible for how it stores and reads its own data across one or more
+  calls (for example appending to a list instead of overwriting it).
+  Response steps that consume request-step data should read
+  `transaction.request_step_context` and report inapplicable when required 
+  context is absent.
+- **Format contracts live together.** Steps that share a parse format
+  (e.g. a citation formatter and the sanitizer that strips it) belong in the
+  same module and should derive from a shared constant so they cannot drift.
+
+## Step plugins
+
+Installed packages advertise steps with setuptools entry points. Request and
+response steps use different groups:
+
+| Pipeline | Entry point group |
+| --- | --- |
+| Request | `brainforge.inference.request_steps` |
+| Response | `brainforge.inference.response_steps` |
+
+Both groups use the step id `author.step_name`:
+
+- `author` is the plugin developer's slug (`acme`, `brainforge`).
+- `step_name` names that one step (`guardrails`, `rag`).
+
+Each part may contain letters, digits, hyphens, and underscores. The class
+`id`, the config `id`, and the context-dict key are that same string.
+
+The same `author.step_name` may be registered once in each group. Each
+pipeline reads only its own group, so the request class and the response class
+stay distinct. Two packages registering the same name in one group is an
+error.
+
+```python
+entry_points={
+    "brainforge.inference.request_steps": [
+        "acme.guardrails=acme_guardrails:GuardrailRequestStep",
+    ],
+    "brainforge.inference.response_steps": [
+        "acme.guardrails=acme_guardrails:GuardrailResponseStep",
+    ],
+}
+```
+
+```yaml
+pipeline:
+  request:
+    - id: acme.guardrails
+  response:
+    - id: acme.guardrails
+```
+

brainforge_inference_utils-0.0.1a1/README.md

@@ -0,0 +1,124 @@
+# BrainForge Inference Utilities
+
+Pluggable pipelines for shaping BrainForge LLM requests and responses.
+
+This package defines request/response orchestration that attaches to an
+existing inference workflow. Concrete behavior (ambient context, RAG/MCP
+injection, request history validation, citations, response sanitizing,
+safety guardrails, ...) can be implemented as **steps** that plug into one of
+two pipelines:
+
+- **Request pipeline** — runs before generation and shapes the request:
+  injecting informational context, RAG retrieval for host-selected
+  providers, validating and truncating history, etc.
+- **Response pipeline** — runs after generation and shapes the response:
+  citation rewrite, sanitization, guardrails, etc.
+
+Primary generation stays with the host, between the two pipelines. The host
+keeps the `UserTransaction` from the request pipeline until the response is
+ready. A pipeline step may call an inference endpoint to modify the transaction
+(for example citation rewrite) without the host owning those requests.
+
+Both pipelines operate on a `UserTransaction`, which carries the request,
+response, and two per-side context dicts (`request_step_context` and
+`response_step_context`). Requests and responses use the existing
+`neon-data-models` models (`LLMRequest` / `LLMResponse`).
+
+## Concepts
+
+| Concept | Purpose |
+| --- | --- |
+| `UserTransaction` | The request/response pair plus `request_step_context` / `response_step_context` dicts. The host holds this object across generation. |
+| `BrainForgeClient` | Builds pipelines from config and exposes `run_request_pipeline` / `run_response_pipeline` / `supported_request_context`. |
+| `RequestStep` | Shapes `transaction.request` before generation. Declares supported `request_context` keys/values. |
+| `ResponseStep` | Annotates/rewrites `transaction.response` after generation. |
+| `RequestContextOption` | One `request_context` key a step reads, with optional allowed values for hosts to present. |
+| `RequestPipeline` / `ResponsePipeline` | Run an ordered list of steps over a transaction. |
+| `PipelineConfig` / `StepConfig` | Declarative, ordered step lists (see below). |
+
+## Usage sketch
+
+```python
+client = BrainForgeClient(pipeline_config)
+
+options = await client.supported_request_context()
+# e.g. options["rag_providers"].values, options["conversational"].values
+
+transaction = await client.run_request_pipeline(llm_request)
+# host performs generation using transaction.request
+transaction = await client.run_response_pipeline(transaction, llm_response)
+```
+
+Request steps write `transaction.request_step_context[step.id]`. Response steps write
+`transaction.response_step_context[step.id]` and may *read* the request-step context. Those
+namespaces are independent, so the same step id may exist on both sides
+without colliding. Context is available across generation only because the
+same `UserTransaction` is passed back in; this package does not store it
+between calls.
+
+## Design notes
+
+- **Steps are independently defensive.** There is no dependency graph between
+  steps. A step that needs something it does not find (e.g. a citation step with
+  no retrieved sources) reports itself inapplicable via `applicable()` and is
+  skipped with a logged reason, rather than failing the pipeline.
+- **Ordering is explicit.** Step order is exactly the order declared in
+  configuration; the pipeline does not reorder.
+- **Steps may be repeated.** The same step id may appear more than once in a
+  pipeline, including with different `config`. Each appearance is a separate
+  instance and runs in declared order. The pipeline does not merge or
+  de-duplicate entries.
+- **Steps own their context.** Each side has its own dict keyed by step id.
+  A repeated step on the *same* side shares that key; a step id on the request
+  side does not clash with the same id on the response side. Each step is
+  responsible for how it stores and reads its own data across one or more
+  calls (for example appending to a list instead of overwriting it).
+  Response steps that consume request-step data should read
+  `transaction.request_step_context` and report inapplicable when required 
+  context is absent.
+- **Format contracts live together.** Steps that share a parse format
+  (e.g. a citation formatter and the sanitizer that strips it) belong in the
+  same module and should derive from a shared constant so they cannot drift.
+
+## Step plugins
+
+Installed packages advertise steps with setuptools entry points. Request and
+response steps use different groups:
+
+| Pipeline | Entry point group |
+| --- | --- |
+| Request | `brainforge.inference.request_steps` |
+| Response | `brainforge.inference.response_steps` |
+
+Both groups use the step id `author.step_name`:
+
+- `author` is the plugin developer's slug (`acme`, `brainforge`).
+- `step_name` names that one step (`guardrails`, `rag`).
+
+Each part may contain letters, digits, hyphens, and underscores. The class
+`id`, the config `id`, and the context-dict key are that same string.
+
+The same `author.step_name` may be registered once in each group. Each
+pipeline reads only its own group, so the request class and the response class
+stay distinct. Two packages registering the same name in one group is an
+error.
+
+```python
+entry_points={
+    "brainforge.inference.request_steps": [
+        "acme.guardrails=acme_guardrails:GuardrailRequestStep",
+    ],
+    "brainforge.inference.response_steps": [
+        "acme.guardrails=acme_guardrails:GuardrailResponseStep",
+    ],
+}
+```
+
+```yaml
+pipeline:
+  request:
+    - id: acme.guardrails
+  response:
+    - id: acme.guardrails
+```
+

brainforge_inference_utils-0.0.1a1/brainforge_inference_utils/__init__.py

@@ -0,0 +1,82 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Framework
+# All trademark and other rights reserved by their respective owners
+# Copyright 2008-2026 Neongecko.com Inc.
+# Contributors: Daniel McKnight, Richard Leeds, Bohdan Mykhailenko, 
+# Dmitry Honcharenko, Mike Gray, Clary Gasper, Charlie Bailey, Ryan Venturi,
+# Roger Wiebe, Pierce Seigne, Sathvika Nadipalli, Guy Daniels, Elon Gasper,
+# Regina Bloomstine, Casimiro Ferreira, Andrii Pernatii, Kirill Hrymailo
+# BSD-3 License
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+# OR PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE,  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""BrainForge inference pipeline utilities."""
+
+from neon_data_models.models.api.llm import (
+    LLMPersona,
+    LLMRequest,
+    LLMResponse,
+)
+
+from brainforge_inference_utils.version import __version__
+
+from brainforge_inference_utils.client import BrainForgeClient
+from brainforge_inference_utils.config import PipelineConfig, StepConfig
+from brainforge_inference_utils.pipeline import (
+    RequestPipeline,
+    ResponsePipeline,
+    build_pipelines,
+)
+from brainforge_inference_utils.registry import (
+    REQUEST_STEP_ENTRY_POINT,
+    RESPONSE_STEP_ENTRY_POINT,
+)
+from brainforge_inference_utils.steps.base import (
+    RequestStep,
+    RequestContextOption,
+    ResponseStep,
+    Step,
+)
+from brainforge_inference_utils.transaction import UserTransaction
+
+__all__ = [
+    "__version__",
+    "BrainForgeClient",
+    # Request/response models (re-exported from neon-data-models)
+    "LLMRequest",
+    "LLMResponse",
+    "LLMPersona",
+    # Transaction
+    "UserTransaction",
+    # Steps
+    "Step",
+    "RequestStep",
+    "ResponseStep",
+    "RequestContextOption",
+    # Pipelines
+    "RequestPipeline",
+    "ResponsePipeline",
+    "build_pipelines",
+    "REQUEST_STEP_ENTRY_POINT",
+    "RESPONSE_STEP_ENTRY_POINT",
+    # Config
+    "PipelineConfig",
+    "StepConfig",
+]

brainforge_inference_utils-0.0.1a1/brainforge_inference_utils/client.py

@@ -0,0 +1,117 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Framework
+# All trademark and other rights reserved by their respective owners
+# Copyright 2008-2026 Neongecko.com Inc.
+# Contributors: Daniel McKnight, Richard Leeds, Bohdan Mykhailenko, 
+# Dmitry Honcharenko, Mike Gray, Clary Gasper, Charlie Bailey, Ryan Venturi,
+# Roger Wiebe, Pierce Seigne, Sathvika Nadipalli, Guy Daniels, Elon Gasper,
+# Regina Bloomstine, Casimiro Ferreira, Andrii Pernatii, Kirill Hrymailo
+# BSD-3 License
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+# OR PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE,  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""Configured runner for the request and response pipelines.
+
+`BrainForgeClient` does not call an LLM. The host runs inference between
+`run_request_pipeline` and `run_response_pipeline`, and is responsible for keeping
+the returned `UserTransaction` until the response is ready.
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from neon_data_models.models.api.llm import LLMRequest, LLMResponse
+
+from brainforge_inference_utils.config import PipelineConfig
+from brainforge_inference_utils.pipeline import build_pipelines
+from brainforge_inference_utils.steps.base import RequestContextOption
+from brainforge_inference_utils.transaction import UserTransaction
+
+
+class BrainForgeClient:
+    """Build pipelines from config and run them around host-owned inference."""
+
+    def __init__(self, config: PipelineConfig):
+        self.config = config
+        self.request_pipeline, self.response_pipeline = build_pipelines(config)
+
+    async def supported_request_context(
+        self, timeout: float = 10.0
+    ) -> Dict[str, RequestContextOption]:
+        """
+        Collect `request_context` keys and allowed values from the pipeline.
+
+        The host uses this to populate UI; it does not call MCP itself.
+        Duplicate keys across steps are merged: enumerated values are unioned
+        in first-seen order, and if any declaration is unconstrained
+        (`values is None`) the merged option is unconstrained.
+        """
+        merged: Dict[str, RequestContextOption] = {}
+        for step in (*self.request_pipeline.steps, *self.response_pipeline.steps):
+            for option in await step.supported_request_context(timeout=timeout):
+                _merge_request_context_option(merged, option)
+        return merged
+
+    async def run_request_pipeline(
+        self, request: LLMRequest
+    ) -> UserTransaction:
+        """
+        Shape `request` and collect step context on a new transaction.
+
+        The caller must hold the returned transaction until
+        `run_response_pipeline` (or drop it if the response pipeline is unused).
+        """
+        transaction = UserTransaction(request=request)
+        return await self.request_pipeline.run(transaction)
+
+    async def run_response_pipeline(
+        self, transaction: UserTransaction, response: LLMResponse
+    ) -> UserTransaction:
+        """
+        Attach `response` to `transaction` and run the response pipeline.
+
+        Request-step context is on `transaction.request_step_context`; response steps
+        write to `transaction.response_step_context`. The caller must pass through
+        the transaction from `run_request_pipeline`.
+        """
+        transaction.response = response
+        return await self.response_pipeline.run(transaction)
+
+
+def _merge_request_context_option(
+    merged: Dict[str, RequestContextOption],
+    option: RequestContextOption,
+) -> None:
+    prior = merged.get(option.key)
+    if prior is None:
+        merged[option.key] = option
+        return
+    description = prior.description or option.description
+    if prior.values is None or option.values is None:
+        merged[option.key] = RequestContextOption(
+            option.key, None, description)
+        return
+    values = list(prior.values)
+    for value in option.values:
+        if value not in values:
+            values.append(value)
+    merged[option.key] = RequestContextOption(
+        option.key, values, description)

brainforge_inference_utils-0.0.1a1/brainforge_inference_utils/config.py

@@ -0,0 +1,105 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Framework
+# All trademark and other rights reserved by their respective owners
+# Copyright 2008-2026 Neongecko.com Inc.
+# Contributors: Daniel McKnight, Richard Leeds, Bohdan Mykhailenko, 
+# Dmitry Honcharenko, Mike Gray, Clary Gasper, Charlie Bailey, Ryan Venturi,
+# Roger Wiebe, Pierce Seigne, Sathvika Nadipalli, Guy Daniels, Elon Gasper,
+# Regina Bloomstine, Casimiro Ferreira, Andrii Pernatii, Kirill Hrymailo
+# BSD-3 License
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+# OR PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE,  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+Pipeline configuration schema.
+
+Configuration is two explicitly ordered lists of step entries: `request` and
+`response`. Order is authoritative; the pipeline runs steps in exactly the
+order given and does not reorder. Each entry names a step `id`
+(`author.step_name`, the entry point name) and optionally carries
+step-specific `config`.
+
+Example (YAML)::
+
+    pipeline:
+      request:
+        - id: brainforge.locale
+          config:
+            mcp_url: https://mcp.neonaiservices2.com/mcp
+            default_location: Renton, WA, USA
+            timeout: 5.0
+        - {id: brainforge.rag, config: {mcp_url: https://mcp.neonaiservices2.com/mcp, top_k: 10}}
+        - brainforge.history                       # last: valid, truncated history
+      response:
+        - id: brainforge.citations
+          config:
+            mcp_url: https://mcp.neonaiservices2.com/mcp
+            openai_url: https://hana.example/brainforge/openai/chat/completions
+
+A host typically loads its own config and hands the `pipeline` section here::
+
+    pipeline_config = PipelineConfig.model_validate(config["pipeline"])
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class StepConfig(BaseModel):
+    """
+    A single step entry within a pipeline.
+
+    :param id: Step id to resolve and instantiate. This is the entry point
+        name, `author.step_name`.
+    :param enabled: When false, the entry is skipped at build time (a
+        convenient way to turn a step off without deleting its config).
+    :param config: Step-specific configuration passed to the step constructor.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    enabled: bool = True
+    config: Dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce_shorthand(cls, data: Any) -> Any:
+        """Allow a bare string entry as shorthand for `{id: <string>}`."""
+        if isinstance(data, str):
+            return {"id": data}
+        return data
+
+
+class PipelineConfig(BaseModel):
+    """
+    Ordered step lists for the request and response pipelines.
+
+    :param request: Ordered `RequestStep` entries, run before generation.
+    :param response: Ordered `ResponseStep` entries, run after generation.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    request: List[StepConfig] = Field(default_factory=list)
+    response: List[StepConfig] = Field(default_factory=list)