feat: add hybrid rule-based extraction support and persistence endpoints for DSPy configs

Author: IgnatG

.env.example

@@ -64,6 +64,12 @@ GUARDRAILS_INCLUDE_OUTPUT_IN_CORRECTION=true
 # Truncate invalid output in correction prompts (unset = no limit)
 # GUARDRAILS_MAX_CORRECTION_OUTPUT_LENGTH=1000
 
+# ── Hybrid regex/LLM (langcore-hybrid) ───────────────────────────────────
+# Enable hybrid regex+LLM model wrapping (skips LLM for high-confidence patterns)
+HYBRID_ENABLED=false
+# Minimum regex confidence to bypass LLM (0.0-1.0)
+HYBRID_MIN_CONFIDENCE=0.8
+
 # ── DSPy prompt optimization (langcore-dspy) ──────────────────────────────
 # Enable DSPy prompt optimization endpoint
 DSPY_ENABLED=false
@@ -78,6 +84,8 @@ DSPY_MAX_BOOTSTRAPPED_DEMOS=3
 DSPY_MAX_LABELED_DEMOS=4
 # Thread count for parallel evaluation during optimization
 DSPY_NUM_THREADS=4
+# Directory for saved optimized configs (save/load persistence)
+DSPY_CONFIG_DIR=.dspy_configs
 
 # ── RAG query parsing (langcore-rag) ──────────────────────────────────────
 # Enable RAG query parsing endpoint

app/api/routes/dspy.py

@@ -1,4 +1,4 @@
-"""DSPy prompt optimization route."""
+"""DSPy prompt optimization, persistence, and evaluation routes."""
 
 from __future__ import annotations
 
@@ -8,10 +8,22 @@
 
 from app.core.config import get_settings
 from app.schemas.plugins import (
+    DSPyEvaluateRequest,
+    DSPyEvaluateResponse,
+    DSPyListResponse,
+    DSPyLoadResponse,
     DSPyOptimizationRequest,
     DSPyOptimizationResponse,
+    DSPySaveRequest,
+    DSPySaveResponse,
+)
+from app.services.dspy_optimizer import (
+    async_load_config,
+    async_run_evaluation,
+    async_run_optimization,
+    async_save_config,
+    list_configs,
 )
-from app.services.dspy_optimizer import async_run_optimization
 
 logger = logging.getLogger(__name__)
 
