flock-core 0.4.0b12__tar.gz → 0.4.0b14__tar.gz

{flock_core-0.4.0b12 → flock_core-0.4.0b14}/PKG-INFO

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

{flock_core-0.4.0b12 → flock_core-0.4.0b14}/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.0b14/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.0b12 → flock_core-0.4.0b14}/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.0b12 → flock_core-0.4.0b14}/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.0b12 → flock_core-0.4.0b14}/pyproject.toml

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

{flock_core-0.4.0b12 → flock_core-0.4.0b14}/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.0b14/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 = 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

flock_core-0.4.0b14/story_agent.flock.yaml

@@ -0,0 +1,311 @@
+name: flock_954aea7e
+model: groq/qwen-qwq-32b
+enable_temporal: false
+enable_logging: false
+show_flock_banner: true
+agents:
+  story_agent:
+    name: story_agent
+    model: groq/qwen-qwq-32b
+    description: An agent that is a master storyteller
+    input: 'story_idea: str'
+    output: 'story: Story, story_bible: StoryBible'
+    use_cache: true
+    evaluator:
+      name: default
+      config:
+        model: groq/qwen-qwq-32b
+        use_cache: false
+        temperature: 0.0
+        max_tokens: 60000
+        stream: true
+      type: DeclarativeEvaluator
+    modules:
+      output:
+        name: output
+        config:
+          enabled: true
+          theme: abernathy
+          render_table: false
+          max_length: 1000
+          wait_for_input: false
+          write_to_file: true
+          output_dir: output/
+          truncate_long_values: true
+          show_metadata: true
+          format_code_blocks: true
+          custom_formatters: {}
+          no_output: false
+          print_context: false
+        type: OutputModule
+      metrics:
+        name: metrics
+        config:
+          enabled: true
+          collect_timing: true
+          collect_memory: true
+          collect_token_usage: true
+          collect_cpu: true
+          storage_type: json
+          metrics_dir: metrics/
+          aggregation_interval: 1h
+          retention_days: 30
+          alert_on_high_latency: true
+          latency_threshold_ms: 30000
+        type: MetricsModule
+types:
+  Story:
+    module_path: __main__
+    type: pydantic.BaseModel
+    schema:
+      $defs:
+        Chapter:
+          properties:
+            title:
+              description: Title of the chapter
+              title: Title
+              type: string
+            chapter_number:
+              description: Chapter number of the chapter
+              title: Chapter Number
+              type: integer
+            purpose:
+              description: Purpose of the chapter
+              title: Purpose
+              type: string
+            summary:
+              description: Key events or chapter summary
+              title: Summary
+              type: string
+            scenes:
+              description: Scenes of the chapter
+              items:
+                $ref: '#/$defs/Scene'
+              title: Scenes
+              type: array
+          required:
+          - title
+          - chapter_number
+          - purpose
+          - summary
+          - scenes
+          title: Chapter
+          type: object
+        Character:
+          properties:
+            name:
+              description: Name of the character
+              title: Name
+              type: string
+            role:
+              description: Role of the character
+              title: Role
+              type: string
+            age:
+              description: Age of the character
+              title: Age
+              type: string
+            appearance:
+              description: Appearance of the character
+              title: Appearance
+              type: string
+            image_prompt:
+              description: Very detailed image prompt for image generation to represent
+                the character
+              title: Image Prompt
+              type: string
+            personality_traits:
+              description: Personality traits of the character
+              items:
+                type: string
+              title: Personality Traits
+              type: array
+            backstory:
+              description: Backstory of the character
+              title: Backstory
+              type: string
+            motivations:
+              description: Motivations of the character
+              title: Motivations
+              type: string
+            weaknesses:
+              description: Weaknesses of the character
+              title: Weaknesses
+              type: string
+            character_arc:
+              description: How the character evolves throughout the story
+              title: Character Arc
+              type: string
+          required:
+          - name
+          - role
+          - age
+          - appearance
+          - image_prompt
+          - personality_traits
+          - backstory
+          - motivations
+          - weaknesses
+          - character_arc
+          title: Character
+          type: object
+        Scene:
+          properties:
+            title:
+              title: Title
+              type: string
+            setting:
+              description: Setting of the scene
+              title: Setting
+              type: string
+            goal:
+              description: Goal of the scene
+              title: Goal
+              type: string
+            conflict:
+              description: Conflict of the scene
+              title: Conflict
+              type: string
+            outcome:
+              description: Outcome of the scene
+              title: Outcome
+              type: string
+            characters_involved:
+              description: Name of characters/entities involved in the scene
+              items:
+                type: string
+              title: Characters Involved
+              type: array
+            story_beats:
+              description: Story beats of the scene
+              items:
+                type: string
+              title: Story Beats
+              type: array
+          required:
+          - title
+          - setting
+          - goal
+          - conflict
+          - outcome
+          - characters_involved
+          - story_beats
+          title: Scene
+          type: object
+      properties:
+        title:
+          title: Title
+          type: string
+        status:
+          default: Idea
+          description: Idea, Drafting, Revising, Completed
+          title: Status
+          type: string
+        genre:
+          description: Genre(s) of the story
+          items:
+            type: string
+          title: Genre
+          type: array
+        tone:
+          description: Tone of the story
+          title: Tone
+          type: string
+        themes:
+          description: Themes of the story
+          items:
+            type: string
+          title: Themes
+          type: array
+        central_conflict:
+          description: Central conflict of the story
+          title: Central Conflict
+          type: string
+        brief_summary:
+          description: Brief summary of the story
+          title: Brief Summary
+          type: string
+        long_summary:
+          description: Long-form summary of the story.
+          title: Long Summary
+          type: string
+        characters:
+          description: Important characters and/or entities of the story
+          items:
+            $ref: '#/$defs/Character'
+          title: Characters
+          type: array
+        chapters:
+          description: All chapters of the story. At least one chapter per act.
+          items:
+            $ref: '#/$defs/Chapter'
+          title: Chapters
+          type: array
+      required:
+      - title
+      - genre
+      - tone
+      - themes
+      - central_conflict
+      - brief_summary
+      - long_summary
+      - characters
+      - chapters
+      type: object
+  StoryBible:
+    module_path: __main__
+    type: pydantic.BaseModel
+    schema:
+      properties:
+        timeline:
+          additionalProperties:
+            type: string
+          description: Timeline of the story
+          title: Timeline
+          type: object
+        worldbuilding_notes:
+          additionalProperties:
+            type: string
+          description: Worldbuilding notes of the story
+          title: Worldbuilding Notes
+          type: object
+        consistency_rules:
+          description: Consistency rules of the story
+          items:
+            type: string
+          title: Consistency Rules
+          type: array
+        writing_reference:
+          anyOf:
+          - type: string
+          - type: 'null'
+          default: null
+          description: Writing reference and/or style guidelines
+          title: Writing Reference
+      required:
+      - timeline
+      - worldbuilding_notes
+      - consistency_rules
+      type: object
+components:
+  DeclarativeEvaluator:
+    type: flock_component
+    module_path: flock.evaluators.declarative.declarative_evaluator
+    file_path: src/flock/evaluators/declarative/declarative_evaluator.py
+    description: Evaluator that uses DSPy for generation.
+  OutputModule:
+    type: flock_component
+    module_path: flock.modules.output.output_module
+    file_path: src/flock/modules/output/output_module.py
+    description: Module that handles output formatting and display.
+  MetricsModule:
+    type: flock_component
+    module_path: flock.modules.performance.metrics_module
+    file_path: src/flock/modules/performance/metrics_module.py
+    description: Module for collecting and analyzing agent performance metrics.
+dependencies:
+- pydantic>=2.0.0
+- flock-core>=0.4.0
+metadata:
+  path_type: relative
+  flock_version: 0.4.0

{flock_core-0.4.0b12 → flock_core-0.4.0b14}/uv.lock

@@ -1245,7 +1245,7 @@ wheels = [
 
 [[package]]
 name = "flock-core"
-version = "0.4.0b12"
+version = "0.4.0b14"
 source = { editable = "." }
 dependencies = [
     { name = "azure-search-documents" },