shinyhub-agent 0.1.1__tar.gz

shinyhub_agent-0.1.1/.gitignore

@@ -0,0 +1,63 @@
+.superpowers/
+docs/superpowers/
+# Raw HTML under docs is an internal design/review artifact, not product
+# documentation. Keep reports and their assets out of Git and deployments.
+/docs/**/*.html
+/docs/reports/
+**report.html
+/scripts/docs-smoke.py
+.claire/
+.codex/
+.impeccable/
+go.work
+go.work.sum
+bin/
+tmp/
+.worktrees/
+.claude/investigations/
+CLAUDE.md
+CLAUDE.local.md
+
+# Product positioning and brand direction, maintained by local tooling rather
+# than as a repo artifact. Nothing in the build or the docs site reads it.
+PRODUCT.md
+
+# JS toolchain (only used for JSDOM tests of UI assets)
+node_modules/
+
+# Compiled server binary from `go build` at the repo root.
+/shinyhub
+
+# Runtime artifacts created when running the server from a checkout
+# (default config writes the SQLite DB and per-app data under ./data).
+/shinyhub.yaml
+/data/
+/site/
+/deploy/demo/.env
+*.db
+*.db-shm
+*.db-wal
+
+# PyPI wheel build artifacts
+/packaging/python/src/shinyhub/_binary/shinyhub
+/packaging/python/dist/
+/packaging/python/build/
+/packaging/python/src/shinyhub.egg-info/
+/packaging/python/__pycache__/
+
+# Python bytecode (repo-wide; the render-rig test suites generate it)
+__pycache__/
+
+# Local investigation scratch. Not shipped, and it carries customer names
+# that must never reach a committed file.
+research/
+
+# Local prototypes kept beside the repo, never part of a build.
+experiments/
+
+# Local font and branding source material. Production-ready application assets
+# belong with the component that ships them, not in this repository-level tree.
+/assets/
+
+# macOS Finder metadata.
+.DS_Store

shinyhub_agent-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruben J. Jongejan
+
+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.