@@ -40,15 +52,7 @@ async def optimize_prompt(
     calls internally.  Expect response times of 30s-5min
     depending on training set size and optimizer strategy.
     """
-    settings = get_settings()
-
-    if not settings.DSPY_ENABLED:
-        raise HTTPException(
-            status_code=503,
-            detail=(
-                "DSPy optimization is disabled. " "Set DSPY_ENABLED=true to enable."
-            ),
-        )
+    _check_dspy_enabled()
 
     if len(request.train_texts) != len(request.expected_results):
         raise HTTPException(
@@ -83,3 +87,167 @@ async def optimize_prompt(
         ) from exc
 
     return DSPyOptimizationResponse(**result)
+
+
+# -------------------------------------------------------------------
+# Config persistence endpoints
+# -------------------------------------------------------------------
+
+
+def _check_dspy_enabled() -> None:
+    """Raise 503 if DSPy is disabled."""
+    settings = get_settings()
+    if not settings.DSPY_ENABLED:
+        raise HTTPException(
+            status_code=503,
+            detail=(
+                "DSPy is disabled. Set DSPY_ENABLED=true to enable."
+            ),
+        )
+
+
+@router.post(
+    "/dspy/configs/save",
+    response_model=DSPySaveResponse,
+    summary="Save an optimized DSPy config",
+    description=(
+        "Persist an optimized prompt description and curated "
+        "few-shot examples to disk under the configured "
+        "``DSPY_CONFIG_DIR``. The saved config can later be loaded "
+        "for extraction or evaluation without re-running "
+        "optimization."
+    ),
+)
+async def save_config(request: DSPySaveRequest) -> DSPySaveResponse:
+    """Save an optimized DSPy config to disk."""
+    _check_dspy_enabled()
+
+    try:
+        result = await async_save_config(
+            config_name=request.config_name,
+            prompt_description=request.prompt_description,
+            examples=request.examples,
+            metadata=request.metadata,
+        )
+    except Exception as exc:
+        logger.exception("Failed to save DSPy config '%s'", request.config_name)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to save config: {exc}",
+        ) from exc
+
+    return DSPySaveResponse(**result)
+
+
+@router.get(
+    "/dspy/configs",
+    response_model=DSPyListResponse,
+    summary="List saved DSPy configs",
+    description=(
+        "Return the names of all saved optimized configs "
+        "available under ``DSPY_CONFIG_DIR``."
+    ),
+)
+async def list_saved_configs() -> DSPyListResponse:
+    """List all saved DSPy config names."""
+    _check_dspy_enabled()
+    return DSPyListResponse(configs=list_configs())
+
+
+@router.get(
+    "/dspy/configs/{config_name}",
+    response_model=DSPyLoadResponse,
+    summary="Load a saved DSPy config",
+    description=(
+        "Load a previously saved optimized config by name. "
+        "Returns the prompt description, examples, and any "
+        "stored metadata."
+    ),
+)
+async def load_config(config_name: str) -> DSPyLoadResponse:
+    """Load a saved DSPy config from disk."""
+    _check_dspy_enabled()
+
+    try:
+        result = await async_load_config(config_name)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.exception("Failed to load DSPy config '%s'", config_name)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to load config: {exc}",
+        ) from exc
+
+    return DSPyLoadResponse(**result)
+
+
+# -------------------------------------------------------------------
+# Evaluation endpoint
+# -------------------------------------------------------------------
+
+
+@router.post(
+    "/dspy/evaluate",
+    response_model=DSPyEvaluateResponse,
+    summary="Evaluate an optimized DSPy config",
+    description=(
+        "Evaluate an optimized config against test documents "
+        "with expected extractions. Returns precision, recall, "
+        "F1 score, and per-document metrics. Supply either a "
+        "``config_name`` (previously saved) or inline "
+        "``prompt_description`` + ``examples``."
+    ),
+)
+async def evaluate_config(
+    request: DSPyEvaluateRequest,
+) -> DSPyEvaluateResponse:
+    """Evaluate a DSPy config against test data."""
+    _check_dspy_enabled()
+
+    if len(request.test_texts) != len(request.expected_results):
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                f"test_texts ({len(request.test_texts)}) and "
+                f"expected_results ({len(request.expected_results)}) "
+                "must have the same length."
+            ),
+        )
+
+    # Validate that exactly one source is provided
+    has_config = request.config_name is not None
+    has_inline = (
+        request.prompt_description is not None
+        and request.examples is not None
+    )
+    if not has_config and not has_inline:
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                "Provide either config_name or both "
+                "prompt_description and examples."
+            ),
+        )
+
+    try:
+        result = await async_run_evaluation(
+            test_texts=request.test_texts,
+            expected_results=request.expected_results,
+            config_name=request.config_name,
+            prompt_description=request.prompt_description,
+            examples=request.examples,
+            model_id=request.model_id,
+        )
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.exception("DSPy evaluation failed")
+        raise HTTPException(
+            status_code=500,
+            detail=f"Evaluation failed: {exc}",
+        ) from exc
+
+    return DSPyEvaluateResponse(**result)

app/core/config.py

@@ -111,6 +111,10 @@ class Settings(BaseSettings):
     GUARDRAILS_MAX_CORRECTION_PROMPT_LENGTH: int | None = None
     GUARDRAILS_MAX_CORRECTION_OUTPUT_LENGTH: int | None = None
 
+    # ── Hybrid rule-based extraction (langcore-hybrid) ──────────────
+    HYBRID_ENABLED: bool = False
+    HYBRID_MIN_CONFIDENCE: float = 0.8
+
     # ── DSPy prompt optimization ────────────────────────────────────
     DSPY_ENABLED: bool = False
     DSPY_MODEL_ID: str = "gemini/gemini-2.5-flash"
@@ -119,6 +123,7 @@ class Settings(BaseSettings):
     DSPY_MAX_BOOTSTRAPPED_DEMOS: int = 3
     DSPY_MAX_LABELED_DEMOS: int = 4
     DSPY_NUM_THREADS: int = 4
+    DSPY_CONFIG_DIR: str = ".dspy_configs"
 
     # ── RAG query parsing ───────────────────────────────────────────
     RAG_ENABLED: bool = False

app/schemas/__init__.py

@@ -13,8 +13,14 @@
 from app.schemas.enums import TaskState
 from app.schemas.health import CeleryHealthResponse, HealthResponse
 from app.schemas.plugins import (
+    DSPyEvaluateRequest,
+    DSPyEvaluateResponse,
+    DSPyListResponse,
+    DSPyLoadResponse,
     DSPyOptimizationRequest,
     DSPyOptimizationResponse,
+    DSPySaveRequest,
+    DSPySaveResponse,
     RAGQueryParseRequest,
     RAGQueryParseResponse,
 )
@@ -43,8 +49,14 @@
     "BatchExtractionRequest",
     "BatchTaskSubmitResponse",
     "CeleryHealthResponse",
+    "DSPyEvaluateRequest",
+    "DSPyEvaluateResponse",
+    "DSPyListResponse",
+    "DSPyLoadResponse",
     "DSPyOptimizationRequest",
     "DSPyOptimizationResponse",
+    "DSPySaveRequest",
+    "DSPySaveResponse",
     "ExtractedEntity",
     "ExtractionConfig",
     "ExtractionMetadata",