flock-core 0.4.0b11__tar.gz → 0.4.0b13__tar.gz

{flock_core-0.4.0b11 → flock_core-0.4.0b13}/PKG-INFO

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

{flock_core-0.4.0b11 → flock_core-0.4.0b13}/examples/01_introduction/08a_serialization.py

@@ -25,6 +25,7 @@ from flock.core import (
     flock_type,
     flock_component,
     flock_tool,
+    flock_callable,
 )
 
 
@@ -64,6 +65,10 @@ class GreetingModule(FlockModule):
             "greeting": f"{greeting}, {name}!"
         }
     
+@flock_callable
+def generate_description(context):
+    return "A greeting agent."
+    
     
 
 # Define a custom type
@@ -95,6 +100,7 @@ def serialization():
     # Create an agent using our GreetingModule
     agent = FlockFactory.create_default_agent(
         name="greeter",
+        description=generate_description,
         input="name: str", 
         output="greeting: str, mobile_number: str",
         tools=[get_mobile_number]

flock_core-0.4.0b13/examples/01_introduction/11_stream.py

@@ -0,0 +1,120 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+from flock.core import FlockFactory, Flock, flock_registry
+from flock.core.flock_registry import flock_type
+from flock.routers.default.default_router import DefaultRouter, DefaultRouterConfig
+
+FlockRegistry = flock_registry.get_registry()
+
+class Scene(BaseModel):
+    title: str
+    setting: str = Field(..., description="Setting of the scene")
+    goal: str = Field(..., description="Goal of the scene")
+    conflict: str = Field(..., description="Conflict of the scene")
+    outcome: str = Field(..., description="Outcome of the scene")
+    characters_involved: list[str] = Field(..., description="Name of characters/entities involved in the scene")
+    story_beats: list[str] = Field(..., description="Story beats of the scene")
+
+
+class Character(BaseModel):
+    name: str = Field(..., description="Name of the character")
+    role: str = Field(..., description="Role of the character")
+    age: str = Field(..., description="Age of the character")
+    appearance: str = Field(..., description="Appearance of the character")
+    image_prompt: str = Field(..., description="Very detailed image prompt for image generation to represent the character")
+    personality_traits: list[str] = Field(..., description="Personality traits of the character")
+    backstory: str = Field(..., description="Backstory of the character")
+    motivations: str = Field(..., description="Motivations of the character")
+    weaknesses: str = Field(..., description="Weaknesses of the character")
+    character_arc: str = Field(..., description="How the character evolves throughout the story")
+    
+class Chapter(BaseModel):
+    title: str = Field(..., description="Title of the chapter")
+    chapter_number: int = Field(..., description="Chapter number of the chapter")
+    purpose: str = Field(..., description="Purpose of the chapter")
+    summary: str = Field(..., description="Key events or chapter summary")
+    scenes: list[Scene] = Field(..., description="Scenes of the chapter")
+    
+
+
+########################################################
+
+class Prompt(BaseModel):
+    prompt: str = Field(..., description="Detailed Prompt for image generation")
+    title: str = Field(..., description="Title of the prompt")
+    
+# Define the whole comic book series as a whole
+    
+class Issue(BaseModel):
+    title: str = Field(..., description="Title of the issue")
+    issue_number: int = Field(..., description="Issue number of the issue")
+    issue_description: str = Field(..., description="Description/Summary of the issue")
+    issue_scenes: dict[int,str] = Field(..., description="Scenes of the story the issue visualizes. Key is the page number and value is the scene title as defined in the story chapters.")
+    issue_cover_image_prompt: str = Field(..., description="Cover image prompt for the issue")
+    number_of_pages: int = Field(..., description="Number of pages in the issue")
+    number_of_panels: int = Field(..., description="Number of panels in the issue")
+    linked_concept_art_prompts: list[str] = Field(..., description="Concept art prompts that are linked to the issue. The prompts are linked to the issue by the title of the prompt.")
+    
+class ComicBookSeries(BaseModel):
+    title: str = Field(..., description="Title of the comic book series")
+    issues: list[Issue] = Field(..., description="Issues of the comic book series")
+    concept_art_prompts: list[Prompt] = Field(..., description="Concept art prompts for the comic book series. Includes character concept art, setting concept art, etc. Everything that needs consistency across the series.")
+    
+    
+########################################################
+    
+class PageLayout(BaseModel):
+    issue_number: int = Field(..., description="Issue number of the page layout")
+    page_number: int = Field(..., description="Page number of the page layout")
+    amount_of_panels: int = Field(..., description="Amount of panels on the page")
+    layout_description: str = Field(..., description="Description of the panel layout of the page")
+    page_prompt: str = Field(..., description="Prompt for the page")
+    story_scene_title: str = Field(..., description="Title of the story scene that is depicted in the page")
+    
+class IssueLayout(Issue):
+    page_layouts: list[PageLayout] = Field(..., description="Page layouts for the issue")
+    
+    
+@flock_type 
+class Story(BaseModel):
+    title: str
+    status: str = Field(default="Idea", description="Idea, Drafting, Revising, Completed")
+    genre: list[str] = Field(..., description="Genre(s) of the story")
+    tone: str = Field(..., description="Tone of the story") 
+    themes: list[str] = Field(..., description="Themes of the story")
+    central_conflict: str = Field(..., description="Central conflict of the story")
+    brief_summary: str = Field(..., description="Brief summary of the story")
+    long_summary: str = Field(..., description="Long-form summary of the story.")
+    characters: list[Character] = Field(..., description="Important characters and/or entities of the story")
+    chapters: list[Chapter] = Field(..., description="All chapters of the story. At least one chapter per act.")
+    
+@flock_type 
+class StoryBible(BaseModel):
+    timeline: dict[str, str]  = Field(..., description="Timeline of the story")
+    worldbuilding_notes: dict[str, str]  = Field(..., description="Worldbuilding notes of the story")
+    consistency_rules: list[str]  = Field(..., description="Consistency rules of the story")
+    writing_reference: Optional[str] = Field(default=None, description="Writing reference and/or style guidelines")
+
+MODEL = "gemini/gemini-2.5-pro-exp-03-25" #"groq/qwen-qwq-32b"    #"openai/gpt-4o" # 
+flock = Flock(model=MODEL)
+
+
+story_agent = FlockFactory.create_default_agent(name="story_agent",
+                                              description="An agent that is a master storyteller",
+                                              input="story_idea: str",
+                                              output="story: Story, story_bible: StoryBible",
+                                              max_tokens=60000,
+                                              write_to_file=True,
+                                              stream=True,
+                                              use_cache=False)
+
+
+flock.add_agent(story_agent)
+flock.to_yaml_file(".flock/story_agent.flock.yaml")
+result = flock.run(start_agent=story_agent, 
+                   input={'story_idea': 
+                       'In a world right at the cusp between LLMs and AGI some guy is experiencing the most peculiar story.' 
+                       'Absurdist Fiction, Satire, Technological Comedy. As much content as possible. At least 10.000 words'}) 
+
+
+

{flock_core-0.4.0b11 → flock_core-0.4.0b13}/examples/01_introduction/data/file_path_demo.flock.yaml

@@ -60,6 +60,7 @@ agents:
         type: GreetingModule
     tools:
     - get_mobile_number
+    description_callable: generate_description
   person_creator:
     name: person_creator
     model: openai/gpt-4o
@@ -151,6 +152,11 @@ components:
     module_path: __main__
     file_path: examples/01_introduction/08a_serialization.py
     description: A simple module that generates greetings.
+  generate_description:
+    type: flock_callable
+    module_path: __main__
+    file_path: examples/01_introduction/08a_serialization.py
+    description: Callable function generate_description
   get_mobile_number:
     type: flock_callable
     module_path: __main__

{flock_core-0.4.0b11 → flock_core-0.4.0b13}/examples/03_apps/story_gen/main.py

@@ -104,15 +104,17 @@ story_agent = FlockFactory.create_default_agent(name="story_agent",
                                               input="story_idea: str",
                                               output="story: Story, story_bible: StoryBible",
                                               max_tokens=60000,
-                                              write_to_file=True)
+                                              write_to_file=True,
+                                              stream=True,
+                                              use_cache=False)
 
 
 flock.add_agent(story_agent)
 flock.to_yaml_file("story_agent.flock.yaml")
