feat: Structured Generative Model Configuration

agents/conditional/src/hyperforge_conditional/conditional.py

@@ -4,6 +4,7 @@
 
 from hyperforge.agent import Agent, AgentConfig
 from hyperforge.configure import get_agent_config_klass, get_agent_klass
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
 from hyperforge.manager import Manager
 from hyperforge.memory.memory import QuestionMemory
 from hyperforge.trace import trace_agent
@@ -93,11 +94,10 @@ class ConditionalAgentConfig(AgentConfig):
         title="Evaluate condition on",
         description="Source to evaluate the condition on. ",
     )
-    model: str = Field(
-        default="chatgpt-o3-mini",
+    model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.reasoning),
         title="Generative model",
         description="Model used to assess the condition",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
 
     @field_serializer("then", "else_")

agents/external/src/hyperforge_external/config.py

@@ -2,6 +2,7 @@
 from typing import Any, Dict, Literal, Optional
 
 from hyperforge.agent import AgentConfig
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
 from hyperforge.utils import WidgetType, sync_dns_validation
 from pydantic import Field, field_validator
 from pydantic.config import ConfigDict
@@ -49,11 +50,10 @@ class ExternalCallAgentConfig(AgentConfig):
         {},
         title="Headers to use on the API call ",
     )
-    model: str = Field(
-        default="chatgpt-o3-mini",
+    model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.reasoning),
         title="Generative model",
         description="Model used to extract the parameters to call the URL",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     context: bool = Field(
         False,

agents/generate/src/hyperforge_generate/agent.py

@@ -3,7 +3,7 @@
 
 from hyperforge.agent import Agent
 from hyperforge.configure import agent
-from hyperforge.manager import Manager
+from hyperforge.manager import Manager, build_reasoning
 from hyperforge.memory import QuestionMemory
 from hyperforge.trace import trace_agent
 from nuclia.lib.nua_responses import ChatModel, UserPrompt
@@ -69,7 +69,8 @@ async def __call__(
             question="",
             user_prompt=UserPrompt(prompt=prompt),
             format_prompt=False,
-            generative_model=self.config.model,
+            generative_model=self.config.model.model_id,
+            reasoning=build_reasoning(self.config.model),
             max_tokens=2000,
             tracking=memory.get_tracking_info(),
         )

agents/generate/src/hyperforge_generate/config.py

@@ -1,6 +1,7 @@
 from typing import Literal, Optional
 
 from hyperforge.agent import AgentConfig
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
 from hyperforge.utils import WidgetType
 from pydantic import Field
 from pydantic.config import ConfigDict
@@ -16,11 +17,10 @@ class GenerateAgentConfig(AgentConfig):
             "widget": WidgetType.EXPANDABLE_TEXTAREA,
         },
     )
-    model: str = Field(
-        default="chatgpt-azure-4o-mini",
+    model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.default),
         title="Generative model",
         description="Model used to generate the response",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     images: bool = False
     generate_image: bool = False

agents/mcp/src/hyperforge_mcp/agent.py

@@ -19,7 +19,7 @@
     PromptFeedbackSchema,
     ValidationFeedbackSchema,
 )
-from hyperforge.manager import Manager
+from hyperforge.manager import Manager, build_reasoning
 from hyperforge.memory import QuestionMemory
 from hyperforge.models import Chunk, Context, Prompt, TrackingInfo
 from hyperforge.utils import iterate_tools_resp
