flock-core 0.2.17__py3-none-any.whl → 0.3.1__py3-none-any.whl

flock/evaluators/declarative/declarative_evaluator.py

@@ -0,0 +1,52 @@
+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
+
+
+class DeclarativeEvaluatorConfig(FlockEvaluatorConfig):
+    agent_type_override: str | None = None
+    model: str | None = "openai/gpt-4o"
+    use_cache: bool = True
+    temperature: float = 0.0
+    max_tokens: int = 4096
+
+
+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."""
+        _dspy_signature = self.create_dspy_signature_class(
+            agent.name,
+            agent.description,
+            f"{agent.input} -> {agent.output}",
+        )
+        self._configure_language_model(
+            model=self.config.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,
+        )
+        # Execute the task.
+        result = agent_task(**inputs)
+        result = self._process_result(result, inputs)
+        return result

flock/evaluators/natural_language/natural_language_evaluator.py

@@ -0,0 +1,66 @@
+from typing import Any
+
+from flock.core.flock_evaluator import FlockEvaluator
+
+
+class NaturalLanguageEvaluator(FlockEvaluator):
+    """Evaluator that uses natural language prompting."""
+
+    name: str = "natural_language"
+    prompt_template: str = ""
+    client: Any = None  # OpenAI client
+
+    async def setup(self, input_schema: str, output_schema: str) -> None:
+        """Set up prompt template and client."""
+        from openai import AsyncOpenAI
+
+        # Create prompt template
+        self.prompt_template = f"""
+        You are an AI assistant that processes inputs and generates outputs.
+        
+        Input Format:
+        {input_schema}
+        
+        Required Output Format:
+        {output_schema}
+        
+        Please process the following input and provide output in the required format:
+        {{input}}
+        """
+
+        # Set up client
+        self.client = AsyncOpenAI()
+
+    async def evaluate(self, inputs: dict[str, Any]) -> dict[str, Any]:
+        """Evaluate using natural language."""
+        if not self.client:
+            raise RuntimeError("Evaluator not set up")
+
+        # Format input for prompt
+        input_str = "\n".join(f"{k}: {v}" for k, v in inputs.items())
+
+        # Get completion
+        response = await self.client.chat.completions.create(
+            model=self.config.model,
+            messages=[
+                {
+                    "role": "user",
+                    "content": self.prompt_template.format(input=input_str),
+                }
+            ],
+            temperature=self.config.temperature,
+            max_tokens=self.config.max_tokens,
+        )
+
+        # Parse response into dictionary
+        try:
+            import json
+
+            return json.loads(response.choices[0].message.content)
+        except json.JSONDecodeError:
+            return {"result": response.choices[0].message.content}
+
+    async def cleanup(self) -> None:
+        """Close client."""
+        if self.client:
+            await self.client.close()

flock/modules/callback/callback_module.py

@@ -0,0 +1,86 @@
+"""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
+
+
+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",
+    )
+
+
+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]) -> None:
+        """Run initialize callback if configured."""
+        if self.config.initialize_callback:
+            await self.config.initialize_callback(agent, inputs)
+
+    async def pre_evaluate(
+        self, agent: Any, inputs: dict[str, Any]
+    ) -> 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], result: dict[str, Any]
+    ) -> 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]
+    ) -> None:
+        """Run error callback if configured."""
+        if self.config.on_error_callback:
+            await self.config.on_error_callback(agent, error, inputs)
+
+    # Other hooks just pass through
+    async def post_initialize(self, agent: Any, inputs: dict[str, Any]) -> None:
+        pass
+
+    async def post_evaluate(
+        self, agent: Any, inputs: dict[str, Any], result: dict[str, Any]
+    ) -> dict[str, Any]:
+        return result
+
+    async def post_terminate(
+        self, agent: Any, inputs: dict[str, Any], result: dict[str, Any]
+    ) -> None:
+        pass

flock/modules/memory/memory_module.py

