flock-core 0.4.542__py3-none-any.whl → 0.5.0__py3-none-any.whl

flock/modules/assertion/assertion_module.py

@@ -1,286 +0,0 @@
-# src/flock/modules/asserts/assertion_module.py (New File)
-
-import json
-from collections.abc import Callable
-from typing import Any, Literal
-
-import dspy  # For potential LLM-based rule checking
-from pydantic import BaseModel, Field, PrivateAttr, ValidationError
-
-from flock.core.context.context import FlockContext
-from flock.core.flock_agent import FlockAgent
-from flock.core.flock_module import FlockModule, FlockModuleConfig
-
-# Need registry access if rules are callables defined elsewhere
-from flock.core.flock_registry import flock_component, get_registry
-from flock.core.logging.logging import get_logger
-
-logger = get_logger("module.assertion")
-
-# --- Rule Definition ---
-# Rules can be defined in several ways:
-# 1. Python lambda/function: (result: Dict, inputs: Dict, context: FlockContext) -> bool | Tuple[bool, str]
-# 2. String referencing a registered callable: "my_validation_function"
-# 3. Natural language rule string: "The summary must contain the keyword 'Flock'." (requires LLM judge)
-# 4. Pydantic Model: The output must conform to this Pydantic model.
-
-RuleType = (
-    Callable[[dict, dict, FlockContext | None], bool | tuple[bool, str]]
-    | str
-    | type[BaseModel]
-)
-
-
-class Rule(BaseModel):
-    """Container for a single assertion rule."""
-
-    condition: RuleType = Field(
-        ...,
-        description="""
-# --- Rule Definition ---
-# Rules can be defined in several ways:
-# 1. Python lambda/function: (result: Dict, inputs: Dict, context: FlockContext) -> bool | Tuple[bool, str]
-# 2. String referencing a registered callable: "my_validation_function"
-# 3. Natural language rule string: "The summary must contain the keyword 'Flock'." (requires LLM judge)
-# 4. Pydantic Model: The output must conform to this Pydantic model.
-                                """,
-    )
-    fail_message: str  # Message to provide as feedback on failure
-    name: str | None = None  # Optional name for clarity
-
-    def __post_init__(self):
-        # Basic validation of fail_message
-        if not isinstance(self.fail_message, str) or not self.fail_message:
-            raise ValueError("Rule fail_message must be a non-empty string.")
-
-
-class AssertionModuleConfig(FlockModuleConfig):
-    """--- Rule Definition ---
-    Rules can be defined in several ways:
-    1. Python lambda/function: (result: Dict, inputs: Dict, context: FlockContext) -> bool | Tuple[bool, str]
-    2. String referencing a registered callable: "my_validation_function"
-    3. Natural language rule string: "The summary must contain the keyword 'Flock'." (requires LLM judge)
-    4. Pydantic Model: The output must conform to this Pydantic model.
-    """
-
-    rules: list[Rule] = Field(
-        default_factory=list,
-        description="List of rules to check against the agent's output.",
-    )
-    # Optional LLM for evaluating natural language rules
-    judge_lm_model: str | None = Field(
-        None, description="LLM model to use for judging natural language rules."
-    )
-    # How to handle failure
-    on_failure: Literal["add_feedback", "raise_error", "log_warning"] = Field(
-        default="add_feedback",
-        description="Action on rule failure: 'add_feedback' to context, 'raise_error', 'log_warning'.",
-    )
-    feedback_context_key: str = Field(
-        default="flock.assertion_feedback",
-        description="Context key to store failure messages for retry loops.",
-    )
-    clear_feedback_on_success: bool = Field(
-        default=True,
-        description="Clear the feedback key from context if all assertions pass.",
-    )
-
-
-@flock_component(config_class=AssertionModuleConfig)
-class AssertionCheckerModule(FlockModule):
-    """Checks the output of an agent against a set of defined rules.
-
-    Can trigger different actions on failure, including adding feedback
-    to the context to enable self-correction loops via routing.
-    """
-
-    name: str = "assertion_checker"
-    config: AssertionModuleConfig = Field(default_factory=AssertionModuleConfig)
-    _judge_lm: dspy.LM | None = PrivateAttr(None)  # Initialize lazily
-
-    def _get_judge_lm(self) -> dspy.LM | None:
-        """Initializes the judge LM if needed."""
-        if self.config.judge_lm_model and self._judge_lm is None:
-            try:
-                self._judge_lm = dspy.LM(self.config.judge_lm_model)
-            except Exception as e:
-                logger.error(
-                    f"Failed to initialize judge LM '{self.config.judge_lm_model}': {e}"
-                )
-                # Proceed without judge LM for other rule types
-        return self._judge_lm
-
-    async def on_post_evaluate(
-        self,
-        agent: FlockAgent,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-        result: dict[str, Any] | None = None,
-    ) -> dict[str, Any]:
-        """Checks rules after the main evaluator runs."""
-        if not self.config.rules:
-            return result  # No rules to check
-
-        logger.debug(f"Running assertion checks for agent '{agent.name}'...")
-        all_passed = True
-        failed_messages = []
-        registry = get_registry()  # Needed for callable lookup
-
-        for i, rule in enumerate(self.config.rules):
-            rule_name = rule.name or f"Rule_{i + 1}"
-            passed = False
-            eval_result = None
-            feedback_msg = rule.fail_message
-
-            try:
-                condition = rule.condition
-                if callable(condition):
-                    # Rule is a Python function/lambda
-                    logger.debug(f"Checking callable rule: {rule_name}")
-                    eval_result = condition(result, inputs, context)
-                elif isinstance(condition, str) and registry.contains(
-                    condition
-                ):
-                    # Rule is a string referencing a registered callable
-                    logger.debug(
-                        f"Checking registered callable rule: '{condition}'"
-                    )
-                    rule_func = registry.get_callable(condition)
-                    eval_result = rule_func(result, inputs, context)
-                elif isinstance(condition, str):
-                    # Rule is a natural language string (requires judge LLM)
-                    logger.debug(
-                        f"Checking natural language rule: '{condition}'"
-                    )
-                    judge_lm = self._get_judge_lm()
-                    if judge_lm:
-                        # Define a simple judge signature dynamically or use a predefined one
-                        class JudgeSignature(dspy.Signature):
-                            """Evaluate if the output meets the rule based on input and output."""
-
-                            program_input: str = dspy.InputField(
-                                desc="Input provided to the agent."
-                            )
-                            program_output: str = dspy.InputField(
-                                desc="Output generated by the agent."
-                            )
-                            rule_to_check: str = dspy.InputField(
-                                desc="The rule to verify."
-                            )
-                            is_met: bool = dspy.OutputField(
-                                desc="True if the rule is met, False otherwise."
-                            )
-                            reasoning: str = dspy.OutputField(
-                                desc="Brief reasoning for the decision."
-                            )
-
-                        judge_predictor = dspy.Predict(
-                            JudgeSignature, llm=judge_lm
-                        )
-                        # Convert complex dicts/lists to strings for the judge prompt
-                        input_str = json.dumps(inputs, default=str, indent=2)
-                        result_str = json.dumps(result, default=str, indent=2)
-                        judge_pred = judge_predictor(
-                            program_input=input_str,
-                            program_output=result_str,
-                            rule_to_check=condition,
-                        )
-                        passed = judge_pred.is_met
-                        feedback_msg = f"{rule.fail_message} (Reason: {judge_pred.reasoning})"
-                        logger.debug(
-                            f"LLM Judge result for rule '{condition}': {passed} ({judge_pred.reasoning})"
-                        )
-                    else:
-                        logger.warning(
-                            f"Cannot evaluate natural language rule '{condition}' - no judge_lm_model configured."
-                        )
-                        passed = True  # Default to pass if no judge available? Or fail? Let's pass.
-
-                elif isinstance(condition, type) and issubclass(
-                    condition, BaseModel
-                ):
-                    # Rule is a Pydantic model for validation
-                    logger.debug(
-                        f"Checking Pydantic validation rule: {condition.__name__}"
-                    )
-                    try:
-                        # Assumes the *entire* result dict should match the model
-                        # More specific logic might be needed (e.g., validate only a specific key)
-                        condition.model_validate(result)
-                        passed = True
-                    except ValidationError as e:
-                        passed = False
-                        feedback_msg = (
-                            f"{rule.fail_message} (Validation Error: {e})"
-                        )
-                else:
-                    logger.warning(
-                        f"Unsupported rule type for rule '{rule_name}': {type(condition)}"
-                    )
-                    continue  # Skip rule
-
-                # Process result if it was a callable returning bool or (bool, msg)
-                if eval_result is not None:
-                    if (
-                        isinstance(eval_result, tuple)
-                        and len(eval_result) == 2
-                        and isinstance(eval_result[0], bool)
-                    ):
-                        passed, custom_msg = eval_result
-                        if not passed and custom_msg:
-                            feedback_msg = (
-                                custom_msg  # Use custom message on failure
-                            )
-                    elif isinstance(eval_result, bool):
-                        passed = eval_result
-                    else:
-                        logger.warning(
-                            f"Rule callable '{rule_name}' returned unexpected type: {type(eval_result)}. Rule skipped."
-                        )
-                        continue
-
-                # Handle failure
-                if not passed:
-                    all_passed = False
-                    failed_messages.append(feedback_msg)
-                    logger.warning(
-                        f"Assertion Failed for agent '{agent.name}': {feedback_msg}"
-                    )
-                    # Optionally break early? For now, check all rules.
-
-            except Exception as e:
-                logger.error(
-                    f"Error executing rule '{rule_name}' for agent '{agent.name}': {e}",
-                    exc_info=True,
-                )
-                all_passed = False
-                failed_messages.append(
-                    f"Error checking rule '{rule_name}': {e}"
-                )
-                # Treat error during check as failure
-
-        # --- Take action based on results ---
-        if not all_passed:
-            logger.warning(f"Agent '{agent.name}' failed assertion checks.")
-            if self.config.on_failure == "add_feedback" and context:
-                context.set_variable(
-                    self.config.feedback_context_key, "\n".join(failed_messages)
-                )
-                logger.debug(
-                    f"Added assertion feedback to context key '{self.config.feedback_context_key}'"
-                )
-            elif self.config.on_failure == "raise_error":
-                # Maybe wrap in a specific FlockAssertionError
-                raise AssertionError(
-                    f"Agent '{agent.name}' failed assertions: {'; '.join(failed_messages)}"
-                )
-            # else "log_warning" is default behavior
-        elif context and self.config.clear_feedback_on_success:
-            # Clear feedback key if all rules passed and key exists
-            if self.config.feedback_context_key in context.state:
-                del context.state[self.config.feedback_context_key]
-                logger.debug(
-                    f"Cleared assertion feedback key '{self.config.feedback_context_key}' on success."
-                )
-
-        return result  # Return the original result unmodified

