bat-adk 2025.12__tar.gz

bat_adk-2025.12/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: bat-adk
+Version: 2025.12
+Summary: Software Development Kit for building AI Agents in BubbleRAN MX-PDK and MX-AI
+Author-email: Andrea LEONE <andrea.leone@bubbleran.com>
+Project-URL: Homepage, https://bubbleran.com/
+Project-URL: Repository, https://github.com/bubbleran/bat
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: a2a-sdk>=0.3.20
+Requires-Dist: a2a-sdk[http-server]
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: langchain>=0.3.24
+Requires-Dist: langchain-mcp-adapters<0.2.0,>=0.1.13
+Requires-Dist: langchain-nvidia-ai-endpoints>=0.3.9
+Requires-Dist: langchain-openai>=0.3.14
+Requires-Dist: langchain-ollama>=0.3.3
+Requires-Dist: langgraph>=1.0.0
+Requires-Dist: mcp[cli]>=1.17.0
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: uvicorn>=0.37.0
+
+# BubbleRAN Agentic Toolkit - Agent Development Kit (ADK)
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](../LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/bat-adk)](https://pypi.org/project/bat-adk/)
+
+The **BAT-ADK** is a Python-based Software Development Kit designed to simplify the development, deployment, and integration of AI Agents within the BubbleRAN architecture.
+This repository includes the ADK framework ([BubbleRAN Software License](https://bubbleran.com/resources/files/BubbleRAN_Licence-Agreement-1.3.pdf)).
+
+## Key Features
+- 🛠️ Easy-to-use Python SDK for developing AI Agents
+- 🔗 Integrates the [LangGraph](https://pypi.org/project/langgraph/) library with the [A2A SDK](https://pypi.org/project/a2a-sdk/) and [MCP SDK]() for building AI Agents beyond POCs (ready for production)
+- ☁️ Ready for Cloud-Native deployment with BubbleRAN [MX-AI](https://bubbleran.com/products/mx-ai/)
+- 🧩 Prebuilt Agentic Workflow (e.g. ReAct, A2A Communication)
+
+## Getting Started
+
+### Prerequisites
+- Python 3.12+
+- `uv` (recommended) or `pip`
+
+## Installation
+
+### Using `uv`
+```bash
+uv add bat-adk
+```
+
+### Using `pip`
+```bash
+pip install bat-adk
+```
+
+## Documentation
+
+The BAT-ADK uses [`pydoc-markdown`](https://pydoc-markdown.readthedocs.io/) to generate API documentation directly from Python docstrings.
+
+### Generating the Documentation
+
+To build the documentation locally, run:
+
+```bash
+uv run pydoc-markdown
+```
+
+The generated documentation will be available at `adk/build/docs/content/bat-adk`

bat_adk-2025.12/README.md

@@ -0,0 +1,45 @@
+# BubbleRAN Agentic Toolkit - Agent Development Kit (ADK)
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](../LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/bat-adk)](https://pypi.org/project/bat-adk/)
+
+The **BAT-ADK** is a Python-based Software Development Kit designed to simplify the development, deployment, and integration of AI Agents within the BubbleRAN architecture.
+This repository includes the ADK framework ([BubbleRAN Software License](https://bubbleran.com/resources/files/BubbleRAN_Licence-Agreement-1.3.pdf)).
+
+## Key Features
+- 🛠️ Easy-to-use Python SDK for developing AI Agents
+- 🔗 Integrates the [LangGraph](https://pypi.org/project/langgraph/) library with the [A2A SDK](https://pypi.org/project/a2a-sdk/) and [MCP SDK]() for building AI Agents beyond POCs (ready for production)
+- ☁️ Ready for Cloud-Native deployment with BubbleRAN [MX-AI](https://bubbleran.com/products/mx-ai/)
+- 🧩 Prebuilt Agentic Workflow (e.g. ReAct, A2A Communication)
+
+## Getting Started
+
+### Prerequisites
+- Python 3.12+
+- `uv` (recommended) or `pip`
+
+## Installation
+
+### Using `uv`
+```bash
+uv add bat-adk
+```
+
+### Using `pip`
+```bash
+pip install bat-adk
+```
+
+## Documentation
+
+The BAT-ADK uses [`pydoc-markdown`](https://pydoc-markdown.readthedocs.io/) to generate API documentation directly from Python docstrings.
+
+### Generating the Documentation
+
+To build the documentation locally, run:
+
+```bash
+uv run pydoc-markdown
+```
+
+The generated documentation will be available at `adk/build/docs/content/bat-adk`

bat_adk-2025.12/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bat-adk"
+version = "2025.12"
+authors = [
+  { name="Andrea LEONE", email="andrea.leone@bubbleran.com" },
+]
+description = "Software Development Kit for building AI Agents in BubbleRAN MX-PDK and MX-AI"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "a2a-sdk>=0.3.20",
+  "a2a-sdk[http-server]",
+  "httpx>=0.28.1",
+  "langchain>=0.3.24",
+  "langchain-mcp-adapters>=0.1.13,<0.2.0",
+  "langchain-nvidia-ai-endpoints>=0.3.9",
+  "langchain-openai>=0.3.14",
+  "langchain-ollama>=0.3.3",
+  "langgraph>=1.0.0",
+  "mcp[cli]>=1.17.0",
+  "pydantic>=2.10.6",
+  "pyyaml>=6.0.1",
+  "uvicorn>=0.37.0",
+]
+[dependency-groups]
+dev = [
+  "build",
+  "twine",
+]
+[project.urls]
+"Homepage" = "https://bubbleran.com/"
+"Repository" = "https://github.com/bubbleran/bat"

bat_adk-2025.12/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bat_adk-2025.12/src/bat/agent/__init__.py

@@ -0,0 +1,4 @@
+from .application import AgentApplication
+from .config import AgentConfig
+from .graph import AgentGraph
+from .state import AgentState, AgentTaskResult

bat_adk-2025.12/src/bat/agent/_executor.py

@@ -0,0 +1,122 @@
+import time
+from ..logging import create_logger
+from .graph import AgentGraph
+from .state import AgentTaskResult
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.server.tasks import TaskUpdater
+from a2a.types import (
+    InternalError,
+    InvalidParamsError,
+    Part,
+    Task,
+    TaskState,
+    TextPart,
+    UnsupportedOperationError,
+)
+from a2a.utils import (
+    new_agent_text_message,
+    new_task,
+)
+from a2a.utils.errors import ServerError
+from typing import Dict
+from typing_extensions import override, Any
+
+_logger = create_logger(__name__, "debug")
+
+class MinimalAgentExecutor(AgentExecutor):
+    """Minimal Agent Executor.
+    
+    Minimal implementation of the AgentExecutor interface used by the `AgentApplication` class to execute agent tasks.
+    """
+
+    def __init__(
+        self,
+        agent_graph: AgentGraph
+    ):
+        self.agent_graph = agent_graph
+
+    @override
+    async def execute(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        if not self._request_ok(context):
+            raise ServerError(error=InvalidParamsError())
+
+        query = context.get_user_input()
+        task = context.current_task
+        if not task:
+            task = new_task(context.message)
+            await event_queue.enqueue_event(task)
+        updater = TaskUpdater(event_queue, task.id, task.context_id)
+        try:
+            config = {"configurable": {"thread_id": task.context_id}}
+            ts = time.time()
+            keep_streaming = True
+            async for item in self.agent_graph.astream(query, config):
+                if keep_streaming:
+                    usage_metadata = self.agent_graph._get_usage_metadata(ts)
+                    ts = time.time()
+                    keep_streaming = await self._process_task_result(task, item, updater, {'usage': usage_metadata})
+                else:
+                    # TODO: add chunk status
+                    _logger.warning("Artifact has been updated: ignoring additional streamed item.")
+        except Exception as e:
+            _logger.error(f'An error occurred while streaming the response: {e}')
+            raise ServerError(error=InternalError()) from e
+
+    def _request_ok(self, context: RequestContext) -> bool:
+        return True
+
+    async def _process_task_result(
+        self,
+        task: Task,
+        task_result: AgentTaskResult,
+        updater: TaskUpdater,
+        metadata: Dict[str, Any]
+    ) -> bool:
+        keep_streaming = True
+        match task_result.task_status:
+            case "working":
+                message = new_agent_text_message(
+                    task_result.content,
+                    task.context_id,
+                    task.id,
+                )
+                await updater.update_status(
+                    TaskState.working,
+                    message,
+                    metadata=metadata,
+                )
+            case "input-required":
+                message = new_agent_text_message(
+                    task_result.content,
+                    task.context_id,
+                    task.id,
+                )
+                await updater.update_status(
+                    TaskState.input_required,
+                    message,
+                    metadata=metadata,
+                    final=True,
+                )
+                keep_streaming = False
+            case "completed":
+                await updater.add_artifact(
+                    [Part(root=TextPart(text=task_result.content))],
+                    metadata=metadata,
+                )
+                keep_streaming = False
+            case "error":
+                raise ServerError(error=InternalError(message=task_result.content))
+            case _:
+                _logger.warning(f"Unknown task status: {task_result.task_status}")
+        return keep_streaming
+
+    @override
+    async def cancel(
+        self, request: RequestContext, event_queue: EventQueue
+    ) -> Task | None:
+        raise ServerError(error=UnsupportedOperationError())

bat_adk-2025.12/src/bat/agent/application.py

@@ -0,0 +1,301 @@
+import asyncio
+import httpx
+import json
+import os
+import uuid
+import uvicorn
+from ..logging import create_logger
+from ._executor import MinimalAgentExecutor
+from .config import AgentConfig
+from .graph import AgentGraph
+from .state import AgentState
+from a2a.client import ClientConfig, ClientFactory
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.types import AgentCard, Message, TextPart
+from dotenv import load_dotenv
+from jsonschema import ValidationError
+from mcp.server import FastMCP
+from starlette.applications import Starlette
+from threading import Thread
+from typing import Optional, Type
+
+load_dotenv()
+_logger = create_logger(__name__, "debug")
+
+A2A_APPLICATION_DEFAULT_PORT = 9900
+MCP_APPLICATION_DEFAULT_PORT = 9800
+DEFAULT_HTTPX_CLIENT_TIMEOUT = 180
+
+class AgentApplication:
+    f"""Agent Application based on `Starlette`.
+    This class sets up an agent application that can handle A2A and MCP protocols.
+    Supported Environment Variables:
+        - `URL` (required): The base URL where the agent will be hosted.
+        - `PORT`: The port for the A2A application. Defaults to `{A2A_APPLICATION_DEFAULT_PORT}`.
+        - `MCP_PORT`: The port for the MCP application. Defaults to `{MCP_APPLICATION_DEFAULT_PORT}`.
+        - `CONFIG`: Path to a configuration file for the agent. Defaults to _"config.yaml"_.
+
+    Attributes
+    -------
+        agent_card (AgentCard): The agent card containing metadata about the agent.
+        agent_graph (AgentGraph): The agent graph that defines the agent's behavior and capabilities.
+    
+    Example
+    -------
+    ```python
+        from bat.agent import AgentApplication
+
+        agent = AgentApplication(
+            agent_card_path='./agent.json',
+            agent_graph=MyAgentGraph(),
+        )
+        agent.run()
+    ```
+    """
+
+    def __init__(
+        self,
+        AgentGraphType: Type[AgentGraph],
+        AgentStateType: Type[AgentState],
+        agent_card_path: str = './agent.json',
+    ):
+        """
+        Initialize the AgentApplication with the given agent card path and agent graph.
+
+        Args:
+            agent_graph (AgentGraph): The agent graph implementing the agent's logic.
+            agent_card_path (str): The path to the agent card JSON file. Defaults to _"./agent.json"_.
+        """
+        self.a2a_port = int(os.getenv("PORT", A2A_APPLICATION_DEFAULT_PORT))
+        self.mcp_port = int(os.getenv("MCP_PORT", MCP_APPLICATION_DEFAULT_PORT))
+
+        self._agent_card = self.load_agent_card(agent_card_path)
+        self._config_path = os.getenv("CONFIG", "config.yaml")
+        self._config = AgentConfig.load(self._config_path)
+
+        self._AgentStateType = AgentStateType
+        self._AgentGraphType = AgentGraphType
+        agent_graph = AgentGraphType(
+            config=self._config,
+            StateType=AgentStateType,
+        )
+        self._agent_executor = MinimalAgentExecutor(agent_graph)
+        self._request_handler = DefaultRequestHandler(
+            agent_executor=self._agent_executor,
+            task_store=InMemoryTaskStore(),
+        )
+        self._a2a_server = A2AStarletteApplication(
+            agent_card=self._agent_card,
+            http_handler=self._request_handler
+        )
+    
+    def load_agent_card(
+        self,
+        agent_card_path: str,
+    ) -> AgentCard:
+        """Load the Agent Card from a JSON file.
+
+        Args:
+            agent_card_path (str): The path to the Agent Card JSON file.
+
+        Returns:
+            AgentCard: The loaded Agent Card.
+
+        Raises:
+            Exception: For general errors during loading.
+            EnvironmentError: If the URL environment variable is not set.
+            FileNotFoundError: If the agent card file does not exist.
+            ValidationError: If the agent card JSON is invalid.
+        """
+        url = os.getenv("URL")
+        if url is None:
+            _logger.error("URL environment variable is not set.")
+            raise EnvironmentError("URL environment variable is not set.")
+        if not url.startswith("http://") and not url.startswith("https://"):
+            url = "http://" + url
+        url = url.rstrip("/")
+        port = int(os.getenv("PORT", A2A_APPLICATION_DEFAULT_PORT))
+
+        try:
+            with open(agent_card_path, 'r') as file:
+                agent_data = json.load(file)
+                agent_data.setdefault('url', f'{url}:{port}')
+                agent_card = AgentCard.model_validate(agent_data)
+                _logger.debug('Agent Card loaded.')
+        except FileNotFoundError as e:
+            raise FileNotFoundError(f'Agent card file not found.') from e
+        except ValidationError as e:
+            raise ValidationError(f'Invalid agent card format.') from e
+        except Exception as e:
+            raise Exception(f'Error loading agent card: {e}') from e
+
+        return agent_card
+
+    @property
+    def agent_graph(self) -> AgentGraph:
+        """Get the agent graph."""
+        return self._agent_executor.agent_graph
+    
+    @property
+    def agent_card(self) -> AgentCard:
+        """Get the agent card."""
+        return self._agent_card
+    
+    def _build_a2a_application(self) -> Starlette:
+        """Build the A2A Starlette application.
+        
+        Returns:
+            Starlette: The built Starlette application.
+        """
+        return self._a2a_server.build()
+
+    def _build_mcp_application(self) -> FastMCP:
+        mcp = FastMCP(
+            name=self.agent_card.name,
+            host="0.0.0.0",
+            port=self.mcp_port,
+        )
+
+        @mcp.tool(
+            name=f"get_{self.agent_card.name.lower().replace(' ', '_')}_card",
+        )
+        def get_agent_card() -> str:
+            """
+            Get the Agent Card as a JSON string, i.e. a description of the Agent and its capabilities.
+
+            Returns:
+                str: The Agent Card in JSON format.
+            """
+            return self.agent_card.model_dump_json()
+
+        @mcp.tool(
+            name=f"call_{self.agent_card.name.lower().replace(' ', '_')}",
+        )
+        def call_agent(
+            query: str,
+            context_id: Optional[str] = None,
+            message_id: str = "1",
+        ) -> str:
+            """
+            Call the Agent with a query and return the response.
+
+            Args:
+                query (str): The input query for the Agent.
+                context_id (Optional[str]): The context ID for the conversation. Defaults to None.
+                    If None, a random context ID will be generated calling `uuid.uuid4()`.
+                message_id (str): The message ID in the conversation. Defaults to "1".
+
+            Returns:
+                str: The Agent's response.
+            """
+            async def get_response_from_stream() -> str:
+                client_factory = ClientFactory(
+                    config=ClientConfig(
+                        streaming=False,
+                        httpx_client=httpx.AsyncClient(timeout=DEFAULT_HTTPX_CLIENT_TIMEOUT),
+                    ),
+                )
+                client = client_factory.create(card=self.agent_card)
+                message = Message(
+                    context_id=context_id or str(uuid.uuid4()),
+                    message_id=message_id,
+                    role="user",
+                    parts=[TextPart(text=query)]
+                )
+                stream = client.send_message(message)
+                item = await anext(stream)
+
+                response = None
+                if isinstance(item, Message):
+                    if item.parts and item.parts[0].root.kind == "text":
+                        response = item.parts[0].root.text
+                    else:
+                        _logger.warning("Received Message with non-text part; ignoring.")
+                else:
+                    task = item[0]
+                    if task.artifacts:
+                        artifact = task.artifacts[0]
+                        if artifact.parts and artifact.parts[0].root.kind == "text":
+                            response = artifact.parts[0].root.text
+                        else:
+                            _logger.warning("Received Artifact with non-text part; ignoring.")
+
+                if response is None:
+                    response = "No valid response received."
+                    _logger.warning("No valid response was obtained from the agent stream.")
+                return response
+
+            try:
+                result = {}
+                def runner(coro):
+                    try:
+                        loop = asyncio.new_event_loop()
+                        asyncio.set_event_loop(loop)
+                        result["value"] = loop.run_until_complete(coro)
+                    except Exception as e:
+                        result["error"] = e
+                    finally:
+                        pending = asyncio.all_tasks(loop)
+                        for task in pending:
+                            task.cancel()
+                        loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+                        loop.close()
+
+                t = Thread(
+                    target=runner,
+                    args=(get_response_from_stream(),),
+                )
+                t.start()
+                t.join()
+
+                if "error" in result:
+                    raise result["error"]
+                response = result["value"]
+            except Exception as e:
+                _logger.error(f"Error while getting response from Agent: {e}")
+                response = f"An error occurred while processing your request: {e}"
+            return response
+
+        return mcp
+
+    def run(
+        self,
+        expose_mcp: bool = False,
+    ) -> None:
+        """Run the agent application.
+
+        Args:
+            expose_mcp (bool, optional): Whether to expose the MCP protocol. Defaults to False.
+                **This parameter isn't fully supported yet and may lead to unexpected behavior
+                when set to True.**
+        """
+
+        if expose_mcp:
+            a2a_app = self._build_a2a_application()
+            mcp_app = self._build_mcp_application()
+
+            a2a_server_config = uvicorn.Config(
+                app=a2a_app,
+                host="0.0.0.0",
+                port=self.a2a_port,
+                reload=False,
+            )
+            a2a_server = uvicorn.Server(config=a2a_server_config)
+
+            t_a2a = Thread(target=lambda: a2a_server.run())
+            t_mcp = Thread(target=lambda: asyncio.run(mcp_app.run_streamable_http_async()))
+
+            t_a2a.start()
+            t_mcp.start()
+            t_mcp.join()        
+            t_a2a.join()
+        else:
+            a2a_app = self._build_a2a_application()
+            uvicorn.run(
+                app=a2a_app,
+                host="0.0.0.0",
+                port=self.a2a_port,
+                reload=False,
+            )