@@ -331,7 +331,8 @@ async def choose_tool(
             question="",
             user_id="mcp_agent",
             query_context_images=images,
-            generative_model=self.config.tool_choice_model,
+            generative_model=self.config.tool_choice_model.model_id,
+            reasoning=build_reasoning(self.config.tool_choice_model),
             tools=tools,
             user_prompt=UserPrompt(
                 prompt="Choose the best tool or tools for the task, select task_complete if no more tools are needed according to the user request and previous interactions"
@@ -915,7 +916,8 @@ async def sampling_callback(
             question="",
             user_id=self.config.id or "mcp_agent",
             query_context_images=images,
-            generative_model=self.config.sampling_model,
+            generative_model=self.config.sampling_model.model_id,
+            reasoning=build_reasoning(self.config.sampling_model),
             format_prompt=False,
             system=params.systemPrompt,
             context=new_messages,
@@ -940,7 +942,7 @@ async def sampling_callback(
         return CreateMessageResult(
             role="user",
             content=types.TextContent(type="text", text=resp.answer),
-            model=self.config.sampling_model,
+            model=self.config.sampling_model.model_id,
         )
 
     async def elicitation_callback(

agents/mcp/src/hyperforge_mcp/config.py

@@ -2,7 +2,7 @@
 from typing import Dict, List, Literal
 
 from hyperforge.context.config import ContextAgentConfig
-from hyperforge.utils import WidgetType
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
 from pydantic import Field
 from pydantic.config import ConfigDict
 
@@ -22,11 +22,10 @@ class MCPAgentConfig(ContextAgentConfig):
             "show_in_node": True,
         },
     )
-    tool_choice_model: str = Field(
-        default="chatgpt-4.1",
+    tool_choice_model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.smart),
         title="Tool choice model",
         description="Model used to choose the tool to use",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     valid_headers: List[str] = Field(
         default_factory=list, title="Valid headers to forward to the agent"
@@ -44,11 +43,10 @@ class MCPAgentConfig(ContextAgentConfig):
     max_turns: int = Field(
         default=5, title="Maximum number of tool calls before stopping"
     )
-    sampling_model: str = Field(
-        default="gemini-2.5-flash",
+    sampling_model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.fast),
         title="Sampling model",
         description="Model used for sampling",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     include_mcp_prompts: bool = Field(
         default=False,
@@ -70,16 +68,19 @@ class MultiMCPAgentConfig(ContextAgentConfig):
     configs: List[MCPAgentConfig] = Field(
         default_factory=list, title="List of MCP agent configurations"
     )
-    summarize_model: str = "gemini-2.5-flash"
+    summarize_model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.default),
+        title="Summarize model",
+        description="Model used to summarize results",
+    )
     feedback_timeout: int = Field(
         default=10000, title="Feedback timeout in milliseconds"
     )
     interaction: bool = Field(default=True, title="Enable interaction with the user")
-    tool_choice_model: str = Field(
-        default="chatgpt-4.1",
+    tool_choice_model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.smart),
         title="Tool choice model",
         description="Model used to choose the tool to use",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     work_chain: bool = Field(default=True, title="Enable loop on tool")
     max_turns: int = Field(

agents/nucliadb/src/hyperforge_nucliadb/advanced_ask_agent.py

@@ -190,7 +190,7 @@ def build_ask_request(
     filter_expression = parse_filter_expression(agent, driver)
     ask_request = AskRequest(
         query=question,
-        generative_model=agent.generative_model,
+        generative_model=agent.generative_model.model_id,
         citations=True,
         filters=driver.filters,
     )

agents/nucliadb/src/hyperforge_nucliadb/advanced_ask_config.py

@@ -1,6 +1,7 @@
 from typing import Any, List, Literal, Optional, Union
 
 from hyperforge.context.config import ContextAgentConfig
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
 from hyperforge.utils import WidgetType
 from nucliadb_models.filters import FilterExpression
 from nucliadb_models.search import (
@@ -30,11 +31,10 @@ class AdvancedAskAgentConfig(ContextAgentConfig):
             "show_in_node": True,
         },
     )
-    generative_model: str = Field(
-        default="chatgpt-azure-4o-mini",
+    generative_model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.default),
         title="Generative model",
         description="Model used to generate answers",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     features: Optional[list[ChatOptions]] = Field(
         default=None,

agents/nucliadb/src/hyperforge_nucliadb/ask/config.py

@@ -1,6 +1,7 @@
 from typing import List, Literal, Optional
 
 from hyperforge.context.config import ContextAgentConfig
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
 from hyperforge.utils import WidgetType
 from nucliadb_models.search import KnowledgeGraphEntity
 from pydantic import Field
@@ -40,11 +41,10 @@ class AskAgentConfig(ContextAgentConfig):
             "show_in_node": True,
         },
     )
-    configuration_model: str = Field(
-        default="gemini-2.5-flash",
+    configuration_model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.fast),
         title="Generative model",
         description="Model used to generate the configuration",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     fast_answer: bool = True
     # Setting this to True so that this PR will not break the current behavior

agents/nucliadb/src/hyperforge_nucliadb/basic_ask_agent.py

@@ -709,7 +709,7 @@ async def do_nucliadb_query(
         # Use full resource strategy by requesting title and summary fields
         ask_request = AskRequest(
             query=question,
-            generative_model=self.config.generative_model,
+            generative_model=self.config.generative_model.model_id,
             # TODO: Consider what to do when multiple resources match
             filter_expression=filter_expression,
             rag_strategies=[
@@ -1132,7 +1132,7 @@ async def inner_rag(
             query=question,
             show=[ResourceProperties.BASIC, ResourceProperties.ORIGIN],
             citations=CitationsType.LLM_FOOTNOTES,
-            generative_model=self.config.generative_model,
+            generative_model=self.config.generative_model.model_id,
             filter_expression=filter_expression,
             rag_strategies=rag_strategies,
         )
@@ -1244,7 +1244,7 @@ async def rag(
         ask_request = AskRequest(
             query=question,
             citations=True,
-            generative_model=self.config.generative_model,
+            generative_model=self.config.generative_model.model_id,
             filters=nucliadb_driver.config.filters,
         )
         paragraphs = await nucliadb_driver.ask(

agents/nucliadb/src/hyperforge_nucliadb/basic_ask_config.py

@@ -1,6 +1,7 @@
 from typing import List, Literal, Optional, Tuple
 
 from hyperforge.context.agent import ContextAgentConfig
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
 from hyperforge.utils import WidgetType
 from pydantic import Field
 from pydantic.config import ConfigDict
@@ -15,11 +16,10 @@ class BasicAskAgentConfig(ContextAgentConfig):
             "show_in_node": True,
         },
     )
-    generative_model: str = Field(
-        default="chatgpt-azure-4o-mini",
+    generative_model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.default),
         title="Generative model",
         description="Model used to generate answers",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     published_functions: Optional[Tuple[str, ...]] = Field(
         default=(

agents/related/src/hyperforge_related/agent.py

@@ -1,11 +1,11 @@
 from time import time
 
+from hyperforge import PROMPT_ENVIRONMENT
 from hyperforge.agent import Agent
 from hyperforge.manager import Manager
 from hyperforge.memory import QuestionMemory
 from hyperforge.trace import trace_agent
 
-from hyperforge import PROMPT_ENVIRONMENT
 from hyperforge_related.config import RelatedAgentConfig
 
 ASK_JSON_SCHEMA = {

agents/related/src/hyperforge_related/config.py

@@ -1,12 +1,18 @@
 from typing import Literal, Optional
 
 from hyperforge.agent import AgentConfig
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
+from pydantic import Field
 from pydantic.config import ConfigDict
 
 
 class RelatedAgentConfig(AgentConfig):
     model_config = ConfigDict(title="Related")
     module: Literal["related"] = "related"
     prompt: Optional[str] = None
-    model: str = "chatgpt-azure-4o-mini"
+    model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.default),
+        title="Generative model",
+        description="Model used to generate related questions",
+    )
     images: bool = False

agents/related/tests/test_related.py

@@ -1,17 +1,21 @@
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
+from hyperforge.llm_config import LLMConfig
 from hyperforge.manager import Manager
 from hyperforge.memory.memory import EphemeralSessionMemory
 from hyperforge.models import MemoryConfig, Rules
+
 from hyperforge_related.agent import RelatedAgent
 from hyperforge_related.config import RelatedAgentConfig
 
 
 def make_agent(
     model: str = "chatgpt-azure-4o-mini", prompt: str | None = None
 ) -> RelatedAgent:
-    config = RelatedAgentConfig(id="test-related", model=model, prompt=prompt)
+    config = RelatedAgentConfig(
+        id="test-related", model=LLMConfig(model_id=model), prompt=prompt
+    )
     return RelatedAgent(config=config)
 
 
@@ -33,22 +37,6 @@ def make_manager(related: list[str] | None = None, return_none: bool = False):
     return manager
 
 
-# --- Config tests ---
-
-
-def test_config_defaults():
-    config = RelatedAgentConfig()
-    assert config.module == "related"
-    assert config.model == "chatgpt-azure-4o-mini"
-    assert config.prompt is None
-    assert config.images is False
-
-
-def test_step_title():
-    agent = make_agent()
-    assert agent.step_title("Related questions") == "Related: Related questions"
-
-
 # --- Behaviour tests ---
 
 
@@ -119,7 +107,7 @@ async def test_execute_json_called_with_correct_model():
     await agent(memory=memory, manager=manager)
 
     call_kwargs = manager.execute_json.call_args.kwargs
-    assert call_kwargs["model"] == "my-custom-model"
+    assert call_kwargs["model"].model_id == "my-custom-model"
 
 
 @pytest.mark.asyncio

agents/rephrase/src/hyperforge_rephrase/config.py

@@ -1,7 +1,7 @@
 from typing import Dict, List, Literal, Optional
 
 from hyperforge.agent import AgentConfig
-from hyperforge.utils import WidgetType
+from hyperforge.llm_config import LLMConfig, LLMField, llm_defaults
 from pydantic import Field
 from pydantic.config import ConfigDict
 
@@ -18,11 +18,10 @@ class RephraseAgentConfig(AgentConfig):
     extend: bool = True
     session_info: bool = False
     history: bool = False
-    model: str = Field(
-        default="gemini-2.5-flash-lite",
+    model: LLMField = Field(
+        default_factory=lambda: LLMConfig(model_id=llm_defaults.default),
         title="Generative model",
         description="Model used to generate the rephrased question",
-        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
     )
     module: Literal["rephrase"] = "rephrase"
     split_question: bool = False