welt-io 0.1.0__tar.gz

welt_io-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.so
+dist/
+.venv*/
+.coverage
+.pytest_cache/
+.ruff_cache/
+src/welt_io/_version.py

welt_io-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+We welcome contributions! Please follow these guidelines when submitting pull requests.
+
+## Recommended setup
+
+After cloning, enable the git hooks:
+
+```bash
+mise run enable-git-hooks
+```
+
+This wires `./validate.sh` to `pre-commit`, plus DCO and Conventional Commits checks to `commit-msg`, so the requirements below run automatically on each commit.
+
+## Before Submitting a PR
+
+### 1. Run Validation
+
+```bash
+./validate.sh
+```
+
+Runs the project's validation pipeline.
+
+### 2. Sign Commits with DCO
+
+All commits must be signed with DCO. Use `git commit -s` to sign your commits.
+
+- Use your real name (no pseudonyms)
+- All commits in a PR must be signed
+- If the DCO check fails, see the check details page for instructions on fixing unsigned commits
+
+For more about DCO: https://developercertificate.org/
+
+### 3. Follow Conventional Commits
+
+Commit subjects (first line) must follow `<type>(<scope>)?!?: <description>`. Allowed types: `feat`, `fix`, `chore`, `docs`. Append `!` for breaking changes.
+
+```
+feat: add dark-mode toggle
+fix(auth): handle expired token
+chore: bump dependencies
+feat!: drop legacy API
+```
+
+Other types (`refactor`, `ci`, `test`, etc.) are intentionally rejected — use `chore:` instead.
+
+For more about Conventional Commits: https://www.conventionalcommits.org/

welt_io-0.1.0/LICENSE

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

