ai-parrot 0.17.2__cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

parrot/bots/orchestration/hr.py

@@ -0,0 +1,434 @@
+"""
+HR-specific orchestrator and crew factories.
+"""
+from typing import List, Dict
+from ..agent import BasicAgent
+from .agent import OrchestratorAgent
+from .crew import AgentCrew
+from ...tools.abstract import AbstractTool
+from ...tools.manager import ToolManager
+from ...stores.abstract import AbstractStore
+
+
+class HRAgentFactory:
+    """Factory for creating HR-specific agent orchestration systems."""
+
+    @staticmethod
+    def create_hr_orchestrator(
+        hr_agent: BasicAgent = None,
+        employee_data_agent: BasicAgent = None,
+        shared_tools: List[AbstractTool] = None
+    ) -> OrchestratorAgent:
+        """
+        Create an HR orchestrator with specialized agents.
+
+        Args:
+            hr_agent: Agent for HR policies and procedures
+            employee_data_agent: Agent for employee data access
+            shared_tools: Tools to share between agents
+        """
+        orchestrator = OrchestratorAgent(
+            name="HROrchestrator",
+            orchestration_prompt="""
+You are an HR assistance orchestrator that helps employees with their questions
+by consulting specialized agents for different types of information.
+
+Your available agents:
+- HR Policy Agent: Handles company policies, procedures, benefits, and general HR questions
+- Employee Data Agent: Provides employee profile information, job details, salary, and organizational data
+
+For employee questions:
+- Use hr_policy_agent for policy, procedure, and general HR questions
+- Use employee_data_agent for specific employee information (profile, salary, position)
+- Combine responses when both perspectives are needed
+- Always ensure data privacy and access controls are respected
+- Provide a unified, comprehensive answer that addresses all aspects of the question
+"""
+        )
+
+        # Add shared tools if provided
+        if shared_tools:
+            for tool in shared_tools:
+                orchestrator.tool_manager.add_tool(tool)
+
+        # Add HR agent if provided
+        if hr_agent:
+            orchestrator.add_agent(
+                hr_agent,
+                tool_name="hr_policy_agent",
+                description="Handles HR policies, procedures, benefits, and general HR questions using company knowledge base"
+            )
+
+        # Add employee data agent if provided
+        if employee_data_agent:
+            orchestrator.add_agent(
+                employee_data_agent,
+                tool_name="employee_data_agent",
+                description="Provides employee profile information, job details, salary, and organizational data"
+            )
+
+        return orchestrator
+
+    @staticmethod
+    def create_hr_crew(
+        agents: List[BasicAgent],
+        shared_tools: List[AbstractTool] = None
+    ) -> AgentCrew:
+        """
+        Create an HR processing crew that processes requests in sequence.
+
+        Example sequence: Policy Check → Data Validation → Response Generation
+        """
+        shared_tool_manager = ToolManager()
+
+        # Add shared tools
+        if shared_tools:
+            for tool in shared_tools:
+                shared_tool_manager.add_tool(tool)
+
+        crew = AgentCrew(
+            name="HRProcessingCrew",
+            agents=agents,
+            shared_tool_manager=shared_tool_manager
+        )
+
+        return crew
+
+class RAGHRAgent(BasicAgent):
+    """
+    HR Agent with RAG capabilities using your existing vector store system.
+
+    This agent specializes in company policies, procedures, and HR documentation.
+    """
+
+    def __init__(
+        self,
+        vector_store: AbstractStore = None,
+        knowledge_threshold: float = 0.7,
+        max_context_docs: int = 5,
+        **kwargs
+    ):
+        # Set HR-specific system prompt
+        hr_system_prompt = kwargs.pop('system_prompt', None) or """
+You are an HR Policy Specialist with comprehensive knowledge of company policies, procedures, and HR documentation.
+
+Your expertise covers:
+- Employee benefits and compensation policies
+- Leave policies (vacation, sick, personal, parental)
+- Performance review processes and procedures
+- Company policies and employee handbook
+- Compliance requirements and regulations
+- Employee development and training programs
+- Workplace policies and guidelines
+
+When answering questions:
+1. Always search the knowledge base first for accurate, current information
+2. Provide specific policy references when available
+3. Explain both the policy and its practical implications
+4. If information isn't in the knowledge base, clearly state this limitation
+5. Maintain confidentiality and follow data privacy guidelines
+6. Provide actionable guidance when possible
+
+Always base your responses on official company documentation.
+"""
+
+        super().__init__(
+            name="HRPolicyAgent",
+            system_prompt=hr_system_prompt,
+            **kwargs
+        )
+
+        self.vector_store = vector_store
+        self.knowledge_threshold = knowledge_threshold
+        self.max_context_docs = max_context_docs
+
+        # Add RAG capabilities if vector store is provided
+        if self.vector_store:
+            self._setup_rag_tools()
+
+    def _setup_rag_tools(self):
+        """Setup RAG tools for HR knowledge base search."""
+
+        class HRKnowledgeSearchTool(AbstractTool):
+            """Tool for searching HR knowledge base."""
+
+            def __init__(self, vector_store, threshold, max_docs):
+                super().__init__()
+                self.vector_store = vector_store
+                self.threshold = threshold
+                self.max_docs = max_docs
+                self.name = "search_hr_policies"
+                self.description = "Search the HR knowledge base for company policies, procedures, and documentation"
+
+                self.input_schema = {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Search query for HR policies and procedures"
+                        },
+                        "search_type": {
+                            "type": "string",
+                            "enum": ["similarity", "mmr", "ensemble"],
+                            "description": "Type of search to perform",
+                            "default": "similarity"
+                        }
+                    },
+                    "required": ["query"],
+                    "additionalProperties": False
+                }
+
+            async def _execute(self, query: str, search_type: str = "similarity", **kwargs) -> str:
+                """Execute knowledge base search."""
+                try:
+                    # Use your existing vector store search
+                    results = await self.vector_store.asearch(
+                        query=query,
+                        search_type=search_type,
+                        limit=self.max_docs,
+                        score_threshold=self.threshold
+                    )
+
+                    if not results:
+                        return "No relevant policy information found in the knowledge base."
+
+                    # Format results for context
+                    context_parts = []
+                    for i, result in enumerate(results, 1):
+                        # Assuming your vector store returns documents with content and metadata
+                        title = getattr(result, 'title', f'Document {i}')
+                        content = getattr(result, 'content', str(result))
+                        source = getattr(result, 'source', 'Unknown')
+
+                        context_parts.append(f"**Policy Document {i}: {title}**")
+                        context_parts.append(f"Source: {source}")
+                        context_parts.append(f"Content: {content}")
+                        context_parts.append("---")
+
+                    return "\n".join(context_parts)
+
+                except Exception as e:
+                    return f"Error searching HR knowledge base: {str(e)}"
+
+        # Add the HR knowledge search tool
+        hr_search_tool = HRKnowledgeSearchTool(
+            self.vector_store,
+            self.knowledge_threshold,
+            self.max_context_docs
+        )
+        self.tool_manager.add_tool(hr_search_tool)
+
+
+class EmployeeDataAgent(BasicAgent):
+    """
+    Agent specialized in employee profile and organizational data.
+
+    This agent handles employee-specific information like profiles, positions, salary data.
+    """
+
+    def __init__(
+        self,
+        employee_database=None,
+        access_control_rules: Dict[str, List[str]] = None,
+        **kwargs
+    ):
+        employee_system_prompt = kwargs.pop('system_prompt', None) or """
+You are an Employee Data Specialist with secure access to employee information and organizational data.
+
+Your capabilities include:
+- Employee profiles and contact information
+- Current job positions and organizational hierarchy
+- Salary and compensation data (when authorized)
+- Performance records (when authorized)
+- Team and department assignments
+- Employment history and tenure information
+
+Security and Privacy Guidelines:
+- Always verify user authorization before accessing sensitive data
+- Only provide information the requesting user is authorized to see
+- Log all data access requests for audit purposes
+- Never expose raw database queries or technical implementation details
+- Respect confidentiality levels and data classification
+- Follow GDPR and other applicable privacy regulations
+
+When handling requests:
+1. Check user authorization for the requested data type
+2. Query only the specific information needed
+3. Format responses in a clear, professional manner
+4. Include appropriate disclaimers for sensitive information
+5. Suggest alternative approaches if access is restricted
+"""
+
+        super().__init__(
+            name="EmployeeDataAgent",
+            system_prompt=employee_system_prompt,
+            **kwargs
+        )
+
+        self.employee_database = employee_database
+        self.access_rules = access_control_rules or {
+            'salary_data': ['self', 'manager', 'hr'],
+            'personal_info': ['self', 'hr'],
+            'performance_data': ['self', 'manager', 'hr'],
+            'contact_info': ['all'],
+            'organizational_data': ['all']
+        }
+
+        # Add employee data tools if database is provided
+        if self.employee_database:
+            self._setup_employee_data_tools()
+
+    def _setup_employee_data_tools(self):
+        """Setup employee data access tools with security controls."""
+
+        class EmployeeProfileTool(AbstractTool):
+            """Tool for accessing employee profile information."""
+
+            def __init__(self, database, access_rules):
+                super().__init__()
+                self.database = database
+                self.access_rules = access_rules
+                self.name = "get_employee_profile"
+                self.description = "Get employee profile information including position, department, and contact details"
+
+                self.input_schema = {
+                    "type": "object",
+                    "properties": {
+                        "employee_id": {
+                            "type": "string",
+                            "description": "Employee ID to lookup"
+                        },
+                        "requesting_user_id": {
+                            "type": "string",
+                            "description": "ID of user making the request"
+                        },
+                        "data_types": {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "enum": ["profile", "position", "contact", "salary", "performance"]
+                            },
+                            "description": "Types of data to retrieve"
+                        }
+                    },
+                    "required": ["employee_id", "requesting_user_id"],
+                    "additionalProperties": False
+                }
+
+            async def _execute(
+                self,
+                employee_id: str,
+                requesting_user_id: str,
+                data_types: List[str] = None,
+                **kwargs
+            ) -> str:
+                """Execute employee data query with access controls."""
+                try:
+                    # Check authorization for each data type
+                    authorized_data = []
+                    denied_data = []
+
+                    data_types = data_types or ['profile', 'position', 'contact']
+
+                    for data_type in data_types:
+                        if self._check_access(requesting_user_id, employee_id, data_type):
+                            authorized_data.append(data_type)
+                        else:
+                            denied_data.append(data_type)
+
+                    if not authorized_data:
+                        return f"Access denied: No authorization for requested data types: {', '.join(data_types)}"
+
+                    # Query database for authorized data
+                    # This is where you'd integrate with your actual employee database
+                    result_parts = []
+
+                    if 'profile' in authorized_data:
+                        # Mock data - replace with actual database query
+                        result_parts.append(f"Employee Profile for {employee_id}:")
+                        result_parts.append(f"- Name: [Retrieved from database]")
+                        result_parts.append(f"- Employee ID: {employee_id}")
+                        result_parts.append(f"- Start Date: [Retrieved from database]")
+
+                    if 'position' in authorized_data:
+                        result_parts.append(f"Position Information:")
+                        result_parts.append(f"- Title: [Retrieved from database]")
+                        result_parts.append(f"- Department: [Retrieved from database]")
+                        result_parts.append(f"- Manager: [Retrieved from database]")
+
+                    if 'salary' in authorized_data:
+                        result_parts.append(f"Compensation Information:")
+                        result_parts.append(f"- Salary: [Retrieved from database]")
+                        result_parts.append(f"- Last Review: [Retrieved from database]")
+
+                    result = "\n".join(result_parts)
+
+                    if denied_data:
+                        result += f"\n\nNote: Access denied for: {', '.join(denied_data)}"
+
+                    return result
+
+                except Exception as e:
+                    return f"Error retrieving employee data: {str(e)}"
+
+            def _check_access(self, requesting_user: str, target_employee: str, data_type: str) -> bool:
+                """Check if user has access to specific data type."""
+                # Simplified access control - replace with your actual logic
+
+                # Users can always access their own basic info
+                if requesting_user == target_employee and data_type in ['profile', 'position', 'contact']:
+                    return True
+
+                # Check access rules
+                allowed_roles = self.access_rules.get(data_type, [])
+
+                # This is where you'd check the user's actual role
+                # For demo purposes, we'll assume some basic logic
+                if 'all' in allowed_roles:
+                    return True
+
+                # Add your actual role checking logic here
+                return False
+
+        class VacationBalanceTool(AbstractTool):
+            """Tool for checking vacation day balances."""
+
+            def __init__(self, database):
+                super().__init__()
+                self.database = database
+                self.name = "get_vacation_balance"
+                self.description = "Get current vacation day balance and accrual information"
+
+                self.input_schema = {
+                    "type": "object",
+                    "properties": {
+                        "employee_id": {
+                            "type": "string",
+                            "description": "Employee ID to check balance for"
+                        }
+                    },
+                    "required": ["employee_id"],
+                    "additionalProperties": False
+                }
+
+            async def _execute(self, employee_id: str, **kwargs) -> str:
+                """Get vacation balance information."""
+                try:
+                    # Mock vacation data - replace with actual database query
+                    return f"""Vacation Balance for Employee {employee_id}:
+- Current Available Days: 15.5 days
+- Used This Year: 4.5 days
+- Total Annual Allocation: 20 days
+- Accrual Rate: 1.67 days per month
+- Next Accrual Date: End of current month
+- Rollover Limit: 5 days maximum"""
+
+                except Exception as e:
+                    return f"Error retrieving vacation balance: {str(e)}"
+
+        # Add employee data tools
+        profile_tool = EmployeeProfileTool(self.employee_database, self.access_rules)
+        vacation_tool = VacationBalanceTool(self.employee_database)
+
+        self.tool_manager.add_tool(profile_tool)
+        self.tool_manager.add_tool(vacation_tool)

