flock-core 0.5.0b15__py3-none-any.whl → 0.5.0b17__py3-none-any.whl

flock/core/flock_factory.py

@@ -1,6 +1,11 @@
-"""Factory for creating pre-configured Flock agents."""
+"""Factory for creating pre-configured Flock agents.
+
+Deprecated: Prefer explicit `DefaultAgent` class for new code. This factory
+remains as a thin adapter to ease migration and preserve backward compatibility.
+"""
 
 import os
+import warnings
 from collections.abc import Callable
 from pathlib import Path
 from typing import Any, Literal
@@ -12,12 +17,13 @@ from flock.components.utility.metrics_utility_component import (
     MetricsUtilityComponent,
     MetricsUtilityConfig,
 )
+from flock.core.agent.default_agent import DefaultAgent
 
 # New unified components imported locally to avoid circular imports
-from flock.core.config.flock_agent_config import FlockAgentConfig
 from flock.core.config.scheduled_agent_config import ScheduledAgentConfig
 from flock.core.flock_agent import DynamicStr, FlockAgent
 from flock.core.logging.formatters.themes import OutputTheme
+from flock.core.logging.logging import get_logger
 from flock.core.mcp.flock_mcp_server import FlockMCPServer
 from flock.core.mcp.mcp_config import (
     FlockMCPCachingConfiguration,
@@ -207,6 +213,8 @@ class FlockFactory:
         tool_result_cache_ttl=100,
         description: str | Callable[..., str] | None = None,
         alert_latency_threshold_ms: int = 30000,
+        tool_whitelist: list[str] | None = None,
+        allow_all_tools: bool = True,
     ) -> FlockMCPServer:
         """Create a default MCP Server with common modules.
 
@@ -215,6 +223,26 @@ class FlockFactory:
         - SSE-Server (specify "sse" in type)
         - Stdio-Server (specify "stdio" in type)
         - Websockets-Server (specifiy "websockets" in type)
+
+        Args:
+            name: Unique identifier for the MCP server
+            connection_params: Connection configuration (StdioParams, SSEParams, etc.)
+            tool_whitelist: List of tool names to allow from this server. If provided,
+                          only tools with these names will be available. Used with
+                          allow_all_tools=False for strict filtering. Agent-level
+                          filtering is generally preferred over server-level filtering.
+            allow_all_tools: Whether to allow all tools from the server. When True
+                           (default), all tools are available. When False, only tools
+                           in tool_whitelist (if provided) are available.
+            Other args: Various configuration options for caching, callbacks, etc.
+
+        Returns:
+            FlockMCPServer: Configured MCP server instance
+
+        Note:
+            For security and flexibility, prefer using agent-level tool_whitelist
+            over server-level filtering. This allows different agents to access
+            different tool subsets from the same server.
         """
         # infer server type from the pydantic model class
         if isinstance(connection_params, FlockFactory.StdioParams):
@@ -251,6 +279,7 @@ class FlockFactory:
             tools_enabled=enable_tools_feature,
             prompts_enabled=enable_prompts_feature,
             sampling_enabled=enable_sampling_feature,
+            tool_whitelist=tool_whitelist,
         )
         callback_config = FlockMCPCallbackConfiguration(
             sampling_callback=sampling_callback,
@@ -319,6 +348,7 @@ class FlockFactory:
                 feature_config=feature_config,
                 caching_config=caching_config,
                 callback_config=callback_config,
+                allow_all_tools=allow_all_tools,
             )
 
         elif server_kind == "sse":
@@ -342,6 +372,7 @@ class FlockFactory:
                 feature_config=feature_config,
                 caching_config=caching_config,
                 callback_config=callback_config,
+                allow_all_tools=allow_all_tools,
             )
 
         elif server_kind == "websockets":
@@ -361,6 +392,7 @@ class FlockFactory:
                 feature_config=feature_config,
                 caching_config=caching_config,
                 callback_config=callback_config,
+                allow_all_tools=allow_all_tools,
             )
 
         else:
@@ -412,86 +444,41 @@ class FlockFactory:
         next_agent: DynamicStr | None = None,
         temporal_activity_config: TemporalActivityConfig | None = None,
     ) -> FlockAgent:
-        """Creates a default FlockAgent using unified component architecture.
+        """Create a default FlockAgent.
 
