march-agent 0.1.1__py3-none-any.whl

march_agent/cli.py

@@ -0,0 +1,139 @@
+"""CLI interface for March AI Agent framework.
+
+Inspired by uvicorn's simple pattern: march-agent run main:app
+"""
+
+import sys
+import argparse
+import importlib
+from pathlib import Path
+
+
+def import_from_string(import_str: str):
+    """
+    Import an attribute from a module using uvicorn-style string.
+
+    Examples:
+        "main:app" → imports 'app' from 'main' module
+        "main:setup" → imports 'setup' from 'main' module
+        "main" → imports 'main' module and looks for 'app' attribute
+
+    Args:
+        import_str: Import string in format "module:attribute" or "module"
+
+    Returns:
+        tuple: (module, attribute_name, attribute_value)
+    """
+    # Add current directory to path
+    sys.path.insert(0, str(Path.cwd()))
+
+    # Parse import string
+    if ":" in import_str:
+        module_str, attr_str = import_str.split(":", 1)
+    else:
+        module_str = import_str
+        attr_str = "app"  # Default to 'app' like uvicorn
+
+    # Import module
+    try:
+        module = importlib.import_module(module_str)
+    except ImportError as e:
+        raise ImportError(f"Could not import module '{module_str}': {e}")
+
+    # Get attribute
+    if not hasattr(module, attr_str):
+        raise AttributeError(
+            f"Module '{module_str}' has no attribute '{attr_str}'. "
+            f"Please ensure you have '{attr_str} = MarchAgentApp(...)' in your file."
+        )
+
+    attr = getattr(module, attr_str)
+    return module, attr_str, attr
+
+
+def run_agent(import_str: str) -> None:
+    """
+    Load and run an agent using uvicorn-style import string.
+
+    Args:
+        import_str: Import string like "main:app" or "main"
+    """
+    from march_agent import MarchAgentApp
+
+    print(f"Loading agent from: {import_str}")
+
+    # Import the app
+    module, attr_name, app = import_from_string(import_str)
+
+    # Validate it's a MarchAgentApp
+    if not isinstance(app, MarchAgentApp):
+        raise TypeError(
+            f"Attribute '{attr_name}' must be a MarchAgentApp instance, "
+            f"got {type(app).__name__} instead."
+        )
+
+    print(f"Running {attr_name}.run()...")
+    app.run()
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="march-agent",
+        description="March AI Agent CLI - Run AI agents with uvicorn-style imports",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  march-agent run main:app             Run 'app' from 'main' module (recommended)
+  march-agent run main                 Run 'app' from 'main' module (defaults to :app)
+  march-agent run myagent:application  Run 'application' from 'myagent' module
+
+Your agent file should have:
+  app = MarchAgentApp(...)
+
+  @app.agent(name="...", about="...", document="...")
+  def my_agent(message):
+      # Handle message
+        """,
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # run command
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Run an agent",
+        description="Load and run a March AI agent using module:attribute syntax",
+    )
+    run_parser.add_argument(
+        "app",
+        help="Import path in format 'module:attribute' (e.g., main:app)",
+    )
+
+    # version command
+    version_parser = subparsers.add_parser(
+        "version",
+        help="Show version information",
+    )
+
+    args = parser.parse_args()
+
+    # Handle commands
+    if args.command == "run":
+        try:
+            run_agent(args.app)
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.command == "version":
+        from march_agent import __version__
+        print(f"march-agent version {__version__}")
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

march_agent/conversation.py

@@ -0,0 +1,103 @@
+"""Conversation context for accessing message history."""
+
+import asyncio
+from typing import List, Dict, Any, Optional
+
+from .conversation_client import ConversationClient
+from .conversation_message import ConversationMessage
+
+
+class Conversation:
+    """Lazy-loaded conversation context (async)."""
+
+    def __init__(
+        self,
+        conversation_id: str,
+        client: ConversationClient,
+        agent_name: Optional[str] = None,
+    ):
+        self.id = conversation_id
+        self._client = client
+        self._agent_name = agent_name
+
+    async def get_history(
+        self,
+        role: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[ConversationMessage]:
+        """Fetch conversation message history.
+
+        Args:
+            role: Optional filter by role ('user', 'assistant', 'system')
+            limit: Maximum messages to fetch
+            offset: Pagination offset
+
+        Returns:
+            List of ConversationMessage objects
+        """
+        messages = await self._client.get_messages(
+            conversation_id=self.id, role=role, limit=limit, offset=offset
+        )
+        return ConversationMessage.from_list(messages)
+
+    async def get_metadata(self) -> Dict[str, Any]:
+        """Fetch conversation metadata."""
+        return await self._client.get_conversation(self.id)
+
+    async def get_agent_history(
+        self,
+        agent_name: Optional[str] = None,
+        role: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[ConversationMessage]:
+        """Fetch messages where agent was sender or recipient.
+
+        Makes two API calls concurrently to get both sent and received messages,
+        then merges and sorts by sequence number.
+
+        Args:
+            agent_name: The agent name to filter by. Defaults to the current agent
+                if not specified (requires agent_name to be set during Conversation init).
+            role: Optional role filter ('user', 'assistant', 'system')
+            limit: Maximum messages to fetch per query
+            offset: Pagination offset
+
+        Returns:
+            List of ConversationMessage where from_==agent_name OR to_==agent_name
+
+        Raises:
+            ValueError: If agent_name is not provided and no default is set.
+        """
+        # Use provided agent_name or fall back to the default from init
+        agent_name = agent_name or self._agent_name
+        if not agent_name:
+            raise ValueError(
+                "agent_name must be provided either as argument or set during Conversation initialization"
+            )
+        # Run both queries concurrently
+        sent_task = self._client.get_messages(
+            conversation_id=self.id,
+            role=role,
+            from_=agent_name,
+            limit=limit,
+            offset=offset,
+        )
+
+        received_task = self._client.get_messages(
+            conversation_id=self.id,
+            role=role,
+            to_=agent_name,
+            limit=limit,
+            offset=offset,
+        )
+
+        sent, received = await asyncio.gather(sent_task, received_task)
+
+        # Merge and dedupe (in case from_==to_)
+        all_msgs = {msg["id"]: msg for msg in sent + received}
+
+        # Sort by sequence_number and convert to typed messages
+        sorted_msgs = sorted(all_msgs.values(), key=lambda m: m.get("sequence_number", 0))
+        return ConversationMessage.from_list(sorted_msgs)

march_agent/conversation_client.py

@@ -0,0 +1,86 @@
+"""Conversation store client for fetching conversation history."""
+
+import logging
+from typing import List, Dict, Any, Optional
+import aiohttp
+
+from .exceptions import APIException
+
+logger = logging.getLogger(__name__)
+
+
+class ConversationClient:
+    """Client for interacting with conversation-store API (async)."""
+
+    def __init__(self, base_url: str):
+        self.base_url = base_url.rstrip("/")
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        """Get or create aiohttp session."""
+        if self._session is None or self._session.closed:
+            timeout = aiohttp.ClientTimeout(total=10.0)
+            self._session = aiohttp.ClientSession(timeout=timeout)
+        return self._session
+
+    async def close(self):
+        """Close the aiohttp session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def get_conversation(self, conversation_id: str) -> Dict[str, Any]:
+        """Get conversation metadata."""
+        url = f"{self.base_url}/conversations/{conversation_id}"
+        session = await self._get_session()
+        try:
+            async with session.get(url) as response:
+                if response.status == 404:
+                    raise APIException(f"Conversation {conversation_id} not found")
+                response.raise_for_status()
+                return await response.json()
+        except aiohttp.ClientError as e:
+            raise APIException(f"Failed to fetch conversation: {e}")
+
+    async def get_messages(
+        self,
+        conversation_id: str,
+        role: Optional[str] = None,
+        from_: Optional[str] = None,
+        to_: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """Get messages from a conversation."""
+        url = f"{self.base_url}/conversations/{conversation_id}/messages"
+        params = {"limit": min(limit, 1000), "offset": offset}
+        if role:
+            params["role"] = role
+        if from_:
+            params["from"] = from_
+        if to_:
+            params["to"] = to_
+
+        session = await self._get_session()
+        try:
+            async with session.get(url, params=params) as response:
+                if response.status == 404:
+                    raise APIException(f"Conversation {conversation_id} not found")
+                response.raise_for_status()
+                return await response.json()
+        except aiohttp.ClientError as e:
+            raise APIException(f"Failed to fetch messages: {e}")
+
+    async def update_conversation(
+        self,
+        conversation_id: str,
+        data: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Update conversation fields (PATCH)."""
+        url = f"{self.base_url}/conversations/{conversation_id}"
+        session = await self._get_session()
+        try:
+            async with session.patch(url, json=data) as response:
+                response.raise_for_status()
+                return await response.json()
+        except aiohttp.ClientError as e:
+            raise APIException(f"Failed to update conversation: {e}")

march_agent/conversation_message.py

@@ -0,0 +1,48 @@
+"""Typed message from conversation-store."""
+
+from dataclasses import dataclass
+from typing import Dict, Any, Optional, List
+
+
+@dataclass
+class ConversationMessage:
+    """A message from conversation-store.
+
+    Represents a stored message in a conversation with full metadata.
+    """
+
+    id: str
+    conversation_id: str
+    role: str  # "user", "assistant", "system"
+    content: str
+    sequence_number: int
+    from_: Optional[str] = None  # Sender (agent name or "user")
+    to_: Optional[str] = None  # Recipient
+    metadata: Optional[Dict[str, Any]] = None
+    schema: Optional[Dict[str, Any]] = None
+    response_schema: Optional[Dict[str, Any]] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ConversationMessage":
+        """Create from conversation-store API response."""
+        return cls(
+            id=str(data.get("id", "")),
+            conversation_id=str(data.get("conversation_id", "")),
+            role=data.get("role", ""),
+            content=data.get("content", ""),
+            sequence_number=data.get("sequence_number", 0),
+            from_=data.get("from_"),
+            to_=data.get("to_"),
+            metadata=data.get("metadata"),
+            schema=data.get("schema"),
+            response_schema=data.get("response_schema"),
+            created_at=data.get("created_at"),
+            updated_at=data.get("updated_at"),
+        )
+
+    @classmethod
+    def from_list(cls, data: List[Dict[str, Any]]) -> List["ConversationMessage"]:
+        """Create list from conversation-store API response."""
+        return [cls.from_dict(item) for item in data]

march_agent/exceptions.py

@@ -0,0 +1,36 @@
+"""Custom exceptions for March AI Agent framework."""
+
+
+class MarchAgentError(Exception):
+    """Base exception for all March Agent errors."""
+    pass
+
+
+class RegistrationError(MarchAgentError):
+    """Raised when agent registration fails."""
+    pass
+
+
+class KafkaError(MarchAgentError):
+    """Raised when Kafka operations fail."""
+    pass
+
+
+class HeartbeatError(MarchAgentError):
+    """Raised when heartbeat operations fail."""
+    pass
+
+
+class MessageHandlerError(MarchAgentError):
+    """Raised when message handler execution fails."""
+    pass
+
+
+class ConfigurationError(MarchAgentError):
+    """Raised when configuration is invalid."""
+    pass
+
+
+class APIException(MarchAgentError):
+    """Raised when conversation-store API requests fail."""
+    pass

march_agent/extensions/__init__.py

@@ -0,0 +1 @@
+# Extensions package for march_agent