3tears-channels 0.14.0__tar.gz

3tears_channels-0.14.0/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Claude Code local state
+.claude/
+
+# prawduct session evidence (local governance artifacts, never shipped)
+.prawduct/
+
+# macOS folder metadata
+.DS_Store

3tears_channels-0.14.0/LICENSE

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

3tears_channels-0.14.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: 3tears-channels
+Version: 0.14.0
+Summary: Unified message protocol for channel adapters in the 3tears platform
+Project-URL: Repository, https://github.com/pacepace/3tears
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: 3tears
+Requires-Dist: 3tears-agent-acl
+Requires-Dist: 3tears-nats
+Requires-Dist: 3tears-observe
+Provides-Extra: discord
+Requires-Dist: discord-py>=2.7; extra == 'discord'
+Provides-Extra: slack
+Requires-Dist: aiohttp>=3.9; extra == 'slack'
+Requires-Dist: slack-bolt>=1.28; extra == 'slack'
+Requires-Dist: slack-sdk>=3.41; extra == 'slack'
+Provides-Extra: webhook
+Requires-Dist: 3tears-agent-wake>=0.9.0; extra == 'webhook'
+Requires-Dist: fastapi>=0.110; extra == 'webhook'
+Provides-Extra: websocket
+Requires-Dist: starlette>=0.36; extra == 'websocket'
+Description-Content-Type: text/markdown
+
+# 3tears-channels
+
+A unified message protocol for the 3tears framework, with adapters for Slack, Discord, and WebSocket clients. Write your agent logic once and deliver it across channels.
+
+```bash
+pip install 3tears-channels
+```
+
+## What you get
+
+- **One message model** -- `ChannelMessage`, `ChannelResponse`, `ChannelDeliveryMessage`, and `Attachment` carry a request and its reply regardless of channel.
+- **Routing** -- `ChannelRouter` and `StreamingChannelRouter` dispatch inbound messages and stream responses back.
+- **Slack and Discord** -- payload and rich-formatting builders (`build_slack_blocks`, `build_slack_payload`, `build_discord_embed`, `build_discord_payload`) plus a `should_use_rich_formatting` helper.
+- **WebSocket** -- `WebSocketHandler`, `WebSocketProtocol`, a `ConnectionRegistry`, and frame primitives for real-time clients.
+- **Rooms and presence** -- `RoomFanout`, `RoomState`, `RoomIndexCollection`, and a three-tier-backed `PresenceCollection` with a `PresenceSweeper` for connection liveness.
+
+## Quickstart
+
+```python
+from threetears.channels import ChannelRouter, ChannelMessage, build_slack_blocks
+
+router = ChannelRouter(...)
+response = await router.dispatch(ChannelMessage(text="hello", channel="slack", ...))
+
+blocks = build_slack_blocks(response)
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

3tears_channels-0.14.0/README.md

@@ -0,0 +1,30 @@
+# 3tears-channels
+
+A unified message protocol for the 3tears framework, with adapters for Slack, Discord, and WebSocket clients. Write your agent logic once and deliver it across channels.
+
+```bash
+pip install 3tears-channels
+```
+
+## What you get
+
+- **One message model** -- `ChannelMessage`, `ChannelResponse`, `ChannelDeliveryMessage`, and `Attachment` carry a request and its reply regardless of channel.
+- **Routing** -- `ChannelRouter` and `StreamingChannelRouter` dispatch inbound messages and stream responses back.
+- **Slack and Discord** -- payload and rich-formatting builders (`build_slack_blocks`, `build_slack_payload`, `build_discord_embed`, `build_discord_payload`) plus a `should_use_rich_formatting` helper.
+- **WebSocket** -- `WebSocketHandler`, `WebSocketProtocol`, a `ConnectionRegistry`, and frame primitives for real-time clients.
+- **Rooms and presence** -- `RoomFanout`, `RoomState`, `RoomIndexCollection`, and a three-tier-backed `PresenceCollection` with a `PresenceSweeper` for connection liveness.
+
+## Quickstart
+
+```python
+from threetears.channels import ChannelRouter, ChannelMessage, build_slack_blocks
+
+router = ChannelRouter(...)
+response = await router.dispatch(ChannelMessage(text="hello", channel="slack", ...))
+
+blocks = build_slack_blocks(response)
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