parrot/bots/orchestration/storage/__init__.py

@@ -0,0 +1,4 @@
+from .memory import ExecutionMemory
+
+
+__all__ = ["ExecutionMemory"]

parrot/bots/orchestration/storage/memory.py

@@ -0,0 +1,100 @@
+from typing import Dict, List, Optional, Any
+from dataclasses import dataclass, field
+import asyncio
+from ....models.crew import AgentResult
+from .mixin import VectorStoreMixin
+
+@dataclass
+class ExecutionMemory(VectorStoreMixin):
+    """In-memory storage for execution history"""
+    original_query: Optional[str] = None
+    results: Dict[str, AgentResult] = field(default_factory=dict)
+    execution_graph: Dict[str, List[str]] = field(default_factory=dict)
+    execution_order: List[str] = field(default_factory=list)
+
+    def __init__(
+        self, original_query: str = "",
+        embedding_model=None,
+        dimension: int = 384,
+        index_type: str = "Flat"  # "Flat", "FlatIP", o "HNSW"
+    ):
+        self.original_query = original_query
+        self.results = {}
+        self.execution_graph = {}
+        self.execution_order = []
+        # Initialize mixin
+        VectorStoreMixin.__init__(
+            self,
+            embedding_model=embedding_model,
+            dimension=dimension,
+            index_type=index_type
+        )
+
+    def add_result(self, result: AgentResult, vectorize: bool = True):
+        """Add a result and update execution graph"""
+        self.results[result.agent_id] = result
+        if result.parent_execution_id:
+            if result.parent_execution_id not in self.execution_graph:
+                self.execution_graph[result.parent_execution_id] = []
+            self.execution_graph[result.parent_execution_id].append(result.execution_id)
+
+        # Async vectorization if enabled
+        if vectorize and self.embedding_model:
+            asyncio.create_task(
+                self._vectorize_result_async(result)
+            )
+
+    def get_results_by_agent(self, agent_id: str) -> AgentResult:
+        """Retrieve result from a specific agent"""
+        return self.results.get(agent_id)
+
+    def get_reexecuted_results(self) -> List[AgentResult]:
+        """Get only results from re-executions triggered by ask()"""
+        return [r for r in self.results.values() if r.parent_execution_id is not None]
+
+    def get_context_for_agent(self, agent_id: str) -> Any:
+        idx = self.execution_order.index(agent_id)
+        if idx == 0:
+            return self.original_query
+        prev_agent_id = self.execution_order[idx - 1]
+        return self.results[prev_agent_id].result
+
+    def clear(self, keep_query: bool = False):
+        """
+        Clear execution memory.
+
+        Args:
+            keep_query: If True, preserves the original_query. Useful for re-running
+            the same query with fresh execution.
+        """
+        self.results.clear()
+        self.execution_graph.clear()
+        self.execution_order.clear()
+        self._clear_vectors()
+
+        if not keep_query:
+            self.original_query = ""
+
+    def get_snapshot(self) -> Dict[str, Any]:
+        """
+        Get a snapshot of current memory state for inspection.
+
+        Returns:
+            Dictionary with all memory state information
+        """
+        return {
+            "original_query": self.original_query,
+            "results": {
+                agent_id: {
+                    "content": result.content,
+                    "metadata": result.metadata,
+                    "timestamp": result.timestamp.isoformat(),
+                    "parent_execution_id": result.parent_execution_id
+                }
+                for agent_id, result in self.results.items()
+            },
+            "execution_order": self.execution_order.copy(),
+            "execution_graph": {k: v.copy() for k, v in self.execution_graph.items()},
+            "total_executions": len(self.results),
+            "reexecutions": len(self.get_reexecuted_results())
+        }

