academy-dashboard 0.1.0__tar.gz

academy_dashboard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,107 @@
+# Release process (read carefully):
+#
+#   1. Choose the next semver version number (e.g., 1.3.2) with optional
+#      release candidate segments. See: https://peps.python.org/pep-0440/
+#
+#   2. Open and merge any PRs required for documentation updates
+#      (e.g., migration guides for version bumps with breaking changes).
+#      Documentation changes must be made *before* running this publish
+#      workflow for the changes to be included in the tagged version of
+#      the docs site.
+#
+#   3. Tag the target commit on main for the release. Note that
+#      setuptools_scm requires the version tag is prepended with "v".
+#      This command creates a signed tag (recommended) using your GPG key.
+#
+#      export VERSION=v1.3.2
+#      git tag -s $VERSION <SHORT_COMMIT_HASH> -m "Dashboard $VERSION"
+#      git push origin $VERSION
+#
+#   4. Create a new release on GitHub corresponding to the tag. Releases
+#      will trigger this publish workflow that will publish the package
+#      to PyPI and push a new version of the docs.
+#
+#      * Go to https://github.com/academy-agents/nexus/releases
+#      * Click "Draft a new release"
+#      * Select the tag you created
+#
+#      Official releases:
+#
+#        * Select the previous tag as the previous *official* release. For
+#          example, use v0.4.0 as the previous release tag and NOT v0.4.0rc1.
+#          This is necessary for generating the diff link on the release
+#          correctly
+#        * Click "Generate release notes"
+#        * Add an "Upgrade Steps" section at the top (see previous releases
+#          for examples)
+#        * Review the generated notes and edit as needed. PRs are organized
+#          by tag, but some PRs will be missing tags and need to be moved
+#          from the "Other Changes" section to the correct section
+#        * Select "Set as the latest release"
+#        * Publish the release
+#
+#     Pre releases:
+#
+#        * Do NOT generate release notes. A description of "Development
+#          pre-release for <VERSION>" is sufficient
+#        * Leave the previous tag as "auto"
+#        * Select "Set as a pre-release"
+#        * Publish the release
+#
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Extract package version from tag
+        run: |
+          # Removes 'v' prefix from tag (e.g., v1.0.0 -> 1.0.0)
+          VERSION=${GITHUB_REF_NAME#v}
+          echo "PACKAGE_VERSION=$VERSION" >> $GITHUB_ENV
+          echo "Extracted version from tag: $VERSION"
+
+      - name: Setup Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install pypa/build and build
+        run: |
+          pip install build
+          python -m build --sdist --wheel --outdir dist/ .
+
+      - name: Upload files to release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+
+      - name: Publish to PyPI
+        if: startsWith(github.ref, 'refs/tags')
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Configure git
+        run: |
+          git config --local user.name "GitHub Actions Bot"
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy docs for release version to gh-pages branch
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          pip install .[docs]
+          mike deploy --push --update-aliases "${{ env.PACKAGE_VERSION }}" stable

academy_dashboard-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+ci:
+  autofix_prs: false
+repos:
+  - repo: 'https://github.com/pre-commit/pre-commit-hooks'
+    rev: v6.0.0
+    hooks:
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-added-large-files
+      - id: check-docstring-first
+      - id: check-json
+      - id: check-yaml
+      - id: check-merge-conflict
+      - id: name-tests-test
+  - repo: 'https://github.com/codespell-project/codespell'
+    rev: v2.4.2
+    hooks:
+      - id: codespell
+        exclude: ".svg$"
+  - repo: 'https://github.com/astral-sh/ruff-pre-commit'
+    rev: v0.14.11
+    hooks:
+      - id: ruff-check
+        args:
+          - '--fix'
+          - '--exit-non-zero-on-fix'
+      - id: ruff-format
+  - repo: 'https://github.com/pre-commit/mirrors-mypy'
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-requests

academy_dashboard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Academy Agents
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

academy_dashboard-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: academy-dashboard
+Version: 0.1.0
+Summary: Observability and Oversight components for Academy Agents
+Author: ModCon BASE Core Agentic Frameworks Team
+Author-email: yadunand@uchicago.edu
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: ==3.13.*
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: academy-py>=0.5.0
+Requires-Dist: dotenv
+Requires-Dist: globus-compute-sdk
+Requires-Dist: tox>=4.34.1
+Requires-Dist: flask>=3.1
+Requires-Dist: psutil
+Provides-Extra: dev
+Requires-Dist: covdefaults>=2.2; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pre-commit>=4.5.1; extra == "dev"
+Requires-Dist: ruff>=0.15.0; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: virtualenv; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: black==24.4.2; extra == "docs"
+Requires-Dist: mkdocs-autorefs==1.3.1; extra == "docs"
+Requires-Dist: mkdocs-click==0.8.1; extra == "docs"
+Requires-Dist: mkdocs-gen-files==0.5.0; extra == "docs"
+Requires-Dist: mkdocs-literate-nav==0.6.1; extra == "docs"
+Requires-Dist: mkdocs-material==9.5.32; extra == "docs"
+Requires-Dist: mkdocs-section-index==0.3.9; extra == "docs"
+Requires-Dist: mkdocstrings==0.25.2; extra == "docs"
+Requires-Dist: mkdocstrings-python==1.10.8; extra == "docs"
+Requires-Dist: mike==2.1.3; extra == "docs"
+Dynamic: license-file
+
+# Academy-Dashboard
+
+**Observability and Oversight for Academy Agents**
+
+As agents act autonomously, the ability to observe what they are doing and intervene
+when appropriate becomes a critical capability. `academy-dashboard` addresses these
+challenges in agentic deployments through the following extensions for `Academy`:
+
+* `UserAgent`: Specialized Academy agents that 1. accepts information from MonitoredAgents \
+   and 2. presents this information over a web based dashboard.
+* `MonitoredAgent`: Extends academy's `Agent` class to support observability and control features.
+
+Here are some of the supported capabilities:
+
+* Logging: Live log stream from `MonitoredAgents` is presented via the `UserAgent`
+* Human-in-the-loop: `MonitoredAgents` can send user prompts to the `UserAgent` where a user can respond over a webpage
+* Performance Stats: Dashboard presents performance stats collected from `MonitoredAgents`
+* Shutdown: `MonitoredAgent`s can be terminated from the dashboard provided by `UserAgents`
+* Location: Locate your agents on a map
+
+## Using the `UserAgent`
+
+There are two supported modes for using starting a `UserAgent`:
+
+
+#### `Hosted UserAgent`
+
+>>   Go to [dashboard.academy-agents.org](https://dashboard.academy-agents.org/)
+
+    1) Login with Globus Auth \
+    2) Click the `[+]` button to launch a new `UserAgent` \
+    3) Copy the agent UUID and plug this back into your scripts \
+
+### `Local Deployment`:
+
+Launch locally with: `user-agent-launcher`,
+
+```bash
+:>user-agent-launcher
+User Agent UUID >>>>
+     a9337401-3d22-4205-923a-0040bb8d3a7b
+ * Serving Flask app 'academy_dashboard.user_agent.dashboard'
+ * Debug mode: off
+
+```
+
+> NOTE: MonitoredAgents need the User Agent's UUID (printed above) to establish a connection.
+
+```bash
+:> user-agent-launcher -h
+usage: user-agent-launcher [-h] [-p PORT] [-r REGISTRATION_FILE] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+
+options:
+  -h, --help            show this help message and exit
+  -p, --port PORT       Port at which the flask service is listening
+  -r, --registration_file REGISTRATION_FILE
+                        UserAgent registration file
+  -l, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Log level
+```
+
+## Using the `MonitoredAgent`
+
+```python
+import os
+
+USER_AGENT_ID=os.environ('USER_AGENT_UUID')
+```