3tears_channels-0.14.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "3tears-channels"
+version = "0.14.0"
+description = "Unified message protocol for channel adapters in the 3tears platform"
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [{name = "pace"}]
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "3tears",
+    "3tears-agent-acl",
+    "3tears-nats",
+    "3tears-observe",
+]
+
+[project.optional-dependencies]
+slack = ["slack-bolt>=1.28", "slack-sdk>=3.41", "aiohttp>=3.9"]
+discord = ["discord.py>=2.7"]
+websocket = ["starlette>=0.36"]
+# webhook receiver depends on:
+#   * fastapi -- the route-mount target (consumers register the
+#     receiver on their FastAPI app via ``add_api_route``)
+#   * 3tears-agent-wake -- ``webhook_receive`` is the verify+rate-limit+
+#     dispatch entry point the receiver delegates to. This creates a
+#     one-direction edge: channels -> agent-wake -> conversations +
+#     agent-skills. agent-wake does NOT depend on channels (the wake
+#     adapter is a function the channels-side HTTP shim calls into).
+webhook = ["fastapi>=0.110", "3tears-agent-wake>=0.9.0"]
+
+[project.urls]
+Repository = "https://github.com/pacepace/3tears"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threetears"]
+
+[tool.uv.sources]
+3tears = { workspace = true }
+3tears-agent-acl = { workspace = true }
+3tears-nats = { workspace = true }
+3tears-observe = { workspace = true }
+3tears-agent-wake = { workspace = true }

3tears_channels-0.14.0/src/threetears/channels/__init__.py

@@ -0,0 +1,133 @@
+"""3tears-channels: unified message protocol for channel adapters."""
+
+from __future__ import annotations
+
+# Version derived from pyproject.toml so the metadata is the single
+# source of truth -- a future release that bumps pyproject without
+# updating ``__init__.py`` can't drift the runtime ``__version__``.
+# The except guard handles the rare case where the package isn't
+# installed via importlib.metadata (e.g. running directly from a
+# checked-out source tree without ``uv sync``); the fallback keeps
+# imports working but reports ``unknown`` rather than crashing.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("3tears-channels")
+except _PackageNotFoundError:  # pragma: no cover - dev fallback
+    __version__ = "unknown"
+
+from threetears.channels.formatting import (
+    build_discord_embed,
+    build_discord_payload,
+    build_slack_blocks,
+    build_slack_payload,
+    should_use_rich_formatting,
+)
+from threetears.channels.frames import (
+    Frame,
+    FrameHandler,
+    NsEntity,
+    NsResolver,
+    OpHandler,
+    OpRejected,
+    OpResult,
+    ReplaySource,
+)
+from threetears.channels.delivery import (
+    ChannelDeliveryMessage,
+)
+from threetears.channels.protocol import (
+    Attachment,
+    ChannelMessage,
+    ChannelResponse,
+    ChannelRouter,
+)
+from threetears.channels.presence import (
+    PRESENCE_L1_METADATA,
+    PRESENCE_L1_TABLE_NAMES,
+    PresenceCollection,
+    PresenceConnectionCollection,
+    PresenceConnectionEntity,
+    PresenceSweeper,
+    RoomFanout,
+    RoomFrame,
+    RoomIndexCollection,
+    RoomIndexEntity,
+    RoomMember,
+    RoomState,
+    create_presence_l1_backend,
+)
+from threetears.channels.websocket import (
+    ConnectionRegistry,
+    StreamingChannelRouter,
+    WebSocketHandler,
+    WebSocketProtocol,
+)
+
+__all__ = [
+    "PRESENCE_L1_METADATA",
+    "PRESENCE_L1_TABLE_NAMES",
+    "Attachment",
+    "ChannelDeliveryMessage",
+    "ChannelMessage",
+    "ChannelResponse",
+    "ChannelRouter",
+    "ConnectionRegistry",
+    "Frame",
+    "FrameHandler",
+    "NsEntity",
+    "NsResolver",
+    "OpHandler",
+    "OpRejected",
+    "OpResult",
+    "PresenceCollection",
+    "PresenceConnectionCollection",
+    "PresenceConnectionEntity",
+    "PresenceSweeper",
+    "ReplaySource",
+    "RoomFanout",
+    "RoomFrame",
+    "RoomIndexCollection",
+    "RoomIndexEntity",
+    "RoomMember",
+    "RoomState",
+    "StreamingChannelRouter",
+    "WebSocketHandler",
+    "WebSocketProtocol",
+    "build_discord_embed",
+    "build_discord_payload",
+    "build_slack_blocks",
+    "build_slack_payload",
+    "create_presence_l1_backend",
+    "should_use_rich_formatting",
+]
+
+try:
+    from threetears.channels.slack import SlackAdapter  # noqa: F401
+
+    __all__.append("SlackAdapter")
+except ImportError:
+    pass
+
+try:
+    from threetears.channels.discord import DiscordAdapter  # noqa: F401
+
+    __all__.append("DiscordAdapter")
+except ImportError:
+    pass
+
+# The webhook receiver requires the ``webhook`` extra (fastapi +
+# 3tears-agent-wake). Guarded the same way as the slack / discord
+# adapters so consumers without the extra installed can still import
+# the rest of the channels package.
+try:
+    from threetears.channels.webhook import (  # noqa: F401
+        Verifier,
+        WebhookReceiver,
+        verify_generic_hmac_sha256,
+    )
+
+    __all__.extend(["Verifier", "WebhookReceiver", "verify_generic_hmac_sha256"])
+except ImportError:
+    pass