-# result = flock.run(start_agent=story_agent, 
-#                    input={'story_idea': 
-#                        'In a world right at the cusp between LLMs and AGI some guy is experiencing the most peculiar story.' 
-#                        'Absurdist Fiction, Satire, Technological Comedy. As much content as possible. At least 10.000 words'}) 
+result = flock.run(start_agent=story_agent, 
+                   input={'story_idea': 
+                       'In a world right at the cusp between LLMs and AGI some guy is experiencing the most peculiar story.' 
+                       'Absurdist Fiction, Satire, Technological Comedy. As much content as possible. At least 10.000 words'}) 
 
 
 

{flock_core-0.4.0b11 → flock_core-0.4.0b13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.4.0b-11"
+version = "0.4.0b-13"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [

{flock_core-0.4.0b11 → flock_core-0.4.0b13}/src/flock/core/flock_factory.py

@@ -37,6 +37,7 @@ class FlockFactory:
         no_output: bool = False,
         print_context: bool = False,
         write_to_file: bool = False,
+        stream: bool = False,
     ) -> FlockAgent:
         """Creates a default FlockAgent.
 
@@ -50,6 +51,7 @@ class FlockFactory:
             use_cache=use_cache,
             max_tokens=max_tokens,
             temperature=temperature,
+            stream=stream,
         )
 
         evaluator = DeclarativeEvaluator(name="default", config=eval_config)

{flock_core-0.4.0b11 → flock_core-0.4.0b13}/src/flock/core/serialization/flock_serializer.py

@@ -145,6 +145,66 @@ class FlockSerializer:
                             )
                         )
 
+                # Description (Callables)
+                if agent_data.get("description_callable"):
+                    logger.debug(
+                        f"Adding description callable '{agent_data['description_callable']}' from agent '{name}'"
+                    )
+                    description_callable_name = agent_data[
+                        "description_callable"
+                    ]
+                    description_callable = agent_instance.description
+                    path_str = FlockRegistry.get_callable_path_string(
+                        description_callable
+                    )
+                    if path_str:
+                        logger.debug(
+                            f"Adding description callable '{description_callable_name}' (from path '{path_str}') to components"
+                        )
+                        components[description_callable_name] = (
+                            FlockSerializer._get_callable_definition(
+                                path_str, description_callable_name, path_type
+                            )
+                        )
+
+                if agent_data.get("input_callable"):
+                    logger.debug(
+                        f"Adding input callable '{agent_data['input_callable']}' from agent '{name}'"
+                    )
+                    input_callable_name = agent_data["input_callable"]
+                    input_callable = agent_instance.input
+                    path_str = FlockRegistry.get_callable_path_string(
+                        input_callable
+                    )
+                    if path_str:
+                        logger.debug(
+                            f"Adding input callable '{input_callable_name}' (from path '{path_str}') to components"
+                        )
+                        components[input_callable_name] = (
+                            FlockSerializer._get_callable_definition(
+                                path_str, input_callable_name, path_type
+                            )
+                        )
+
+                if agent_data.get("output_callable"):
+                    logger.debug(
+                        f"Adding output callable '{agent_data['output_callable']}' from agent '{name}'"
+                    )
+                    output_callable_name = agent_data["output_callable"]
+                    output_callable = agent_instance.output
+                    path_str = FlockRegistry.get_callable_path_string(
+                        output_callable
+                    )
+                    if path_str:
+                        logger.debug(
+                            f"Adding output callable '{output_callable_name}' (from path '{path_str}') to components"
+                        )
+                        components[output_callable_name] = (
+                            FlockSerializer._get_callable_definition(
+                                path_str, output_callable_name, path_type
+                            )
+                        )
+
                 # Tools (Callables)
                 if agent_data.get("tools"):
                     logger.debug(

flock_core-0.4.0b13/src/flock/evaluators/declarative/declarative_evaluator.py

@@ -0,0 +1,128 @@
+from collections.abc import Generator
+from typing import Any
+
+import dspy
+from pydantic import Field
+from rich.console import Console
+
+from flock.core.flock_agent import FlockAgent
+from flock.core.flock_evaluator import FlockEvaluator, FlockEvaluatorConfig
+from flock.core.logging.logging import get_logger
+from flock.core.mixin.dspy_integration import DSPyIntegrationMixin
+from flock.core.mixin.prompt_parser import PromptParserMixin
+
+console = Console()
+
+logger = get_logger("evaluators.declarative")
+
+
+class DeclarativeEvaluatorConfig(FlockEvaluatorConfig):
+    """Configuration for the DeclarativeEvaluator."""
+
+    agent_type_override: str | None = None
+    model: str | None = "openai/gpt-4o"
+    use_cache: bool = True
+    temperature: float = 0.0
+    max_tokens: int = 4096
+    stream: bool = Field(
+        default=False,
+        description="Enable streaming output from the underlying DSPy program.",
+    )
+
+
+class DeclarativeEvaluator(
+    FlockEvaluator, DSPyIntegrationMixin, PromptParserMixin
+):
+    """Evaluator that uses DSPy for generation."""
+
+    config: DeclarativeEvaluatorConfig = Field(
+        default_factory=DeclarativeEvaluatorConfig,
+        description="Evaluator configuration",
+    )
+
+    async def evaluate(
+        self, agent: FlockAgent, inputs: dict[str, Any], tools: list[Any]
+    ) -> dict[str, Any]:
+        """Evaluate using DSPy, with optional asynchronous streaming."""
+        # --- Setup Signature and LM ---
+        try:
+            _dspy_signature = self.create_dspy_signature_class(
+                agent.name,
+                agent.description,
+                f"{agent.input} -> {agent.output}",
+            )
+            # --- Get output field names ---
+            # dspy.Signature holds fields in .output_fields attribute
+            output_field_names = list(_dspy_signature.output_fields.keys())
+            if not output_field_names:
+                logger.warning(
+                    f"DSPy signature for agent '{agent.name}' has no defined output fields. Streaming might not produce text."
+                )
+            # -----------------------------
+
+            self._configure_language_model(
+                model=self.config.model or agent.model,
+                use_cache=self.config.use_cache,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens,
+            )
+            agent_task = self._select_task(
+                _dspy_signature,
+                agent_type_override=self.config.agent_type_override,
+                tools=tools,
+            )
+        except Exception as setup_error:
+            logger.error(
+                f"Error setting up DSPy task for agent '{agent.name}': {setup_error}",
+                exc_info=True,
+            )
+            raise RuntimeError(
+                f"DSPy task setup failed: {setup_error}"
+            ) from setup_error
+
+        # --- Conditional Evaluation (Stream vs No Stream) ---
+        if self.config.stream:
+            logger.info(
+                f"Evaluating agent '{agent.name}' with async streaming."
+            )
+            if not callable(agent_task):
+                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)
+            stream_generator: Generator = streaming_task(**inputs)
+
+            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 = self._process_result(chunk, inputs)
+
+            console.print("\n")
+            return result_dict
+
+        else:  # Non-streaming path
+            logger.info(f"Evaluating agent '{agent.name}' without streaming.")
+            try:
+                # Ensure the call is awaited if the underlying task is async
+                result_obj = await agent_task(**inputs)
+                result_dict = self._process_result(result_obj, inputs)
+                return result_dict
+            except Exception as e:
+                logger.error(
+                    f"Error during non-streaming evaluation for agent '{agent.name}': {e}",
+                    exc_info=True,
+                )
+                raise RuntimeError(f"Evaluation failed: {e}") from e