brainforge-inference-utils 0.0.1a1__py3-none-any.whl

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/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/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)

brainforge_inference_utils/mcp.py

@@ -0,0 +1,92 @@
+# 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.
+"""Generic MCP client helpers shared by pipeline steps."""
+
+from __future__ import annotations
+
+import json
+from contextlib import asynccontextmanager
+from typing import Any, AsyncIterator
+
+from fastmcp import Client as MCPClient
+from fastmcp.client.transports import StreamableHttpTransport
+
+
+@asynccontextmanager
+async def mcp_client(mcp_url: str) -> AsyncIterator[MCPClient]:
+    """
+    Open a short-lived MCP client session for one or more tool calls.
+
+    :param mcp_url: MCP server URL from step configuration.
+    """
+    transport = StreamableHttpTransport(mcp_url)
+    async with MCPClient(transport) as client:
+        yield client
+
+
+def mcp_tool_inner_payload(result: Any) -> dict:
+    """
+    Server tool payload from tools/call structuredContent envelope.
+
+    Newer mcp CallToolResult stores structuredContent as a model field; older
+    stacks put it only in model_extra. Fall back to JSON in text content.
+    """
+    envelope = getattr(result, "structuredContent", None)
+    if not isinstance(envelope, dict):
+        envelope = (getattr(result, "model_extra", None) or {}).get(
+            "structuredContent") or {}
+    inner = envelope.get("result") or {}
+    payload = inner.get("result")
+    if isinstance(payload, dict):
+        return payload
+    content = getattr(result, "content", None) or []
+    if not content:
+        return {}
+    try:
+        parsed = json.loads(content[0].text)
+    except (json.JSONDecodeError, TypeError, AttributeError, IndexError):
+        return {}
+    inner = parsed.get("result") or {}
+    payload = inner.get("result")
+    return payload if isinstance(payload, dict) else {}
+
+
+def mcp_tool_content_parts(tool_result: Any) -> list:
+    """
+    Normalize tools/call handling across fastmcp and raw protocol objects.
+    """
+    if isinstance(tool_result, list):
+        return tool_result
+    content = getattr(tool_result, "content", None)
+    if isinstance(content, list):
+        return content
+    raise TypeError(
+        f"Unexpected MCP tool result {type(tool_result)!r}; "
+        "expected list or .content list")

brainforge_inference_utils/pipeline.py