academy_dashboard-0.1.0/README.md

@@ -0,0 +1,68 @@
+# Academy-Dashboard
+
+**Observability and Oversight for Academy Agents**
+
+As agents act autonomously, the ability to observe what they are doing and intervene
+when appropriate becomes a critical capability. `academy-dashboard` addresses these
+challenges in agentic deployments through the following extensions for `Academy`:
+
+* `UserAgent`: Specialized Academy agents that 1. accepts information from MonitoredAgents \
+   and 2. presents this information over a web based dashboard.
+* `MonitoredAgent`: Extends academy's `Agent` class to support observability and control features.
+
+Here are some of the supported capabilities:
+
+* Logging: Live log stream from `MonitoredAgents` is presented via the `UserAgent`
+* Human-in-the-loop: `MonitoredAgents` can send user prompts to the `UserAgent` where a user can respond over a webpage
+* Performance Stats: Dashboard presents performance stats collected from `MonitoredAgents`
+* Shutdown: `MonitoredAgent`s can be terminated from the dashboard provided by `UserAgents`
+* Location: Locate your agents on a map
+
+## Using the `UserAgent`
+
+There are two supported modes for using starting a `UserAgent`:
+
+
+#### `Hosted UserAgent`
+
+>>   Go to [dashboard.academy-agents.org](https://dashboard.academy-agents.org/)
+
+    1) Login with Globus Auth \
+    2) Click the `[+]` button to launch a new `UserAgent` \
+    3) Copy the agent UUID and plug this back into your scripts \
+
+### `Local Deployment`:
+
+Launch locally with: `user-agent-launcher`,
+
+```bash
+:>user-agent-launcher
+User Agent UUID >>>>
+     a9337401-3d22-4205-923a-0040bb8d3a7b
+ * Serving Flask app 'academy_dashboard.user_agent.dashboard'
+ * Debug mode: off
+
+```
+
+> NOTE: MonitoredAgents need the User Agent's UUID (printed above) to establish a connection.
+
+```bash
+:> user-agent-launcher -h
+usage: user-agent-launcher [-h] [-p PORT] [-r REGISTRATION_FILE] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
+
+options:
+  -h, --help            show this help message and exit
+  -p, --port PORT       Port at which the flask service is listening
+  -r, --registration_file REGISTRATION_FILE
+                        UserAgent registration file
+  -l, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+                        Log level
+```
+
+## Using the `MonitoredAgent`
+
+```python
+import os
+
+USER_AGENT_ID=os.environ('USER_AGENT_UUID')
+```

