✨ implement /v1/guardrail/checks endpoint

Author: m-misiura

nemoguardrails/rails/llm/llmrails.py

@@ -1680,11 +1680,11 @@ async def check_async(
         result_content = _get_last_response_content(response)
 
         if blocking_rail:
-            return RailsResult(status=RailStatus.BLOCKED, content=result_content, rail=blocking_rail)
+            return RailsResult(status=RailStatus.BLOCKED, content=result_content, rail=blocking_rail, log=response.log)
 
         if result_content != original_content:
-            return RailsResult(status=RailStatus.MODIFIED, content=result_content)
-        return RailsResult(status=RailStatus.PASSED, content=result_content)
+            return RailsResult(status=RailStatus.MODIFIED, content=result_content, log=response.log)
+        return RailsResult(status=RailStatus.PASSED, content=result_content, log=response.log)
 
     def check(
         self,

nemoguardrails/rails/llm/options.py

@@ -100,6 +100,7 @@ class RailsResult(BaseModel):
     status: RailStatus = Field(description="Status of the rails check: passed, modified, or blocked.")
     content: str = Field(description="The content after rails processing.")
     rail: Optional[str] = Field(default=None, description="Name of the rail that blocked the content.")
+    log: Optional["GenerationLog"] = Field(default=None, description="Generation log from the rails check.")
 
 
 class GenerationLogOptions(BaseModel):

nemoguardrails/server/api.py

@@ -35,12 +35,16 @@
 
 from nemoguardrails import LLMRails, RailsConfig, utils
 from nemoguardrails.rails.llm.config import Model
-from nemoguardrails.rails.llm.options import GenerationResponse
+from nemoguardrails.rails.llm.options import GenerationResponse, RailStatus
 from nemoguardrails.server.datastore.datastore import DataStore
 from nemoguardrails.server.schemas.openai import (
+    GuardrailCheckDataOutput,
+    GuardrailCheckRequest,
+    GuardrailCheckResponse,
     GuardrailsChatCompletion,
     GuardrailsChatCompletionRequest,
     OpenAIModelsList,
+    RailStatusEntry,
 )
 from nemoguardrails.server.schemas.utils import (
     create_error_chat_completion,
@@ -328,6 +332,20 @@ def _update_models_in_config(config: RailsConfig, main_model: Model) -> RailsCon
     return config.model_copy(update={"models": models})
 
 
+def _inject_model(config: RailsConfig, model_name: str) -> RailsConfig:
+    """Inject the request's model into a RailsConfig using env-based engine/base_url."""
+    engine = os.environ.get("MAIN_MODEL_ENGINE")
+    if not engine:
+        engine = "openai"
+        log.warning("MAIN_MODEL_ENGINE not set, defaulting to 'openai'. ")
+    parameters = {}
+    base_url = os.environ.get("MAIN_MODEL_BASE_URL")
+    if base_url:
+        parameters["base_url"] = base_url
+    main_model = Model(model=model_name, type="main", engine=engine, parameters=parameters)
+    return _update_models_in_config(config, main_model)
+
+
 async def _get_rails(config_ids: List[str], model_name: Optional[str] = None) -> LLMRails:
     """Returns the rails instance for the given config id and model.
 
@@ -373,18 +391,7 @@ async def _get_rails(config_ids: List[str], model_name: Optional[str] = None) ->
         raise ValueError("No valid rails configuration found.")
 
     if model_name:
-        engine = os.environ.get("MAIN_MODEL_ENGINE")
-        if not engine:
-            engine = "openai"
-            log.warning("MAIN_MODEL_ENGINE not set, defaulting to 'openai'. ")
-
-        parameters = {}
-        base_url = os.environ.get("MAIN_MODEL_BASE_URL")
-        if base_url:
-            parameters["base_url"] = base_url
-
-        main_model = Model(model=model_name, type="main", engine=engine, parameters=parameters)
-        full_llm_rails_config = _update_models_in_config(full_llm_rails_config, main_model)
+        full_llm_rails_config = _inject_model(full_llm_rails_config, model_name)
 
     llm_rails = LLMRails(config=full_llm_rails_config, verbose=True)
     llm_rails_instances[configs_cache_key] = llm_rails
@@ -643,6 +650,114 @@ async def chat_completion(body: GuardrailsChatCompletionRequest, request: Reques
         )
 
 
+def _filter_log(log_dict: dict, log_options) -> dict:
+    """Filter log output based on caller's log preferences.
+
+    check_async always enables activated_rails internally (needed for
+    rails_status), but the response log should only include fields the
+    caller requested.
+    """
+    filtered = {}
+    if log_options.activated_rails:
+        filtered["activated_rails"] = log_dict.get("activated_rails", [])
+    else:
+        filtered["activated_rails"] = []
+    if log_options.llm_calls and "llm_calls" in log_dict:
+        filtered["llm_calls"] = log_dict["llm_calls"]
+    if log_options.internal_events and "internal_events" in log_dict:
+        filtered["internal_events"] = log_dict["internal_events"]
+    if log_options.colang_history and "colang_history" in log_dict:
+        filtered["colang_history"] = log_dict["colang_history"]
+    if "stats" in log_dict:
+        filtered["stats"] = log_dict["stats"]
+    return filtered
+
+
+def _map_rail_status(status: RailStatus) -> str:
+    """Map internal RailStatus to upstream StatusEnum values."""
+    if status == RailStatus.BLOCKED:
+        return "blocked"
+    return "success"
+
+
+def _build_rails_status(result) -> dict:
+    """Build rails_status dict from activated rails in the generation log."""
+    rails_status = {}
+    if result.log and result.log.activated_rails:
+        for rail in result.log.activated_rails:
+            rail_status = "blocked" if rail.stop else "success"
+            rails_status[rail.name] = RailStatusEntry(status=rail_status)
+    return rails_status
+
+
+@app.post(
+    "/v1/guardrail/checks",
+    response_model=GuardrailCheckResponse,
+    response_model_exclude_none=True,
+)
+async def guardrail_check(body: GuardrailCheckRequest, request: Request):
+    """Guardrail check request."""
+    api_request_headers.set(request.headers)
+
+    if not body.messages:
+        raise HTTPException(status_code=422, detail="messages must be non-empty")
+
+    config_ids = None
+    config = body.guardrails.config
+
+    if isinstance(config, dict):
+        try:
+            rails_config = RailsConfig.from_content(config=config)
+            if body.model:
+                rails_config = _inject_model(rails_config, body.model)
+            llm_rails = LLMRails(config=rails_config, verbose=True)
+        except Exception as ex:
+            log.exception(ex)
+            raise HTTPException(status_code=422, detail=f"Invalid inline config: {ex}")
+    else:
+        if isinstance(config, str):
+            config_ids = [config]
+        elif body.guardrails.config_ids:
+            config_ids = list(body.guardrails.config_ids)
+        elif app.default_config_id:
+            config_ids = [app.default_config_id]
+        else:
+            raise HTTPException(
+                status_code=422,
+                detail="No guardrails config_id provided and server has no default configuration",
+            )
+        try:
+            llm_rails = await _get_rails(config_ids, model_name=body.model)
+        except ValueError as ex:
+            log.exception(ex)
+            raise HTTPException(status_code=422, detail=str(ex))
+
+    try:
+        messages = list(body.messages)
+        if body.guardrails.context:
+            messages.insert(0, {"role": "context", "content": body.guardrails.context})
+
+        result = await llm_rails.check_async(messages=messages)
+
+        log_dict = _filter_log(result.log.model_dump(), body.guardrails.options.log) if result.log else None
+        guardrails_data = GuardrailCheckDataOutput(
+            config_ids=config_ids,
+            log=log_dict,
+        )
+
+        return GuardrailCheckResponse(
+            status=_map_rail_status(result.status),
+            rails_status=_build_rails_status(result),
+            guardrails_data=guardrails_data,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as ex:
+        log.exception(ex)
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
 # By default, there are no challenges
 challenges = []
 

nemoguardrails/server/schemas/openai.py

@@ -16,7 +16,7 @@
 """OpenAI API schema definitions for the NeMo Guardrails server."""
 
 import os
-from typing import Any, List, Literal, Optional, Union
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from openai.types.chat.chat_completion import ChatCompletion
 from pydantic import BaseModel, Field, ValidationInfo, field_validator, model_validator
@@ -165,3 +165,60 @@ class OpenAIModelsList(BaseModel):
     """Standard OpenAI models list response."""
 
     data: list[OpenAIModel] = Field(..., description="List of OpenAI model objects.")
+
+
+class RailStatusEntry(BaseModel):
+    """Status of an individual rail."""
+
+    status: str = Field(..., description="Status of the individual rail.")
+
+
+class GuardrailCheckDataInput(GuardrailsDataInput):
+    """Guardrails input options specific to the checks endpoint."""
+
+    config: Optional[Union[str, dict]] = Field(
+        default=None,
+        description="The id of the configuration or its dict representation to be used.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_config_exclusivity(cls, data: Any) -> Any:
+        if isinstance(data, dict) and data.get("config") is not None:
+            if data.get("config_id") is not None or data.get("config_ids") is not None:
+                raise ValueError("config is mutually exclusive with config_id and config_ids")
+        return data
+
+
+class GuardrailCheckRequest(OpenAIChatCompletionRequest):
+    """Request body for the /v1/guardrail/checks endpoint."""
+
+    guardrails: GuardrailCheckDataInput = Field(
+        default_factory=GuardrailCheckDataInput,
+        description="Guardrails specific options for the request.",
+    )
+
+
+class GuardrailCheckDataOutput(BaseModel):
+    """Guardrails-specific output data for the checks endpoint (upstream-aligned)."""
+
+    llm_output: Optional[dict] = Field(default=None, description="Contains any additional output coming from the LLM.")
+    config_ids: Optional[List[str]] = Field(
+        default=None,
+        description="The list of configuration ids that were used.",
+    )
+    output_data: Optional[dict] = Field(
+        default=None,
+        description="The output data, i.e. a dict with the values corresponding to the output_vars.",
+    )
+    log: Optional[dict] = Field(default=None, description="Additional logging information.")
+
+
+class GuardrailCheckResponse(BaseModel):
+    """Response from the /v1/guardrail/checks endpoint."""
+
+    status: str = Field(..., description="Overall status indicating if all rails passed or if any failed.")
+    rails_status: Dict[str, RailStatusEntry] = Field(..., description="Dictionary mapping each rail to its status.")
+    guardrails_data: Optional[GuardrailCheckDataOutput] = Field(
+        default=None, description="Additional data related to guardrails."
+    )