flock/modules/callback/__init__.py

@@ -1 +0,0 @@
-# Package for modules

flock/modules/callback/callback_module.py

@@ -1,91 +0,0 @@
-"""Callback module for handling agent lifecycle hooks."""
-
-from collections.abc import Awaitable, Callable
-from typing import Any
-
-from pydantic import Field
-
-from flock.core import FlockModule, FlockModuleConfig
-from flock.core.context.context import FlockContext
-from flock.core.flock_registry import flock_component
-
-
-class CallbackModuleConfig(FlockModuleConfig):
-    """Configuration for callback module."""
-
-    initialize_callback: (
-        Callable[[Any, dict[str, Any]], Awaitable[None]] | None
-    ) = Field(
-        default=None,
-        description="Optional callback function for initialization",
-    )
-    evaluate_callback: (
-        Callable[[Any, dict[str, Any]], Awaitable[dict[str, Any]]] | None
-    ) = Field(
-        default=None, description="Optional callback function for evaluate"
-    )
-    terminate_callback: (
-        Callable[[Any, dict[str, Any], dict[str, Any]], Awaitable[None]] | None
-    ) = Field(
-        default=None, description="Optional callback function for termination"
-    )
-    on_error_callback: (
-        Callable[[Any, Exception, dict[str, Any]], Awaitable[None]] | None
-    ) = Field(
-        default=None,
-        description="Optional callback function for error handling",
-    )
-
-
-@flock_component(config_class=CallbackModuleConfig)
-class CallbackModule(FlockModule):
-    """Module that provides callback functionality for agent lifecycle events."""
-
-    name: str = "callbacks"
-    config: CallbackModuleConfig = Field(
-        default_factory=CallbackModuleConfig,
-        description="Callback module configuration",
-    )
-
-    async def pre_initialize(
-        self,
-        agent: Any,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-    ) -> None:
-        """Run initialize callback if configured."""
-        if self.config.initialize_callback:
-            await self.config.initialize_callback(agent, inputs)
-
-    async def on_pre_evaluate(
-        self,
-        agent: Any,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-    ) -> dict[str, Any]:
-        """Run evaluate callback if configured."""
-        if self.config.evaluate_callback:
-            return await self.config.evaluate_callback(agent, inputs)
-        return inputs
-
-    async def pre_terminate(
-        self,
-        agent: Any,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-        result: dict[str, Any] | None = None,
-    ) -> None:
-        """Run terminate callback if configured."""
-        if self.config.terminate_callback:
-            await self.config.terminate_callback(agent, inputs, result)
-
-    async def on_error(
-        self,
-        agent: Any,
-        error: Exception,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-    ) -> None:
-        """Run error callback if configured."""
-        if self.config.on_error_callback:
-            await self.config.on_error_callback(agent, error, inputs)