3tears_channels-0.14.0/src/threetears/channels/delivery.py

@@ -0,0 +1,75 @@
+"""durable channel-delivery wire model.
+
+the agent publishes a finished answer to the durable JetStream delivery subject
+(:func:`threetears.nats.Subjects.channels_deliver`) with the channel routing
+lifted off the inbound message; the channel adapter durable-consumes it and
+posts it to the destination thread. this is the typed wire envelope for that
+hand-off -- a Pydantic model because it crosses the NATS boundary (the channel
+``protocol`` dataclasses are internal working objects, never serialized).
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+__all__ = ["ChannelDeliveryMessage"]
+
+
+class ChannelDeliveryMessage(BaseModel):
+    """a finished agent answer awaiting durable delivery to a channel thread.
+
+    carries the answer content plus exactly the routing the adapter needs to
+    post out-of-band: the channel family, the workspace / channel / thread refs
+    (lifted off the inbound message's metadata), and the dedup coordinates.
+
+    :param correlation_id: per-turn correlation id of the originating request;
+        with ``conversation_id`` forms the dedup key so a JetStream redelivery
+        (or a second adapter replica) never double-posts
+    :ptype correlation_id: UUID
+    :param conversation_id: derived conversation id the answer belongs to
+    :ptype conversation_id: UUID
+    :param agent_id: agent that produced the answer
+    :ptype agent_id: UUID
+    :param channel_type: channel family (``slack``, ``discord``, ...)
+    :ptype channel_type: str
+    :param workspace_ref: platform workspace / team reference (slack ``team``);
+        the adapter maps this to the right bot token
+    :ptype workspace_ref: str | None
+    :param channel_ref: platform channel reference to post into
+    :ptype channel_ref: str | None
+    :param thread_ref: platform thread reference to reply in (slack ``thread_ts``)
+    :ptype thread_ref: str | None
+    :param content: answer text in markdown
+    :ptype content: str
+    :param date_created: answer-ready timestamp (timezone-aware UTC)
+    :ptype date_created: datetime
+    """
+
+    correlation_id: UUID
+    conversation_id: UUID
+    agent_id: UUID
+    channel_type: str
+    workspace_ref: str | None = None
+    channel_ref: str | None = None
+    thread_ref: str | None = None
+    content: str
+    date_created: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    @property
+    def dedup_key(self) -> str:
+        """return deterministic dedup key for at-least-once delivery.
+
+        keyed on ``(conversation, correlation)`` so the same answer redelivered
+        by JetStream -- or drained by a second adapter replica -- is posted at
+        most once. the separator is ``-`` (not ``:``) because this string is a
+        NATS KV key, and KV keys admit only ``[-/_=.a-zA-Z0-9]`` -- a colon
+        raises ``InvalidKeyError``. both halves are 32-char hex, so ``-`` is
+        unambiguous.
+
+        :return: dedup key ``{conversation_hex}-{correlation_hex}``
+        :rtype: str
+        """
+        return f"{self.conversation_id.hex}-{self.correlation_id.hex}"