basion-agent 0.4.0__py3-none-any.whl

basion_agent/attachment_client.py

@@ -0,0 +1,153 @@
+"""HTTP client for downloading attachments via gateway proxy."""
+
+import base64
+import logging
+from dataclasses import dataclass
+from io import BytesIO
+from typing import Optional
+
+import aiohttp
+
+from .exceptions import APIException
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AttachmentInfo:
+    """Attachment metadata from message."""
+
+    id: str
+    url: str
+    filename: str
+    content_type: str
+    size: int
+    object_key: Optional[str] = None
+
+    @property
+    def file_extension(self) -> str:
+        """Get file extension without dot (e.g., 'pdf', 'png')."""
+        if "." in self.filename:
+            return self.filename.rsplit(".", 1)[-1].lower()
+        return ""
+
+    @property
+    def file_type(self) -> str:
+        """Get plain text file type (e.g., 'png', 'jpeg', 'pdf')."""
+        # Map common MIME types to simple names
+        mime_to_type = {
+            "image/png": "png",
+            "image/jpeg": "jpeg",
+            "image/jpg": "jpeg",
+            "image/gif": "gif",
+            "image/webp": "webp",
+            "image/svg+xml": "svg",
+            "application/pdf": "pdf",
+        }
+        if self.content_type in mime_to_type:
+            return mime_to_type[self.content_type]
+        # Fallback to extension or content_type subtype
+        if self.file_extension:
+            return self.file_extension
+        if "/" in self.content_type:
+            return self.content_type.split("/")[-1]
+        return "unknown"
+
+    def is_image(self) -> bool:
+        """Check if attachment is an image."""
+        return self.content_type.startswith("image/")
+
+    def is_pdf(self) -> bool:
+        """Check if attachment is a PDF."""
+        return self.content_type == "application/pdf"
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "AttachmentInfo":
+        """Create AttachmentInfo from dictionary."""
+        return cls(
+            id=data.get("id", ""),
+            url=data.get("url", ""),
+            filename=data.get("filename", ""),
+            content_type=data.get("content_type", "application/octet-stream"),
+            size=data.get("size", 0),
+            object_key=data.get("object_key"),
+        )
+
+
+class AttachmentClient:
+    """Client for downloading attachments into memory via gateway proxy."""
+
+    def __init__(self, base_url: str):
+        """
+        Initialize the attachment client.
+
+        Args:
+            base_url: Base URL for the attachment service proxy (e.g., "http://gateway:8080/s/attachment")
+        """
+        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=120.0)  # 2 min for large files
+            self._session = aiohttp.ClientSession(timeout=timeout)
+        return self._session
+
+    async def close(self):
+        """Close the HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def download(self, url: str) -> bytes:
+        """
+        Download file into memory as bytes.
+
+        Args:
+            url: URL path to the attachment (e.g., "/attachments/file/tenant/conv/id_file.pdf")
+
+        Returns:
+            File content as bytes
+        """
+        # Normalize URL - remove leading slash if present
+        url_path = url.lstrip("/")
+        full_url = f"{self.base_url}/{url_path}"
+        logger.info(f"Downloading attachment from: {full_url}")
+        session = await self._get_session()
+
+        try:
+            async with session.get(full_url) as response:
+                if response.status == 404:
+                    raise APIException(f"Attachment not found: {url}")
+                response.raise_for_status()
+                data = await response.read()
+                logger.debug(f"Downloaded attachment: {url} ({len(data)} bytes)")
+                return data
+        except aiohttp.ClientError as e:
+            raise APIException(f"Failed to download attachment: {e}")
+
+    async def download_as_base64(self, url: str) -> str:
+        """
+        Download and encode as base64 (for LLM vision APIs).
+
+        Args:
+            url: URL path to the attachment
+
+        Returns:
+            Base64 encoded string of the file content
+        """
+        data = await self.download(url)
+        return base64.b64encode(data).decode("utf-8")
+
+    async def download_to_buffer(self, url: str) -> BytesIO:
+        """
+        Download to BytesIO buffer (for PDF/document processing libraries).
+
+        Args:
+            url: URL path to the attachment
+
+        Returns:
+            BytesIO buffer containing the file content
+        """
+        data = await self.download(url)
+        return BytesIO(data)

basion_agent/checkpoint_client.py

@@ -0,0 +1,169 @@
+"""HTTP client for checkpoint storage API."""
+
+import logging
+from typing import List, Dict, Any, Optional
+import aiohttp
+
+from .exceptions import APIException
+
+logger = logging.getLogger(__name__)
+
+
+class CheckpointClient:
+    """Async HTTP client for checkpoint-store API.
+
+    This client communicates with the conversation-store's checkpoint endpoints
+    to store and retrieve LangGraph-compatible checkpoints.
+    """
+
+    def __init__(self, base_url: str):
+        """Initialize checkpoint client.
+
+        Args:
+            base_url: Base URL for the checkpoint API (e.g., http://gateway/s/conversation-store)
+        """
+        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=30.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 put(
+        self,
+        config: Dict[str, Any],
+        checkpoint: Dict[str, Any],
+        metadata: Dict[str, Any],
+        new_versions: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Store a checkpoint.
+
+        Args:
+            config: RunnableConfig with configurable containing thread_id, checkpoint_ns, checkpoint_id
+            checkpoint: Checkpoint data (channel_values, channel_versions, etc.)
+            metadata: Checkpoint metadata (source, step, parents, writes)
+            new_versions: New channel versions (optional)
+
+        Returns:
+            Config of the stored checkpoint
+        """
+        url = f"{self.base_url}/checkpoints/"
+        payload = {
+            "config": config,
+            "checkpoint": checkpoint,
+            "metadata": metadata,
+            "new_versions": new_versions or {},
+        }
+
+        session = await self._get_session()
+        try:
+            async with session.put(url, json=payload) as response:
+                if response.status >= 400:
+                    error_text = await response.text()
+                    raise APIException(f"Failed to store checkpoint: {response.status} - {error_text}")
+                return await response.json()
+        except aiohttp.ClientError as e:
+            raise APIException(f"Failed to store checkpoint: {e}")
+
+    async def get_tuple(
+        self,
+        thread_id: str,
+        checkpoint_ns: str = "",
+        checkpoint_id: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Get a checkpoint tuple.
+
+        Args:
+            thread_id: Thread identifier
+            checkpoint_ns: Checkpoint namespace (default "")
+            checkpoint_id: Specific checkpoint ID (latest if not provided)
+
+        Returns:
+            CheckpointTuple dict or None if not found
+        """
+        url = f"{self.base_url}/checkpoints/{thread_id}"
+        params = {"checkpoint_ns": checkpoint_ns}
+        if checkpoint_id:
+            params["checkpoint_id"] = checkpoint_id
+
+        session = await self._get_session()
+        try:
+            async with session.get(url, params=params) as response:
+                if response.status == 404:
+                    return None
+                if response.status >= 400:
+                    error_text = await response.text()
+                    raise APIException(f"Failed to get checkpoint: {response.status} - {error_text}")
+                result = await response.json()
+                # API returns null for not found
+                return result if result else None
+        except aiohttp.ClientError as e:
+            raise APIException(f"Failed to get checkpoint: {e}")
+
+    async def list(
+        self,
+        thread_id: Optional[str] = None,
+        checkpoint_ns: Optional[str] = None,
+        before: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """List checkpoints.
+
+        Args:
+            thread_id: Filter by thread ID
+            checkpoint_ns: Filter by namespace
+            before: Return checkpoints before this checkpoint_id
+            limit: Maximum number of checkpoints to return
+
+        Returns:
+            List of CheckpointTuple dicts
+        """
+        url = f"{self.base_url}/checkpoints/"
+        params = {}
+        if thread_id:
+            params["thread_id"] = thread_id
+        if checkpoint_ns is not None:
+            params["checkpoint_ns"] = checkpoint_ns
+        if before:
+            params["before"] = before
+        if limit:
+            params["limit"] = limit
+
+        session = await self._get_session()
+        try:
+            async with session.get(url, params=params) as response:
+                if response.status >= 400:
+                    error_text = await response.text()
+                    raise APIException(f"Failed to list checkpoints: {response.status} - {error_text}")
+                return await response.json()
+        except aiohttp.ClientError as e:
+            raise APIException(f"Failed to list checkpoints: {e}")
+
+    async def delete_thread(self, thread_id: str) -> Dict[str, Any]:
+        """Delete all checkpoints for a thread.
+
+        Args:
+            thread_id: Thread identifier
+
+        Returns:
+            Dict with thread_id and deleted count
+        """
+        url = f"{self.base_url}/checkpoints/{thread_id}"
+
+        session = await self._get_session()
+        try:
+            async with session.delete(url) as response:
+                if response.status >= 400:
+                    error_text = await response.text()
+                    raise APIException(f"Failed to delete checkpoints: {response.status} - {error_text}")
+                return await response.json()
+        except aiohttp.ClientError as e:
+            raise APIException(f"Failed to delete checkpoints: {e}")

basion_agent/checkpointer.py

@@ -0,0 +1,16 @@
+"""Checkpoint client module.
+
+This module provides the low-level HTTP client for checkpoint operations.
+For the LangGraph-compatible checkpointer, see basion_agent.extensions.langgraph.
+
+Usage:
+    from basion_agent.extensions.langgraph import HTTPCheckpointSaver
+
+    app = BasionAgentApp(gateway_url="agent-gateway:8080", api_key="key")
+    checkpointer = HTTPCheckpointSaver(app=app)
+"""
+
+# Re-export CheckpointClient for backwards compatibility
+from .checkpoint_client import CheckpointClient
+
+__all__ = ["CheckpointClient"]

basion_agent/cli.py

@@ -0,0 +1,139 @@
+"""CLI interface for Basion AI Agent framework.
+
+Inspired by uvicorn's simple pattern: basion-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} = BasionAgentApp(...)' 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 basion_agent import BasionAgentApp
+
+    print(f"Loading agent from: {import_str}")
+
+    # Import the app
+    module, attr_name, app = import_from_string(import_str)
+
+    # Validate it's a BasionAgentApp
+    if not isinstance(app, BasionAgentApp):
+        raise TypeError(
+            f"Attribute '{attr_name}' must be a BasionAgentApp 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="basion-agent",
+        description="Basion AI Agent CLI - Run AI agents with uvicorn-style imports",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  basion-agent run main:app             Run 'app' from 'main' module (recommended)
+  basion-agent run main                 Run 'app' from 'main' module (defaults to :app)
+  basion-agent run myagent:application  Run 'application' from 'myagent' module
+
+Your agent file should have:
+  app = BasionAgentApp(...)
+
+  @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 Basion 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 basion_agent import __version__
+        print(f"basion-agent version {__version__}")
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

basion_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)

basion_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}")