feat(generation): remote vLLM/NIM generation backend (GPU-free)

AGENTS.md

@@ -50,7 +50,7 @@ Source code lives in `src/nemo_safe_synthesizer/`:
 | `configurator/` | Pydantic-to-Click mapping, Parameter types, validators |
 | `data_processing/` | Holdout, actions, assembler, records, shared token budget (`budget.py`), shared column validators (`validation.py`) |
 | `evaluation/` | Evaluator, components (privacy, MI, AIA, PII replay), reports |
-| `generation/` | GeneratorBackend, VllmBackend, regex manager, batch gen |
+| `generation/` | GeneratorBackend (owns the concrete `generate()` batch-loop template method), VllmBackend, RemoteBackend (GPU-free; calls a vLLM/NIM OpenAI-compatible endpoint), regex manager, batch gen |
 | `holdout/` | Train/test splitting |
 | `llm/` | Model loading, metadata, memory management |
 | `pii_replacer/` | NER-based PII detection and replacement |

src/nemo_safe_synthesizer/config/__init__.py

@@ -9,7 +9,7 @@
 from .differential_privacy import DifferentialPrivacyHyperparams
 from .evaluate import EvaluationParameters
 from .external_results import SafeSynthesizerSummary, SafeSynthesizerTiming
-from .generate import GenerateParameters, StructuredGenerationParameters
+from .generate import GenerateParameters, RemoteParameters, StructuredGenerationParameters
 from .internal_results import SafeSynthesizerResults
 from .job import SafeSynthesizerJobConfig
 from .parameters import SafeSynthesizerParameters
@@ -26,6 +26,7 @@
     "GenerateParameters",
     "PiiReplacerConfig",
     "PreflightParameters",
+    "RemoteParameters",
     "SafeSynthesizerJobConfig",
     "SafeSynthesizerParameters",
     "SafeSynthesizerResults",

src/nemo_safe_synthesizer/config/generate.py

@@ -26,11 +26,14 @@
 StructuredGenerationSchemaMethod = Literal["auto", "regex", "json_schema", "structural_tag"]
 ResolvedStructuredGenerationSchemaMethod = Literal["regex", "json_schema", "structural_tag"]
 StructuredGenerationBackend = Literal["auto", "xgrammar", "guidance", "outlines", "lm-format-enforcer"]
+RemoteDialect = Literal["vllm", "openai"]
 
 STRUCTURAL_TAG_COMPATIBLE_BACKENDS = frozenset({"auto", "xgrammar"})
 
 __all__ = [
     "GenerateParameters",
+    "RemoteDialect",
+    "RemoteParameters",
     "ResolvedStructuredGenerationSchemaMethod",
     "StructuredGenerationParameters",
     "StructuredGenerationBackend",
@@ -176,6 +179,91 @@ def _validate_structural_tag_backend(self) -> Self:
         return self
 
 
+class RemoteParameters(Parameters, BaseModel):
+    """Connection to an external vLLM OpenAI-compatible inference server.
+
+    When set on :class:`GenerateParameters`, generation issues HTTP requests
+    to this endpoint instead of loading a local vLLM engine. The server must
+    already serve the base model with the fine-tuned LoRA adapter attached,
+    registered under ``model``. No GPU is used locally.
+
+    Structured generation maps to vLLM's ``structured_outputs`` request field
+    (``regex`` / ``json`` / ``structural_tag``), so all schema methods are
+    supported against a vLLM 0.20+ server.
+    """
+
+    dialect: Annotated[
+        RemoteDialect,
+        Field(
+            title="dialect",
+            description=(
+                "Which request fields to send. 'vllm' (default) adds vLLM's sampling extensions "
+                "(repetition_penalty, top_k, min_p, skip_special_tokens, include_stop_str_in_output, "
+                "ignore_eos). 'openai' sends only the universal OpenAI fields, for stricter servers "
+                "(e.g. NIM / TensorRT-LLM) that reject those extensions."
+            ),
+        ),
+    ] = "vllm"
+
+    endpoint_url: Annotated[
+        str,
+        Field(
+            title="endpoint_url",
+            description="Base URL of the OpenAI-compatible server, e.g. 'http://localhost:8000/v1'.",
+        ),
+    ]
+
+    model: Annotated[
+        str,
+        Field(
+            title="model",
+            description="Model name as registered on the server (the served base model or LoRA adapter name).",
+        ),
+    ]
+
+    api_key_env: Annotated[
+        str | None,
+        Field(
+            title="api_key_env",
+            description=(
+                "Name of the environment variable holding the bearer token for the endpoint. "
+                "When unset, no Authorization header is sent."
+            ),
+        ),
+    ] = None
+
+    timeout_seconds: Annotated[
+        float,
+        ValueValidator(value_func=lambda v: v > 0),
+        Field(
+            title="timeout_seconds",
+            description="Per-request timeout in seconds. Must be > 0.",
+        ),
+    ] = 300.0
+
+    max_concurrency: Annotated[
+        int,
+        ValueValidator(value_func=lambda v: v >= 1),
+        Field(
+            title="max_concurrency",
+            description="Maximum number of concurrent in-flight requests per batch. Must be >= 1.",
+        ),
+    ] = 16
+
+    max_retries: Annotated[
+        int,
+        ValueValidator(value_func=lambda v: v >= 0),
+        Field(
+            title="max_retries",
+            description=(
+                "Number of retry attempts per request for transient failures (connection drops, "
+                "timeouts, and HTTP 408/409/425/429/500/502/503/504), using exponential backoff with "
+                "full jitter and honoring a Retry-After header. 0 disables retries. Must be >= 0."
+            ),
+        ),
+    ] = 4
+
+
 class GenerateParameters(Parameters, BaseModel):
     """Configuration parameters for synthetic data generation.
 
@@ -260,6 +348,18 @@ class GenerateParameters(Parameters, BaseModel):
         default_factory=ValidationParameters,
     )
 
+    remote: Annotated[
+        RemoteParameters | None,
+        Field(
+            title="remote",
+            description=(
+                "When set, generate by calling an external vLLM OpenAI-compatible server instead of "
+                "loading a local vLLM engine. The server must already serve the trained LoRA adapter. "
+                "Not supported for time-series generation."
+            ),
+        ),
+    ] = None
+
     attention_backend: Annotated[
         str | None,
         Field(

src/nemo_safe_synthesizer/config/parameters.py

@@ -163,6 +163,18 @@ def check_timeseries_group_column(self) -> Self:
                 )
         return self
 
+    @model_validator(mode="after")
+    def check_remote_not_timeseries(self) -> Self:
+        """Reject remote generation for time-series datasets at config time.
+
+        The remote backend has no equivalent of the grouped time-series
+        generation loop, so the combination is unsupported. Catching it here
+        fails fast instead of after training completes.
+        """
+        if self.generation.remote is not None and self.time_series is not None and self.time_series.is_timeseries:
+            raise ParameterError("Remote generation is not supported for time-series datasets.")
+        return self
+
     @classmethod
     @override
     def from_params(cls, **kwargs: object) -> "SafeSynthesizerParameters":