interagent-framework 0.1.0__py3-none-any.whl

interagent/constants.py

@@ -0,0 +1,49 @@
+"""Constants for the InterAgent framework."""
+
+from pathlib import Path
+
+# Directory structure
+INTERAGENT_DIR = Path(".interagent")
+AGENTS_DIR = INTERAGENT_DIR / "agents"
+TASKS_DIR = INTERAGENT_DIR / "tasks"
+MESSAGES_DIR = INTERAGENT_DIR / "messages"
+SHARED_DIR = INTERAGENT_DIR / "shared"
+
+# Task directories
+TASKS_ACTIVE_DIR = TASKS_DIR / "active"
+TASKS_COMPLETED_DIR = TASKS_DIR / "completed"
+
+# Message directories
+MESSAGES_PENDING_DIR = MESSAGES_DIR / "pending"
+MESSAGES_ARCHIVE_DIR = MESSAGES_DIR / "archive"
+
+# File paths
+SESSION_FILE = INTERAGENT_DIR / "session.json"
+AGENTS_FILE = INTERAGENT_DIR / "agents.json"
+
+# Valid agents
+VALID_AGENTS = ["claude", "kimi"]
+
+# Valid roles
+VALID_ROLES = ["principal", "delegate", "reviewer", "collaborator"]
+
+# Valid modes
+VALID_MODES = ["hierarchical", "peer", "review"]
+
+# Task statuses
+TASK_STATUSES = [
+    "pending",
+    "assigned",
+    "in_progress",
+    "completed",
+    "under_review",
+    "revision_needed",
+    "approved",
+    "rejected",
+]
+
+# Message types
+MESSAGE_TYPES = ["message", "delegation", "review", "discussion"]
+
+# Priorities
+PRIORITIES = ["low", "medium", "high", "critical"]

interagent/locking.py

@@ -0,0 +1,147 @@
+"""File locking mechanism for preventing race conditions."""
+
+import time
+from pathlib import Path
+from typing import Optional
+from contextlib import contextmanager
+
+from .constants import INTERAGENT_DIR
+
+LOCK_DIR = INTERAGENT_DIR / ".locks"
+DEFAULT_TIMEOUT = 30  # seconds
+DEFAULT_RETRY_DELAY = 0.1  # seconds
+
+
+class LockError(Exception):
+    """Raised when lock cannot be acquired."""
+    pass
+
+
+def acquire_lock(lock_name: str, timeout: float = DEFAULT_TIMEOUT) -> bool:
+    """Acquire a lock by creating a lock file.
+    
+    Args:
+        lock_name: Name of the lock (e.g., task_id)
+        timeout: Maximum time to wait for lock
+        
+    Returns:
+        True if lock acquired, False otherwise
+    """
+    LOCK_DIR.mkdir(parents=True, exist_ok=True)
+    lock_file = LOCK_DIR / f"{lock_name}.lock"
+    
+    start_time = time.time()
+    
+    while time.time() - start_time < timeout:
+        try:
+            # Try to create lock file exclusively
+            with open(lock_file, "x") as f:
+                f.write(str(time.time()))
+            return True
+        except FileExistsError:
+            # Lock exists, check if stale
+            try:
+                with open(lock_file, "r") as f:
+                    lock_time = float(f.read().strip())
+                
+                # If lock is older than 5 minutes, it's stale
+                if time.time() - lock_time > 300:
+                    lock_file.unlink()
+                    continue
+                    
+            except (ValueError, IOError):
+                pass
+            
+            # Wait and retry
+            time.sleep(DEFAULT_RETRY_DELAY)
+    
+    return False
+
+
+def release_lock(lock_name: str) -> bool:
+    """Release a lock by removing the lock file.
+    
+    Args:
+        lock_name: Name of the lock
+        
+    Returns:
+        True if lock was released, False if it didn't exist
+    """
+    lock_file = LOCK_DIR / f"{lock_name}.lock"
+    
+    try:
+        if lock_file.exists():
+            lock_file.unlink()
+            return True
+    except IOError:
+        pass
+    
+    return False
+
+
+@contextmanager
+def lock(lock_name: str, timeout: float = DEFAULT_TIMEOUT):
+    """Context manager for acquiring and releasing locks.
+    
+    Usage:
+        with lock("task-123"):
+            # Do work on task-123
+            pass
+    """
+    if not acquire_lock(lock_name, timeout):
+        raise LockError(f"Could not acquire lock: {lock_name}")
+    
+    try:
+        yield
+    finally:
+        release_lock(lock_name)
+
+
+def is_locked(lock_name: str) -> bool:
+    """Check if a resource is currently locked.
+    
+    Args:
+        lock_name: Name of the lock
+        
+    Returns:
+        True if locked, False otherwise
+    """
+    lock_file = LOCK_DIR / f"{lock_name}.lock"
+    
+    if not lock_file.exists():
+        return False
+    
+    # Check if lock is stale (read-only check, no side effects)
+    try:
+        with open(lock_file, "r") as f:
+            lock_time = float(f.read().strip())
+
+        # If lock is older than 5 minutes, treat as not locked
+        # (acquire_lock() will clean it up when needed)
+        if time.time() - lock_time > 300:
+            return False
+
+    except (ValueError, IOError):
+        pass
+
+    return True
+
+
+def wait_for_unlock(lock_name: str, timeout: float = DEFAULT_TIMEOUT) -> bool:
+    """Wait for a lock to be released.
+    
+    Args:
+        lock_name: Name of the lock
+        timeout: Maximum time to wait
+        
+    Returns:
+        True if unlocked (or was never locked), False if timeout
+    """
+    start_time = time.time()
+    
+    while time.time() - start_time < timeout:
+        if not is_locked(lock_name):
+            return True
+        time.sleep(DEFAULT_RETRY_DELAY)
+    
+    return False

