gentui 0.1.0__py3-none-any.whl

gentui/__init__.py

@@ -0,0 +1 @@
+"""Gentui: a terminal client for any AG-UI agent backend."""

gentui/cli.py

@@ -0,0 +1,102 @@
+"""`gentui` command: point it at any AG-UI backend and go."""
+
+import argparse
+import sys
+
+from gentui.config import load_config
+
+
+def _version() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("gentui")
+    except PackageNotFoundError:  # running from a source tree that is not installed
+        return "unknown"
+
+
+def parse_headers(items: list[str] | None) -> dict[str, str] | None:
+    if not items:
+        return None
+    headers = {}
+    for item in items:
+        key, sep, value = item.partition(":")
+        if not sep:
+            raise SystemExit(f"--header expects 'Name: value', got {item!r}")
+        headers[key.strip()] = value.strip()
+    return headers
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="gentui",
+        description="Terminal client for any AG-UI agent backend.",
+        epilog="Options can also live in gentui.toml (see gentui.example.toml).",
+    )
+    parser.add_argument(
+        "url_pos", nargs="?", metavar="URL|ARN",
+        help="AG-UI endpoint, or an AgentCore runtime ARN (same as --url / --agentcore-arn)",
+    )
+    parser.add_argument("--url", help="AG-UI endpoint [default: http://localhost:8000/agent]")
+    parser.add_argument("--agentcore-arn", metavar="ARN", help="agent on Amazon Bedrock AgentCore Runtime (AG-UI protocol)")
+    parser.add_argument("--region", help="AWS region for AgentCore [default: the region in the ARN]")
+    parser.add_argument("--profile", help="AWS profile for AgentCore [default: the standard credential chain]")
+    parser.add_argument("--qualifier", help="AgentCore runtime endpoint name [default: DEFAULT]")
+    parser.add_argument("--token", help="send 'Authorization: Bearer <token>' (or set GENTUI_TOKEN)")
+    parser.add_argument("--header", "-H", action="append", metavar="'Name: value'", help="extra HTTP header (repeatable)")
+    parser.add_argument("--config", "-c", metavar="FILE", help="config file [default: ./gentui.toml]")
+    parser.add_argument("--theme", help="Textual theme name")
+    parser.add_argument("--css", metavar="FILE", help="your own CSS file (hot-reloaded)")
+    parser.add_argument("--plugin", "-p", action="append", metavar="MODULE|FILE", help="load a plugin (repeatable)")
+    parser.add_argument("--version", action="version", version=f"gentui {_version()}")
+    parser.add_argument("--no-reasoning", action="store_true", help="hide the model's chain of thought")
+    parser.add_argument("--dev", action="store_true", help="open the AG-UI event inspector at start")
+    args = parser.parse_args(argv)
+
+    target = args.url or args.url_pos
+    arn = args.agentcore_arn or (target if target and target.startswith("arn:") else None)
+    try:
+        config = load_config(
+            args.config,
+            url=None if arn else target,
+            agentcore_arn=arn,
+            region=args.region,
+            aws_profile=args.profile,
+            qualifier=args.qualifier,
+            token=args.token,
+            headers=parse_headers(args.header),
+            theme=args.theme,
+            css=args.css,
+            plugins=args.plugin,
+            show_reasoning=False if args.no_reasoning else None,
+            dev_pane=True if args.dev else None,
+        )
+    except (OSError, ValueError) as exc:
+        sys.exit(f"gentui: {exc}")
+
+    from gentui.tui.agui_client import AguiClient, BackendError
+    from gentui.tui.app import GentuiApp
+
+    if config.agentcore_arn:
+        try:
+            from gentui.tui.agentcore_client import AgentCoreClient
+
+            client = AgentCoreClient(
+                config.agentcore_arn, config.region, config.aws_profile, config.qualifier,
+                config.timeout, config.send_history,
+            )
+        except ImportError:
+            sys.exit(
+                "gentui: AgentCore support needs boto3. Install it with:\n"
+                "    uv sync --extra agentcore        (from a clone)\n"
+                "    pip install 'gentui[agentcore]'   (from PyPI, once published)"
+            )
+        except (BackendError, ValueError) as exc:
+            sys.exit(f"gentui: {exc}")
+    else:
+        client = AguiClient(config.url, config.request_headers, config.timeout, config.send_history)
+    GentuiApp(client, config).run()
+
+
+if __name__ == "__main__":
+    main()

