flock-core 0.5.0b16__py3-none-any.whl → 0.5.0b18__py3-none-any.whl

flock/components/evaluation/declarative_evaluation_component.py

@@ -2,7 +2,7 @@
 """DeclarativeEvaluationComponent - DSPy-based evaluation using the unified component system."""
 
 from collections.abc import Generator
-from typing import Any, override
+from typing import Any, Literal, override
 
 from temporalio import workflow
 
@@ -29,7 +29,7 @@ class DeclarativeEvaluationConfig(AgentComponentConfig):
     model: str | None = "openai/gpt-4o"
     use_cache: bool = True
     temperature: float = 1.0
-    max_tokens: int = 8192
+    max_tokens: int = 32000
     max_retries: int = 3
     max_tool_calls: int = 10
     stream: bool = Field(
@@ -44,6 +44,14 @@ class DeclarativeEvaluationConfig(AgentComponentConfig):
         default=False,
         description="Include the reasoning in the output.",
     )
+    adapter: Literal["chat", "json", "xml", "two_step"] | None = Field(
+        default=None,
+        description="Optional DSPy adapter to use for formatting/parsing.",
+    )
+    extraction_model: str | None = Field(
+        default=None,
+        description="Extraction LM for TwoStepAdapter when adapter='two_step'",
+    )
     kwargs: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -70,7 +78,7 @@ class DeclarativeEvaluationComponent(
         super().__init__(**data)
 
     @override
-    def set_model(self, model: str, temperature: float = 1.0, max_tokens: int = 8192) -> None:
+    def set_model(self, model: str, temperature: float = 1.0, max_tokens: int = 32000) -> None:
         """Set the model for the evaluation component."""
         self.config.model = model
         self.config.temperature = temperature
@@ -87,16 +95,32 @@ class DeclarativeEvaluationComponent(
         """Core evaluation logic using DSPy - migrated from DeclarativeEvaluator."""
         logger.debug(f"Starting declarative evaluation for component '{self.name}'")
 
-        # Setup DSPy context with LM (directly from original implementation)
-        with dspy.context(
-            lm=dspy.LM(
-                model=self.config.model or agent.model,
-                cache=self.config.use_cache,
-                temperature=self.config.temperature,
-                max_tokens=self.config.max_tokens,
-                num_retries=self.config.max_retries,
-            )
-        ):
+        # Prepare LM and optional adapter; keep settings changes scoped with dspy.context
+        lm = dspy.LM(
+            model=self.config.model or agent.model,
+            cache=self.config.use_cache,
+            temperature=self.config.temperature,
+            max_tokens=self.config.max_tokens,
+            num_retries=self.config.max_retries,
+        )
+
+        adapter = None
+        if self.config.adapter:
+            try:
+                if self.config.adapter == "json":
+                    adapter = dspy.JSONAdapter()
+                elif self.config.adapter == "xml":
+                    adapter = dspy.XMLAdapter()
+                elif self.config.adapter == "two_step":
+                    extractor = dspy.LM(self.config.extraction_model or "openai/gpt-4o-mini")
+                    adapter = dspy.TwoStepAdapter(extraction_model=extractor)
+                else:
+                    # chat is default; leave adapter=None
+                    adapter = None
+            except Exception as e:
+                logger.warning(f"Failed to construct adapter '{self.config.adapter}': {e}. Proceeding without.")
+
+        with dspy.context(lm=lm, adapter=adapter):
             try:
                 from rich.console import Console
                 console = Console()
@@ -136,11 +160,11 @@ class DeclarativeEvaluationComponent(
 
             # Execute with streaming or non-streaming
             if self.config.stream:
-                return await self._execute_streaming(agent_task, inputs, agent, console)
+                return await self._execute_streaming(_dspy_signature, agent_task, inputs, agent, console)
             else:
                 return await self._execute_standard(agent_task, inputs, agent)
 
-    async def _execute_streaming(self, agent_task, inputs: dict[str, Any], agent: Any, console) -> dict[str, Any]:
+    async def _execute_streaming(self, signature, agent_task, inputs: dict[str, Any], agent: Any, console) -> dict[str, Any]:
         """Execute DSPy program in streaming mode (from original implementation)."""
         logger.info(f"Evaluating agent '{agent.name}' with async streaming.")
 
@@ -148,34 +172,70 @@ class DeclarativeEvaluationComponent(
             logger.error("agent_task is not callable, cannot stream.")
             raise TypeError("DSPy task could not be created or is not callable.")
 
-        streaming_task = dspy.streamify(agent_task, is_async_program=True)
+        # Prepare stream listeners for any string output fields
+        listeners = []
+        try:
+            for name, field in signature.output_fields.items():
+                if field.annotation is str:
+                    listeners.append(dspy.streaming.StreamListener(signature_field_name=name))
+        except Exception:
+            listeners = []
+
+        streaming_task = dspy.streamify(
+            agent_task,
+            is_async_program=True,
+            stream_listeners=listeners if listeners else None,
+        )
         stream_generator: Generator = streaming_task(**inputs)
-        delta_content = ""
 
         console.print("\n")
-        async for chunk in stream_generator:
-            if (
-                hasattr(chunk, "choices")
-                and chunk.choices
-                and hasattr(chunk.choices[0], "delta")
-                and chunk.choices[0].delta
-                and hasattr(chunk.choices[0].delta, "content")
-            ):
-                delta_content = chunk.choices[0].delta.content
-
-            if delta_content:
-                console.print(delta_content, end="")
-
-            result_dict, cost, lm_history = self._process_result(chunk, inputs)
-            self._cost = cost
-            self._lm_history = lm_history
+        final_result: dict[str, Any] | None = None
+        async for value in stream_generator:
+            # Handle DSPy streaming artifacts
+            try:
+                from dspy.streaming import StatusMessage, StreamResponse
+                from litellm import ModelResponseStream
+                import dspy as _d
+            except Exception:
+                StatusMessage = object  # type: ignore
+                StreamResponse = object  # type: ignore
+                ModelResponseStream = object  # type: ignore
+                _d = None
+
+            if isinstance(value, StatusMessage):
+                # Optionally surface status to console
+                console.print(f"[status] {getattr(value, 'message', '')}")
+                continue
+            if isinstance(value, StreamResponse):
+                token = getattr(value, "token", None)
+                if token:
+                    console.print(token, end="")
+                continue
+            if isinstance(value, ModelResponseStream):
+                # Raw model chunk; print minimal content if available for debug
+                try:
+                    chunk = value
+                    text = chunk.choices[0].delta.content or ""
+                    if text:
+                        console.print(text, end="")
+                except Exception:
+                    pass
+                continue
+            if _d and isinstance(value, _d.Prediction):
+                # Final prediction
+                result_dict, cost, lm_history = self._process_result(value, inputs)
+                self._cost = cost
+                self._lm_history = lm_history
+                final_result = result_dict
 
         console.print("\n")
-        result_dict = self.filter_reasoning(
-                    result_dict, self.config.include_reasoning
-                )
+        if final_result is None:
+            raise RuntimeError("Streaming did not yield a final prediction.")
+        final_result = self.filter_reasoning(
+            final_result, self.config.include_reasoning
+        )
         return self.filter_thought_process(
-            result_dict, self.config.include_thought_process
+            final_result, self.config.include_thought_process
         )
 
     async def _execute_standard(self, agent_task, inputs: dict[str, Any], agent: Any) -> dict[str, Any]:
@@ -189,8 +249,8 @@ class DeclarativeEvaluationComponent(
             self._cost = cost
             self._lm_history = lm_history
             result_dict = self.filter_reasoning(
-                    result_dict, self.config.include_reasoning
-                )
+                result_dict, self.config.include_reasoning
+            )
             return self.filter_thought_process(
                 result_dict, self.config.include_thought_process
             )
@@ -226,4 +286,3 @@ class DeclarativeEvaluationComponent(
                 for k, v in result_dict.items()
                 if not (k.startswith("reasoning"))
             }
-

flock/components/utility/memory_utility_component.py

@@ -542,7 +542,9 @@ class MemoryUtilityComponent(UtilityComponent):
             "Extract key concepts from text",
             "text: str | Input text -> concepts: list[str] | key concepts lower case",
         )
-        agent._configure_language_model(agent.model, True, 0.0, 8192)
-        predictor = agent._select_task(concept_signature, "Completion")
-        res = predictor(text=text)
+        import dspy
+        lm = dspy.LM(model=agent.model, cache=True, temperature=0.0, max_tokens=8192)
+        predictor = agent._select_task(concept_signature, "Predict")
+        with dspy.settings.context(lm=lm):
+            res = predictor(text=text)
         return set(getattr(res, "concepts", []))

flock/core/__init__.py

@@ -11,6 +11,7 @@ from typing import Any
 __all__ = [
     "Flock",
     "FlockAgent",
+    "DefaultAgent",
     "FlockContext",
     "FlockFactory",
     # Components
@@ -43,6 +44,10 @@ def __getattr__(name: str) -> Any:  # pragma: no cover - thin loader
         from .flock_agent import FlockAgent
 
         return FlockAgent
+    if name == "DefaultAgent":
+        from .agent.default_agent import DefaultAgent
+
+        return DefaultAgent
     if name == "FlockContext":
         from .context.context import FlockContext
 

flock/core/agent/default_agent.py

@@ -0,0 +1,170 @@
+"""DefaultAgent: explicit preset agent wiring standard components.
+
+This class replaces the need for using FlockFactory for common setups by
+providing a clear, explicit Agent class that mirrors the factory's kwargs
+and composes the standard components under the hood.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from flock.components.utility.metrics_utility_component import (
+    MetricsUtilityComponent,
+    MetricsUtilityConfig,
+)
+from flock.core.config.flock_agent_config import FlockAgentConfig
+from flock.core.flock_agent import DynamicStr, FlockAgent
+from flock.core.logging.formatters.themes import OutputTheme
+from flock.core.mcp.flock_mcp_server import FlockMCPServer
+from flock.workflow.temporal_config import TemporalActivityConfig
+
+
+class DefaultAgent(FlockAgent):
+    """Explicit agent class wiring standard evaluation + utility components.
+
+    Components included:
+    - DeclarativeEvaluationComponent (LLM evaluation)
+    - OutputUtilityComponent (formatting/printing)
+    - MetricsUtilityComponent (latency tracking)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: DynamicStr | None = None,
+        model: str | None = None,
+        input: DynamicStr | None = None,
+        output: DynamicStr | None = None,
+        tools: list[Callable[..., Any] | Any] | None = None,
+        servers: list[str | FlockMCPServer] | None = None,
+        tool_whitelist: list[str] | None = None,
+        # Evaluation parameters
+        use_cache: bool = False,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        max_tool_calls: int = 0,
+        max_retries: int = 2,
+        stream: bool = False,
+        include_thought_process: bool = False,
+        include_reasoning: bool = False,
+        # Output utility parameters
+        enable_rich_tables: bool = True,
+        output_theme: OutputTheme | None = None,
+        no_output: bool = False,
+        print_context: bool = False,
+        # Agent config
+        write_to_file: bool = False,
+        wait_for_input: bool = False,
+        # Metrics utility
+        alert_latency_threshold_ms: int = 30_000,
+        # Workflow
+        next_agent: DynamicStr | None = None,
+        temporal_activity_config: TemporalActivityConfig | None = None,
+    ):
+        """Initialize a DefaultAgent with standard components and configuration.
+
+        Args:
+            name: Unique identifier for the agent
+            description: Human-readable description of the agent's purpose
+            model: Model identifier (e.g., 'openai/gpt-4o'). Uses Flock default if None
+            input: Input signature for the agent
+            output: Output signature for the agent
+            tools: List of callable tools the agent can use
+            servers: List of MCP servers the agent can connect to
+            tool_whitelist: List of tool names that this agent is allowed to use.
+                          If provided, the agent will only have access to tools
+                          whose names are in this list. This applies to both native
+                          Python tools and MCP tools. Recommended for security and
+                          to prevent tool conflicts in multi-agent workflows.
+            use_cache: Whether to enable caching for evaluation
+            temperature: Sampling temperature for LLM generation
+            max_tokens: Maximum tokens for LLM response
+            max_tool_calls: Maximum number of tool calls per evaluation
+            max_retries: Maximum retries for failed LLM calls
+            stream: Whether to enable streaming responses
+            include_thought_process: Include reasoning in output
+            include_reasoning: Include detailed reasoning steps
+            enable_rich_tables: Enable rich table formatting for output
+            output_theme: Theme for output formatting
+            no_output: Disable output printing
+            print_context: Include context in output
+            write_to_file: Save outputs to file
+            wait_for_input: Wait for user input after execution
+            alert_latency_threshold_ms: Threshold for latency alerts
+            next_agent: Next agent in workflow chain
+            temporal_activity_config: Configuration for Temporal workflow execution
+        """
+        # Import evaluation/output components lazily to avoid heavy imports at module import time
+        from flock.components.evaluation.declarative_evaluation_component import (
+            DeclarativeEvaluationComponent,
+            DeclarativeEvaluationConfig,
+        )
+        from flock.components.utility.output_utility_component import (
+            OutputUtilityComponent,
+            OutputUtilityConfig,
+        )
+
+        # Apply sensible defaults for special models if needed
+        if model and "gpt-oss" in model:
+            # Ensure defaults are generous for local OSS models
+            temperature = 1.0
+            max_tokens = 32_768
+
+        # Evaluation component
+        _eval_kwargs = dict(
+            model=model,
+            use_cache=use_cache,
+            temperature=temperature,
+            max_tool_calls=max_tool_calls,
+            max_retries=max_retries,
+            stream=stream,
+            include_thought_process=include_thought_process,
+            include_reasoning=include_reasoning,
+        )
+        if max_tokens is not None:
+            _eval_kwargs["max_tokens"] = max_tokens
+        eval_config = DeclarativeEvaluationConfig(**_eval_kwargs)
+        evaluator = DeclarativeEvaluationComponent(
+            name="default_evaluator", config=eval_config
+        )
+
+        # Output utility component
+        _output_kwargs = dict(
+            render_table=enable_rich_tables,
+            no_output=no_output,
+            print_context=print_context,
+        )
+        if output_theme is not None:
+            _output_kwargs["theme"] = output_theme
+        output_config = OutputUtilityConfig(**_output_kwargs)
+        output_component = OutputUtilityComponent(
+            name="output_formatter", config=output_config
+        )
+
+        # Metrics utility component
+        metrics_config = MetricsUtilityConfig(
+            latency_threshold_ms=alert_latency_threshold_ms
+        )
+        metrics_component = MetricsUtilityComponent(
+            name="metrics_tracker", config=metrics_config
+        )
+
+        super().__init__(
+            name=name,
+            model=model,
+            description=description,
+            input=input,
+            output=output,
+            tools=tools,
+            servers=servers,
+            tool_whitelist=tool_whitelist,
+            components=[evaluator, output_component, metrics_component],
+            config=FlockAgentConfig(
+                write_to_file=write_to_file,
+                wait_for_input=wait_for_input,
+            ),
+            next_agent=next_agent,
+            temporal_activity_config=temporal_activity_config,
+        )

flock/core/agent/flock_agent_integration.py

@@ -9,6 +9,12 @@ from typing import TYPE_CHECKING, Any, TypeVar, cast
 from flock.core.context.context import FlockContext
 from flock.core.logging.logging import get_logger
 from flock.core.mcp.flock_mcp_server import FlockMCPServer
+from pydantic import BaseModel
+from flock.core.registry import get_registry
+from flock.core.serialization.serialization_utils import (
+    _format_type_to_string,
+    collect_pydantic_models,
+)
 
 if TYPE_CHECKING:
     from flock.core.flock_agent import FlockAgent
@@ -83,10 +89,58 @@ class FlockAgentIntegration:
         self.agent = agent
 
     def _resolve(self, raw: str | Callable[..., str], name: str, ctx: FlockContext | None) -> str | None:
+        # Support Pydantic BaseModel classes (alternative I/O definitions)
+        try:
+            if isinstance(raw, type) and issubclass(raw, BaseModel):
+                return self._build_spec_from_pydantic(raw)
+            # Also support instances directly (use their class schema)
+            if isinstance(raw, BaseModel):
+                return self._build_spec_from_pydantic(type(raw))
+        except Exception:
+            # If introspection failed, fall through to normal handling
+            pass
+
         if callable(raw):
             raw = adapt(name, raw)(ctx or FlockContext())
         return raw
 
+    def _build_spec_from_pydantic(self, model_cls: type[BaseModel]) -> str:
+        """Builds a flock I/O spec string from a Pydantic BaseModel class.
+
+        Format per field: "name: type | description"; description omitted when empty.
+        Also ensures involved Pydantic models are registered in the TypeRegistry
+        so type resolution works when constructing DSPy signatures.
+        """
+        # Proactively register this model and any nested models
+        try:
+            registry = get_registry()
+            registry.register_type(model_cls, name=model_cls.__name__)
+            # Register nested Pydantic models used in type hints
+            if hasattr(model_cls, "model_fields"):
+                for _, f in model_cls.model_fields.items():
+                    ann = getattr(f, "annotation", None)
+                    for m in collect_pydantic_models(ann):
+                        registry.register_type(m, name=m.__name__)
+        except Exception:
+            # Registration best-effort; continue building spec
+            pass
+
+        fields = []
+        # Pydantic v2: class-level model_fields
+        if not hasattr(model_cls, "model_fields") or model_cls.model_fields is None:  # type: ignore[attr-defined]
+            return ""
+
+        for name, field in model_cls.model_fields.items():  # type: ignore[attr-defined]
+            type_hint = getattr(field, "annotation", None)
+            type_str = _format_type_to_string(type_hint) if type_hint is not None else "str"
+            desc = getattr(field, "description", None) or ""
+            if desc:
+                fields.append(f"{name}: {type_str} | {desc}")
+            else:
+                fields.append(f"{name}: {type_str}")
+
+        return ", ".join(fields)
+
     def resolve_description(self, context: FlockContext | None = None) -> str | None:
         """Resolve the agent's description, handling callable descriptions."""
         return self._resolve(self.agent.description_spec, "description", context)

flock/core/agent/flock_agent_lifecycle.py

@@ -131,6 +131,15 @@ class FlockAgentLifecycle:
                 if self.agent.servers:
                     mcp_tools = await self.agent._integration.get_mcp_tools()
 
+                # Filter tools based on the agent's whitelist (if it has been provided)
+                if self.agent.tool_whitelist is not None and len(self.agent.tool_whitelist) > 0:
+                    for tool in mcp_tools:
+                        if hasattr(tool, "name") and tool.name not in self.agent.tool_whitelist:
+                            mcp_tools.remove(tool)
+                    for tool in registered_tools:
+                        if hasattr(tool, "__name__") and tool.__name__ not in self.agent.tool_whitelist:
+                            registered_tools.remove(tool)
+
                 # --------------------------------------------------
                 # Use evaluator component's evaluate_core method
                 # --------------------------------------------------

flock/core/context/context.py

@@ -178,9 +178,8 @@ class FlockContext(Serializable, BaseModel):
                     return AgentRunRecord(
                         **{
                             **obj,
-                            "timestamp": datetime.fromisoformat(
-                                obj["timestamp"]
-                            ),
+                            "timestamp": obj["timestamp"]
+                            ,
                         }
                     )
                 if "agent_type" in obj:

flock/core/execution/local_executor.py

@@ -1,4 +1,4 @@
-# src/your_package/core/execution/local_executor.py
+# src/flock/core/execution/local_executor.py
 from flock.core.context.context import FlockContext
 from flock.core.logging.logging import get_logger
 from flock.workflow.activities import (

flock/core/execution/temporal_executor.py

@@ -1,4 +1,4 @@
-# src/your_package/core/execution/temporal_executor.py
+# src/flock/core/execution/temporal_executor.py
 
 import asyncio  # Import asyncio
 from typing import TYPE_CHECKING, Any
@@ -20,6 +20,7 @@ from flock.workflow.temporal_config import (
     TemporalWorkflowConfig,
 )
 from flock.workflow.temporal_setup import create_temporal_client, setup_worker
+from flock.config import TEMPORAL_SERVER_URL
 
 logger = get_logger("flock")
 
@@ -50,7 +51,7 @@ async def run_temporal_workflow(
         wf_config = flock_instance.temporal_config or TemporalWorkflowConfig()
 
         logger.debug("Creating Temporal client")
-        flock_client = await create_temporal_client()
+        flock_client = await create_temporal_client(server_address=TEMPORAL_SERVER_URL)
 
         # Determine if we need to manage an in-process worker
         start_worker_locally = flock_instance.temporal_start_in_process_worker
@@ -70,12 +71,9 @@ async def run_temporal_workflow(
                 [execute_single_agent, determine_next_agent],
             )
 
-            # Run the worker in the background
+            # Run the worker in the background; result awaiting will block until a worker picks up tasks
             worker_task = asyncio.create_task(worker.run())
             logger.info("Temporal worker started in background.")
-
-            # Allow worker time to start polling (heuristic for local testing)
-            await asyncio.sleep(2)
         else:
             logger.info(
                 "Skipping in-process worker startup. Assuming dedicated workers are running."

flock/core/flock_agent.py

@@ -35,11 +35,11 @@ DynamicStr = str | Callable[[FlockContext], str]
 
 class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
     """Unified FlockAgent using the new component architecture.
-    
+
     This is the next-generation FlockAgent that uses a single components list
     instead of separate evaluator, router, and modules. All agent functionality
     is now provided through AgentComponent instances.
-    
+
     Key changes:
     - components: list[AgentComponent] - unified component list
     - next_agent: str | None - explicit workflow state
@@ -79,6 +79,19 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         default=None,
         description="List of callable tools the agent can use. These must be registered.",
     )
+
+    tool_whitelist: list[str] | None = Field(
+        default=None,
+        description="Whitelist of tool names that this agent can use during execution. "
+                   "If provided, the agent will only have access to tools whose names "
+                   "are in this list. This applies to both native Python tools (identified "
+                   "by __name__) and MCP tools (identified by name attribute). "
+                   "When combined with server-level tool filtering, the agent gets access "
+                   "to the intersection of both whitelists. If None, all available tools "
+                   "from servers and native tools are accessible. "
+                   "Recommended over server-level filtering for granular control."
+    )
+
     servers: list[str | FlockMCPServer] | None = Field(
         default=None,
         description="List of MCP Servers the agent can use to enhance its capabilities.",
@@ -124,6 +137,7 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         output: DynamicStr | None = None,
         tools: list[Callable[..., Any]] | None = None,
         servers: list[str | FlockMCPServer] | None = None,
+        tool_whitelist: list[str] | None = None,
         components: list[AgentComponent] | None = None,
         config: FlockAgentConfig | None = None,
         next_agent: DynamicStr | None = None,
@@ -140,6 +154,7 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
             output=output,
             tools=tools,
             servers=servers,
+            tool_whitelist=tool_whitelist,
             components=components if components is not None else [],
             config=config,
             temporal_activity_config=temporal_activity_config,