shinyhub_agent-0.1.1/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: shinyhub-agent
+Version: 0.1.1
+Summary: Session-scoped agent tools for Python Shiny apps on ShinyHub
+Project-URL: Homepage, https://github.com/rvben/shinyhub
+Project-URL: Repository, https://github.com/rvben/shinyhub
+Project-URL: Issues, https://github.com/rvben/shinyhub/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ag-ui,agents,shiny,shinyhub,webmcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.20
+Requires-Dist: shiny<2,>=1.8.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ShinyHub agent tools for Python Shiny
+
+This helper lets an app declare a small, typed set of tools for the **current
+viewer session**. The app owns all data access and state changes. ShinyHub does
+not infer tools from visible inputs or let a model run arbitrary R/Python code.
+The same registry powers built-in chat and browser WebMCP.
+
+```python
+from shiny import App, reactive, ui
+from shinyhub_agent import AgentTool, agent_dependency, register
+
+app_ui = ui.page_fluid(agent_dependency(), ui.input_select("period", "Period", ["week", "year"]))
+
+def server(input, output, session):
+    selected_period = reactive.value("week")
+
+    @reactive.effect
+    @reactive.event(input.period)
+    def from_control():
+        selected_period.set(input.period())
+
+    async def current_view(args):
+        return {"period": selected_period.get()}
+
+    async def set_period(args):
+        selected_period.set(args["period"])
+        ui.update_select("period", selected=args["period"], session=session)
+        return {"period": selected_period.get()}
+
+    register(session=session, input=input, tools=[
+        AgentTool("get_view", "Read the selected period", {
+            "type": "object", "properties": {}, "additionalProperties": False,
+        }, current_view),
+        AgentTool("set_period", "Change the selected period", {
+            "type": "object", "properties": {"period": {"type": "string", "enum": ["week", "year"]}},
+            "required": ["period"], "additionalProperties": False,
+        }, set_period, read_only=False, confirmation="Change the dashboard period?"),
+    ])
+
+app = App(app_ui, server)
+```
+
+The helper sends version 1 capability messages over the existing Shiny session.
+Arguments are validated again on the server with JSON Schema. Each session has
+its own registry, nonce, concurrency lock, request budget, timeouts, and bounded
+messages. Errors do not reveal handler exceptions or tool arguments. A handler
+must perform its own permission checks for sensitive data or actions.
+
+## Built-in chat or a hoster-owned agent
+
+Add `chat_dependency()` to the UI and pass one chat backend to `register()`:
+
+```python
+import os
+from shinyhub_agent import AGUIChat, OpenAIChat, chat_dependency
+
+# Include chat_dependency() alongside agent_dependency() in the app UI.
+if os.environ.get("SHINYHUB_AGENT_AGUI_URL"):
+    chat = AGUIChat(
+        endpoint=os.environ["SHINYHUB_AGENT_AGUI_URL"],
+        bearer_token=os.environ.get("SHINYHUB_AGENT_AGUI_TOKEN", ""),
+    )
+else:
+    chat = OpenAIChat(
+        api_key=os.environ["OPENAI_API_KEY"],
+        instructions="You help with this dashboard. Use registered tools for app facts.",
+    )
+register(session=session, input=input, tools=tools, chat=chat)
+```
+
+The app stores both credentials as private ShinyHub environment secrets. The
+browser never receives them. OpenAI requests use the Responses API with
+streaming, bounded output, and `store: false`. AG-UI requests carry the current
+session's thread ID, recent messages, and registered tool schemas; they do not
+carry ShinyHub cookies, identity headers, or other apps' data. The hoster must
+authorize and secure their endpoint. Tool calls from either backend are
+validated again by the app. A write pauses for visitor approval in the chat
+panel, then runs the handler and returns its applied result to the agent.
+
+When WebMCP is available, `bridge.js` registers the declared tools. In other
+browsers it makes them available through `window.shinyhubAgentTools.invoke()`
+for an app-supplied assistant. Browser tool writes show visitor confirmation
+before dispatch. This confirmation is a browser interaction, **not a security
+authorization boundary**; the app handler still decides what the viewer may do.
+
+The chat history exists only in the viewer's Shiny session and is limited to
+the last six exchanges. A new chat clears it. The app currently has no durable
+conversation store. The helper does not provide a remote MCP server or a
+platform-wide agent registry, administration UI, or billing controls.
+
+## Operational requirements
+
+- Keep app access behind ShinyHub's authentication and per-app access policy.
+- Give tools the least authority required, and check the viewer's permissions
+  inside handlers for sensitive reads and actions.
+- Return only data the viewer may see. Tool results are sent to the model
+  provider or hoster-owned AG-UI endpoint to compose an answer.
+- Set model and endpoint secrets per app, never in the page or manifest.
+- Review tool names, schemas, descriptions, and app instructions when the app
+  changes. Add a regression test for each consequential action.
+- Run at most one chat request and one tool request at a time per viewer;
+  the adapter enforces per-session request budgets and bounded payloads.
+
+The package is a reusable app integration. A platform-owned chat service,
+central cost policy, admin configuration, and R Shiny helper remain separate
+work before this becomes a platform-wide production feature.

shinyhub_agent-0.1.1/README.md