-        The default agent includes the following unified components:
-        - DeclarativeEvaluationComponent (core LLM evaluation)
-        - OutputUtilityComponent (result formatting and display)
-        - MetricsUtilityComponent (performance tracking)
-
-        This provides a complete, production-ready agent with sensible defaults.
+        Deprecated: Use `DefaultAgent(...)` instead. This method now delegates to
+        `DefaultAgent` and emits an optional one-time deprecation warning if the
+        environment variable `FLOCK_WARN_FACTORY_DEPRECATION` is truthy (default).
         """
-        # Import unified components locally to avoid circular imports
-        from flock.components.evaluation.declarative_evaluation_component import (
-            DeclarativeEvaluationComponent,
-            DeclarativeEvaluationConfig,
-        )
-        from flock.components.utility.metrics_utility_component import (
-            MetricsUtilityComponent,
-            MetricsUtilityConfig,
-        )
-        from flock.components.utility.output_utility_component import (
-            OutputUtilityComponent,
-            OutputUtilityConfig,
-        )
-
-        if model and "gpt-oss" in model:
-            temperature = 1.0
-            max_tokens = 32768
+        _maybe_warn_factory_deprecation()
 
-        # Create evaluation component
-        eval_config = DeclarativeEvaluationConfig(
+        return DefaultAgent(
+            name=name,
+            description=description,
             model=model,
+            input=input,
+            output=output,
+            tools=tools,
+            servers=servers,
             use_cache=use_cache,
-            max_tokens=max_tokens,
             temperature=temperature,
+            max_tokens=max_tokens,
             max_tool_calls=max_tool_calls,
             max_retries=max_retries,
             stream=stream,
             include_thought_process=include_thought_process,
             include_reasoning=include_reasoning,
-        )
-        evaluator = DeclarativeEvaluationComponent(
-            name="default_evaluator", config=eval_config
-        )
-
-        # Create output utility component
-        output_config = OutputUtilityConfig(
-            render_table=enable_rich_tables,
-            theme=output_theme,
+            enable_rich_tables=enable_rich_tables,
+            output_theme=output_theme,
             no_output=no_output,
             print_context=print_context,
-        )
-        output_component = OutputUtilityComponent(
-            name="output_formatter", config=output_config
-        )
-
-        # Create metrics utility component
-        metrics_config = MetricsUtilityConfig(
-            latency_threshold_ms=alert_latency_threshold_ms
-        )
-        metrics_component = MetricsUtilityComponent(
-            name="metrics_tracker", config=metrics_config
-        )
-
-        # Create agent with unified components
-        agent = FlockAgent(
-            name=name,
-            input=input,
-            output=output,
-            tools=tools,
-            servers=servers,
-            model=model,
-            description=description,
-            components=[evaluator, output_component, metrics_component],
-            config=FlockAgentConfig(write_to_file=write_to_file,
-                                    wait_for_input=wait_for_input),
+            write_to_file=write_to_file,
+            wait_for_input=wait_for_input,
+            alert_latency_threshold_ms=alert_latency_threshold_ms,
             next_agent=next_agent,
             temporal_activity_config=temporal_activity_config,
         )
 
-        return agent
-
     @staticmethod
     def create_scheduled_agent(
         name: str,
@@ -518,22 +505,47 @@ class FlockFactory:
             **kwargs,
         )
 
-        agent = (
-            FlockFactory.create_default_agent(  # Reuse your existing factory
-                name=name,
-                description=description,
-                model=model,
-                input="trigger_time: str | Time of scheduled execution",
-                output=output,
-                tools=tools,
-                servers=servers,
-                temporal_activity_config=temporal_activity_config,
-                use_cache=use_cache,
-                temperature=temperature,
-                next_agent=next_agent,
-                **kwargs,
-            )
+        agent = DefaultAgent(
+            name=name,
+            description=description,
+            model=model,
+            input="trigger_time: str | Time of scheduled execution",
+            output=output,
+            tools=tools,
+            servers=servers,
+            temporal_activity_config=temporal_activity_config,
+            use_cache=use_cache,
+            temperature=temperature,
+            next_agent=next_agent,
+            **kwargs,
         )
         agent.config = agent_config  # Assign the scheduled agent config
 
         return agent
+
+
+# ---- one-time deprecation warning helper ----
+_FACTORY_DEPRECATION_WARNED = False
+_factory_logger = get_logger("core.factory")
+
+
+def _maybe_warn_factory_deprecation() -> None:  # pragma: no cover - side-effect
+    global _FACTORY_DEPRECATION_WARNED
+    if _FACTORY_DEPRECATION_WARNED:
+        return
+    flag = os.getenv("FLOCK_WARN_FACTORY_DEPRECATION", "1").strip()
+    enabled = flag not in {"0", "false", "False", "off", "OFF"}
+    if not enabled:
+        _FACTORY_DEPRECATION_WARNED = True
+        return
+    msg = (
+        "FlockFactory.create_default_agent is deprecated and will be removed in a future release. "
+        "Please use DefaultAgent(...) instead. Set FLOCK_WARN_FACTORY_DEPRECATION=0 to disable this notice."
+    )
+    # Log and emit a warnings.warn once
+    try:
+        _factory_logger.warning(msg)
+    except Exception:
+        pass
+    warnings.warn(msg, DeprecationWarning, stacklevel=2)
+    _FACTORY_DEPRECATION_WARNED = True

flock/core/logging/telemetry.py

@@ -1,8 +1,8 @@
 """This module sets up OpenTelemetry tracing for a service."""
 
+import os
 import sys
 
-import os
 from opentelemetry import trace
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
@@ -77,7 +77,9 @@ class TelemetryConfig:
             return False
         try:
             # If a provider is already installed (typically by user/tests), don't override it
-            from opentelemetry.sdk.trace import TracerProvider as SDKTracerProvider  # type: ignore
+            from opentelemetry.sdk.trace import (
+                TracerProvider as SDKTracerProvider,  # type: ignore
+            )
 
             current = trace.get_tracer_provider()
             if isinstance(current, SDKTracerProvider):
@@ -184,6 +186,9 @@ class TelemetryConfig:
             sys.__excepthook__(exc_type, exc_value, exc_traceback)
             return
 
+        if not self.global_tracer:
+            return
+
         # Use OpenTelemetry to record the exception
         with self.global_tracer.start_as_current_span(
             "UnhandledException"

flock/core/mcp/flock_mcp_server.py

@@ -153,6 +153,10 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
                     self.client_manager = await self.initialize()
                     self.initialized = True
                     await self.post_init()
+            if not self.config.allow_all_tools:
+                whitelist = self.config.feature_config.tool_whitelist
+                if whitelist is not None and len(whitelist) > 0 and name not in whitelist:
+                    return None
             async with self.condition:
                 try:
                     additional_params: dict[str, Any] = {
@@ -217,6 +221,14 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
                         run_id=run_id,
                         additional_params=additional_params,
                     )
+                    # filtering based on whitelist
+                    if not self.config.allow_all_tools:
+                        whitelist = self.config.feature_config.tool_whitelist
+                        filtered_results: list[FlockMCPTool] = []
+                        for tool in result:
+                            if tool.name in whitelist:
+                                filtered_results.append(tool)
+                        result = filtered_results
                     converted_tools = [
                         t.as_dspy_tool(server=self) for t in result
                     ]
@@ -263,6 +275,13 @@ class FlockMCPServer(BaseModel, Serializable, ABC):
         )
         with tracer.start_as_current_span("server.pre_init") as span:
             span.set_attribute("server.name", self.config.name)
+            # run whitelist checks
+            whitelist = self.config.feature_config
+            if whitelist is not None and len(whitelist) > 0:
+                self.config.feature_config = False
+            else:
+                # if the whitelist is none..
+                self.config.allow_all_tools = True
             try:
                 for module in self.get_enabled_components():
                     await module.on_pre_server_init(self)

flock/core/mcp/flock_mcp_tool.py

@@ -3,6 +3,7 @@
 from typing import Any, TypeVar
 
 from dspy import Tool as DSPyTool
+from dspy.adapters.types.tool import convert_input_schema_to_tool_args
 from mcp import Tool
 from mcp.types import CallToolResult, TextContent, ToolAnnotations
 from opentelemetry import trace
@@ -75,59 +76,14 @@ class FlockMCPTool(BaseModel):
             annotations=instance.annotations,
         )
 
-    def resolve_json_schema_reference(self, schema: dict) -> dict:
-        """Recursively resolve json model schema, expanding all references."""
-        if "$defs" not in schema and "definitions" not in schema:
-            return schema
-
-        def resolve_refs(obj: Any) -> Any:
-            if not isinstance(obj, dict[list, list]):
-                return obj
-            if isinstance(obj, dict) and "$ref" in obj:
-                # ref_path = obj["$ref"].split("/")[-1]
-                return {resolve_refs(v) for k, v in obj.items()}
-
-            return [resolve_refs(item) for item in obj]
-
-        resolved_schema = resolve_refs(schema)
-
-        resolved_schema.pop("$defs", None)
-        return resolved_schema
-
-    def _convert_input_schema_to_tool_args(
-        self, input_schema: dict[str, Any]
-    ) -> tuple[dict[str, Any], dict[str, type], dict[str, str]]:
-        """Convert an input schema to tool arguments compatible with Dspy Tool.
-
-        Args:
-            schema: an input schema describing the tool's input parameters
-
-        Returns:
-            A tuple of (args, arg_types, arg_desc) for Dspy Tool definition
-        """
-        args, arg_types, arg_desc = {}, {}, {}
-        properties = input_schema.get("properties")
-        if properties is None:
-            return args, arg_types, arg_desc
-
-        required = input_schema.get("required", [])
-
-        defs = input_schema.get("$defs", {})
-
-        for name, prop in properties.items():
-            if len(defs) > 0:
-                prop = self.resolve_json_schema_reference(
-                    {"$defs": defs, **prop}
-                )
-
-            args[name] = prop
-
-            arg_types[name] = TYPE_MAPPING.get(prop.get("type"), Any)
-            arg_desc[name] = prop.get("description", "No description provided")
-            if name in required:
-                arg_desc[name] += " (Required)"
-
-        return args, arg_types, arg_desc
+    # Use DSPy's converter for JSON Schema → Tool args to stay aligned with DSPy.
+    def _convert_input_schema_to_tool_args(self, input_schema: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any], dict[str, str]]:
+        try:
+            return convert_input_schema_to_tool_args(input_schema)
+        except Exception as e:  # pragma: no cover - defensive
+            logger.error("Failed to convert MCP tool schema to DSPy tool args: %s", e)
+            # Fallback to empty definitions to avoid breaking execution
+            return {}, {}, {}
 
     def _convert_mcp_tool_result(
         self, call_tool_result: CallToolResult

flock/core/mcp/mcp_config.py

@@ -302,22 +302,31 @@ class FlockMCPFeatureConfiguration(BaseModel, Serializable):
     """Base Configuration Class for switching MCP Features on and off."""
 
     roots_enabled: bool = Field(
-        default=False,
+        default=True,
         description="Whether or not the Roots feature is enabled for this client.",
     )
 
     sampling_enabled: bool = Field(
-        default=False,
+        default=True,
         description="Whether or not the Sampling feature is enabled for this client.",
     )
 
     tools_enabled: bool = Field(
-        default=False,
+        default=True,
         description="Whether or not the Tools feature is enabled for this client.",
     )
 
+    tool_whitelist: list[str] | None = Field(
+        default=None,
+        description="Whitelist of tool names that are enabled for this MCP server. "
+                   "If provided, only tools with names in this list will be available "
+                   "from this server. Used in conjunction with allow_all_tools setting. "
+                   "Note: Agent-level tool filtering is generally preferred over "
+                   "server-level filtering for better granular control."
+    )
+
     prompts_enabled: bool = Field(
-        default=False,
+        default=True,
         description="Whether or not the Prompts feature is enabled for this client.",
     )
 
@@ -357,6 +366,15 @@ class FlockMCPConfiguration(BaseModel, Serializable):
         ..., description="Name of the server the client connects to."
     )
 
+    allow_all_tools: bool = Field(
+        default=True,
+        description="Whether to allow usage of all tools from this MCP server. "
+                   "When True (default), all tools are available unless restricted "
+                   "by tool_whitelist. When False, tool access is controlled entirely "
+                   "by tool_whitelist (if provided). Setting to False with no whitelist "
+                   "will block all tools from this server."
+    )
+
     connection_config: FlockMCPConnectionConfiguration = Field(
         ..., description="MCP Connection Configuration for a client."
     )