academy_dashboard-0.1.0/TODO.md

@@ -0,0 +1,64 @@
+Known bugs:
+
+
+# Heartbeats don't work
+[Pending]
+The UserAgent treats every message from an agent as a heartbeat,
+but this mechanism appears to be broken now.
+We should switch over to using mailbox/agent liveness info provided
+by the exchange directly.
+
+# Shutdown doesn't work
+[Pending]
+The shutdown button on the agent cards no longer trigger agent shutdown
+
+
+# Log issues
+[Pending]
+Logging issues are being worked out with the switch away from `init_logging()` to the `recommended` loggers from BenC.
+The issue here is that logConfig objects are handled by the manager and we do not use a manager in the `user-agent-launcher`.
+We use `http_exchange_client.register_agent -> make Runtime(registration=AgentReg)` which leaves out a point to plug in log configuration.
+
+# HTTP Timeouts
+[Addressed]
+The following bug was addressed by upgrading academy-py to latest which has support for handling
+aiohttp timeouts within the HTTPExchangeClient. The fix basically is:
+
+> factory = HttpExchangeFactory(client_timeout=aiohttp.ClientTimeout(total=None, sock_connect=30))
+
+```
+[2026-05-15 23:35:57.671] ERROR    (academy.logging) Background task raised an exception.
+Traceback (most recent call last):
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/aiohttp/streams.py", line 372, in _wait
+    await waiter
+asyncio.exceptions.CancelledError
+
+The above exception was the direct cause of the following exception:
+
+Traceback (most recent call last):
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/academy/logging.py", line 213, in execute_and_log_traceback
+    return await fut
+           ^^^^^^^^^
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/academy/exchange/client.py", line 224, in _listen_for_messages
+    async for message in self._transport.listen():
+    ...<10 lines>...
+            await asyncio.sleep(0)
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/academy/exchange/cloud/client.py", line 252, in listen
+    async for line_in_bytes in response.content:
+    ...<11 lines>...
+        current_message_lines.append(line)
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/aiohttp/streams.py", line 53, in __anext__
+    rv = await self.read_func()
+         ^^^^^^^^^^^^^^^^^^^^^^
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/aiohttp/streams.py", line 377, in readline
+    return await self.readuntil(max_size=max_line_length)
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/aiohttp/streams.py", line 414, in readuntil
+    await self._wait("readuntil")
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/aiohttp/streams.py", line 371, in _wait
+    with self._timer:
+         ^^^^^^^^^^^
+  File "/Users/yadu/src/nexus/.venv/lib/python3.13/site-packages/aiohttp/helpers.py", line 713, in __exit__
+    raise asyncio.TimeoutError from exc_val
+TimeoutError
+```