gentui/config.py

@@ -0,0 +1,148 @@
+"""User configuration: where the backend is and how the UI looks.
+
+Sources, lowest to highest priority:  defaults < config file < environment < CLI flags.
+
+Config file (first found wins):  --config PATH, ./gentui.toml, ~/.config/gentui/config.toml
+See `gentui.example.toml` for every option.
+"""
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+from typing import Any
+
+DEFAULT_WELCOME = (
+    "◈ Welcome to Gentui!\n\n"
+    "  /help for commands · ctrl+q to quit · d for the dev pane\n"
+    "  backend: {url}\n"
+    "  cwd: {cwd}"
+)
+
+
+_RUNTIME_ARN = re.compile(
+    r"^(?P<runtime>arn:aws[a-z-]*:bedrock-agentcore:(?P<region>[a-z0-9-]+):(?P<account>\d{12}):runtime/[^/\s]+)"
+    r"(?:/runtime-endpoint/(?P<endpoint>[^/\s]+))?$"
+)
+
+
+def _match_runtime_arn(arn: str) -> re.Match[str]:
+    match = _RUNTIME_ARN.match(arn.strip())
+    if not match:
+        raise ValueError(
+            f"not an AgentCore runtime ARN: {arn!r} "
+            "(expected arn:aws:bedrock-agentcore:<region>:<account>:runtime/<name>"
+            "[/runtime-endpoint/<endpoint>])"
+        )
+    return match
+
+
+def parse_runtime_arn(arn: str) -> tuple[str, str]:
+    """(region, account id) of an AgentCore runtime ARN. Raises ValueError for anything else."""
+    match = _match_runtime_arn(arn)
+    return match["region"], match["account"]
+
+
+def split_runtime_arn(arn: str) -> tuple[str, str | None]:
+    """(runtime ARN, endpoint name). An endpoint ARN (`.../runtime/<name>/runtime-endpoint/<endpoint>`) is
+    accepted: invoke_agent_runtime wants the plain runtime ARN, with the endpoint passed as its qualifier."""
+    match = _match_runtime_arn(arn)
+    return match["runtime"], match["endpoint"]
+
+
+@dataclass
+class Config:
+    # -- backend -----------------------------------------------------------------------
+    url: str = "http://localhost:8000/agent"  # any AG-UI endpoint
+    # An agent hosted on Amazon Bedrock AgentCore Runtime (AG-UI protocol), invoked with boto3.
+    # When set it is used instead of `url`. Needs the optional dependency: gentui[agentcore].
+    agentcore_arn: str | None = None
+    region: str | None = None  # default: the region in the ARN
+    aws_profile: str | None = None  # default: the standard AWS credential chain
+    qualifier: str | None = None  # runtime endpoint name; default: the runtime's DEFAULT endpoint
+    headers: dict[str, str] = field(default_factory=dict)  # extra HTTP headers (auth etc.)
+    token: str | None = None  # shortcut for "Authorization: Bearer <token>"
+    forwarded_props: dict[str, Any] = field(default_factory=dict)  # sent with every run
+    send_history: bool = False  # True: send the whole conversation each run (stateless backends need it)
+    timeout: float | None = None  # seconds between bytes; None = wait forever (agents are slow)
+
+    # -- look & feel -------------------------------------------------------------------
+    title: str = "Gentui"
+    subtitle: str = "Generative UI for your terminal"
+    welcome: str = DEFAULT_WELCOME
+    placeholder: str = "Ask anything…"
+    theme: str = "gentui"  # "gentui", "claude" or any Textual theme name; /theme lists them
+    splash: bool = True  # animated logo on startup (any key skips it)
+    logo: bool = True  # keep the finished logo at the top of the chat after the splash
+    show_time: bool = True  # a timestamp on every message
+    time_format: str = "%H:%M"  # strftime format for those timestamps
+    css: str | None = None  # your own Textual CSS file, hot-reloaded while the app runs
+    show_reasoning: bool = True  # render the model's chain of thought
+    dev_pane: bool = False  # start with the AG-UI event inspector open
+
+    # -- extending ---------------------------------------------------------------------
+    plugins: list[str] = field(default_factory=list)  # module names or .py paths to load
+    widgets: dict[str, str] = field(default_factory=dict)  # tool name -> "module:Class"
+    default_widget: str | None = None  # "module:Class" for tools without a widget
+
+    source: Path | None = None  # the config file that was loaded (informational)
+
+    @property
+    def request_headers(self) -> dict[str, str]:
+        headers = dict(self.headers)
+        if self.token:
+            headers.setdefault("Authorization", f"Bearer {self.token}")
+        return headers
+
+    @property
+    def target(self) -> str:
+        """What the client talks to: the AgentCore runtime ARN, or the URL."""
+        return self.agentcore_arn or self.url
+
+    @property
+    def welcome_text(self) -> str:
+        return self.welcome.replace("{url}", self.target).replace("{cwd}", os.getcwd())
+
+
+def find_config(explicit: str | None = None) -> Path | None:
+    if explicit:
+        path = Path(explicit).expanduser()
+        if not path.is_file():
+            raise FileNotFoundError(f"config file not found: {path}")
+        return path
+    for path in (Path("gentui.toml"), Path.home() / ".config" / "gentui" / "config.toml"):
+        if path.is_file():
+            return path
+    return None
+
+
+def load_config(path: str | None = None, **overrides: Any) -> Config:
+    """Build a Config. `overrides` (e.g. from CLI flags) win; None values are ignored."""
+    cfg = Config()
+    known = {f.name for f in fields(Config)} - {"source"}
+
+    file = find_config(path)
+    if file:
+        data = tomllib.loads(file.read_text(encoding="utf-8"))
+        unknown = set(data) - known
+        if unknown:
+            raise ValueError(f"{file}: unknown option(s): {', '.join(sorted(unknown))}")
+        for key, value in data.items():
+            setattr(cfg, key, value)
+        if cfg.css:  # relative CSS paths are relative to the config file
+            cfg.css = str((file.parent / cfg.css).expanduser())
+        cfg.source = file
+
+    cfg.url = os.environ.get("GENTUI_URL", cfg.url)
+    cfg.token = os.environ.get("GENTUI_TOKEN", cfg.token)
+    cfg.agentcore_arn = os.environ.get("GENTUI_AGENTCORE_ARN", cfg.agentcore_arn)
+
+    for key, value in overrides.items():
+        if value is not None:
+            if key not in known:
+                raise KeyError(key)
+            setattr(cfg, key, value)
+    if cfg.agentcore_arn:
+        parse_runtime_arn(cfg.agentcore_arn)  # fail early with a clear message
+    return cfg