interagent/messaging.py

@@ -0,0 +1,183 @@
+"""Messaging system for InterAgent."""
+
+from typing import Any, Dict, List, Optional
+
+from .constants import MESSAGES_PENDING_DIR, MESSAGES_ARCHIVE_DIR, MESSAGE_TYPES
+from .utils import load_json, save_json, generate_id, now_iso
+
+
+class Message:
+    """Represents a message between agents."""
+
+    def __init__(self, data: Dict[str, Any]):
+        """Initialize message with data."""
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        """Get message ID."""
+        return self._data.get("id", "unknown")
+
+    @property
+    def sender(self) -> str:
+        """Get sender agent."""
+        return self._data.get("from", "unknown")
+
+    @property
+    def recipient(self) -> str:
+        """Get recipient agent."""
+        return self._data.get("to", "unknown")
+
+    @property
+    def subject(self) -> str:
+        """Get message subject."""
+        return self._data.get("subject", "")
+
+    @property
+    def content(self) -> str:
+        """Get message content."""
+        return self._data.get("content", "")
+
+    @property
+    def message_type(self) -> str:
+        """Get message type."""
+        return self._data.get("type", "message")
+
+    @property
+    def timestamp(self) -> str:
+        """Get timestamp."""
+        return self._data.get("timestamp", "")
+
+    @property
+    def is_read(self) -> bool:
+        """Check if message is read."""
+        return self._data.get("read", False)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return self._data
+
+    def to_markdown(self) -> str:
+        """Convert to markdown format."""
+        lines = [
+            f"## Message from {self.sender.upper()}",
+            "",
+            f"**To:** {self.recipient}",
+            f"**Subject:** {self.subject or '(no subject)'}",
+            f"**Time:** {self.timestamp}",
+            f"**Type:** {self.message_type}",
+            "",
+            self.content,
+            "",
+        ]
+        return "\n".join(lines)
+
+    @classmethod
+    def load(cls, message_id: str, pending: bool = True) -> Optional["Message"]:
+        """Load message by ID."""
+        if pending:
+            filepath = MESSAGES_PENDING_DIR / f"{message_id}.json"
+        else:
+            filepath = MESSAGES_ARCHIVE_DIR / f"{message_id}.json"
+        
+        data = load_json(filepath)
+        if data:
+            return cls(data)
+        return None
+
+    def save(self, pending: bool = True) -> bool:
+        """Save message to file."""
+        if pending:
+            filepath = MESSAGES_PENDING_DIR / f"{self.id}.json"
+        else:
+            filepath = MESSAGES_ARCHIVE_DIR / f"{self.id}.json"
+        return save_json(filepath, self._data)
+
+    def mark_read(self) -> bool:
+        """Mark message as read and move to archive."""
+        pending_path = MESSAGES_PENDING_DIR / f"{self.id}.json"
+        archive_path = MESSAGES_ARCHIVE_DIR / f"{self.id}.json"
+        
+        self._data["read"] = True
+        self._data["read_at"] = now_iso()
+        
+        save_json(archive_path, self._data)
+        
+        if pending_path.exists():
+            pending_path.unlink()
+            return True
+        return False
+
+    @classmethod
+    def create(
+        cls,
+        sender: str,
+        recipient: str,
+        content: str,
+        subject: str = "",
+        message_type: str = "message",
+        task_id: Optional[str] = None,
+    ) -> "Message":
+        """Create a new message."""
+        if message_type not in MESSAGE_TYPES:
+            message_type = "message"
+
+        data = {
+            "id": generate_id("msg"),
+            "from": sender,
+            "to": recipient,
+            "subject": subject,
+            "content": content,
+            "type": message_type,
+            "timestamp": now_iso(),
+            "read": False,
+            "task_id": task_id,
+        }
+
+        return cls(data)
+
+
+class MessageBus:
+    """Manages message routing and storage."""
+
+    @staticmethod
+    def send(message: Message) -> bool:
+        """Send a message (save to pending)."""
+        return message.save(pending=True)
+
+    @staticmethod
+    def get_inbox(agent: str) -> List[Message]:
+        """Get all pending messages for an agent."""
+        messages = []
+        for filepath in MESSAGES_PENDING_DIR.glob("*.json"):
+            data = load_json(filepath)
+            if data and data.get("to") == agent:
+                messages.append(Message(data))
+        return sorted(messages, key=lambda m: m.timestamp)
+
+    @staticmethod
+    def get_outbox(agent: str) -> List[Message]:
+        """Get all sent messages from an agent."""
+        messages = []
+        
+        # Check pending
+        for filepath in MESSAGES_PENDING_DIR.glob("*.json"):
+            data = load_json(filepath)
+            if data and data.get("from") == agent:
+                messages.append(Message(data))
+        
+        # Check archive
+        for filepath in MESSAGES_ARCHIVE_DIR.glob("*.json"):
+            data = load_json(filepath)
+            if data and data.get("from") == agent:
+                messages.append(Message(data))
+        
+        return sorted(messages, key=lambda m: m.timestamp)
+
+    @staticmethod
+    def mark_read(message_id: str) -> bool:
+        """Mark a message as read."""
+        message = Message.load(message_id, pending=True)
+        if message:
+            return message.mark_read()
+        return False

