flock-core 0.3.1__tar.gz → 0.3.3__tar.gz

{flock_core-0.3.1 → flock_core-0.3.3}/.vscode/settings.json

@@ -13,8 +13,22 @@
         "source.organizeImports.ruff": "always",
         "source.fixAll.ruff": "always"
     },
-    // we try to make semantic highlighting look good
+    "editor.fontFamily": "'Jetbrains Mono', 'FiraCode Nerd Font', 'Hack Nerd Font', 'monospace'",
+    "editor.smoothScrolling": true,
+    "terminal.integrated.fontFamily": "'Jetbrains Mono', 'FiraCode Nerd Font', 'Hack Nerd Font', 'monospace'",
+    "editor.renderIndentGuides": false,
+    "editor.renderWhitespace": "none",
+    //"terminal.integrated.lineHeight": 1.5,
+    "editor.fontSize": 15.5,
+    "editor.fontLigatures": true,
+    //"editor.lineHeight": 1.5,
+    "editor.minimap.enabled": false,
+    "editor.tabSize": 2,
+    "editor.semanticTokenColorCustomizations": {
+        "enabled": true
+    },
     "editor.semanticHighlighting.enabled": true,
+    // we try to make semantic highlighting look good
     // prevent VSCode from modifying the terminal colors
     "terminal.integrated.minimumContrastRatio": 0,
     "cSpell.words": [

{flock_core-0.3.1 → flock_core-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.3.1
+Version: 0.3.3
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -34,6 +34,7 @@ Requires-Dist: temporalio>=1.9.0
 Requires-Dist: tiktoken>=0.8.0
 Requires-Dist: toml>=0.10.2
 Requires-Dist: tqdm>=4.67.1
+Requires-Dist: zep-python>=2.0.2
 Provides-Extra: all-tools
 Requires-Dist: docling>=2.18.0; extra == 'all-tools'
 Requires-Dist: markdownify>=0.14.1; extra == 'all-tools'

{flock_core-0.3.1 → flock_core-0.3.3}/docs/release-notes/release_notes.md

@@ -24,8 +24,7 @@ Like a hummingbird, modules are small and nimble code packages. Put enough of th
 
 ### 🎯 New Module System   
 
-- **Complete redesign** of the module architecture  
-- Simple yet powerful lifecycle hooks: `initialize`, `pre_evaluate`, `post_evaluate`, `terminate`  
+- **Pluggable modules system á la FastAPI**   
 - **Easy-to-implement** module interface  
 - **Configuration system** for clean parameter management  
 
@@ -35,6 +34,7 @@ Like a hummingbird, modules are small and nimble code packages. Put enough of th
 - Built-in support for multiple evaluation strategies:  
   - **Declarative Evaluator** – The default way Flock is designed  
   - **Natural Language Evaluator** – Use "classic" prompting  
+  - **Zep Evaluator** – Add or query data
 - **Easily extendable** with custom evaluation approaches  
 
 ### 🏭 FlockFactory    
@@ -46,6 +46,7 @@ Like a hummingbird, modules are small and nimble code packages. Put enough of th
 - **Memory Module** – Persistent agent memory  
 - **Output Module** – Advanced output formatting and storage  
 - **Metrics Module** – Detailed performance tracking  
+- **Zep Module** – Uses Zep for Knowledge Graphs
 
 ---
 
@@ -113,7 +114,7 @@ pip install flock-core>=0.3.0
 
 ---  
 
-📖 **Full documentation**: [docs.flock.ai](https://docs.flock.ai)  
-💻 **GitHub**: [github.com/flock-ai](https://github.com/flock-ai)  
+📖 **Full documentation**: [https://whiteducksoftware.github.io/flock](https://whiteducksoftware.github.io/flock)  
+💻 **GitHub**: [https://github.com/whiteducksoftware/flock](https://github.com/whiteducksoftware/flock)  
 
 

flock_core-0.3.3/examples/03_misc/multi_hops.py

@@ -0,0 +1,85 @@
+
+from flock.core import Flock, FlockFactory
+from flock.core.logging.formatters.themes import OutputTheme
+from flock.evaluators.zep.zep_evaluator import ZepEvaluator, ZepEvaluatorConfig
+from flock.modules.zep.zep_module import ZepModule, ZepModuleConfig
+
+
+def write_to_kg():
+  write_to_kg_agent = FlockFactory.create_default_agent(name="write_to_kg_agent", 
+                                            input="data", 
+                                            output_theme=OutputTheme.aardvark_blue)
+  
+  # --------------------------------
+  # Evaluators
+  # --------------------------------
+  # Evaluators are the components that evaluate the agent's inputs and outputs.
+  # In this case, we're using the ZepEvaluator to interact with Zep.
+  # This replaces the default declarative evaluator
+  # The ZepEvaluator uses the ZepModule to interact with Zep.
+  # input with "data" will add the data to the memory
+  # input with "query" will search the memory for the query and return the facts
+  write_to_kg_agent.evaluator = ZepEvaluator(name="zep", config=ZepEvaluatorConfig())
+
+  write_to_kg_agent.run(inputs={"data": "Andre is 38 years old and author of the agent framework 'flock'"})
+  write_to_kg_agent.run(inputs={"data": "Andre works for white duck"})
+  write_to_kg_agent.run(inputs={"data": "Andre has two cats"})
+  write_to_kg_agent.run(inputs={"data": "White Duck is a cloud consulting company"})
+  write_to_kg_agent.run(inputs={"data": "Flock is an agent framework designed for scalable multi-agent systems"})
+  write_to_kg_agent.run(inputs={"data": "One of Andre's cats is named Luna"})
+  write_to_kg_agent.run(inputs={"data": "The other cat is named Lucy"})
+  write_to_kg_agent.run(inputs={"data": "Andre lives in Germany"})
+  write_to_kg_agent.run(inputs={"data": "Germany is in Europe"})
+
+def read_from_kg():
+  read_from_kg_agent = FlockFactory.create_default_agent(name="read_from_kg_agent", 
+                                            input="query", 
+                                            output_theme=OutputTheme.aardvark_blue)
+
+  # replace the default evaluator with ZepEvaluator
+  read_from_kg_agent.evaluator = ZepEvaluator(name="zep", config=ZepEvaluatorConfig())
+
+
+  # #### **2-Hop Question:**
+  # **Question:** What kind of company does the employer of the author of 'flock' belong to?  
+  # **Reasoning:**  
+  # 1. "Andre is the author of the agent framework 'flock'."  
+  # 2. "Andre works for White Duck."  
+  # 3. "White Duck is a cloud consulting company."  
+  # 4. Therefore, the employer of the author of 'flock' is a cloud consulting company.
+
+  read_from_kg_agent.run(inputs={"query": "What kind of company does the employer of the author of 'flock' belong to?"})
+
+def read_from_kg_and_evaluate():
+  read_from_kg_and_evaluate_agent = FlockFactory.create_default_agent(name="read_from_kg_and_evaluate_agent", 
+                                            input="query", 
+                                            output="short_answer",
+                                            output_theme=OutputTheme.aardvark_blue)
+  
+  read_from_kg_and_evaluate_agent.add_module(ZepModule(name="zep", config=ZepModuleConfig()))
+
+
+
+  read_from_kg_and_evaluate_agent.run(inputs={"query": "What kind of company does the employer of the author of 'flock' belong to?"})
+
+  # #### **3-Hop Question:**
+  # **Question:** In which continent does the creator of the agent framework 'flock' live?  
+  # **Reasoning:**  
+  # 1. "Andre is the author of the agent framework 'flock'."  
+  # 2. "Andre lives in Germany."  
+  # 3. "Germany is in Europe."  
+  # 4. Therefore, the creator of 'flock' lives in Europe.
+  read_from_kg_and_evaluate_agent.run(inputs={"query": "In which continent does the creator of the agent framework 'flock' live? "})
+
+
+
+if __name__ == "__main__":
+  #write_to_kg()
+  #read_from_kg()
+  #read_from_kg_and_evaluate()
+  pass
+
+
+
+
+

flock_core-0.3.3/examples/03_misc/use_modules.py

@@ -0,0 +1,60 @@
+"""
+Title: Advanced Flock Agent with Caching, Type Hints, and Tool Integration
+
+In this example, we'll show you how to build a more advanced Flock system that:
+  - Uses a custom output formatter (RichTables) for a polished, swaggy display.
+  - Defines output types using standard Python type hints (including lists and Literals) for structured results.
+  - Integrates external tools (like a web content scraper) so that agents can perform more complex operations.
+  - Leverages caching so that if an agent is called with the same input, the cached result is returned—this is particularly
+    useful for expensive operations such as web scraping or during debugging.
+
+The agent in this example takes a URL as input and outputs:
+  - A title,
+  - A list of headings,
+  - A list of dictionaries mapping entities to metadata, and
+  - A type (limited to one of 'news', 'blog', 'opinion piece', or 'tweet').
+
+After executing the agent, you can work with the result as a real Python object that respects the defined types.
+
+Let's dive in!
+"""
+
+
+from pprint import pprint
+
+from flock.core import Flock, FlockFactory
+from flock.core.logging.formatters.themes import OutputTheme
+from flock.core.tools import basic_tools
+from flock.modules.zep.zep_module import ZepModule, ZepModuleConfig
+
+
+flock = Flock(enable_logging=True)
+
+agent = FlockFactory.create_default_agent(
+    name="my_agent",
+    input="url",
+    output="title, headings: list[str]," 
+            "entities_and_metadata: list[dict[str, str]]," 
+            "type:Literal['news', 'blog', 'opinion piece', 'tweet']",
+    tools=[basic_tools.get_web_content_as_markdown],
+    enable_rich_tables=True,
+    output_theme=OutputTheme.aardvark_blue,
+)
+
+# --------------------------------
+# Add a module to the agent
+# --------------------------------
+# Modules are modules (heh) that can be added to an agent to extend its capabilities.
+# Modules run at certain points in the agent's lifecycle and can manipulate the inputs and outputs and the agent itself.
+# In this case, we're adding the Zep module to the agent, 
+# which allows it to use Zep to store and retrieve information in Knowledge Graphs.
+zep = ZepModule(name="zep",config=ZepModuleConfig())
+agent.add_module(zep)
+
+
+flock.add_agent(agent)
+result = flock.run(
+    start_agent=agent,
+    input={"url": "https://lite.cnn.com/travel/alexander-the-great-macedon-persian-empire-darius/index.html"},
+)
+

{flock_core-0.3.1 → flock_core-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flock-core"
-version = "0.3.01"
+version = "0.3.3"
 description = "Declarative LLM Orchestration at Scale"
 readme = "README.md"
 authors = [
@@ -39,6 +39,7 @@ dependencies = [
     "tiktoken>=0.8.0",
     "toml>=0.10.2",
     "tqdm>=4.67.1",
+    "zep-python>=2.0.2",
 ]
 
 [project.optional-dependencies]

flock_core-0.3.3/src/flock/evaluators/zep/zep_evaluator.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+from pydantic import Field
+
+from flock.core.flock_agent import FlockAgent
+from flock.core.flock_evaluator import FlockEvaluator, FlockEvaluatorConfig
+from flock.core.mixin.dspy_integration import DSPyIntegrationMixin
+from flock.core.mixin.prompt_parser import PromptParserMixin
+from flock.modules.zep.zep_module import ZepModule, ZepModuleConfig
+
+
+class ZepEvaluatorConfig(FlockEvaluatorConfig):
+    zep_url: str = "http://localhost:8000"
+    zep_api_key: str = "apikey"
+    min_fact_rating: float = Field(
+        default=0.7, description="Minimum rating for facts to be considered"
+    )
+
+
+class ZepEvaluator(FlockEvaluator, DSPyIntegrationMixin, PromptParserMixin):
+    """Evaluator that uses DSPy for generation."""
+
+    config: ZepEvaluatorConfig = Field(
+        default_factory=ZepEvaluatorConfig,
+        description="Evaluator configuration",
+    )
+
+    async def evaluate(
+        self, agent: FlockAgent, inputs: dict[str, Any], tools: list[Any]
+    ) -> dict[str, Any]:
+        """Simple evaluator that uses Zep.
+
+        if inputs contain "query", it searches memory for the query and returns the facts.
+        if inputs contain "data", it adds the data to memory
+        """
+        result = {}
+        zep = ZepModule(
+            name=self.name,
+            config=ZepModuleConfig(
+                zep_api_key=self.config.zep_api_key,
+                zep_url=self.config.zep_url,
+                min_fact_rating=self.config.min_fact_rating,
+            ),
+        )
+        client = zep.get_client()
+        if "query" in inputs:
+            query = inputs["query"]
+            facts = zep.search_memory(query, client)
+            result = {"facts": facts}
+
+        if "data" in inputs:
+            data = inputs["data"]
+            zep.add_to_memory(data, client)
+            result = {"message": "Data added to memory"}
+        return result

flock_core-0.3.3/src/flock/modules/zep/zep_module.py

@@ -0,0 +1,177 @@
+import uuid
+from typing import Any
+
+from pydantic import Field
+from zep_python.client import Zep
+from zep_python.types import Message as ZepMessage, SessionSearchResult
+
+from flock.core.flock_agent import FlockAgent
+from flock.core.flock_module import FlockModule, FlockModuleConfig
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("module.zep")
+
+
+class ZepModuleConfig(FlockModuleConfig):
+    """Configuration for the Zep module."""
+
+    zep_url: str = "http://localhost:8000"
+    zep_api_key: str = "apikey"
+    min_fact_rating: float = Field(
+        default=0.7, description="Minimum rating for facts to be considered"
+    )
+    enable_read: bool = True
+    enable_write: bool = False
+
+
+class ZepModule(FlockModule):
+    """Module that adds Zep capabilities to a Flock agent."""
+
+    name: str = "zep"
+    config: ZepModuleConfig = ZepModuleConfig()
+    session_id: str | None = None
+    user_id: str | None = None
+
+    def __init__(self, name, config: ZepModuleConfig) -> None:
+        """Initialize Zep module."""
+        super().__init__(name=name, config=config)
+        logger.debug("Initializing Zep module")
+        zep_client = Zep(
+            base_url=self.config.zep_url, api_key=self.config.zep_api_key
+        )
+        self.user_id = self.name
+        self._setup_user(zep_client)
+        self.session_id = str(uuid.uuid4())
+        self._setup_session(zep_client)
+
+    def _setup_user(self, zep_client: Zep) -> None:
+        """Set up user in Zep."""
+        if not zep_client or not self.user_id:
+            raise ValueError("Zep service or user_id not initialized")
+
+        try:
+            user = zep_client.user.get(user_id=self.user_id)
+            if not user:
+                zep_client.user.add(user_id=self.user_id)
+        except Exception:
+            zep_client.user.add(user_id=self.user_id)
+
+    def _setup_session(self, zep_client: Zep) -> None:
+        """Set up new session."""
+        if not zep_client or not self.user_id or not self.session_id:
+            raise ValueError(
+                "Zep service, user_id, or session_id not initialized"
+            )
+
+        zep_client.memory.add_session(
+            user_id=self.user_id,
+            session_id=self.session_id,
+        )
+
+    def get_client(self) -> Zep:
+        """Get Zep client."""
+        return Zep(
+            base_url=self.config.zep_url, api_key=self.config.zep_api_key
+        )
+
+    def get_memory(self, zep_client: Zep) -> str | None:
+        """Get memory for the current session."""
+        if not zep_client or not self.session_id:
+            logger.error("Zep service or session_id not initialized")
+            return None
+
+        try:
+            memory = zep_client.memory.get(
+                self.session_id, min_rating=self.config.min_fact_rating
+            )
+            if memory:
+                return f"{memory.relevant_facts}"
+        except Exception as e:
+            logger.error(f"Error fetching memory: {e}")
+            return None
+
+        return None
+
+    def split_text(
+        self, text: str | None, max_length: int = 1000
+    ) -> list[ZepMessage]:
+        """Split text into smaller chunks."""
+        result: list[ZepMessage] = []
+        if not text:
+            return result
+        if len(text) <= max_length:
+            return [ZepMessage(role="user", content=text, role_type="user")]
+        for i in range(0, len(text), max_length):
+            result.append(
+                ZepMessage(
+                    role="user",
+                    content=text[i : i + max_length],
+                    role_type="user",
+                )
+            )
+        return result
+
+    def add_to_memory(self, text: str, zep_client: Zep) -> None:
+        """Add text to memory."""
+        if not zep_client or not self.session_id:
+            logger.error("Zep service or session_id not initialized")
+            return
+
+        messages = self.split_text(text)
+        zep_client.memory.add(session_id=self.session_id, messages=messages)
+
+    def search_memory(
+        self, query: str, zep_client: Zep
+    ) -> list[SessionSearchResult]:
+        """Search memory for a query."""
+        if not zep_client or not self.user_id:
+            logger.error("Zep service or user_id not initialized")
+            return []
+
+        response = zep_client.memory.search_sessions(
+            text=query,
+            user_id=self.user_id,
+            search_scope="facts",
+            min_fact_rating=self.config.min_fact_rating,
+        )
+        if not response.results:
+            return []
+        return response.results
+
+    async def post_evaluate(
+        self, agent: FlockAgent, inputs: dict[str, Any], result: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Format and display the output."""
+        if not self.config.enable_write:
+            return result
+        logger.debug("Saving data to memory")
+        zep_client = Zep(
+            base_url=self.config.zep_url, api_key=self.config.zep_api_key
+        )
+        self.add_to_memory(str(result), zep_client)
+        return result
+
+    async def pre_evaluate(
+        self, agent: FlockAgent, inputs: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Format and display the output."""
+        if not self.config.enable_read:
+            return inputs
+
+        zep_client = Zep(
+            base_url=self.config.zep_url, api_key=self.config.zep_api_key
+        )
+
+        logger.debug("Searching memory")
+        facts = self.search_memory(str(inputs), zep_client)
+
+        # Add memory to inputs
+        facts_str = ""
+        if facts:
+            for fact in facts:
+                facts_str += fact.fact.fact + "\n"
+            logger.debug("Found facts in memory: {}", facts_str)
+            agent.input = agent.input + ", memory"
+            inputs["memory"] = facts_str
+
+        return inputs

{flock_core-0.3.1 → flock_core-0.3.3}/uv.lock

@@ -1,4 +1,5 @@
 version = 1
+revision = 1
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version >= '3.12' and platform_machine == 'x86_64' and sys_platform == 'darwin'",
@@ -1031,7 +1032,7 @@ wheels = [
 
 [[package]]
 name = "flock-core"
-version = "0.3.1"
+version = "0.3.3"
 source = { editable = "." }
 dependencies = [
     { name = "cloudpickle" },
@@ -1060,6 +1061,7 @@ dependencies = [
     { name = "tiktoken" },
     { name = "toml" },
     { name = "tqdm" },
+    { name = "zep-python" },
 ]
 
 [package.optional-dependencies]
@@ -1132,7 +1134,9 @@ requires-dist = [
     { name = "tiktoken", specifier = ">=0.8.0" },
     { name = "toml", specifier = ">=0.10.2" },
     { name = "tqdm", specifier = ">=4.67.1" },
+    { name = "zep-python", specifier = ">=2.0.2" },
 ]
+provides-extras = ["all-tools", "tools"]
 
 [package.metadata.requires-dev]
 app = [
@@ -5590,6 +5594,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f5/4b/a06e0ec3d155924f77835ed2d167ebd3b211a7b0853da1cf8d8414d784ef/yarl-1.18.3-py3-none-any.whl", hash = "sha256:b57f4f58099328dfb26c6a771d09fb20dbbae81d20cfb66141251ea063bd101b", size = 45109 },
 ]
 
+[[package]]
+name = "zep-python"
+version = "2.0.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "httpx" },
+    { name = "pydantic" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b5/64/1b0c4afa6d0e8f35e1072eacdfe8ec216871be5f2dfd569942f69232482f/zep_python-2.0.2.tar.gz", hash = "sha256:919fd635ad5801f30d9ef6da0bb99e854ed4c3cd1357dc8ada4a39b8171a41bc", size = 22273 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1c/d4/09a6bc0c32f91b7b5b93322513d51299ca9b35bdd6b0560b39104c296f39/zep_python-2.0.2-py3-none-any.whl", hash = "sha256:d7b2cadf1eb15007825362cae5ddff9c9d0ada5b4f75cf91e5b87986459f7817", size = 40011 },
+]
+
 [[package]]
 name = "zipp"
 version = "3.21.0"