flock/modules/enterprise_memory/README.md

@@ -1,99 +0,0 @@
-# Enterprise Memory Module
-
-The **EnterpriseMemoryModule** brings durable, scalable memory to Flock agents by
-combining a true vector store (Chroma) with a property-graph database
-(Neo4j / Memgraph).  It is a drop‐in replacement for the default
-`memory` module when you need:
-
-* millions of memory chunks without exhausting RAM
-* concurrent writers (many agents / processes / machines)
-* rich concept-graph queries and visualisation
-
----
-## How it works
-
-| Concern              | Technology |
-|--------------------- |------------|
-| Vector similarity    | **Pinecone**, **Chroma**, **Azure Cognitive Search** |
-| Concept graph        | **Cypher** database (Neo4j / Memgraph) |
-| Embeddings           | `sentence-transformers` (`all-MiniLM-L6-v2`) |
-| Concept extraction   | Agent's LLM via DSPy signature |
-
-* Each memory chunk is embedded and added to the Chroma collection.
-* Concepts are extracted; duplicates are eliminated via case-insensitive
-  and fuzzy matching (≥ 0.85 similarity).
-* Memory nodes and `(:Memory)-[:MENTIONS]->(:Concept)` edges are merged
-  into the graph DB in batched transactions.
-* Optional: export a PNG of the concept graph after every update.
-
----
-## Configuration options (`EnterpriseMemoryModuleConfig`)
-
-```yaml
-chroma_path: ./vector_store          # disk path if running embedded
-chroma_host: null                    # host of remote Chroma server (optional)
-chroma_port: 8000
-chroma_collection: flock_memories    # collection name
-
-# or Pinecone
-vector_backend: pinecone
-pinecone_api_key: <YOUR_KEY>
-pinecone_env: gcp-starter
-pinecone_index: flock-memories
-
-# or Azure Cognitive Search
-vector_backend: azure
-azure_search_endpoint: https://<service>.search.windows.net
-azure_search_key: <KEY>
-azure_search_index_name: flock-memories
-
-cypher_uri: bolt://localhost:7687
-cypher_username: neo4j
-cypher_password: password
-
-similarity_threshold: 0.5            # for retrieval
-max_results: 10
-number_of_concepts_to_extract: 3
-save_interval: 10                    # batch size before commit
-
-export_graph_image: false            # set true to emit PNGs
-graph_image_dir: ./concept_graphs    # where to store images
-```
-
----
-## Dependencies
-
-Add the following to your project (examples with pip):
-
-```bash
-pip install chromadb>=0.4.20
-pip install neo4j>=5.14.0
-pip install sentence-transformers>=2.7.0
-pip install matplotlib networkx     # only needed when export_graph_image = true
-pip install pinecone-client         # if using Pinecone
-pip install azure-search-documents  # if using Azure Search
-```
-
-You also need a running Neo4j **or** Memgraph instance.  The module uses
-the Bolt protocol and Cypher `MERGE`, which works on both.
-
----
-## Usage
-
-```python
-from flock.modules.enterprise_memory.enterprise_memory_module import (
-    EnterpriseMemoryModule, EnterpriseMemoryModuleConfig,
-)
-
-agent.add_module(
-    EnterpriseMemoryModule(
-        name="enterprise_memory",
-        config=EnterpriseMemoryModuleConfig(
-            cypher_password=os.environ["NEO4J_PASSWORD"],
-            export_graph_image=True,
-        ),
-    )
-)
-```
-
-The rest of the agent code stays unchanged.