welt_io-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: welt-io
+Version: 0.1.0
+Summary: Agent-side adapters for Welt's wire contract
+Project-URL: Repository, https://github.com/iwamot/welt-io
+Project-URL: Issues, https://github.com/iwamot/welt-io/issues
+Author: Takashi Iwamoto
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentcore,bedrock,slack,strands,welt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: pip-licenses==5.5.5; extra == 'dev'
+Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# welt-io
+
+[![pypi](https://img.shields.io/pypi/v/welt-io.svg)](https://pypi.org/project/welt-io/)
+[![python](https://img.shields.io/pypi/pyversions/welt-io.svg)](https://pypi.org/project/welt-io/)
+
+Agent-side adapters for [Welt](https://github.com/iwamot/welt)'s wire contract.
+
+The wire between Welt and your agent is JSON, and plain Strands values do not fit it in either direction:
+
+- **Inbound**, JSON cannot carry raw bytes, so Welt base64-encodes the `bytes` slot of the Converse image/document/video blocks it builds from Slack uploads. `decode_file_blocks` restores them before Strands (Bedrock Converse) sees the messages; without uploads it is a no-op.
+- **Outbound**, raw `stream_async` events carry values that are not JSON-serializable (the Agent itself, UUIDs, traces), which the AgentCore Runtime SDK would degrade to a plain string on the SSE wire. `renderable_events` reduces the stream to the events Welt renders: text chunks (`data`), tool-use starts (`current_tool_use`), and tool completions (`tool_result`, slimmed to the toolUseId and status so tool output stays off the wire).
+
+## Install
+
+```bash
+uv add welt-io
+```
+
+## Usage
+
+```python
+from collections.abc import AsyncIterator
+
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+from strands import Agent
+from welt_io import decode_file_blocks, renderable_events
+
+app = BedrockAgentCoreApp()
+
+
+@app.entrypoint
+async def invoke(payload: dict) -> AsyncIterator[dict]:
+    messages = payload["messages"]
+    decode_file_blocks(messages)  # base64 file bytes -> raw bytes, in place
+    agent = Agent()
+    # Reduce the stream to the JSON-serializable events Welt renders
+    async for event in renderable_events(agent.stream_async(messages)):
+        yield event
+
+
+if __name__ == "__main__":
+    app.run()
+```
+
+## License
+
+MIT

welt_io-0.1.0/README.md

@@ -0,0 +1,47 @@
+# welt-io
+
+[![pypi](https://img.shields.io/pypi/v/welt-io.svg)](https://pypi.org/project/welt-io/)
+[![python](https://img.shields.io/pypi/pyversions/welt-io.svg)](https://pypi.org/project/welt-io/)
+
+Agent-side adapters for [Welt](https://github.com/iwamot/welt)'s wire contract.
+
+The wire between Welt and your agent is JSON, and plain Strands values do not fit it in either direction:
+
+- **Inbound**, JSON cannot carry raw bytes, so Welt base64-encodes the `bytes` slot of the Converse image/document/video blocks it builds from Slack uploads. `decode_file_blocks` restores them before Strands (Bedrock Converse) sees the messages; without uploads it is a no-op.
+- **Outbound**, raw `stream_async` events carry values that are not JSON-serializable (the Agent itself, UUIDs, traces), which the AgentCore Runtime SDK would degrade to a plain string on the SSE wire. `renderable_events` reduces the stream to the events Welt renders: text chunks (`data`), tool-use starts (`current_tool_use`), and tool completions (`tool_result`, slimmed to the toolUseId and status so tool output stays off the wire).
+
+## Install
+
+```bash
+uv add welt-io
+```
+
+## Usage
+
+```python
+from collections.abc import AsyncIterator
+
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+from strands import Agent
+from welt_io import decode_file_blocks, renderable_events
+
+app = BedrockAgentCoreApp()
+
+
+@app.entrypoint
+async def invoke(payload: dict) -> AsyncIterator[dict]:
+    messages = payload["messages"]
+    decode_file_blocks(messages)  # base64 file bytes -> raw bytes, in place
+    agent = Agent()
+    # Reduce the stream to the JSON-serializable events Welt renders
+    async for event in renderable_events(agent.stream_async(messages)):
+        yield event
+
+
+if __name__ == "__main__":
+    app.run()
+```
+
+## License
+
+MIT

welt_io-0.1.0/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Disclaimer
+
+This software is provided "as is" without warranty. Security issues will be addressed on a best-effort basis.
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities through GitHub's Security Advisory "Report a Vulnerability" feature.

welt_io-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "welt-io"
+dynamic = ["version"]
+description = "Agent-side adapters for Welt's wire contract"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Takashi Iwamoto" }]
+keywords = ["welt", "slack", "agentcore", "bedrock", "strands"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/iwamot/welt-io"
+Issues = "https://github.com/iwamot/welt-io/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pip-licenses==5.5.5",
+    "pytest==9.1.1",
+    "pytest-cov==7.1.0",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/welt_io/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/welt_io"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.codecov.yml",
+    "/.github",
+    "/compatibility.sh",
+    "/mise.toml",
+    "/uv.lock",
+    "/validate.sh",
+]
+
+[tool.uv]
+exclude-newer = "1 day"
+
+[tool.ruff]
+include = ["*.py", "src/**/*.py", "tests/**/*.py"]
+
+[tool.ruff.lint]
+# Reference: https://pydevtools.com/handbook/how-to/how-to-configure-recommended-ruff-defaults/
+extend-select = [
+    "F",    # Pyflakes rules
+    "W",    # PyCodeStyle warnings
+    # "E",    # PyCodeStyle errors
+    "I",    # Sort imports properly
+    "UP",   # Warn if certain things can changed due to newer Python versions
+    "C4",   # Catch incorrect use of comprehensions, dict, list, etc
+    "FA",   # Enforce from __future__ import annotations
+    "ISC",  # Good use of string concatenation
+    "ICN",  # Use common import conventions
+    "RET",  # Good return practices
+    # "SIM",  # Common simplification rules
+    "TID",  # Some good import practices
+    # "TC",   # Enforce importing certain types in a TYPE_CHECKING block
+    "PTH",  # Use pathlib instead of os.path
+    "TD",   # Be diligent with TODO comments
+    # "NPY",  # Some numpy-specific things
+    # Not in the reference URL
+    "S",    # flake8-bandit (security)
+]
+ignore = [
+    "S101",  # Allow assert in tests (pytest standard practice)
+]
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["welt_io"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true

welt_io-0.1.0/src/welt_io/__init__.py

@@ -0,0 +1,110 @@
+"""Adapters for the two directions of Welt's wire contract.
+
+The wire between Welt and the agent is JSON, and plain Strands values do not
+fit it in either direction:
+
+- Inbound, JSON cannot carry raw bytes, so Welt base64-encodes the `bytes`
+  slot of the Converse image/document/video blocks it builds from Slack
+  uploads. `decode_file_blocks` restores them before Strands (Bedrock
+  Converse) sees the messages; without uploads it is a no-op.
+- Outbound, raw `stream_async` events carry values that are not
+  JSON-serializable (the Agent itself, UUIDs, traces), which the AgentCore
+  Runtime SDK would degrade to a plain string on the SSE wire.
+  `renderable_events` reduces the stream to the events Welt renders.
+"""
+
+import base64
+from collections.abc import AsyncIterator
+
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["decode_file_blocks", "renderable_events"]
+
+
+def decode_file_blocks(messages: list) -> None:
+    """
+    Decode base64 image/document/video bytes back to raw bytes, in place.
+
+    Args:
+        messages (list): The Converse-shaped messages from Welt's payload.
+
+    Returns:
+        None
+    """
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        content = message.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            for key in ("image", "document", "video"):
+                media = block.get(key)
+                if not isinstance(media, dict):
+                    continue
+                source = media.get("source")
+                if isinstance(source, dict) and isinstance(source.get("bytes"), str):
+                    source["bytes"] = base64.b64decode(source["bytes"])
+
+
+async def renderable_events(events: AsyncIterator[dict]) -> AsyncIterator[dict]:
+    """
+    Reduce Strands `stream_async` events to the subset Welt renders.
+
+    Args:
+        events (AsyncIterator[dict]): Raw `stream_async` events.
+
+    Yields:
+        dict: A `data` event per text chunk, a `current_tool_use` event per
+            tool-use update, and a `tool_result` event — slimmed to the
+            toolUseId and status, so tool output (arbitrarily large, possibly
+            raw bytes) stays off the wire — per completed tool.
+    """
+    async for event in events:
+        if "data" in event:
+            yield {"data": event["data"]}
+        elif "current_tool_use" in event:
+            yield {"current_tool_use": event["current_tool_use"]}
+        elif "message" in event:
+            for tool_result in _tool_results(event["message"]):
+                yield {"tool_result": tool_result}
+
+
+def _tool_results(message: object) -> list[dict]:
+    """
+    Extract slimmed toolResult entries from a Strands message event.
+
+    Strands adds tool results to the conversation as a message whose content
+    blocks each carry a `toolResult`; model messages carry none, so they
+    yield an empty list.
+
+    Args:
+        message (object): The `message` value of a stream event.
+
+    Returns:
+        list[dict]: One `{"toolUseId", "status"}` entry per tool result.
+    """
+    if not isinstance(message, dict):
+        return []
+    content = message.get("content")
+    if not isinstance(content, list):
+        return []
+    results: list[dict] = []
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        tool_result = block.get("toolResult")
+        if not isinstance(tool_result, dict):
+            continue
+        results.append(
+            {
+                "toolUseId": tool_result.get("toolUseId"),
+                "status": tool_result.get("status"),
+            }
+        )
+    return results

welt_io-0.1.0/src/welt_io/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

welt_io-0.1.0/tests/test_decode_file_blocks.py

@@ -0,0 +1,110 @@
+import base64
+
+from welt_io import decode_file_blocks
+
+
+def encoded(raw: bytes) -> str:
+    return base64.b64encode(raw).decode()
+
+
+def test_decodes_image_document_and_video_blocks() -> None:
+    image_source: dict[str, object] = {"bytes": encoded(b"img")}
+    document_source: dict[str, object] = {"bytes": encoded(b"doc")}
+    video_source: dict[str, object] = {"bytes": encoded(b"vid")}
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"image": {"format": "png", "source": image_source}},
+                {"document": {"format": "pdf", "source": document_source}},
+                {"video": {"format": "mp4", "source": video_source}},
+            ],
+        }
+    ]
+
+    decode_file_blocks(messages)
+
+    assert image_source["bytes"] == b"img"
+    assert document_source["bytes"] == b"doc"
+    assert video_source["bytes"] == b"vid"
+
+
+def test_decodes_across_multiple_messages() -> None:
+    first_source: dict[str, object] = {"bytes": encoded(b"a")}
+    second_source: dict[str, object] = {"bytes": encoded(b"b")}
+    messages = [
+        {"role": "user", "content": [{"image": {"source": first_source}}]},
+        {"role": "user", "content": [{"image": {"source": second_source}}]},
+    ]
+
+    decode_file_blocks(messages)
+
+    assert first_source["bytes"] == b"a"
+    assert second_source["bytes"] == b"b"
+
+
+def test_leaves_text_blocks_alone() -> None:
+    messages = [{"role": "user", "content": [{"text": "hello"}]}]
+
+    decode_file_blocks(messages)
+
+    assert messages == [{"role": "user", "content": [{"text": "hello"}]}]
+
+
+def test_no_op_on_empty_messages() -> None:
+    messages: list = []
+
+    decode_file_blocks(messages)
+
+    assert messages == []
+
+
+def test_skips_non_dict_message() -> None:
+    messages = ["not a dict"]
+
+    decode_file_blocks(messages)
+
+    assert messages == ["not a dict"]
+
+
+def test_skips_non_list_content() -> None:
+    messages = [{"role": "user", "content": "not a list"}]
+
+    decode_file_blocks(messages)
+
+    assert messages == [{"role": "user", "content": "not a list"}]
+
+
+def test_skips_non_dict_block() -> None:
+    messages = [{"role": "user", "content": ["not a dict"]}]
+
+    decode_file_blocks(messages)
+
+    assert messages == [{"role": "user", "content": ["not a dict"]}]
+
+
+def test_skips_non_dict_media() -> None:
+    messages = [{"role": "user", "content": [{"image": "not a dict"}]}]
+
+    decode_file_blocks(messages)
+
+    assert messages == [{"role": "user", "content": [{"image": "not a dict"}]}]
+
+
+def test_skips_non_dict_source() -> None:
+    messages = [{"role": "user", "content": [{"image": {"source": "not a dict"}}]}]
+
+    decode_file_blocks(messages)
+
+    assert messages == [
+        {"role": "user", "content": [{"image": {"source": "not a dict"}}]}
+    ]
+
+
+def test_skips_bytes_that_are_not_str() -> None:
+    source: dict[str, object] = {"bytes": b"raw"}
+    messages = [{"role": "user", "content": [{"image": {"source": source}}]}]
+
+    decode_file_blocks(messages)
+
+    assert source["bytes"] == b"raw"

welt_io-0.1.0/tests/test_renderable_events.py

@@ -0,0 +1,137 @@
+import asyncio
+from collections.abc import AsyncIterator
+
+from welt_io import renderable_events
+
+
+def rendered(events: list) -> list[dict]:
+    async def source() -> AsyncIterator[dict]:
+        for event in events:
+            yield event
+
+    async def gather() -> list[dict]:
+        return [event async for event in renderable_events(source())]
+
+    return asyncio.run(gather())
+
+
+def test_data_event_is_reduced_to_its_data_key() -> None:
+    events = [{"data": "hello", "delta": {"text": "hello"}, "agent": object()}]
+
+    assert rendered(events) == [{"data": "hello"}]
+
+
+def test_current_tool_use_event_is_reduced_to_its_key() -> None:
+    tool_use = {"toolUseId": "id-1", "name": "current_time", "input": {}}
+    events = [{"current_tool_use": tool_use, "agent": object()}]
+
+    assert rendered(events) == [{"current_tool_use": tool_use}]
+
+
+def test_data_takes_precedence_over_current_tool_use() -> None:
+    events = [{"data": "hello", "current_tool_use": {"toolUseId": "id-1"}}]
+
+    assert rendered(events) == [{"data": "hello"}]
+
+
+def test_tool_result_message_is_slimmed_to_id_and_status() -> None:
+    events = [
+        {
+            "message": {
+                "role": "user",
+                "content": [
+                    {
+                        "toolResult": {
+                            "toolUseId": "id-1",
+                            "status": "success",
+                            "content": [{"text": "arbitrarily large output"}],
+                        }
+                    }
+                ],
+            }
+        }
+    ]
+
+    assert rendered(events) == [
+        {"tool_result": {"toolUseId": "id-1", "status": "success"}}
+    ]
+
+
+def test_yields_one_tool_result_per_block() -> None:
+    events = [
+        {
+            "message": {
+                "role": "user",
+                "content": [
+                    {"toolResult": {"toolUseId": "id-1", "status": "success"}},
+                    {"toolResult": {"toolUseId": "id-2", "status": "error"}},
+                ],
+            }
+        }
+    ]
+
+    assert rendered(events) == [
+        {"tool_result": {"toolUseId": "id-1", "status": "success"}},
+        {"tool_result": {"toolUseId": "id-2", "status": "error"}},
+    ]
+
+
+def test_missing_tool_result_fields_become_none() -> None:
+    events = [{"message": {"role": "user", "content": [{"toolResult": {}}]}}]
+
+    assert rendered(events) == [{"tool_result": {"toolUseId": None, "status": None}}]
+
+
+def test_model_message_without_tool_results_yields_nothing() -> None:
+    events = [{"message": {"role": "assistant", "content": [{"text": "hi"}]}}]
+
+    assert rendered(events) == []
+
+
+def test_non_dict_message_yields_nothing() -> None:
+    assert rendered([{"message": "not a dict"}]) == []
+
+
+def test_non_list_message_content_yields_nothing() -> None:
+    assert rendered([{"message": {"role": "user", "content": "not a list"}}]) == []
+
+
+def test_non_dict_content_block_is_skipped() -> None:
+    assert rendered([{"message": {"role": "user", "content": ["not a dict"]}}]) == []
+
+
+def test_non_dict_tool_result_is_skipped() -> None:
+    events = [{"message": {"role": "user", "content": [{"toolResult": "not a dict"}]}}]
+
+    assert rendered(events) == []
+
+
+def test_unrenderable_events_are_dropped() -> None:
+    events = [
+        {"init_event_loop": True},
+        {"delta": {"text": "chunk"}},
+        {"result": object()},
+    ]
+
+    assert rendered(events) == []
+
+
+def test_stream_order_is_preserved() -> None:
+    events = [
+        {"data": "a"},
+        {"current_tool_use": {"toolUseId": "id-1"}},
+        {
+            "message": {
+                "role": "user",
+                "content": [{"toolResult": {"toolUseId": "id-1", "status": "success"}}],
+            }
+        },
+        {"data": "b"},
+    ]
+
+    assert rendered(events) == [
+        {"data": "a"},
+        {"current_tool_use": {"toolUseId": "id-1"}},
+        {"tool_result": {"toolUseId": "id-1", "status": "success"}},
+        {"data": "b"},
+    ]