@@ -0,0 +1,171 @@
+# 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.
+"""
+The request and response pipelines.
+
+- `RequestPipeline` runs ordered `RequestStep`s over a `UserTransaction` to shape
+  its request before generation.
+- `ResponsePipeline` runs ordered `ResponseStep`s over a `UserTransaction` to
+  annotate or rewrite its response after generation.
+
+Generation itself is out of scope here: a caller runs the request pipeline,
+performs generation separately to populate `transaction.response`, then runs the
+response pipeline. Steps that are inapplicable to a given transaction are
+skipped (with a logged reason) rather than failing the pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import List, Mapping, Sequence, Tuple, Type
+
+from brainforge_inference_utils.config import PipelineConfig
+from brainforge_inference_utils.registry import (
+    REQUEST_STEP_ENTRY_POINT,
+    RESPONSE_STEP_ENTRY_POINT,
+    load_entry_point_steps,
+)
+from brainforge_inference_utils.steps.base import (
+    RequestStep,
+    ResponseStep,
+    Step,
+)
+from brainforge_inference_utils.transaction import UserTransaction
+
+LOG = logging.getLogger(__name__)
+
+
+class RequestPipeline:
+    """
+    Runs `RequestStep`s in order over a transaction's request.
+
+    :param steps: Ordered request steps.
+    """
+
+    def __init__(self, steps: Sequence[RequestStep]):
+        self.steps: List[RequestStep] = list(steps)
+
+    async def run(self, transaction: UserTransaction) -> UserTransaction:
+        """
+        Run every applicable request step, mutating the transaction in place.
+
+        :param transaction: The transaction whose request to shape.
+        :returns: The same `transaction`.
+        """
+        for step in self.steps:
+            reason = step.applicable(transaction)
+            if reason is not None:
+                LOG.debug("Skipping request step %r: %s", step.id, reason)
+                continue
+            await step.process(transaction)
+        return transaction
+
+
+class ResponsePipeline:
+    """
+    Runs `ResponseStep`s in order over a transaction's response.
+
+    :param steps: Ordered response steps.
+    """
+
+    def __init__(self, steps: Sequence[ResponseStep]):
+        self.steps: List[ResponseStep] = list(steps)
+
+    async def run(self, transaction: UserTransaction) -> UserTransaction:
+        """
+        Run every applicable response step, mutating the transaction in place.
+
+        :param transaction: The transaction whose response to shape.
+        :returns: The same `transaction`.
+        """
+        for step in self.steps:
+            reason = step.applicable(transaction)
+            if reason is not None:
+                LOG.debug("Skipping response step %r: %s", step.id, reason)
+                continue
+            await step.process(transaction)
+        return transaction
+
+
+def _resolve_step(stage_id: str,
+                  steps: Mapping[str, Type[Step]]) -> Type[Step]:
+    try:
+        return steps[stage_id]
+    except KeyError:
+        raise KeyError(
+            f"No step registered with id {stage_id!r}. "
+            f"Known steps: {sorted(steps)}")
+
+
+def build_pipelines(
+    config: PipelineConfig,
+) -> Tuple[RequestPipeline, ResponsePipeline]:
+    """
+    Instantiate both pipelines from configuration.
+
+    Step classes come from the entry point group for that pipeline
+    (`brainforge.inference.request_steps` or
+    `brainforge.inference.response_steps`). A response step placed in the
+    request list (or vice versa) is absent from that group and fails at
+    build time.
+
+    :param config: Parsed pipeline configuration.
+    :returns: `(request_pipeline, response_pipeline)`.
+    :raises KeyError: If a configured step id is not registered in that
+        pipeline's entry point group.
+    :raises TypeError: If an installed entry point is not the step type for
+        its group.
+    """
+    request_step_classes = load_entry_point_steps(
+        REQUEST_STEP_ENTRY_POINT, RequestStep)
+    response_step_classes = load_entry_point_steps(
+        RESPONSE_STEP_ENTRY_POINT, ResponseStep)
+
+    request_steps: List[RequestStep] = []
+    for entry in config.request:
+        if not entry.enabled:
+            LOG.info("Request step %r disabled by config", entry.id)
+            continue
+        cls = _resolve_step(entry.id, request_step_classes)
+        request_steps.append(cls(entry.config))
+
+    response_steps: List[ResponseStep] = []
+    for entry in config.response:
+        if not entry.enabled:
+            LOG.info("Response step %r disabled by config", entry.id)
+            continue
+        cls = _resolve_step(entry.id, response_step_classes)
+        response_steps.append(cls(entry.config))
+
+    LOG.info("Built request pipeline: %s",
+             [s.id for s in request_steps] or "(empty)")
+    LOG.info("Built response pipeline: %s",
+             [s.id for s in response_steps] or "(empty)")
+    return RequestPipeline(request_steps), ResponsePipeline(response_steps)

brainforge_inference_utils/registry.py

@@ -0,0 +1,115 @@
+# 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.
+"""
+Discovery of plugin steps via setuptools entry points.
+
+Request and response steps are registered in separate groups, so the same
+`author.step_name` id can exist on both sides. Every step class comes from
+the entry point group for its pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from importlib.metadata import entry_points
+from typing import Dict, Type
+
+from brainforge_inference_utils.steps.base import Step
+
+LOG = logging.getLogger(__name__)
+
+REQUEST_STEP_ENTRY_POINT = "brainforge.inference.request_steps"
+RESPONSE_STEP_ENTRY_POINT = "brainforge.inference.response_steps"
+
+# author.step_name — letters, digits, hyphens, and underscores in each part.
+STEP_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$")
+
+
+def _distribution_name(entry_point) -> str:
+    dist = getattr(entry_point, "dist", None)
+    return getattr(dist, "name", None) or "unknown"
+
+
+def load_entry_point_steps(
+    group: str,
+    expected_type: Type[Step],
+) -> Dict[str, Type[Step]]:
+    """
+    Load step classes advertised under `group`.
+
+    Each entry point name must be `author.step_name` and must equal the
+    loaded class's `id`. Each part may contain letters, digits, hyphens, and
+    underscores. Names must be unique within the group. The same name may
+    still be registered under the other pipeline's group.
+
+    :param group: Entry point group to read.
+    :param expected_type: `RequestStep` or `ResponseStep`. Loaded classes must
+        subclass it.
+    :returns: Entry point name -> step class.
+    :raises ValueError: If a name is malformed, duplicated, or differs from
+        the class `id`.
+    :raises TypeError: If a loaded object is not a subclass of `expected_type`.
+    """
+    seen: Dict[str, str] = {}
+    loaded: Dict[str, Type[Step]] = {}
+    for entry_point in entry_points(group=group):
+        dist_name = _distribution_name(entry_point)
+        if not STEP_ID_PATTERN.fullmatch(entry_point.name):
+            raise ValueError(
+                f"Entry point {entry_point.name!r} in {group} from "
+                f"{dist_name} must use the form author.step_name")
+        prior = seen.get(entry_point.name)
+        if prior is not None:
+            raise ValueError(
+                f"Multiple packages register {group} step "
+                f"{entry_point.name!r}: {prior} and {dist_name}")
+        seen[entry_point.name] = dist_name
+
+        try:
+            step_cls = entry_point.load()
+        except Exception as exc:
+            raise ImportError(
+                f"Failed to load step {entry_point.name!r} from {dist_name}"
+            ) from exc
+        if not (isinstance(step_cls, type) and issubclass(step_cls, expected_type)):
+            raise TypeError(
+                f"Entry point {entry_point.name!r} in {group} from {dist_name} "
+                f"loaded {getattr(step_cls, '__name__', step_cls)!r}, which is "
+                f"not a {expected_type.__name__}")
+        if step_cls.id != entry_point.name:
+            raise ValueError(
+                f"Step {step_cls.__name__} from {dist_name} has id "
+                f"{step_cls.id!r}, which does not match entry point "
+                f"{entry_point.name!r}")
+        loaded[entry_point.name] = step_cls
+        LOG.debug("Loaded %s step %r from %s",
+                  expected_type.__name__, entry_point.name, dist_name)
+    return loaded

