aiecs 1.0.1__py3-none-any.whl → 1.7.6__py3-none-any.whl

aiecs/domain/community/exceptions.py

@@ -0,0 +1,231 @@
+"""
+Community Exceptions
+
+Defines community-specific exception classes with clear error messages
+and recovery suggestions.
+"""
+
+from typing import Optional
+
+
+class CommunityException(Exception):
+    """Base exception for community-related errors."""
+
+    def __init__(self, message: str, recovery_suggestion: Optional[str] = None):
+        """
+        Initialize community exception.
+
+        Args:
+            message: Error message
+            recovery_suggestion: Optional suggestion for recovery
+        """
+        self.message = message
+        self.recovery_suggestion = recovery_suggestion
+        super().__init__(self.message)
+
+    def __str__(self):
+        """String representation with recovery suggestion."""
+        if self.recovery_suggestion:
+            return f"{self.message}\nSuggestion: {self.recovery_suggestion}"
+        return self.message
+
+
+class CommunityNotFoundError(CommunityException):
+    """Raised when a community is not found."""
+
+    def __init__(self, community_id: str):
+        super().__init__(
+            f"Community not found: {community_id}",
+            "Verify the community ID is correct and the community exists.",
+        )
+        self.community_id = community_id
+
+
+class MemberNotFoundError(CommunityException):
+    """Raised when a member is not found."""
+
+    def __init__(self, member_id: str):
+        super().__init__(
+            f"Member not found: {member_id}",
+            "Verify the member ID is correct and the member exists in the community.",
+        )
+        self.member_id = member_id
+
+
+class ResourceNotFoundError(CommunityException):
+    """Raised when a resource is not found."""
+
+    def __init__(self, resource_id: str):
+        super().__init__(
+            f"Resource not found: {resource_id}",
+            "Verify the resource ID is correct and the resource exists.",
+        )
+        self.resource_id = resource_id
+
+
+class DecisionNotFoundError(CommunityException):
+    """Raised when a decision is not found."""
+
+    def __init__(self, decision_id: str):
+        super().__init__(
+            f"Decision not found: {decision_id}",
+            "Verify the decision ID is correct and the decision exists.",
+        )
+        self.decision_id = decision_id
+
+
+class AccessDeniedError(CommunityException):
+    """Raised when access to a community resource is denied."""
+
+    def __init__(self, agent_id: str, resource_type: str, resource_id: str):
+        super().__init__(
+            f"Access denied for agent {agent_id} to {resource_type} {resource_id}",
+            "Request access from the resource owner or community administrator.",
+        )
+        self.agent_id = agent_id
+        self.resource_type = resource_type
+        self.resource_id = resource_id
+
+
+class MembershipError(CommunityException):
+    """Raised when there's an issue with community membership."""
+
+    def __init__(self, message: str, agent_id: Optional[str] = None):
+        super().__init__(message, "Check membership status and community requirements.")
+        self.agent_id = agent_id
+
+
+class VotingError(CommunityException):
+    """Raised when there's an issue with voting."""
+
+    def __init__(self, message: str, decision_id: Optional[str] = None):
+        super().__init__(
+            message,
+            "Verify voting is open and you are eligible to vote on this decision.",
+        )
+        self.decision_id = decision_id
+
+
+class GovernanceError(CommunityException):
+    """Raised when there's an issue with community governance."""
+
+    def __init__(self, message: str, community_id: Optional[str] = None):
+        super().__init__(message, "Review community governance rules and requirements.")
+        self.community_id = community_id
+
+
+class CollaborationError(CommunityException):
+    """Raised when there's an issue with collaboration."""
+
+    def __init__(self, message: str, session_id: Optional[str] = None):
+        super().__init__(message, "Check session status and participant availability.")
+        self.session_id = session_id
+
+
+class CommunityInitializationError(CommunityException):
+    """Raised when community initialization fails."""
+
+    def __init__(self, component: str, reason: str):
+        super().__init__(
+            f"Failed to initialize {component}: {reason}",
+            "Check configuration and dependencies are properly set up.",
+        )
+        self.component = component
+        self.reason = reason
+
+
+class CommunityValidationError(CommunityException):
+    """Raised when community validation fails."""
+
+    def __init__(self, field_or_message: str, reason: Optional[str] = None):
+        # Initialize attributes first
+        self.field: Optional[str]
+        self.reason: Optional[str]
+
+        if reason:
+            # Two-argument form: field and reason
+            message = f"Validation error for {field_or_message}: {reason}"
+            self.field = field_or_message
+            self.reason = reason
+        else:
+            # One-argument form: just message
+            message = field_or_message
+            self.field = None
+            self.reason = None
+
+        super().__init__(message, "Review the field value and ensure it meets requirements.")
+
+
+class QuorumNotMetError(CommunityException):
+    """Raised when quorum is not met for a decision."""
+
+    def __init__(self, required: int, actual: int, decision_id: Optional[str] = None):
+        super().__init__(
+            f"Quorum not met: {actual} votes cast, {required} required",
+            "Encourage more members to participate in voting.",
+        )
+        self.required = required
+        self.actual = actual
+        self.decision_id = decision_id
+
+
+class ConflictResolutionError(CommunityException):
+    """Raised when conflict resolution fails."""
+
+    def __init__(self, decision_id: str, strategy: str):
+        super().__init__(
+            f"Conflict resolution failed for decision {decision_id} using {strategy}",
+            "Try a different conflict resolution strategy or escalate the decision.",
+        )
+        self.decision_id = decision_id
+        self.strategy = strategy
+
+
+class CommunityCapacityError(CommunityException):
+    """Raised when community reaches capacity."""
+
+    def __init__(self, community_id: str, current: int, maximum: int):
+        super().__init__(
+            f"Community {community_id} is at capacity: {current}/{maximum} members",
+            "Create a new community or increase the member limit.",
+        )
+        self.community_id = community_id
+        self.current = current
+        self.maximum = maximum
+
+
+class AgentAdapterError(CommunityException):
+    """Raised when there's an issue with agent adapter."""
+
+    def __init__(self, agent_id: str, reason: str):
+        super().__init__(
+            f"Agent adapter error for {agent_id}: {reason}",
+            "Check agent adapter configuration and connectivity.",
+        )
+        self.agent_id = agent_id
+        self.reason = reason
+
+
+class CommunicationError(CommunityException):
+    """Raised when there's an issue with agent communication."""
+
+    def __init__(self, sender_id: str, recipient_id: str, reason: str):
+        super().__init__(
+            f"Communication error from {sender_id} to {recipient_id}: {reason}",
+            "Verify both agents are registered and active in the communication hub.",
+        )
+        self.sender_id = sender_id
+        self.recipient_id = recipient_id
+        self.reason = reason
+
+
+class ContextError(CommunityException):
+    """Raised when there's an issue with shared context."""
+
+    def __init__(self, context_id: str, reason: str):
+        super().__init__(
+            f"Context error for {context_id}: {reason}",
+            "Check context access permissions and version compatibility.",
+        )
+        self.context_id = context_id
+        self.reason = reason