interagent/session.py

@@ -0,0 +1,129 @@
+"""Session management for InterAgent."""
+
+from typing import Any, Dict, List, Optional
+
+from .constants import SESSION_FILE, VALID_AGENTS, VALID_MODES
+from .utils import load_json, save_json, generate_id, now_iso
+
+
+class Session:
+    """Manages an inter-agent collaboration session."""
+
+    def __init__(self, data: Optional[Dict[str, Any]] = None):
+        """Initialize session with data."""
+        self._data = data or {}
+
+    @property
+    def id(self) -> str:
+        """Get session ID."""
+        return self._data.get("id", "unknown")
+
+    @property
+    def name(self) -> str:
+        """Get session name."""
+        return self._data.get("name", "Unnamed Session")
+
+    @property
+    def mode(self) -> str:
+        """Get collaboration mode."""
+        return self._data.get("mode", "hierarchical")
+
+    @property
+    def principal(self) -> str:
+        """Get principal agent."""
+        return self._data.get("principal", "claude")
+
+    @property
+    def agents(self) -> Dict[str, Dict[str, Any]]:
+        """Get agent configurations."""
+        return self._data.get("agents", {})
+
+    def get_agent_role(self, agent: str) -> str:
+        """Get role for an agent."""
+        return self.agents.get(agent, {}).get("role", "delegate")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return self._data
+
+    @classmethod
+    def load(cls) -> Optional["Session"]:
+        """Load session from file."""
+        data = load_json(SESSION_FILE)
+        if data:
+            return cls(data)
+        return None
+
+    def save(self) -> bool:
+        """Save session to file."""
+        return save_json(SESSION_FILE, self._data)
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        principal: str = "claude",
+        mode: str = "hierarchical",
+    ) -> "Session":
+        """Create a new session."""
+        if principal not in VALID_AGENTS:
+            raise ValueError(f"Invalid principal: {principal}")
+        if mode not in VALID_MODES:
+            raise ValueError(f"Invalid mode: {mode}")
+
+        agents = {}
+        for agent in VALID_AGENTS:
+            agents[agent] = {
+                "role": "principal" if agent == principal else "delegate",
+                "since": now_iso(),
+            }
+
+        data = {
+            "id": generate_id("session"),
+            "name": name,
+            "created": now_iso(),
+            "updated": now_iso(),
+            "mode": mode,
+            "principal": principal,
+            "agents": agents,
+            "active_tasks": [],
+            "completed_tasks": [],
+            "discussions": [],
+        }
+
+        return cls(data)
+
+    def update(self, **kwargs) -> None:
+        """Update session fields."""
+        self._data.update(kwargs)
+        self._data["updated"] = now_iso()
+
+    def add_task(self, task_id: str) -> None:
+        """Add task to active tasks."""
+        tasks = self._data.get("active_tasks", [])
+        if task_id not in tasks:
+            tasks.append(task_id)
+            self._data["active_tasks"] = tasks
+
+    def complete_task(self, task_id: str) -> None:
+        """Move task from active to completed."""
+        active = self._data.get("active_tasks", [])
+        completed = self._data.get("completed_tasks", [])
+        
+        if task_id in active:
+            active.remove(task_id)
+            completed.append(task_id)
+            self._data["active_tasks"] = active
+            self._data["completed_tasks"] = completed
+
+    def get_summary(self) -> Dict[str, Any]:
+        """Get session summary."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "mode": self.mode,
+            "principal": self.principal,
+            "agents": self.agents,
+            "active_tasks_count": len(self._data.get("active_tasks", [])),
+            "completed_tasks_count": len(self._data.get("completed_tasks", [])),
+        }