brainforge_inference_utils/steps/__init__.py

@@ -0,0 +1,51 @@
+# 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.
+"""
+Step base classes.
+
+Concrete steps ship in separate plugins and are discovered from entry points.
+Step ids use `author.step_name`.
+"""
+
+from __future__ import annotations
+
+from brainforge_inference_utils.steps.base import (
+    RequestStep,
+    RequestContextOption,
+    ResponseStep,
+    Step,
+)
+
+__all__ = [
+    "Step",
+    "RequestStep",
+    "ResponseStep",
+    "RequestContextOption",
+]

brainforge_inference_utils/steps/base.py

@@ -0,0 +1,194 @@
+# 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.
+"""
+Step base classes.
+
+Two step types plug into the two pipelines:
+
+- `RequestStep` runs before generation. It shapes the request on the
+  `UserTransaction` (RAG/MCP context, ambient context, request history
+  validation, ...), mutating it in place.
+- `ResponseStep` runs after generation. It shapes the response on the
+  `UserTransaction` (citations, sanitizing, guardrails, ...), mutating it
+  in place.
+
+Both share two conventions:
+
+1. **Defensive, not dependent.** Steps declare no relationships to one another.
+   A step that requires something it does not find reports itself inapplicable
+   from `applicable()` and is skipped (with a logged reason) rather than failing
+   the pipeline. This keeps configuration order the only ordering contract and
+   lets steps be added, removed, or substituted freely.
+
+2. **Shared object, separate namespaces.** Data that must pass between steps
+   travels on the `UserTransaction`, not through a step-to-step interface.
+   Request steps use `transaction.request_step_context`; response steps use
+   `transaction.response_step_context`. Step ids are unique only within one side.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, ClassVar, List, Optional, Sequence
+
+from brainforge_inference_utils.transaction import UserTransaction
+
+
+@dataclass(frozen=True)
+class RequestContextOption:
+    """
+    One `UserTransaction.request_context` key a step reads.
+
+    Hosts collect these from the built pipeline to present the keys and, when
+    known, the values a client may send. `values is None` means the key is
+    supported but unconstrained (any value of the implied type). An empty
+    `values` list means the key is supported but no choices are available
+    right now (for example an empty live catalog).
+    """
+
+    key: str
+    values: Optional[Sequence[Any]] = None
+    description: str = ""
+
+
+class Step(ABC):
+    """
+    Common base for all pipeline steps.
+
+    A step is constructed once, at pipeline build time, with its resolved
+    configuration. The same instance is reused across transactions, so steps
+    should keep per-request state on the `UserTransaction`, not on `self`.
+
+    :cvar id: Unique step identifier used in configuration. Subclasses must set
+        this to a stable, non-empty string. Plugin steps use `author.step_name`
+        and that string must match the entry point name.
+    :cvar request_context_options: Static `request_context` keys this step
+        reads. Override `supported_request_context` when allowed values must be
+        fetched live (for example a provider catalog).
+    """
+
+    id: ClassVar[str] = ""
+    request_context_options: ClassVar[Sequence[RequestContextOption]] = ()
+
+    def __init__(self, config: Optional[dict] = None):
+        """
+        :param config: Step-specific configuration from the pipeline config
+            entry's `config` mapping. Stored as `self.config`.
+        """
+        self.config: dict = dict(config or {})
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} id={self.id!r}>"
+
+    async def supported_request_context(
+        self, timeout: float = 10.0
+    ) -> List[RequestContextOption]:
+        """
+        Return the `request_context` keys this step reads, with allowed values.
+
+        The default copies `request_context_options`. Override when values must
+        be fetched live (for example a provider catalog). `timeout` is unused
+        for static declarations.
+
+        :param timeout: Seconds to wait for a live catalog, when overridden.
+        """
+        return list(self.request_context_options)
+
+
+class RequestStep(Step, ABC):
+    """
+    A step that shapes the request before generation.
+
+    Implementations mutate `transaction.request` in place (selecting a persona,
+    trimming or compacting history, injecting retrieved context, adjusting
+    generation params, ...).
+
+    Steps that read `transaction.request_context` should declare those keys on
+    `request_context_options` (static choices) or override
+    `supported_request_context` (live catalogs). Hosts collect the result via
+    `BrainForgeClient.supported_request_context`.
+    """
+
+    def applicable(self, transaction: UserTransaction) -> Optional[str]:
+        """
+        Decide whether this step should run for the given transaction.
+
+        :param transaction: The current transaction.
+        :returns: `None` to run the step, or a short human-readable reason to
+            skip it (logged). The default runs unconditionally; override to add
+            per-request gating.
+        """
+        return None
+
+    @abstractmethod
+    async def process(self, transaction: UserTransaction) -> None:
+        """
+        Apply this step's effect to the request.
+
+        Only called when `applicable(transaction)` returned `None`.
+        Implementations mutate `transaction` in place and return nothing.
+
+        :param transaction: The transaction whose `request` to shape.
+        """
+        raise NotImplementedError
+
+
+class ResponseStep(Step, ABC):
+    """
+    A step that shapes the generated response.
+
+    Implementations mutate `transaction.response` in place (annotating or
+    rewriting it). They return nothing.
+    """
+
+    def applicable(self, transaction: UserTransaction) -> Optional[str]:
+        """
+        Decide whether this step should run for the given transaction.
+
+        :param transaction: The current transaction (with `response` populated).
+        :returns: `None` to run the step, or a short human-readable reason to
+            skip it (logged). The default runs unconditionally; override to add
+            per-request gating (e.g. skip when there is nothing to annotate).
+        """
+        return None
+
+    @abstractmethod
+    async def process(self, transaction: UserTransaction) -> None:
+        """
+        Apply this step's effect to the response.
+
+        Only called when `applicable(transaction)` returned `None`.
+        Implementations mutate `transaction.response` in place and return
+        nothing.
+
+        :param transaction: The transaction whose `response` to shape.
+        """
+        raise NotImplementedError

brainforge_inference_utils/transaction.py

@@ -0,0 +1,79 @@
+# 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.
+"""
+The object a pipeline operates on.
+
+`UserTransaction` represents one user request/response cycle. Request steps shape
+its `request` and write `request_step_context`; generation (performed elsewhere)
+populates its `response`; response steps annotate that `response` and write
+`response_step_context`.
+
+The request and response are the existing `neon-data-models` models used across
+the BrainForge stack (HANA, `brainforge-llm-service`), so this package does not
+redefine their shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from neon_data_models.models.api.llm import LLMRequest, LLMResponse
+
+
+class UserTransaction(BaseModel):
+    """
+    One user request/response cycle as it flows through the pipelines.
+
+    :param request: The request being shaped by the request pipeline.
+    :param response: The generated response, populated after generation and
+        shaped by the response pipeline. `None` until generation completes.
+    :param request_step_context: Transient data written by request steps, keyed by
+        request step id.
+    :param response_step_context: Transient data written by response steps, keyed by
+        response step id.
+    """
+
+    request: LLMRequest = Field(
+        description="The LLM request shaped by the request pipeline")
+    response: Optional[LLMResponse] = Field(
+        default=None,
+        description="The generated response shaped by the response pipeline; "
+                    "None until generation completes")
+    request_context: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Client-provided context read by request steps")
+    request_step_context: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Request-step context keyed by request step id")
+    response_step_context: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Response-step context keyed by response step id")