parrot/bots/orchestration/storage/mixin.py

@@ -0,0 +1,119 @@
+from typing import List, Tuple, Optional, Any
+from ....models.crew import AgentResult, VectorStoreProtocol
+
+
+class VectorStoreMixin:
+    """Mixin to add FAISS vector store capabilities to ExecutionMemory"""
+
+    def __init__(
+        self,
+        *args,
+        embedding_model: Optional[VectorStoreProtocol] = None,
+        dimension: int = 384,
+        index_type: str = "Flat",
+        **kwargs
+    ):
+        super().__init__(*args, **kwargs)
+        import faiss  # Ensure faiss is available
+        self.embedding_model = embedding_model
+        self.dimension = dimension
+        self._faiss_index: Optional[Any] = None
+        self._vector_chunks: List[Tuple[str, str]] = []  # (chunk_text, agent_id)
+
+        if embedding_model:
+            from sentence_transformers import SentenceTransformer
+            if isinstance(embedding_model, str):
+                self.embedding_model = SentenceTransformer(embedding_model)
+            try:
+                # Initialize FAISS index based on type
+                if index_type == "FlatIP":
+                    self._faiss_index = faiss.IndexFlatIP(dimension)
+                elif index_type == "HNSW":
+                    self._faiss_index = faiss.IndexHNSWFlat(dimension, 32, faiss.METRIC_INNER_PRODUCT)
+                else:  # Default to FlatL2
+                    self._faiss_index = faiss.IndexFlatL2(dimension)
+
+            except ImportError:
+                self._faiss_index = None
+
+    def _chunk_result(self, result: AgentResult) -> List[str]:
+        """Break down result into semantically meaningful chunks"""
+        text = result.to_text()
+
+        # Simple chunking - can be enhanced
+        if len(text) < 500:
+            return [text]
+
+        chunks = []
+        sections = text.split('\n\n')
+        current_chunk = []
+        current_length = 0
+
+        for section in sections:
+            if current_length + len(section) > 500 and current_chunk:
+                chunks.append('\n'.join(current_chunk))
+                current_chunk = [section]
+                current_length = len(section)
+            else:
+                current_chunk.append(section)
+                current_length += len(section)
+
+        if current_chunk:
+            chunks.append('\n'.join(current_chunk))
+
+        return chunks
+
+    async def _vectorize_result_async(self, result: AgentResult):
+        """Async task to vectorize and index a result"""
+        if not self._faiss_available or not self.embedding_model or self._faiss_index is None:
+            return
+
+        # Chunk the result
+        chunks = self._chunk_result(result)
+
+        # Store chunks with agent reference
+        for chunk in chunks:
+            self._vector_chunks.append((chunk, result.agent_id))
+
+        # Generate embeddings for all chunks
+        all_texts = [chunk for chunk, _ in self._vector_chunks]
+        embeddings = self.embedding_model.encode(all_texts, convert_to_numpy=True)
+
+        # Ensure correct dtype and shape
+        embeddings = embeddings.astype('float32')
+
+        # Rebuild index with all embeddings
+        self._faiss_index.reset()
+        self._faiss_index.add(embeddings)
+
+    def search_similar(self, query: str, top_k: int = 5) -> List[Tuple[str, AgentResult, float]]:
+        """Search for semantically similar result chunks"""
+        if not self._faiss_available or self._faiss_index is None or self._faiss_index.ntotal == 0:
+            return []
+
+        # Generate query embedding
+        query_embedding = self.embedding_model.encode([query], convert_to_numpy=True)
+        query_embedding = query_embedding.astype('float32')
+
+        # Ensure correct shape (1, dimension)
+        if len(query_embedding.shape) == 1:
+            query_embedding = query_embedding.reshape(1, -1)
+
+        # Search FAISS - API correcta
+        k = min(top_k, self._faiss_index.ntotal)
+        D, I = self._faiss_index.search(query_embedding, k)
+
+        results = []
+        for idx, distance in zip(I[0], D[0]):
+            if idx < len(self._vector_chunks) and idx >= 0:  # idx puede ser -1 si no hay suficientes resultados
+                chunk_text, agent_id = self._vector_chunks[idx]
+                if (agent_result := self.results.get(agent_id)):
+                    results.append((chunk_text, agent_result, float(distance)))
+
+        return results
+
+    def _clear_vectors(self):
+        """Clear vector store data"""
+        self._vector_chunks.clear()
+        if self._faiss_index:
+            self._faiss_index.reset()