Integrate Config Management with Unified Api

backend/app/crud/config/config.py

@@ -47,7 +47,7 @@ def create_or_raise(
             version = ConfigVersion(
                 config_id=config.id,
                 version=1,
-                config_blob=config_create.config_blob,
+                config_blob=config_create.config_blob.model_dump(),
                 commit_message=config_create.commit_message,
             )
 

backend/app/crud/config/version.py

@@ -34,7 +34,7 @@ def create_or_raise(self, version_create: ConfigVersionCreate) -> ConfigVersion:
             version = ConfigVersion(
                 config_id=self.config_id,
                 version=next_version,
-                config_blob=version_create.config_blob,
+                config_blob=version_create.config_blob.model_dump(),
                 commit_message=version_create.commit_message,
             )
 

backend/app/models/__init__.py

@@ -87,6 +87,8 @@
 from .job import Job, JobType, JobStatus, JobUpdate
 
 from .llm import (
+    ConfigBlob,
+    CompletionConfig,
     LLMCallRequest,
     LLMCallResponse,
 )

backend/app/models/config/config.py

@@ -2,10 +2,11 @@
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
-from sqlmodel import Field, SQLModel, UniqueConstraint, Index, text
+from sqlmodel import Field, SQLModel, Index, text
 from pydantic import field_validator
 
 from app.core.util import now
+from app.models.llm.request import ConfigBlob
 from .version import ConfigVersionPublic
 
 
@@ -56,7 +57,7 @@ class ConfigCreate(ConfigBase):
     """Create new configuration"""
 
     # Initial version data
-    config_blob: dict[str, Any] = Field(description="Provider-specific parameters")
+    config_blob: ConfigBlob = Field(description="Provider-specific parameters")
     commit_message: str | None = Field(
         default=None,
         max_length=512,

backend/app/models/config/version.py

@@ -8,6 +8,7 @@
 from sqlmodel import Field, SQLModel, UniqueConstraint, Index, text
 
 from app.core.util import now
+from app.models.llm.request import ConfigBlob
 
 
 class ConfigVersionBase(SQLModel):
@@ -60,7 +61,12 @@ class ConfigVersion(ConfigVersionBase, table=True):
 
 
 class ConfigVersionCreate(ConfigVersionBase):
-    pass
+    # Store config_blob as JSON in the DB. Validation uses ConfigBlob only at creation
+    # time, since schema may evolve. When fetching, it is returned as a raw dict and
+    # re-validated against the latest schema before use.
+    config_blob: ConfigBlob = Field(
+        description="Provider-specific configuration parameters (temperature, max_tokens, etc.)",
+    )
 
 
 class ConfigVersionPublic(ConfigVersionBase):

backend/app/models/llm/__init__.py

@@ -1,2 +1,7 @@
-from app.models.llm.request import LLMCallRequest, CompletionConfig, QueryParams
+from app.models.llm.request import (
+    LLMCallRequest,
+    CompletionConfig,
+    QueryParams,
+    ConfigBlob,
+)
 from app.models.llm.response import LLMCallResponse, LLMResponse, LLMOutput, Usage

backend/app/models/llm/request.py

@@ -1,5 +1,6 @@
 from typing import Any, Literal
 
+from uuid import UUID
 from sqlmodel import Field, SQLModel
 from pydantic import model_validator, HttpUrl
 
@@ -57,20 +58,94 @@ class CompletionConfig(SQLModel):
     )
 
 
-class LLMCallConfig(SQLModel):
-    """Complete configuration for LLM call including all processing stages."""
+class ConfigBlob(SQLModel):
+    """Raw JSON blob of config."""
 
     completion: CompletionConfig = Field(..., description="Completion configuration")
     # Future additions:
     # classifier: ClassifierConfig | None = None
     # pre_filter: PreFilterConfig | None = None
 
 
+class LLMCallConfig(SQLModel):
+    """
+    Complete configuration for LLM call including all processing stages.
+    Either references a stored config (id + version) or provides an ad-hoc config blob.
+    Depending on which is provided, only one of the two options should be used.
+    """
+
+    id: UUID | None = Field(
+        default=None,
+        description=(
+            "Identifier for an existing LLM call configuration. [require version if provided]"
+        ),
+    )
+    version: int | None = Field(
+        default=None,
+        ge=1,
+        description=(
+            "Version of the stored config to use. [require if id is provided]"
+        ),
+    )
+
+    blob: ConfigBlob | None = Field(
+        default=None,
+        description=(
+            "Raw JSON blob of the full configuration. Used for ad-hoc configurations without storing."
+            "Either this or (id + version) must be provided."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_config_logic(self):
+        has_stored = self.id is not None or self.version is not None
+        has_blob = self.blob is not None
+
+        if has_stored and has_blob:
+            raise ValueError(
+                "Provide either 'id' with 'version' for stored config OR 'blob' for ad-hoc config, not both."
+            )
+
+        if has_stored:
+            if not self.id or not self.version:
+                raise ValueError(
+                    "'id' and 'version' must both be provided together for stored config."
+                )
+            return self
+
+        if not has_blob:
+            raise ValueError(
+                "Must provide either a stored config (id + version) or an ad-hoc config (blob)."
+            )
+
+        return self
+
+    @property
+    def is_stored_config(self) -> bool:
+        """Check if the config refers to a stored config or not."""
+        return self.id is not None and self.version is not None
+
+
 class LLMCallRequest(SQLModel):
-    """User-facing API request for LLM completion."""
+    """
+    API request for an LLM completion.
+
+    The `config` field accepts either:
+    - **Stored config (id + version)** — recommended for all production use.
+    - **Inline config blob** — for testing or validating new configs.
+
+    Prefer stored configs in production; use blobs only for development/testing/validations.
+    """
 
     query: QueryParams = Field(..., description="Query-specific parameters")
-    config: LLMCallConfig = Field(..., description="Configuration for the LLM call")
+    config: LLMCallConfig = Field(
+        ...,
+        description=(
+            "Complete LLM call configuration, provided either by reference (id + version) "
+            "or as config blob. Use the blob only for testing/validation; "
+            "in production, always use the id + version."
+        ),
+    )
     callback_url: HttpUrl | None = Field(
         default=None, description="Webhook URL for async response delivery"
     )

backend/app/services/llm/jobs.py

@@ -6,8 +6,10 @@
 from sqlmodel import Session
 
 from app.core.db import engine
+from app.crud.config import ConfigVersionCrud
 from app.crud.jobs import JobCrud
-from app.models import JobStatus, JobType, JobUpdate, LLMCallRequest, LLMCallResponse
+from app.models import JobStatus, JobType, JobUpdate, LLMCallRequest
+from app.models.llm.request import ConfigBlob, LLMCallConfig
 from app.utils import APIResponse, send_callback
 from app.celery.utils import start_high_priority_job
 from app.services.llm.providers.registry import get_llm_provider
@@ -76,6 +78,41 @@ def handle_job_error(
     return callback_response.model_dump()
 
 
+def resolve_config_blob(
+    config_crud: ConfigVersionCrud, config: LLMCallConfig
+) -> tuple[ConfigBlob | None, str | None]:
+    """Fetch and parse stored config version into ConfigBlob.
+
+    Returns:
+        (config_blob, error_message)
+        - config_blob: ConfigBlob if successful, else None
+        - error_message: human-safe error string if an error occurs, else None
+    """
+    try:
+        config_version = config_crud.exists_or_raise(version_number=config.version)
+    except HTTPException as e:
+        return None, f"Failed to retrieve stored configuration: {e.detail}"
+    except Exception:
+        logger.error(
+            f"[resolve_config_blob] Unexpected error retrieving config version | "
+            f"config_id={config.id}, version={config.version}",
+            exc_info=True,
+        )
+        return None, "Unexpected error occurred while retrieving stored configuration"
+
+    try:
+        return ConfigBlob(**config_version.config_blob), None
+    except (TypeError, ValueError) as e:
+        return None, f"Stored configuration blob is invalid: {str(e)}"
+    except Exception:
+        logger.error(
+            f"[resolve_config_blob] Unexpected error parsing config blob | "
+            f"config_id={config.id}, version={config.version}",
+            exc_info=True,
+        )
+        return None, "Unexpected error occurred while parsing stored configuration"
+
+
 def execute_job(
     request_data: dict,
     project_id: int,
@@ -93,53 +130,72 @@ def execute_job(
     request = LLMCallRequest(**request_data)
     job_id: UUID = UUID(job_id)
 
+    # one of (id, version) or blob is guaranteed to be present due to prior validation
     config = request.config
-    provider = config.completion.provider
-    callback = None
+    callback_response = None
+    config_blob: ConfigBlob | None = None
 
     logger.info(
         f"[execute_job] Starting LLM job execution | job_id={job_id}, task_id={task_id}, "
-        f"provider={provider}"
     )
 
     try:
-        # Update job status to PROCESSING
         with Session(engine) as session:
+            # Update job status to PROCESSING
             job_crud = JobCrud(session=session)
             job_crud.update(
                 job_id=job_id, job_update=JobUpdate(status=JobStatus.PROCESSING)
             )
 
+            # if stored config, fetch blob from DB
+            if config.is_stored_config:
+                config_crud = ConfigVersionCrud(
+                    session=session, project_id=project_id, config_id=config.id
+                )
+
+                # blob is dynamic, need to resolve to ConfigBlob format
+                config_blob, error = resolve_config_blob(config_crud, config)
+
+                if error:
+                    callback_response = APIResponse.failure_response(
+                        error=error,
+                        metadata=request.request_metadata,
+                    )
+                    return handle_job_error(
+                        job_id, request.callback_url, callback_response
+                    )
+
+            else:
+                config_blob = config.blob
+
             try:
                 provider_instance = get_llm_provider(
                     session=session,
-                    provider_type=provider,
+                    provider_type=config_blob.completion.provider,
                     project_id=project_id,
                     organization_id=organization_id,
                 )
             except ValueError as ve:
-                callback = APIResponse.failure_response(
+                callback_response = APIResponse.failure_response(
                     error=str(ve),
                     metadata=request.request_metadata,
                 )
-
-        if callback:
-            return handle_job_error(job_id, request.callback_url, callback)
+                return handle_job_error(job_id, request.callback_url, callback_response)
 
         response, error = provider_instance.execute(
-            completion_config=config.completion,
+            completion_config=config_blob.completion,
             query=request.query,
             include_provider_raw_response=request.include_provider_raw_response,
         )
 
         if response:
-            callback = APIResponse.success_response(
+            callback_response = APIResponse.success_response(
                 data=response, metadata=request.request_metadata
             )
             if request.callback_url:
                 send_callback(
                     callback_url=request.callback_url,
-                    data=callback.model_dump(),
+                    data=callback_response.model_dump(),
                 )
 
             with Session(engine) as session:
@@ -152,21 +208,21 @@ def execute_job(
                     f"[execute_job] Successfully completed LLM job | job_id={job_id}, "
                     f"provider_response_id={response.response.provider_response_id}, tokens={response.usage.total_tokens}"
                 )
-                return callback.model_dump()
+                return callback_response.model_dump()
 
-        callback = APIResponse.failure_response(
+        callback_response = APIResponse.failure_response(
             error=error or "Unknown error occurred",
             metadata=request.request_metadata,
         )
-        return handle_job_error(job_id, request.callback_url, callback)
+        return handle_job_error(job_id, request.callback_url, callback_response)
 
     except Exception as e:
-        callback = APIResponse.failure_response(
+        callback_response = APIResponse.failure_response(
             error=f"Unexpected error occurred",
             metadata=request.request_metadata,
         )
         logger.error(
-            f"[execute_job] {callback.error} {str(e)} | job_id={job_id}, task_id={task_id}",
+            f"[execute_job] Unknown error occurred: {str(e)} | job_id={job_id}, task_id={task_id}",
             exc_info=True,
         )
-        return handle_job_error(job_id, request.callback_url, callback)
+        return handle_job_error(job_id, request.callback_url, callback_response)

backend/app/tests/api/routes/configs/test_config.py

@@ -18,9 +18,14 @@ def test_create_config_success(
         "name": "test-llm-config",
         "description": "A test LLM configuration",
         "config_blob": {
-            "model": "gpt-4",
-            "temperature": 0.8,
-            "max_tokens": 2000,
+            "completion": {
+                "provider": "openai",
+                "params": {
+                    "model": "gpt-4",
+                    "temperature": 0.8,
+                    "max_tokens": 2000,
+                },
+            }
         },
         "commit_message": "Initial configuration",
     }
@@ -81,7 +86,12 @@ def test_create_config_duplicate_name_fails(
     config_data = {
         "name": "duplicate-config",
         "description": "Should fail",
-        "config_blob": {"model": "gpt-4"},
+        "config_blob": {
+            "completion": {
+                "provider": "openai",
+                "params": {"model": "gpt-4"},
+            }
+        },
         "commit_message": "Initial",
     }
 
@@ -406,7 +416,12 @@ def test_create_config_requires_authentication(
     config_data = {
         "name": "test-config",
         "description": "Test",
-        "config_blob": {"model": "gpt-4"},
+        "config_blob": {
+            "completion": {
+                "provider": "openai",
+                "params": {"model": "gpt-4"},
+            }
+        },
         "commit_message": "Initial",
     }