aiecs/domain/community/models/__init__.py

@@ -0,0 +1,33 @@
+"""
+Community Models
+
+Data models for agent community collaboration, governance, and resource sharing.
+"""
+
+from .community_models import (
+    # Enums
+    CommunityRole,
+    GovernanceType,
+    DecisionStatus,
+    ResourceType,
+    # Models
+    CommunityMember,
+    CommunityResource,
+    CommunityDecision,
+    AgentCommunity,
+    CollaborationSession,
+)
+
+__all__ = [
+    # Enums
+    "CommunityRole",
+    "GovernanceType",
+    "DecisionStatus",
+    "ResourceType",
+    # Models
+    "CommunityMember",
+    "CommunityResource",
+    "CommunityDecision",
+    "AgentCommunity",
+    "CollaborationSession",
+]

aiecs/domain/community/models/community_models.py

@@ -0,0 +1,234 @@
+"""
+Community Collaboration Models
+
+Defines the data models for agent community collaboration,
+including governance, resource sharing, and collective decision-making.
+"""
+
+from datetime import datetime
+from typing import Dict, List, Any, Optional
+from enum import Enum
+from pydantic import BaseModel, Field, ConfigDict
+import uuid
+
+
+class CommunityRole(str, Enum):
+    """Roles within the agent community."""
+
+    LEADER = "leader"
+    COORDINATOR = "coordinator"
+    SPECIALIST = "specialist"
+    CONTRIBUTOR = "contributor"
+    OBSERVER = "observer"
+
+
+class GovernanceType(str, Enum):
+    """Types of community governance."""
+
+    DEMOCRATIC = "democratic"  # Voting-based decisions
+    CONSENSUS = "consensus"  # Consensus-based decisions
+    HIERARCHICAL = "hierarchical"  # Leader-based decisions
+    HYBRID = "hybrid"  # Mixed governance
+
+
+class DecisionStatus(str, Enum):
+    """Status of community decisions."""
+
+    PROPOSED = "proposed"
+    VOTING = "voting"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    IMPLEMENTED = "implemented"
+
+
+class ResourceType(str, Enum):
+    """Types of community resources."""
+
+    KNOWLEDGE = "knowledge"
+    TOOL = "tool"
+    EXPERIENCE = "experience"
+    DATA = "data"
+    CAPABILITY = "capability"
+
+
+class CommunityMember(BaseModel):
+    """Model representing a member of the agent community."""
+
+    member_id: str = Field(..., description="Unique identifier for the member")
+    agent_id: str = Field(..., description="Associated agent ID")
+    agent_role: str = Field(..., description="Agent's functional role")
+    community_role: CommunityRole = Field(..., description="Role within the community")
+
+    # Participation metrics
+    contribution_score: float = Field(default=0.0, description="Contribution score to the community")
+    reputation: float = Field(default=0.0, description="Reputation within the community")
+    participation_level: str = Field(default="active", description="Level of participation")
+
+    # Capabilities and specializations
+    specializations: List[str] = Field(default_factory=list, description="Areas of specialization")
+    available_resources: List[str] = Field(default_factory=list, description="Resources this member can provide")
+
+    # Status
+    is_active: bool = Field(default=True, description="Whether the member is active")
+    joined_at: datetime = Field(default_factory=datetime.utcnow, description="When the member joined")
+    last_active_at: Optional[datetime] = Field(None, description="Last activity timestamp")
+
+    # Metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    model_config = ConfigDict()
+
+
+class CommunityResource(BaseModel):
+    """Model representing a shared community resource."""
+
+    resource_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique resource identifier",
+    )
+    name: str = Field(..., description="Name of the resource")
+    resource_type: ResourceType = Field(..., description="Type of resource")
+    description: Optional[str] = Field(None, description="Description of the resource")
+
+    # Ownership and access
+    owner_id: str = Field(..., description="ID of the member who owns/contributed this resource")
+    access_level: str = Field(
+        default="public",
+        description="Access level (public, restricted, private)",
+    )
+    allowed_members: List[str] = Field(
+        default_factory=list,
+        description="Members allowed to access (if restricted)",
+    )
+
+    # Content
+    content: Dict[str, Any] = Field(default_factory=dict, description="Resource content/data")
+    tags: List[str] = Field(default_factory=list, description="Tags for categorization")
+
+    # Usage metrics
+    usage_count: int = Field(default=0, description="Number of times this resource has been used")
+    rating: float = Field(default=0.0, description="Average rating from community members")
+
+    # Status
+    is_available: bool = Field(default=True, description="Whether the resource is available")
+    created_at: datetime = Field(default_factory=datetime.utcnow, description="Creation timestamp")
+    updated_at: Optional[datetime] = Field(None, description="Last update timestamp")
+
+    # Metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    model_config = ConfigDict()
+
+
+class CommunityDecision(BaseModel):
+    """Model representing a community decision or proposal."""
+
+    decision_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique decision identifier",
+    )
+    title: str = Field(..., description="Title of the decision/proposal")
+    description: str = Field(..., description="Detailed description")
+
+    # Proposal details
+    proposer_id: str = Field(..., description="ID of the member who proposed this")
+    decision_type: str = Field(..., description="Type of decision (policy, resource, task, etc.)")
+    priority: str = Field(default="medium", description="Priority level")
+
+    # Voting and consensus
+    status: DecisionStatus = Field(default=DecisionStatus.PROPOSED, description="Current status")
+    votes_for: List[str] = Field(default_factory=list, description="Member IDs who voted for")
+    votes_against: List[str] = Field(default_factory=list, description="Member IDs who voted against")
+    abstentions: List[str] = Field(default_factory=list, description="Member IDs who abstained")
+
+    # Implementation
+    implementation_plan: Optional[str] = Field(None, description="Plan for implementing the decision")
+    assigned_members: List[str] = Field(default_factory=list, description="Members assigned to implement")
+    deadline: Optional[datetime] = Field(None, description="Implementation deadline")
+
+    # Status tracking
+    created_at: datetime = Field(default_factory=datetime.utcnow, description="Creation timestamp")
+    voting_ends_at: Optional[datetime] = Field(None, description="When voting ends")
+    implemented_at: Optional[datetime] = Field(None, description="When decision was implemented")
+
+    # Metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    model_config = ConfigDict()
+
+
+class AgentCommunity(BaseModel):
+    """Model representing an agent community."""
+
+    community_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique community identifier",
+    )
+    name: str = Field(..., description="Name of the community")
+    description: Optional[str] = Field(None, description="Description of the community")
+
+    # Governance
+    governance_type: GovernanceType = Field(default=GovernanceType.DEMOCRATIC, description="Type of governance")
+    governance_rules: Dict[str, Any] = Field(default_factory=dict, description="Governance rules and policies")
+
+    # Membership
+    members: List[str] = Field(default_factory=list, description="List of member IDs")
+    max_members: Optional[int] = Field(None, description="Maximum number of members")
+    membership_criteria: Dict[str, Any] = Field(default_factory=dict, description="Criteria for membership")
+
+    # Leadership
+    leaders: List[str] = Field(default_factory=list, description="List of leader member IDs")
+    coordinators: List[str] = Field(default_factory=list, description="List of coordinator member IDs")
+
+    # Resources and capabilities
+    shared_resources: List[str] = Field(default_factory=list, description="List of shared resource IDs")
+    collective_capabilities: List[str] = Field(default_factory=list, description="Collective capabilities")
+    knowledge_base: Dict[str, Any] = Field(default_factory=dict, description="Community knowledge base")
+
+    # Activity and metrics
+    activity_level: str = Field(default="active", description="Overall activity level")
+    collaboration_score: float = Field(default=0.0, description="Overall collaboration effectiveness score")
+    decision_count: int = Field(default=0, description="Number of decisions made")
+    resource_count: int = Field(default=0, description="Number of shared resources")
+
+    # Status
+    is_active: bool = Field(default=True, description="Whether the community is active")
+    created_at: datetime = Field(default_factory=datetime.utcnow, description="Creation timestamp")
+    updated_at: Optional[datetime] = Field(None, description="Last update timestamp")
+
+    # Metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    model_config = ConfigDict()
+
+
+class CollaborationSession(BaseModel):
+    """Model representing a collaborative session between community members."""
+
+    session_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()),
+        description="Unique session identifier",
+    )
+    community_id: str = Field(..., description="Associated community ID")
+
+    # Participants
+    participants: List[str] = Field(..., description="List of participating member IDs")
+    session_leader: Optional[str] = Field(None, description="Session leader member ID")
+
+    # Session details
+    purpose: str = Field(..., description="Purpose of the collaboration session")
+    session_type: str = Field(
+        ...,
+        description="Type of session (brainstorm, decision, problem-solving, etc.)",
+    )
+    agenda: List[str] = Field(default_factory=list, description="Session agenda items")
+
+    # Outcomes
+    decisions_made: List[str] = Field(default_factory=list, description="Decision IDs made during session")
+    resources_created: List[str] = Field(default_factory=list, description="Resource IDs created during session")
+    action_items: List[Dict[str, Any]] = Field(default_factory=list, description="Action items from the session")
+
+    # Status
+    status: str = Field(default="active", description="Session status")
+    started_at: datetime = Field(default_factory=datetime.utcnow, description="Session start time")
+    ended_at: Optional[datetime] = Field(None, description="Session end time")
+
+    # Metadata
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    model_config = ConfigDict()