gentui/plugins.py

@@ -0,0 +1,136 @@
+"""Plugin API. A plugin is a plain Python file or module that imports these decorators.
+
+    from gentui.plugins import register_command, on_event
+    from gentui.tui.widgets.base import ToolWidget
+    from gentui.tui.widgets.registry import register_widget
+
+    @register_widget("weather")                 # render tool calls named "weather"
+    class WeatherWidget(ToolWidget): ...
+
+    @register_command("ping", "say pong")       # adds /ping
+    def ping(app, args): app.notify("pong")
+
+    @on_event("TOOL_CALL_RESULT")               # runs for every matching AG-UI event
+    def log_results(app, event): ...
+
+    def setup(app): ...                         # optional; called once the app is mounted
+
+Where plugins are loaded from: the `plugins = [...]` config option / `--plugin`,
+`./gentui_plugins/*.py`, `~/.config/gentui/plugins/*.py`, and the `gentui.plugins`
+entry-point group (for pip-installable plugins).
+"""
+
+import importlib
+import importlib.metadata
+import importlib.util
+import inspect
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+Command = Callable[[Any, str], Any]  # (app, argument string)
+Hook = Callable[[Any, Any], Any]  # (app, ag_ui event)
+
+COMMANDS: dict[str, tuple[Command, str]] = {}
+HOOKS: list[tuple[frozenset[str] | None, Hook]] = []
+SETUPS: list[Callable[[Any], Any]] = []
+
+
+def register_command(name: str, help: str = "") -> Callable[[Command], Command]:
+    def deco(fn: Command) -> Command:
+        COMMANDS[name.lstrip("/")] = (fn, help)
+        return fn
+
+    return deco
+
+
+def on_event(*types: str) -> Callable[[Hook], Hook]:
+    """Hook called with (app, event). No types = every event. Types are EventType names."""
+
+    def deco(fn: Hook) -> Hook:
+        HOOKS.append((frozenset(types) or None, fn))
+        return fn
+
+    return deco
+
+
+async def call(fn: Callable[..., Any], *args: Any) -> Any:
+    result = fn(*args)
+    return await result if inspect.isawaitable(result) else result
+
+
+async def dispatch_event(app: Any, event: Any) -> None:
+    kind = event.type.value
+    for types, hook in HOOKS:
+        if types is None or kind in types:
+            try:
+                await call(hook, app, event)
+            except Exception as exc:  # noqa: BLE001 - a broken plugin must not kill the UI
+                app.notify(f"plugin hook {hook.__name__} failed: {exc!r}", severity="error")
+
+
+def import_string(spec: str) -> Any:
+    """'package.module:Name' -> the object."""
+    module, _, name = spec.partition(":")
+    if not name:
+        raise ValueError(f"expected 'module:Name', got {spec!r}")
+    return getattr(importlib.import_module(module), name)
+
+
+def _load_file(path: Path) -> None:
+    name = f"gentui_plugin_{path.stem}"
+    if name in sys.modules:  # already loaded (e.g. several apps in one process)
+        return
+    spec = importlib.util.spec_from_file_location(name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"cannot load plugin {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    _register_setup(module)
+
+
+def _register_setup(module: Any) -> None:
+    setup = getattr(module, "setup", None)
+    if callable(setup) and setup not in SETUPS:
+        SETUPS.append(setup)
+
+
+def load_plugin(spec: str) -> None:
+    """Load one plugin: a .py file, a directory of .py files, or an importable module."""
+    path = Path(spec).expanduser()
+    if path.is_dir():
+        for file in sorted(path.glob("*.py")):
+            if not file.name.startswith("_"):
+                _load_file(file)
+    elif path.suffix == ".py":
+        _load_file(path)
+    else:
+        _register_setup(importlib.import_module(spec))
+
+
+def load_all(extra: list[str], widgets: dict[str, str], default_widget: str | None) -> list[str]:
+    """Load every plugin source and apply config widget overrides. Returns error messages."""
+    from gentui.tui.widgets.registry import register_widget, set_default_widget
+
+    errors: list[str] = []
+
+    def attempt(label: str, fn: Callable[[], None]) -> None:
+        try:
+            fn()
+        except Exception as exc:  # noqa: BLE001 - report, keep starting
+            errors.append(f"{label}: {exc!r}")
+
+    for ep in importlib.metadata.entry_points(group="gentui.plugins"):
+        attempt(f"plugin {ep.name}", lambda ep=ep: _register_setup(ep.load()))  # importing registers
+    for folder in (Path.home() / ".config" / "gentui" / "plugins", Path("gentui_plugins")):
+        if folder.is_dir():
+            attempt(f"plugins in {folder}", lambda folder=folder: load_plugin(str(folder)))
+    for spec in extra:
+        attempt(f"plugin {spec}", lambda spec=spec: load_plugin(spec))
+    for tool, spec in widgets.items():
+        attempt(f"widget {tool}", lambda tool=tool, spec=spec: register_widget(tool)(import_string(spec)))
+    if default_widget:
+        attempt("default_widget", lambda: set_default_widget(import_string(default_widget)))
+    return errors

gentui/tui/agentcore_client.py

@@ -0,0 +1,182 @@
+"""Amazon Bedrock AgentCore Runtime transport.
+
+An agent deployed on AgentCore Runtime with the **AG-UI protocol** accepts a `RunAgentInput` on
+`/invocations` and answers with an SSE stream of AG-UI events. This client sends that request with
+boto3's `invoke_agent_runtime` (so AWS credentials and SigV4 signing just work) and feeds the stream
+into the same event handling as the plain HTTP client.
+
+Needs boto3: `pip install 'gentui[agentcore]'`.
+"""
+
+import asyncio
+import hashlib
+import re
+import threading
+import time
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from gentui.config import parse_runtime_arn, split_runtime_arn
+from gentui.tui.agui_client import AguiClient, BackendError
+
+_DONE = object()
+_RETRIES = 3  # for RetryableConflictException ("session busy"); AG-UI clients are expected to retry it
+_SESSION_MIN, _SESSION_MAX = 33, 256  # the API's limits for runtimeSessionId
+
+
+def session_id_for(thread_id: str) -> str:
+    """A stable AgentCore runtime session id for a Gentui conversation.
+
+    AgentCore keeps one isolated session (and its state) per id, so one thread = one session. The API
+    requires 33 to 256 characters, so short or odd thread ids are made safe and padded with a hash."""
+    clean = re.sub(r"[^A-Za-z0-9_-]", "-", thread_id)
+    sid = f"gentui-{clean}"
+    if len(sid) < _SESSION_MIN:
+        sid = f"{sid}-{hashlib.sha256(thread_id.encode()).hexdigest()}"
+    return sid[:_SESSION_MAX]
+
+
+def explain(exc: BaseException) -> BackendError:
+    """Turn a boto3 / botocore exception into a message that tells the user what to do."""
+    name = type(exc).__name__
+    error = (getattr(exc, "response", None) or {}).get("Error", {})
+    code, message = error.get("Code", name), error.get("Message", str(exc))
+    if name in ("NoCredentialsError", "PartialCredentialsError"):
+        return BackendError(
+            "No AWS credentials found. Run `aws sso login`, or set AWS_PROFILE / "
+            "AWS_ACCESS_KEY_ID, or pass --profile."
+        )
+    if code in ("ExpiredTokenException", "ExpiredToken", "UnrecognizedClientException", "InvalidSignatureException"):
+        return BackendError(f"Your AWS credentials were rejected ({code}). Refresh them (e.g. `aws sso login`).")
+    friendly = {
+        "AccessDeniedException": "Access denied. The caller needs bedrock-agentcore:InvokeAgentRuntime on this "
+        "runtime (and bedrock-agentcore:InvokeAgentRuntimeForUser if a user id is used).",
+        "ResourceNotFoundException": "Runtime not found. Check the ARN, the region and --qualifier.",
+        "ThrottlingException": "AgentCore is throttling requests. Wait a moment and try again.",
+        "ServiceQuotaExceededException": "AgentCore service quota exceeded (too many sessions or requests).",
+        "RuntimeClientError": "The agent code failed while running. Check the runtime's CloudWatch logs.",
+        "RetryableConflictException": "The runtime session is busy (starting or finishing another call). Try again.",
+    }
+    if code in friendly:
+        return BackendError(f"{friendly[code]} ({code})")
+    if name in ("EndpointConnectionError", "ConnectTimeoutError", "ReadTimeoutError", "ConnectionClosedError"):
+        return BackendError(f"Cannot reach AgentCore: {exc}")
+    return BackendError(f"AgentCore error: {code}: {message}")
+
+
+class AgentCoreClient(AguiClient):
+    """Same interface and behaviour as `AguiClient`, but the transport is boto3 invoke_agent_runtime."""
+
+    def __init__(
+        self,
+        arn: str,
+        region: str | None = None,
+        profile: str | None = None,
+        qualifier: str | None = None,
+        timeout: float | None = None,
+        send_history: bool = False,
+        client: Any = None,
+    ) -> None:
+        arn_region, _ = parse_runtime_arn(arn)  # ValueError for a malformed ARN
+        runtime_arn, endpoint = split_runtime_arn(arn)
+        if qualifier and endpoint and qualifier != endpoint:
+            raise ValueError(f"the ARN names endpoint {endpoint!r} but --qualifier is {qualifier!r}; use only one")
+        super().__init__(runtime_arn, None, timeout, send_history)
+        self.arn = runtime_arn  # the API wants the plain runtime ARN ...
+        self.qualifier = qualifier or endpoint  # ... and the endpoint as `qualifier`
+        self._client = client if client is not None else self._make_client(region or arn_region, profile, timeout)
+
+    @staticmethod
+    def _make_client(region: str, profile: str | None, timeout: float | None) -> Any:
+        import boto3  # optional dependency: ImportError is handled by the CLI with install instructions
+        from botocore.config import Config
+        from botocore.exceptions import ProfileNotFound
+
+        try:
+            session = boto3.Session(profile_name=profile, region_name=region)
+        except ProfileNotFound as exc:
+            raise BackendError(f"AWS profile {profile!r} was not found.") from exc
+        # Agents can think for a long time without sending bytes; botocore needs a number, not None.
+        config = Config(read_timeout=timeout or 3600, connect_timeout=10, retries={"max_attempts": 2, "mode": "standard"})
+        return session.client("bedrock-agentcore", config=config)
+
+    # -- transport -------------------------------------------------------------------------------
+
+    async def _stream_lines(self, body: dict[str, Any]) -> AsyncIterator[str]:
+        """boto3 is blocking, so the call and the stream read run in a thread that feeds a queue."""
+        import json
+
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[Any] = asyncio.Queue()
+        stop = threading.Event()
+        payload = json.dumps(body).encode()
+        session_id = session_id_for(str(body.get("threadId", "")))
+
+        def worker() -> None:
+            try:
+                for line in self._invoke(payload, session_id, stop):
+                    loop.call_soon_threadsafe(queue.put_nowait, line)
+                loop.call_soon_threadsafe(queue.put_nowait, _DONE)
+            except BaseException as exc:  # noqa: BLE001 - handed to the consumer, which re-raises
+                loop.call_soon_threadsafe(queue.put_nowait, exc)
+
+        threading.Thread(target=worker, daemon=True, name="agentcore-stream").start()
+        try:
+            while True:
+                item = await queue.get()
+                if item is _DONE:
+                    return
+                if isinstance(item, BaseException):
+                    raise item
+                yield item
+        finally:
+            stop.set()  # the consumer went away (app closed, run cancelled): stop reading
+
+    def _invoke(self, payload: bytes, session_id: str, stop: threading.Event) -> Iterator[str]:
+        request: dict[str, Any] = {
+            "agentRuntimeArn": self.arn,
+            "runtimeSessionId": session_id,
+            "payload": payload,
+            "contentType": "application/json",
+            "accept": "text/event-stream",
+        }
+        if self.qualifier:
+            request["qualifier"] = self.qualifier
+
+        delay = 0.5
+        for attempt in range(_RETRIES + 1):
+            try:
+                response = self._client.invoke_agent_runtime(**request)
+                break
+            except Exception as exc:  # noqa: BLE001 - mapped to a friendly BackendError below
+                code = (getattr(exc, "response", None) or {}).get("Error", {}).get("Code")
+                if code == "RetryableConflictException" and attempt < _RETRIES:
+                    time.sleep(delay)  # transient: the session is being started or torn down
+                    delay *= 2
+                    continue
+                raise explain(exc) from exc
+
+        stream = response["response"]
+        try:
+            content_type = str(response.get("contentType", ""))
+            if not content_type.startswith("text/event-stream"):
+                sample = stream.read(400).decode("utf-8", "replace").strip()
+                raise BackendError(
+                    f"This runtime did not return an AG-UI event stream (content type {content_type or 'unknown'}). "
+                    "Deploy it with the AG-UI protocol (serverProtocol AGUI). "
+                    f"It said: {sample[:200]!r}"
+                )
+            # chunk_size=1: a larger chunk makes read() wait until that many bytes arrive, which would
+            # hold back a short event (a single token) until the next one shows up.
+            for raw in stream.iter_lines(chunk_size=1):
+                if stop.is_set():
+                    return
+                yield raw.decode("utf-8", "replace")
+        except BackendError:
+            raise
+        except Exception as exc:  # noqa: BLE001 - a read error mid-stream
+            raise explain(exc) from exc
+        finally:
+            close = getattr(stream, "close", None)
+            if close:
+                close()