@@ -0,0 +1,235 @@
+"""Memory module implementation for Flock agents."""
+
+import json
+import uuid
+from datetime import datetime
+from typing import Any
+
+from pydantic import Field
+
+from flock.core import FlockAgent, FlockModule, FlockModuleConfig
+from flock.core.logging.logging import get_logger
+from flock.modules.memory.memory_parser import MemoryMappingParser
+from flock.modules.memory.memory_storage import FlockMemoryStore, MemoryEntry
+
+
+class MemoryModuleConfig(FlockModuleConfig):
+    """Configuration for the memory module."""
+
+    file_path: str | None = Field(
+        default="agent_memory.json", description="Path to save memory file"
+    )
+    memory_mapping: str | None = Field(
+        default=None, description="Memory mapping configuration"
+    )
+    similarity_threshold: float = Field(
+        default=0.5, description="Threshold for semantic similarity"
+    )
+    context_window: int = Field(
+        default=3, description="Number of memory entries to return"
+    )
+    max_length: int = Field(
+        default=1000, description="Max length of memory entry before splitting"
+    )
+    save_after_update: bool = Field(
+        default=True, description="Whether to save memory after each update"
+    )
+
+
+logger = get_logger("memory")
+
+
+class MemoryModule(FlockModule):
+    """Module that adds memory capabilities to a Flock agent.
+
+    This module encapsulates all memory-related functionality that was previously
+    hardcoded into FlockAgent.
+    """
+
+    name: str = "memory"
+    config: MemoryModuleConfig = Field(
+        default_factory=MemoryModuleConfig,
+        description="Memory module configuration",
+    )
+    memory_store: FlockMemoryStore | None = None
+    memory_ops: list = []
+
+    async def pre_initialize(
+        self, agent: FlockAgent, inputs: dict[str, Any]
+    ) -> None:
+        """Initialize memory store if needed."""
+        if not self.memory_store:
+            self.memory_store = FlockMemoryStore.load_from_file(
+                self.config.file_path
+            )
+
+        if not self.config.memory_mapping:
+            self.memory_ops = []
+            self.memory_ops.append({"type": "semantic"})
+        else:
+            self.memory_ops = MemoryMappingParser().parse(
+                self.config.memory_mapping
+            )
+
+        logger.debug(f"Initialized memory module for agent {agent.name}")
+
+    async def post_initialize(self, agent: Any, inputs: dict[str, Any]) -> None:
+        """No post-initialization needed."""
+        pass
+
+    async def pre_evaluate(
+        self, agent: FlockAgent, inputs: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Check memory before evaluation."""
+        if not self.memory_store:
+            return inputs
+
+        try:
+            # Convert input to embedding
+            input_text = json.dumps(inputs)
+            query_embedding = self.memory_store.compute_embedding(input_text)
+
+            # Extract concepts
+            concepts = await self._extract_concepts(agent, input_text)
+
+            memory_results = []
+            for op in self.memory_ops:
+                if op["type"] == "semantic":
+                    semantic_results = self.memory_store.retrieve(
+                        query_embedding,
+                        concepts,
+                        similarity_threshold=self.config.similarity_threshold,
+                    )
+                    memory_results.extend(semantic_results)
+
+                elif op["type"] == "exact":
+                    exact_results = self.memory_store.exact_match(inputs)
+                    memory_results.extend(exact_results)
+
+            if memory_results:
+                logger.debug(
+                    f"Found {len(memory_results)} relevant memories",
+                    agent=agent.name,
+                )
+                inputs["memory_results"] = memory_results
+
+            return inputs
+
+        except Exception as e:
+            logger.warning(f"Memory retrieval failed: {e!s}", agent=agent.name)
+            return inputs
+
+    async def post_evaluate(
+        self, agent: FlockAgent, inputs: dict[str, Any], result: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Store results in memory after evaluation."""
+        if not self.memory_store:
+            return result
+
+        try:
+            # Extract information chunks
+            chunks = await self._extract_information(agent, inputs, result)
+            chunk_concepts = await self._extract_concepts(agent, chunks)
+
+            # Create memory entry
+            entry = MemoryEntry(
+                id=str(uuid.uuid4()),
+                content=chunks,
+                embedding=self.memory_store.compute_embedding(chunks).tolist(),
+                concepts=chunk_concepts,
+                timestamp=datetime.now(),
+            )
+
+            # Add to memory store
+            self.memory_store.add_entry(entry)
+
+            if self.config.save_after_update:
+                self.save_memory()
+
+            logger.debug(
+                "Stored interaction in memory",
+                agent=agent.name,
+                entry_id=entry.id,
+                concepts=chunk_concepts,
+            )
+
+        except Exception as e:
+            logger.warning(f"Memory storage failed: {e!s}", agent=agent.name)
+
+        return result
+
+    async def pre_terminate(
+        self, agent: Any, inputs: dict[str, Any], result: dict[str, Any]
+    ) -> None:
+        """No pre-termination needed."""
+        pass
+
+    async def post_terminate(
+        self, agent: Any, inputs: dict[str, Any], result: dict[str, Any]
+    ) -> None:
+        """Save memory store if configured."""
+        if self.config.save_after_update and self.memory_store:
+            self.save_memory()
+
+    async def _extract_concepts(self, agent: FlockAgent, text: str) -> set[str]:
+        """Extract concepts using agent's LLM capabilities."""
+        existing_concepts = None
+        if self.memory_store.concept_graph:
+            existing_concepts = set(
+                self.memory_store.concept_graph.graph.nodes()
+            )
+
+        input = "text: str | Text to analyze"
+        if existing_concepts:
+            input += ", existing_concepts: list[str] | Already known concepts that might apply"
+
+        # Create signature for concept extraction using agent's capabilities
+        concept_signature = agent.create_dspy_signature_class(
+            f"{agent.name}_concept_extractor",
+            "Extract key concepts from text",
+            f"{input} -> concepts: list[str] | Max five key concepts all lower case",
+        )
+
+        # Configure and run the predictor
+        agent._configure_language_model()
+        predictor = agent._select_task(concept_signature, "Completion")
+        result = predictor(
+            text=text,
+            existing_concepts=list(existing_concepts)
+            if existing_concepts
+            else None,
+        )
+
+        concept_list = result.concepts if hasattr(result, "concepts") else []
+        return set(concept_list)
+
+    async def _extract_information(
+        self, agent: FlockAgent, inputs: dict[str, Any], result: dict[str, Any]
+    ) -> str:
+        """Extract information chunks from interaction."""
+        # Create splitter signature using agent's capabilities
+        split_signature = agent.create_dspy_signature_class(
+            f"{agent.name}_splitter",
+            "Extract a list of potentially needed data and information for future reference",
+            """
+            content: str | The content to split
+            -> chunks: list[str] | list of data and information for future reference
+            """,
+        )
+
+        # Configure and run the predictor
+        agent._configure_language_model()
+        splitter = agent._select_task(split_signature, "Completion")
+
+        # Get the content to split
+        full_text = json.dumps(inputs) + json.dumps(result)
+        split_result = splitter(content=full_text)
+
+        return "\n".join(split_result.chunks)
+
+    def save_memory(self) -> None:
+        """Save memory store to file."""
+        if self.memory_store and self.config.file_path:
+            json_str = self.memory_store.model_dump_json()
+            with open(self.config.file_path, "w") as file:
+                file.write(json_str)

flock/modules/memory/memory_parser.py

@@ -0,0 +1,125 @@
+"""Parser for memory mapping declarations into executable operations."""
+
+import re
+from typing import Any
+
+from flock.core.memory.memory_storage import (
+    CombineOperation,
+    EnrichOperation,
+    ExactOperation,
+    FilterOperation,
+    MemoryOperation,
+    MemoryScope,
+    SemanticOperation,
+    SortOperation,
+)
+
+
+class MemoryMappingParser:
+    """Parses memory mapping declarations into executable operations."""
+
+    def parse(self, mapping: str) -> list[MemoryOperation]:
+        """Parse a memory mapping string into operations.
+
+        Example mappings:
+        "topic -> memory.semantic(threshold=0.9) | memory.exact -> output"
+        "query -> memory.semantic(scope='global') | memory.filter(recency='7d') | memory.sort(by='relevance')"
+        """
+        operations = []
+        stages = [s.strip() for s in mapping.split("|")]
+
+        for stage in stages:
+            if "->" not in stage:
+                continue
+
+            inputs, op_spec = stage.split("->")
+            inputs = [i.strip() for i in inputs.split(",")]
+
+            if "memory." in op_spec:
+                # Extract operation name and parameters
+                match = re.match(r"memory\.(\w+)(?:\((.*)\))?", op_spec.strip())
+                if not match:
+                    continue
+
+                op_name, params_str = match.groups()
+                params = self._parse_params(params_str or "")
+
+                # Create appropriate operation object
+                if op_name == "semantic":
+                    operation = SemanticOperation(
+                        threshold=params.get("threshold", 0.8),
+                        scope=params.get("scope", MemoryScope.BOTH),
+                        max_results=params.get("max_results", 10),
+                    )
+                elif op_name == "exact":
+                    operation = ExactOperation(
+                        keys=inputs, scope=params.get("scope", MemoryScope.BOTH)
+                    )
+                elif op_name == "enrich":
+                    operation = EnrichOperation(
+                        tools=params.get("tools", []),
+                        strategy=params.get("strategy", "comprehensive"),
+                        scope=params.get("scope", MemoryScope.BOTH),
+                    )
+                elif op_name == "filter":
+                    operation = FilterOperation(
+                        recency=params.get("recency"),
+                        relevance=params.get("relevance"),
+                        metadata=params.get("metadata", {}),
+                    )
+                elif op_name == "sort":
+                    operation = SortOperation(
+                        by=params.get("by", "relevance"),
+                        ascending=params.get("ascending", False),
+                    )
+                elif op_name == "combine":
+                    operation = CombineOperation(
+                        weights=params.get(
+                            "weights", {"semantic": 0.7, "exact": 0.3}
+                        )
+                    )
+
+                operations.append(operation)
+
+        return operations
+
+    def _parse_params(self, params_str: str) -> dict[str, Any]:
+        """Parse parameters string into a dictionary.
+
+        Handles:
+        - Quoted strings: threshold='high'
+        - Numbers: threshold=0.9
+        - Lists: tools=['web_search', 'extract_numbers']
+        - Dictionaries: weights={'semantic': 0.7, 'exact': 0.3}
+        """
+        if not params_str:
+            return {}
+
+        params = {}
+        # Split on commas not inside brackets or quotes
+        param_pairs = re.findall(
+            r"""
+            (?:[^,"]|"[^"]*"|'[^']*')+  # Match everything except comma, or quoted strings
+        """,
+            params_str,
+            re.VERBOSE,
+        )
+
+        for pair in param_pairs:
+            if "=" not in pair:
+                continue
+            key, value = pair.split("=", 1)
+            key = key.strip()
+            value = value.strip()
+
+            # Try to evaluate the value (for lists, dicts, numbers)
+            try:
+                # Safely evaluate the value
+                value = eval(value, {"__builtins__": {}}, {})
+            except:
+                # If evaluation fails, treat as string
+                value = value.strip("'\"")
+
+            params[key] = value
+
+        return params