@@ -0,0 +1,106 @@
+# ShinyHub agent tools for Python Shiny
+
+This helper lets an app declare a small, typed set of tools for the **current
+viewer session**. The app owns all data access and state changes. ShinyHub does
+not infer tools from visible inputs or let a model run arbitrary R/Python code.
+The same registry powers built-in chat and browser WebMCP.
+
+```python
+from shiny import App, reactive, ui
+from shinyhub_agent import AgentTool, agent_dependency, register
+
+app_ui = ui.page_fluid(agent_dependency(), ui.input_select("period", "Period", ["week", "year"]))
+
+def server(input, output, session):
+    selected_period = reactive.value("week")
+
+    @reactive.effect
+    @reactive.event(input.period)
+    def from_control():
+        selected_period.set(input.period())
+
+    async def current_view(args):
+        return {"period": selected_period.get()}
+
+    async def set_period(args):
+        selected_period.set(args["period"])
+        ui.update_select("period", selected=args["period"], session=session)
+        return {"period": selected_period.get()}
+
+    register(session=session, input=input, tools=[
+        AgentTool("get_view", "Read the selected period", {
+            "type": "object", "properties": {}, "additionalProperties": False,
+        }, current_view),
+        AgentTool("set_period", "Change the selected period", {
+            "type": "object", "properties": {"period": {"type": "string", "enum": ["week", "year"]}},
+            "required": ["period"], "additionalProperties": False,
+        }, set_period, read_only=False, confirmation="Change the dashboard period?"),
+    ])
+
+app = App(app_ui, server)
+```
+
+The helper sends version 1 capability messages over the existing Shiny session.
+Arguments are validated again on the server with JSON Schema. Each session has
+its own registry, nonce, concurrency lock, request budget, timeouts, and bounded
+messages. Errors do not reveal handler exceptions or tool arguments. A handler
+must perform its own permission checks for sensitive data or actions.
+
+## Built-in chat or a hoster-owned agent
+
+Add `chat_dependency()` to the UI and pass one chat backend to `register()`:
+
+```python
+import os
+from shinyhub_agent import AGUIChat, OpenAIChat, chat_dependency
+
+# Include chat_dependency() alongside agent_dependency() in the app UI.
+if os.environ.get("SHINYHUB_AGENT_AGUI_URL"):
+    chat = AGUIChat(
+        endpoint=os.environ["SHINYHUB_AGENT_AGUI_URL"],
+        bearer_token=os.environ.get("SHINYHUB_AGENT_AGUI_TOKEN", ""),
+    )
+else:
+    chat = OpenAIChat(
+        api_key=os.environ["OPENAI_API_KEY"],
+        instructions="You help with this dashboard. Use registered tools for app facts.",
+    )
+register(session=session, input=input, tools=tools, chat=chat)
+```
+
+The app stores both credentials as private ShinyHub environment secrets. The
+browser never receives them. OpenAI requests use the Responses API with
+streaming, bounded output, and `store: false`. AG-UI requests carry the current
+session's thread ID, recent messages, and registered tool schemas; they do not
+carry ShinyHub cookies, identity headers, or other apps' data. The hoster must
+authorize and secure their endpoint. Tool calls from either backend are
+validated again by the app. A write pauses for visitor approval in the chat
+panel, then runs the handler and returns its applied result to the agent.
+
+When WebMCP is available, `bridge.js` registers the declared tools. In other
+browsers it makes them available through `window.shinyhubAgentTools.invoke()`
+for an app-supplied assistant. Browser tool writes show visitor confirmation
+before dispatch. This confirmation is a browser interaction, **not a security
+authorization boundary**; the app handler still decides what the viewer may do.
+
+The chat history exists only in the viewer's Shiny session and is limited to
+the last six exchanges. A new chat clears it. The app currently has no durable
+conversation store. The helper does not provide a remote MCP server or a
+platform-wide agent registry, administration UI, or billing controls.
+
+## Operational requirements
+
+- Keep app access behind ShinyHub's authentication and per-app access policy.
+- Give tools the least authority required, and check the viewer's permissions
+  inside handlers for sensitive reads and actions.
+- Return only data the viewer may see. Tool results are sent to the model
+  provider or hoster-owned AG-UI endpoint to compose an answer.
+- Set model and endpoint secrets per app, never in the page or manifest.
+- Review tool names, schemas, descriptions, and app instructions when the app
+  changes. Add a regression test for each consequential action.
+- Run at most one chat request and one tool request at a time per viewer;
+  the adapter enforces per-session request budgets and bounded payloads.
+
+The package is a reusable app integration. A platform-owned chat service,
+central cost policy, admin configuration, and R Shiny helper remain separate
+work before this becomes a platform-wide production feature.