brainforge_inference_utils/version.py

@@ -0,0 +1,31 @@
+# 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.
+
+__version__ = "0.0.1a1"

brainforge_inference_utils-0.0.1a1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+brainforge_inference_utils/__init__.py,sha256=EhCt2f4X_swIhULXwmvPrRFDReJjiz0IWZWAm5Nqkbc,3257
+brainforge_inference_utils/client.py,sha256=yGmIlU6Bb9pIt4Oo9vl8m1bhQwpu4diNXGeUPhaWXIY,5398
+brainforge_inference_utils/config.py,sha256=OPLa9G7lTLzad8_tHcC_-K7sWMTfeWZvIfRF9jVmzKg,4491
+brainforge_inference_utils/mcp.py,sha256=TKd884dXkD1X9pSZcy0CaBEuPiXnKuhmvve6iWISg4U,4059
+brainforge_inference_utils/pipeline.py,sha256=2yFYPR0M85XSBNe4qDtxXsoQQKZG0VhM_5382MjwpQg,6877
+brainforge_inference_utils/registry.py,sha256=JGOKyqaGC7wf6Xb9vLIAntTTEq9lcY6bbmjaKXXqx5I,5353
+brainforge_inference_utils/transaction.py,sha256=fIMfLoLxKrwBTF-VLci9R6WdOMS202xAcvqqoOZC1QU,3969
+brainforge_inference_utils/version.py,sha256=qlWZCTABcGFPUiaF907Tq_OSyQNjbvo78jsSyM0NpEU,2004
+brainforge_inference_utils/steps/__init__.py,sha256=e9pQrlsKiK94rHvVy7utDk1qcpHjN5cUStlfhX2YKxs,2374
+brainforge_inference_utils/steps/base.py,sha256=5juJJIeyS-_TVLzSAZaYsZ41qTnCoCxDWVthz-etLrY,8175
+brainforge_inference_utils-0.0.1a1.dist-info/licenses/LICENSE.md,sha256=U4qERlCptYiMPDU7Y_ciX0jYr7DV4IMtvntHL_YAJPM,1635
+brainforge_inference_utils-0.0.1a1.dist-info/METADATA,sha256=FEnsn0nX2jAtdFhBakpluVJtycDJ1IQHAE74qaziFLc,6480
+brainforge_inference_utils-0.0.1a1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+brainforge_inference_utils-0.0.1a1.dist-info/top_level.txt,sha256=MJOy5sqRqWw7qXucFKGEXR7qwEBL6H-hCrfCu1_YV_c,27
+brainforge_inference_utils-0.0.1a1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+brainforge_inference_utils-0.0.1a1.dist-info/RECORD,,

brainforge_inference_utils-0.0.1a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

brainforge_inference_utils-0.0.1a1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+brainforge_inference_utils

brainforge_inference_utils-0.0.1a1.dist-info/zip-safe

@@ -0,0 +1 @@
+