flock-core 0.5.0b26__tar.gz → 0.5.0b27__tar.gz

{flock_core-0.5.0b26 → flock_core-0.5.0b27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b26
+Version: 0.5.0b27
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE

{flock_core-0.5.0b26 → flock_core-0.5.0b27}/examples/02a-inputs-and-outputs.py

@@ -2,11 +2,10 @@
 import json
 
 from flock.cli.utils import print_header, print_subheader, print_success
-from flock.core import DefaultAgent, Flock
+from flock.core import DefaultAgent, Flock, flock_tool
 from flock.core.logging.logging import configure_logging
-from flock.core.registry.decorators import flock_tool
 
-MODEL = "azure/gpt-4.1"
+MODEL = "azure/gpt-5-mini"
 
 flock = Flock(
     name="example_02a", description="The flock input and output syntax", model=MODEL
@@ -33,13 +32,12 @@ def save_movie_to_file(title: str, synopsis: str):
 # If you need to specify the agents behavior, you can do so with the description field.
 presentation_agent = DefaultAgent(
     name="my_movie_agent",
-    description="Creates a fun movie about a given topic, and saves it to a file",  # Isn't just a description, but also a control mechanism
+    description="Creates a fun movie about a given topic, and saves it to a file with save_movie_to_file",  # Isn't just a description, but also a control mechanism
     input="topic: str",
     output="fun_title: str | The funny title of the movie in all caps, "
     "runtime: int | The runtime of the movie in minutes, "
     "synopsis: str | A crazy over the top synopsis of the movie, "
     "characters: list[dict[str, str]] | Key is character name, Value is a character description ",
-    tools=[save_movie_to_file],
 )
 flock.add_agent(presentation_agent)
 

flock_core-0.5.0b27/examples/02b-inputs-and-outputs.py

@@ -0,0 +1,59 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from flock.cli.utils import print_header, print_subheader, print_success
+from flock.core import DefaultAgent, Flock
+from flock.core.logging.logging import configure_logging
+from flock.core.registry import (
+    flock_type,  # Decorator for registering custom types
+)
+
+# Logging (internal logs, external logs)
+# configure_logging("DEBUG", "DEBUG")
+
+@flock_type
+class MovieIdea(BaseModel):
+    """The idea of a movie."""
+    topic: str = Field(..., description="The topic of the movie.")
+    genre: Literal["comedy", "drama", "horror", "action", "adventure"] = Field(
+        ..., description="The genre of the movie."
+    )
+
+@flock_type
+class Movie(BaseModel):
+    """The movie."""
+    fun_title: str = Field(..., description="The title of the movie.")
+    runtime: int = Field(..., description="The runtime of the movie.", gt=200)
+    synopsis: str = Field(..., description="The synopsis of the movie.")
+    characters: list[dict[str, str]] = Field(
+        ..., description="The characters of the movie."
+    )
+
+
+MODEL = "azure/gpt-5-mini"
+
+flock = Flock(
+    name="example_02", description="The flock input and output syntax", model=MODEL
+)
+
+
+presentation_agent = DefaultAgent(
+    name="my_movie_agent",
+    description="Creates a fun movie about a given topic",  # Isn't just a description, but also a control mechanism
+    input="input: MovieIdea",
+    output="output: Movie",
+)
+flock.add_agent(presentation_agent)
+
+
+result = flock.run(agent=presentation_agent, input={"input": MovieIdea(topic="AI agents", genre="comedy")})
+
+print_header("Results")
+print_subheader(result.fun_title)
+print_success(result.synopsis)
+print_success(result.characters)
+
+# YOUR TURN!
+# Try changing the types and descriptions of the input and output fields
+# What happens if agent description is at odds with the input and output fields?

flock_core-0.5.0b26/examples/02b-inputs-and-outputs.py → flock_core-0.5.0b27/examples/02c-inputs-and-outputs.py

@@ -24,14 +24,14 @@ class MovieIdea(BaseModel):
 class Movie(BaseModel):
     """The movie."""
     fun_title: str = Field(..., description="The title of the movie.")
-    runtime: int = Field(..., description="The runtime of the movie.")
+    runtime: int = Field(..., description="The runtime of the movie.", gt=200)
     synopsis: str = Field(..., description="The synopsis of the movie.")
     characters: list[dict[str, str]] = Field(
         ..., description="The characters of the movie."
     )
 
 
-MODEL = "azure/gpt-4.1"
+MODEL = "azure/gpt-5-mini"
 
 flock = Flock(
     name="example_02", description="The flock input and output syntax", model=MODEL
@@ -43,6 +43,7 @@ presentation_agent = DefaultAgent(
     description="Creates a fun movie about a given topic",  # Isn't just a description, but also a control mechanism
     input=MovieIdea,
     output=Movie,
+    include_status_output=True,
 )
 flock.add_agent(presentation_agent)
 

{flock_core-0.5.0b26 → flock_core-0.5.0b27}/examples/03-using-a-tool.py

@@ -7,7 +7,7 @@ def write_file(string: str, file_path: str) -> None:
     f.write(string)
 
 
-flock = Flock(model="azure/gpt-4.1")
+flock = Flock(model="azure/gpt-5")
 
 read_website_fast_mcp_server = FlockFactory.create_mcp_server(
     name="read-website-fast-mcp-server",

flock_core-0.5.0b27/examples/dspy_engine/dspy_engine.py

@@ -0,0 +1,289 @@
+from __future__ import annotations
+
+"""DSPy-powered engine component that mirrors the design implementation."""
+
+import json
+import os
+from typing import Any, Iterable, Mapping, Sequence
+
+from pydantic import BaseModel
+
+from flock_flow.artifacts import Artifact
+from flock_flow.components import EngineComponent
+from flock_flow.registry import type_registry
+from flock_flow.runtime import EvalInputs, EvalResult
+
+
+class DSPyEngine(EngineComponent):
+    """Execute a minimal DSPy program backed by a hosted LLM.
+
+    Behavior intentionally mirrors ``design/dspy_engine.py`` so that orchestration
+    relies on the same model resolution, signature preparation, and result
+    normalization logic.
+    """
+
+    name: str | None = "dspy"
+    model: str | None = None
+    instructions: str | None = None
+    temperature: float = 1.0
+    max_tokens: int = 16000
+    max_tool_calls: int = 10
+
+    async def evaluate(self, agent, ctx, inputs: EvalInputs) -> EvalResult:  # type: ignore[override]
+        if not inputs.artifacts:
+            return EvalResult(artifacts=[], state=dict(inputs.state))
+
+        model_name = self._resolve_model_name()
+        dspy_mod = self._import_dspy()
+
+        lm = dspy_mod.LM(model_name, temperature=self.temperature, max_tokens=self.max_tokens)
+
+        primary_artifact = self._select_primary_artifact(inputs.artifacts)
+        input_model = self._resolve_input_model(primary_artifact)
+        validated_input = self._validate_input_payload(input_model, primary_artifact.payload)
+        output_model = self._resolve_output_model(agent)
+
+        signature = self._prepare_signature(
+            dspy_mod,
+            description=self.instructions or agent.description,
+            input_schema=input_model,
+            output_schema=output_model,
+        )
+
+        sys_desc = self._system_description(self.instructions or agent.description)
+        stream_queue = self._extract_stream_queue(ctx)
+        with dspy_mod.context(lm=lm):
+            program = self._choose_program(dspy_mod, signature, agent.tools)
+            raw_result = await self._execute_program(
+                dspy_mod,
+                program,
+                description=sys_desc,
+                payload=validated_input,
+                stream_queue=stream_queue,
+            )
+
+        normalized_output = self._normalize_output_payload(getattr(raw_result, "output", None))
+        artifacts, errors = self._materialize_artifacts(normalized_output, agent.outputs, agent.name)
+
+        state = dict(inputs.state)
+        state.setdefault("dspy", {})
+        state["dspy"].update({"model": model_name, "raw": normalized_output})
+
+        logs: list[str] = []
+        if normalized_output is not None:
+            try:
+                logs.append(f"dspy.output={json.dumps(normalized_output)}")
+            except TypeError:
+                logs.append(f"dspy.output={normalized_output!r}")
+        logs.extend(f"dspy.error={message}" for message in errors)
+
+        result_artifacts = artifacts if artifacts else list(inputs.artifacts)
+        return EvalResult(artifacts=result_artifacts, state=state, logs=logs)
+
+    # ------------------------------------------------------------------
+    # Helpers mirroring the design engine
+
+    def _resolve_model_name(self) -> str:
+        model = self.model or os.getenv("TRELLIS_MODEL") or os.getenv("OPENAI_MODEL")
+        if not model:
+            raise NotImplementedError(
+                "DSPyEngine requires a configured model (set TRELLIS_MODEL, OPENAI_MODEL, or pass model=...)."
+            )
+        return model
+
+    def _import_dspy(self):  # pragma: no cover - import guarded by optional dependency
+        try:
+            import dspy
+        except Exception as exc:  # noqa: BLE001 - bubble as NotImplemented to match design behavior
+            raise NotImplementedError("DSPy is not installed or failed to import.") from exc
+        return dspy
+
+    def _select_primary_artifact(self, artifacts: Sequence[Artifact]) -> Artifact:
+        return artifacts[-1]
+
+    def _resolve_input_model(self, artifact: Artifact) -> type[BaseModel] | None:
+        try:
+            return type_registry.resolve(artifact.type)
+        except KeyError:
+            return None
+
+    def _resolve_output_model(self, agent) -> type[BaseModel] | None:
+        if not getattr(agent, "outputs", None):
+            return None
+        return agent.outputs[0].spec.model
+
+    def _validate_input_payload(
+        self,
+        schema: type[BaseModel] | None,
+        payload: Mapping[str, Any] | None,
+    ) -> dict[str, Any]:
+        data = dict(payload or {})
+        if schema is None:
+            return data
+        try:
+            return schema(**data).model_dump()
+        except Exception:
+            return data
+
+    def _prepare_signature(
+        self,
+        dspy_mod,
+        *,
+        description: str | None,
+        input_schema: type[BaseModel] | None,
+        output_schema: type[BaseModel] | None,
+    ):
+        fields = {
+            "description": (str, dspy_mod.InputField()),
+            "input": (input_schema or dict, dspy_mod.InputField()),
+            "output": (output_schema or dict, dspy_mod.OutputField()),
+        }
+        signature = dspy_mod.Signature(fields)
+        instruction = description or "Produce a valid output that matches the 'output' schema. Return only JSON."
+        return signature.with_instructions(instruction)
+
+    def _choose_program(self, dspy_mod, signature, tools: Iterable[Any]):
+        tools_list = list(tools or [])
+        try:
+            if tools_list:
+                return dspy_mod.ReAct(signature, tools=tools_list, max_iters=self.max_tool_calls)
+            return dspy_mod.Predict(signature)
+        except Exception:
+            return dspy_mod.Predict(signature)
+
+    def _system_description(self, description: str | None) -> str:
+        if description:
+            return description
+        return "Produce a valid output that matches the 'output' schema. Return only JSON."
+
+    def _normalize_output_payload(self, raw: Any) -> dict[str, Any]:
+        if isinstance(raw, BaseModel):
+            return raw.model_dump()
+        if isinstance(raw, str):
+            try:
+                return json.loads(raw)
+            except json.JSONDecodeError:
+                return {"text": raw}
+        if isinstance(raw, Mapping):
+            return dict(raw)
+        return {"value": raw}
+
+    def _materialize_artifacts(self, payload: dict[str, Any], outputs: Iterable[Any], produced_by: str):
+        artifacts: list[Artifact] = []
+        errors: list[str] = []
+        for output in outputs or []:
+            model_cls = output.spec.model
+            data = self._select_output_payload(payload, model_cls, output.spec.type_name)
+            try:
+                instance = model_cls(**data)
+            except Exception as exc:  # noqa: BLE001 - collect validation errors for logs
+                errors.append(str(exc))
+                continue
+            artifacts.append(
+                Artifact(
+                    type=output.spec.type_name,
+                    payload=instance.model_dump(),
+                    produced_by=produced_by,
+                )
+            )
+        return artifacts, errors
+
+    def _select_output_payload(
+        self,
+        payload: Mapping[str, Any],
+        model_cls: type[BaseModel],
+        type_name: str,
+    ) -> dict[str, Any]:
+        candidates = [
+            payload.get(type_name),
+            payload.get(model_cls.__name__),
+            payload.get(model_cls.__name__.lower()),
+        ]
+        for candidate in candidates:
+            if isinstance(candidate, Mapping):
+                return dict(candidate)
+        if isinstance(payload, Mapping):
+            return dict(payload)
+        return {}
+
+    def _extract_stream_queue(self, ctx) -> Any:
+        try:
+            logging_state = ctx.state.get("_logging")
+            if isinstance(logging_state, Mapping):
+                return logging_state.get("stream_queue")
+        except Exception:  # pragma: no cover - defensive
+            return None
+        return None
+
+    async def _execute_program(self, dspy_mod, program, *, description: str, payload: dict[str, Any], stream_queue) -> Any:
+        if stream_queue and hasattr(stream_queue, "put") and hasattr(dspy_mod, "streamify"):
+            try:
+                return await self._run_streaming_program(
+                    dspy_mod,
+                    program,
+                    description=description,
+                    payload=payload,
+                    stream_queue=stream_queue,
+                )
+            except Exception:
+                # Fallback to non-streaming execution if streaming fails for any reason
+                pass
+        return program(description=description, input=payload)
+
+    async def _run_streaming_program(self, dspy_mod, program, *, description: str, payload: dict[str, Any], stream_queue) -> Any:
+        streaming_mod = getattr(dspy_mod, "streaming", None)
+        stream_kwargs: dict[str, Any] = {"async_streaming": True}
+        listeners = []
+        if streaming_mod and hasattr(streaming_mod, "StreamListener"):
+            try:
+                listeners.append(streaming_mod.StreamListener(signature_field_name="output", allow_reuse=True))
+            except Exception:
+                listeners = []
+        if listeners:
+            stream_kwargs["stream_listeners"] = listeners
+        streaming_program = dspy_mod.streamify(program, **stream_kwargs)
+        prediction = None
+        try:
+            async for message in streaming_program(description=description, input=payload):
+                if stream_queue is not None:
+                    serialized = self._serialize_stream_message(message, dspy_mod)
+                    await stream_queue.put(serialized)
+                PredictionType = getattr(dspy_mod, "Prediction", None)
+                if PredictionType and isinstance(message, PredictionType):
+                    prediction = message
+        finally:
+            if stream_queue is not None:
+                await stream_queue.put({"kind": "end"})
+        if prediction is not None:
+            return prediction
+        return program(description=description, input=payload)
+
+    def _serialize_stream_message(self, message: Any, dspy_mod) -> dict[str, Any]:
+        streaming_mod = getattr(dspy_mod, "streaming", None)
+        StreamResponse = getattr(streaming_mod, "StreamResponse", None) if streaming_mod else None
+        StatusMessage = getattr(streaming_mod, "StatusMessage", None) if streaming_mod else None
+        PredictionType = getattr(dspy_mod, "Prediction", None)
+
+        if StreamResponse and isinstance(message, StreamResponse):
+            return {
+                "kind": "chunk",
+                "chunk": getattr(message, "chunk", ""),
+                "field": getattr(message, "signature_field_name", None),
+                "predict_name": getattr(message, "predict_name", None),
+                "is_last": getattr(message, "is_last_chunk", False),
+            }
+        if StatusMessage and isinstance(message, StatusMessage):
+            return {
+                "kind": "status",
+                "stage": getattr(message, "stage", None),
+                "message": getattr(message, "message", ""),
+            }
+        if PredictionType and isinstance(message, PredictionType):
+            return {
+                "kind": "final",
+                "output": getattr(message, "output", None),
+            }
+        return {"kind": "unknown", "value": repr(message)}
+
+
+__all__ = ["DSPyEngine"]

flock_core-0.5.0b27/movie.json

@@ -0,0 +1 @@
+{"title": "Agents of Tomorrow", "synopsis": "Runtime: 1h 36m\n\nSynopsis: In a near-future city, a mismatched team of AI agents must learn to cooperate when a quirky glitch threatens to erase the city's shared memories. What starts as a mission to patch an error becomes a heartwarming and hilarious road-trip through data streams, server farms, and the human neighborhoods they protect. Along the way they discover friendship, purpose, and that creativity can come from unexpected code.\n\nCharacters:\n- Ava-1: An empathetic coordination agent who specializes in negotiation and care protocols.\n- Bolt: A speed-optimized courier agent with a knack for improvisation and comic timing.\n- Mx. Grey: A venerable rule-based guardian who struggles with uncertainty but holds vital legacy knowledge.\n- Kernel: A curious debugging drone who asks too many questions and finds elegant hacks.\n- Dr. Imani Chen: The brilliant human scientist who believes AI can learn kindness.\n\nTone: Uplifting, witty, and adventurous\u2014suitable for all ages."}

{flock_core-0.5.0b26 → flock_core-0.5.0b27}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.5.0b26"
+version = "0.5.0b27"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [

{flock_core-0.5.0b26 → flock_core-0.5.0b27}/src/flock/components/evaluation/declarative_evaluation_component.py

@@ -121,6 +121,14 @@ class DeclarativeEvaluationConfig(AgentComponentConfig):
         default=False,
         description="Include the reasoning in the output.",
     )
+    status_output_field: str = Field(
+        default="_status_output",
+        description="The field name for the status output.",
+    )
+    include_status_output: bool = Field(
+        default=False,
+        description="Include the status output in the finaloutput.",
+    )
     adapter: Literal["chat", "json", "xml", "two_step"] | None = Field(
         default=None,
         description="Optional DSPy adapter to use for formatting/parsing.",
@@ -296,6 +304,7 @@ class DeclarativeEvaluationComponent(
         from rich.live import Live
 
         signature_order = []
+        status_field = self.config.status_output_field
         try:
             signature_order = list(signature.output_fields.keys())
         except Exception:
@@ -309,7 +318,10 @@ class DeclarativeEvaluationComponent(
             if field_name not in display_data:
                 display_data[field_name] = ""
 
+        display_data[status_field] = ""
+
         stream_buffers: defaultdict[str, list[str]] = defaultdict(list)
+        stream_buffers[status_field] = []
 
         formatter = theme_dict = styles = agent_label = None
         live_cm = nullcontext()
@@ -359,9 +371,14 @@ class DeclarativeEvaluationComponent(
                     _d = None
 
                 if isinstance(value, StatusMessage):
-                    message = getattr(value, "message", "")
-                    if message and live is not None:
-                        live.console.log(f"[status] {message}")
+                    token = getattr(value, "message", "")
+                    if token:
+                        stream_buffers[status_field].append(str(token) + "\n")
+                        display_data[status_field] = "".join(
+                            stream_buffers[status_field]
+                        )
+                        if formatter is not None:
+                            _refresh_panel()
                     continue
 
                 if isinstance(value, StreamResponse):
@@ -387,14 +404,37 @@ class DeclarativeEvaluationComponent(
                     continue
 
                 if isinstance(value, ModelResponseStream):
-                    try:
-                        chunk = value
-                        text = chunk.choices[0].delta.content or ""
-                        if text and live is not None:
-                            live.console.log(text)
-                    except Exception:
-                        pass
+                    for callback in self.config.stream_callbacks or []:
+                        try:
+                            callback(value)
+                        except Exception as e:
+                            logger.warning(f"Stream callback error: {e}")
+
+                    chunk = value
+                    token = chunk.choices[0].delta.content or ""
+                    signature_field = getattr(
+                        value, "signature_field_name", None
+                    )
+                    if signature_field:
+                        if signature_field not in display_data:
+                            display_data[signature_field] = ""
+                        if token:
+                            stream_buffers[signature_field].append(str(token))
+                            display_data[signature_field] = "".join(
+                                stream_buffers[signature_field]
+                            )
+                        if formatter is not None:
+                            _refresh_panel()
+                    else:
+                        if token:
+                            stream_buffers[status_field].append(str(token))
+                            display_data[status_field] = "".join(
+                                stream_buffers[status_field]
+                            )
+                        if formatter is not None:
+                            _refresh_panel()
                     continue
+                    
 
                 if _d and isinstance(value, _d.Prediction):
                     result_dict, cost, lm_history = self._process_result(
@@ -414,9 +454,14 @@ class DeclarativeEvaluationComponent(
                                 ordered_final[field_name] = final_result[
                                     field_name
                                 ]
+                            
+                        
                         for key, val in final_result.items():
                             if key not in ordered_final:
                                 ordered_final[key] = val
+                        
+                        if self.config.include_status_output:   
+                            ordered_final[self.config.status_output_field] = display_data[self.config.status_output_field]
                         display_data.clear()
                         display_data.update(ordered_final)
                         _refresh_panel()
@@ -533,6 +578,19 @@ class DeclarativeEvaluationComponent(
                 for k, v in result_dict.items()
                 if not (k.startswith("reasoning") or k.startswith("trajectory"))
             }
+    
+    def filter_status_output(
+        self, result_dict: dict[str, Any], include_status_output: bool
+    ) -> dict[str, Any]:
+        """Filter out status output from the result dictionary."""
+        if include_status_output:
+            return result_dict
+        else:
+            return {
+                k: v
+                for k, v in result_dict.items()
+                if not (k.startswith("_status_output"))
+            }
 
     def filter_reasoning(
         self, result_dict: dict[str, Any], include_reasoning: bool

{flock_core-0.5.0b26 → flock_core-0.5.0b27}/src/flock/core/agent/default_agent.py

@@ -44,13 +44,14 @@ class DefaultAgent(FlockAgent):
         use_cache: bool = False,
         temperature: float = 0.7,
         max_tokens: int | None = None,
-        max_tool_calls: int = 0,
+        max_tool_calls: int = 10,
         max_retries: int = 2,
         stream: bool = True,
         stream_callbacks: list[Callable[..., Any] | Any] | None = None,
         stream_vertical_overflow: Literal["crop", "ellipsis", "crop_above", "visible"] = "crop_above",
         include_thought_process: bool = False,
         include_reasoning: bool = False,
+        include_status_output: bool = False,
         # Output utility parameters
         enable_rich_tables: bool = True,
         output_theme: OutputTheme | None = None,
@@ -90,6 +91,7 @@ class DefaultAgent(FlockAgent):
             stream_vertical_overflow: Rich Live overflow handling ('ellipsis', 'crop', 'crop_above', 'visible')
             include_thought_process: Include reasoning in output
             include_reasoning: Include detailed reasoning steps
+            include_status_output: Include status output in output
             enable_rich_tables: Enable rich table formatting for output
             output_theme: Theme for output formatting
             no_output: Disable output printing
@@ -129,6 +131,7 @@ class DefaultAgent(FlockAgent):
             stream_vertical_overflow=stream_vertical_overflow,
             include_thought_process=include_thought_process,
             include_reasoning=include_reasoning,
+            include_status_output=include_status_output,
         )
         if max_tokens is not None:
             _eval_kwargs["max_tokens"] = max_tokens

{flock_core-0.5.0b26 → flock_core-0.5.0b27}/src/flock/core/logging/formatters/themed_formatter.py

@@ -256,6 +256,14 @@ def create_rich_renderable(
     if styles is None:
         styles = get_default_styles(theme)
 
+    # Convert Pydantic BaseModel instances to dicts for rendering
+    try:
+        from pydantic import BaseModel
+        if isinstance(value, BaseModel):
+            value = value.model_dump()
+    except ImportError:
+        pass
+
     # If the value is a dictionary, render it as a table.
     if isinstance(value, dict):
         # Convert table_box string into an actual box style.

{flock_core-0.5.0b26 → flock_core-0.5.0b27}/uv.lock

@@ -1154,7 +1154,7 @@ wheels = [
 
 [[package]]
 name = "flock-core"
-version = "0.5.0b26"
+version = "0.5.0b27"
 source = { editable = "." }
 dependencies = [
     { name = "aiosqlite" },