shinyhub_agent-0.1.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shinyhub-agent"
+version = "0.1.1"
+description = "Session-scoped agent tools for Python Shiny apps on ShinyHub"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["shinyhub", "shiny", "agents", "webmcp", "ag-ui"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = ["shiny>=1.8.0,<2", "jsonschema>=4.20,<5", "httpx>=0.27,<1"]
+
+[project.urls]
+Homepage = "https://github.com/rvben/shinyhub"
+Repository = "https://github.com/rvben/shinyhub"
+Issues = "https://github.com/rvben/shinyhub/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shinyhub_agent"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shinyhub_agent-0.1.1/src/shinyhub_agent/__init__.py

@@ -0,0 +1,10 @@
+"""Explicit, session-scoped tools for app assistants and browser agents."""
+
+from ._core import AgentTool, ToolError, ToolRegistry
+from ._openai import OpenAIChat
+from ._agui import AGUIChat
+from ._chat import ChatAgent
+from ._shiny import agent_dependency, chat_dependency, register
+
+__version__ = "0.1.1"
+__all__ = ["AGUIChat", "AgentTool", "ChatAgent", "OpenAIChat", "ToolError", "ToolRegistry", "agent_dependency", "chat_dependency", "register"]

shinyhub_agent-0.1.1/src/shinyhub_agent/_agui.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import json
+import secrets
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._core import ToolError, ToolRegistry
+from ._openai import Approve
+
+MAX_EVENT_BYTES = 65_536
+MAX_RUN_BYTES = 1_048_576
+
+
+@dataclass(frozen=True)
+class AGUIChat:
+    """Connect a hoster-owned AG-UI endpoint to one Shiny viewer session."""
+
+    endpoint: str
+    bearer_token: str = field(default="", repr=False)
+
+    def __post_init__(self) -> None:
+        parsed = urlsplit(self.endpoint)
+        if parsed.scheme != "https" or not parsed.netloc or parsed.username or parsed.password:
+            raise ValueError("AG-UI endpoints must be HTTPS URLs without embedded credentials")
+
+    async def run(self, message: str, history: list[dict[str, str]],
+                  tools: ToolRegistry, approve: Approve, *, thread_id: str
+                  ) -> AsyncIterator[dict[str, Any]]:
+        if not isinstance(message, str) or not 1 <= len(message.strip()) <= 2_000:
+            raise ToolError("invalid_message", "Enter a question of at most 2,000 characters.")
+        messages = [
+            {"id": secrets.token_urlsafe(10), "role": item["role"],
+             "content": item["content"][:2_000]}
+            for item in history[-12:]
+            if item.get("role") in ("user", "assistant") and isinstance(item.get("content"), str)
+        ]
+        messages.append({"id": secrets.token_urlsafe(10), "role": "user", "content": message})
+        offered = [{
+            "name": spec["name"], "description": spec["description"],
+            "parameters": spec["inputSchema"],
+        } for spec in tools.public_spec()["tools"]]
+        headers = {"Accept": "text/event-stream", "Content-Type": "application/json"}
+        if self.bearer_token:
+            headers["Authorization"] = f"Bearer {self.bearer_token}"
+        async with httpx.AsyncClient(timeout=httpx.Timeout(45, connect=5)) as client:
+            for _ in range(4):
+                calls: dict[str, dict[str, Any]] = {}
+                run_finished = False
+                text_seen = False
+                total = 0
+                async with client.stream("POST", self.endpoint, headers=headers, json={
+                    "threadId": thread_id,
+                    "runId": secrets.token_urlsafe(16),
+                    "state": {},
+                    "messages": messages,
+                    "tools": offered,
+                    "context": [],
+                    "forwardedProps": {},
+                }) as response:
+                    response.raise_for_status()
+                    data_lines: list[str] = []
+                    async for line in response.aiter_lines():
+                        total += len(line.encode())
+                        if total > MAX_RUN_BYTES:
+                            raise ToolError("agent_too_large", "The agent sent too much data.")
+                        if line.startswith("data:"):
+                            data_lines.append(line[5:].lstrip())
+                            if sum(map(len, data_lines)) > MAX_EVENT_BYTES:
+                                raise ToolError("agent_too_large", "The agent event was too large.")
+                            continue
+                        if line or not data_lines:
+                            continue
+                        raw_event = "\n".join(data_lines)
+                        data_lines.clear()
+                        event = json.loads(raw_event)
+                        kind = event.get("type")
+                        if kind in ("TEXT_MESSAGE_CONTENT", "TEXT_MESSAGE_CHUNK"):
+                            delta = event.get("delta")
+                            if isinstance(delta, str) and delta:
+                                text_seen = True
+                                yield {"type": "delta", "text": delta}
+                        elif kind == "RUN_STARTED":
+                            yield {"type": "status", "text": "Agent is working"}
+                        elif kind == "TOOL_CALL_START":
+                            call_id = event.get("toolCallId")
+                            if not isinstance(call_id, str) or len(call_id) > 100:
+                                raise ToolError("bad_agent_event", "The agent sent an invalid tool call.")
+                            calls[call_id] = {"name": event.get("toolCallName"), "arguments": "", "ended": False}
+                            yield {"type": "status", "text": "Using app tools"}
+                        elif kind == "TOOL_CALL_ARGS":
+                            call = calls.get(event.get("toolCallId"))
+                            if call is None or not isinstance(event.get("delta"), str):
+                                raise ToolError("bad_agent_event", "The agent sent invalid tool arguments.")
+                            call["arguments"] += event["delta"]
+                            if len(call["arguments"].encode()) > 8_192:
+                                raise ToolError("bad_agent_event", "The agent tool arguments were too large.")
+                        elif kind == "TOOL_CALL_END":
+                            call = calls.get(event.get("toolCallId"))
+                            if call is None:
+                                raise ToolError("bad_agent_event", "The agent ended an unknown tool call.")
+                            call["ended"] = True
+                        elif kind == "TOOL_CALL_RESULT":
+                            calls.pop(event.get("toolCallId"), None)
+                        elif kind == "RUN_ERROR":
+                            raise ToolError("agent_failed", "The connected agent could not finish.")
+                        elif kind == "RUN_FINISHED":
+                            run_finished = True
+                if not run_finished:
+                    raise ToolError("agent_failed", "The connected agent ended early.")
+                if not calls:
+                    if not text_seen:
+                        raise ToolError("agent_failed", "The connected agent returned no answer.")
+                    return
+                if len(calls) > 2 or any(not call["ended"] for call in calls.values()):
+                    raise ToolError("bad_agent_event", "The agent sent incomplete tool calls.")
+                for call_id, call in calls.items():
+                    tool = tools.get(call["name"])
+                    try:
+                        arguments = json.loads(call["arguments"])
+                        if tool is None:
+                            result: Any = {"error": "Tool unavailable"}
+                        elif tool.read_only:
+                            result = await tools.execute(tool.name, arguments)
+                        else:
+                            result = await approve(tool.name, arguments)
+                            yield {"type": "action_applied", "name": tool.name, "result": result}
+                    except (ValueError, ToolError) as error:
+                        result = {"error": str(error)}
+                    messages.append({
+                        "id": secrets.token_urlsafe(10), "role": "tool",
+                        "toolCallId": call_id, "content": json.dumps(result),
+                    })
+                yield {"type": "status", "text": "Writing answer"}
+        raise ToolError("agent_failed", "The connected agent did not finish.")