academy_dashboard-0.1.0/academy_dashboard/__init__.py

@@ -0,0 +1,11 @@
+"""Observability components for agentic blueprints."""
+
+from __future__ import annotations
+
+from academy_dashboard.monitored_agent import MonitoredAgent
+from academy_dashboard.user_agent.user_agent import UserAgent
+
+__all__ = [
+    'MonitoredAgent',
+    'UserAgent',
+]

academy_dashboard-0.1.0/academy_dashboard/agents/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from academy_dashboard.agents.sleeper import Sleeper
+from academy_dashboard.agents.spinner import Spinner
+
+__all__ = ['Sleeper', 'Spinner']

academy_dashboard-0.1.0/academy_dashboard/agents/sleeper.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from academy.agent import loop
+from academy.handle import Handle
+
+from academy_dashboard.monitored_agent import MonitoredAgent
+from academy_dashboard.user_agent.user_agent import UserAgent
+
+
+class Sleeper(MonitoredAgent):
+    """An Agent that sleeps."""
+
+    def __init__(self, user_agent_handle: Handle[UserAgent]) -> None:
+        super().__init__(user_agent_handle=user_agent_handle)
+        print('Spinner init done')
+
+    @loop
+    async def cycle(self, shutdown: asyncio.Event) -> None:
+        """Log and sleep in loop."""
+        counter = 0
+        while not shutdown.is_set():
+            await asyncio.sleep(30)
+            logging.info('Sleeper iteration %d', counter)
+            counter += 1
+        logging.info('Sleeper exiting!!!! ')

academy_dashboard-0.1.0/academy_dashboard/agents/spinner.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from academy.agent import action
+from academy.handle import Handle
+
+from academy_dashboard.monitored_agent import MonitoredAgent
+from academy_dashboard.user_agent.user_agent import UserAgent
+
+
+class Spinner(MonitoredAgent):
+    """A concrete MonitoredAgent that does some work and reports progress."""
+
+    def __init__(self, user_agent_handle: Handle[UserAgent]) -> None:
+        super().__init__(user_agent_handle=user_agent_handle)
+        print('Spinner init done')
+
+    @action
+    async def run(self, iterations: int = 3) -> str:
+        """Simulate work and emit log messages that are forwarded to UserAgent."""
+        logging.info('Starting run!')
+        for i in range(iterations):
+            logging.info(
+                f'{self.agent_name} iteration %d/%d',
+                i + 1,
+                iterations,
+            )
+            await asyncio.sleep(10)
+        logging.warning('Finishing run!')
+        return f'Finished {iterations} iterations'
+
+    @action
+    async def poke(self) -> int:
+        """Mock action that emits a log."""
+        logging.warning('I just got Poked!')
+        return 4
+
+    @action
+    async def trigger_user_query(self) -> None:
+        """Trigger a user query."""
+        logging.info('Triggering user query!')
+        response = await self.prompt_user_agent(
+            'Should I continue?',
+            responses=['Yes', 'No'],
+        )
+        try:
+            _ = 5 / 0
+        except ZeroDivisionError:
+            logging.exception('Something went wrong!')
+        logging.info(f'Got response: {response} from user query')