chatevent 0.0.1__tar.gz

chatevent-0.0.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Rex Wang
+
+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.
+

chatevent-0.0.1/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: chatevent
+Version: 0.0.1
+Summary: Normalized events and async capture interfaces for collaboration platforms
+Author-email: Rex Wang <1073853456@qq.com>
+License-Expression: MIT
+Keywords: agent,event,webhook,zulip,discourse,gitea
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# ChatEvent
+
+`chatevent` provides a small, typed event envelope and capture interface for
+collaboration platforms such as Zulip, Discourse, Gitea, GitHub, and blogs.
+
+It is intended to sit at the Event Capture boundary of an agent system:
+
+```text
+platform events -> ChatEvent -> gateway/router -> agent execution
+```
+
+## Install
+
+```bash
+pip install chatevent
+```
+
+## Define a normalized event
+
+```python
+from datetime import datetime, timezone
+
+from chatevent import CaptureMode, ChatEvent
+
+event = ChatEvent(
+    id="42",
+    source="gitea",
+    kind="issue.opened",
+    occurred_at=datetime.now(timezone.utc),
+    capture_mode=CaptureMode.PUSH,
+    conversation_id="owner/repo#42",
+    payload={"title": "Investigate event routing"},
+)
+
+assert event.dedupe_key == "gitea:42"
+```
+
+## Implement a monitor
+
+An adapter exposes an asynchronous stream. It may receive pushed events or
+poll a platform with an incremental cursor.
+
+```python
+from collections.abc import AsyncIterator
+
+from chatevent import CaptureMode, ChatEvent, EventMonitor
+
+
+class GiteaMonitor:
+    source = "gitea"
+    mode = CaptureMode.PULL
+
+    async def events(self, *, cursor: str | None = None) -> AsyncIterator[ChatEvent]:
+        if False:  # Replace with incremental API reads.
+            yield
+
+
+monitor: EventMonitor = GiteaMonitor()
+```
+
+The initial release deliberately contains no platform SDK or runtime
+dependency. Platform adapters, persistence, filtering, and delivery guarantees
+can evolve independently around this stable boundary.
+

chatevent-0.0.1/README.md

@@ -0,0 +1,64 @@
+# ChatEvent
+
+`chatevent` provides a small, typed event envelope and capture interface for
+collaboration platforms such as Zulip, Discourse, Gitea, GitHub, and blogs.
+
+It is intended to sit at the Event Capture boundary of an agent system:
+
+```text
+platform events -> ChatEvent -> gateway/router -> agent execution
+```
+
+## Install
+
+```bash
+pip install chatevent
+```
+
+## Define a normalized event
+
+```python
+from datetime import datetime, timezone
+
+from chatevent import CaptureMode, ChatEvent
+
+event = ChatEvent(
+    id="42",
+    source="gitea",
+    kind="issue.opened",
+    occurred_at=datetime.now(timezone.utc),
+    capture_mode=CaptureMode.PUSH,
+    conversation_id="owner/repo#42",
+    payload={"title": "Investigate event routing"},
+)
+
+assert event.dedupe_key == "gitea:42"
+```
+
+## Implement a monitor
+
+An adapter exposes an asynchronous stream. It may receive pushed events or
+poll a platform with an incremental cursor.
+
+```python
+from collections.abc import AsyncIterator
+
+from chatevent import CaptureMode, ChatEvent, EventMonitor
+
+
+class GiteaMonitor:
+    source = "gitea"
+    mode = CaptureMode.PULL
+
+    async def events(self, *, cursor: str | None = None) -> AsyncIterator[ChatEvent]:
+        if False:  # Replace with incremental API reads.
+            yield
+
+
+monitor: EventMonitor = GiteaMonitor()
+```
+
+The initial release deliberately contains no platform SDK or runtime
+dependency. Platform adapters, persistence, filtering, and delivery guarantees
+can evolve independently around this stable boundary.
+

chatevent-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chatevent"
+version = "0.0.1"
+authors = [
+    {name = "Rex Wang", email = "1073853456@qq.com"},
+]
+description = "Normalized events and async capture interfaces for collaboration platforms"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["agent", "event", "webhook", "zulip", "discourse", "gitea"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Communications",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+chatevent = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

chatevent-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chatevent-0.0.1/src/chatevent/__init__.py

@@ -0,0 +1,8 @@
+"""Public API for ChatEvent."""
+
+from .model import CaptureMode, ChatEvent
+from .monitor import EventMonitor
+
+__all__ = ["CaptureMode", "ChatEvent", "EventMonitor"]
+__version__ = "0.0.1"
+

chatevent-0.0.1/src/chatevent/model.py

@@ -0,0 +1,65 @@
+"""Normalized event model shared by platform adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Mapping
+
+
+class CaptureMode(str, Enum):
+    """How an event entered the capture layer."""
+
+    PUSH = "push"
+    PULL = "pull"
+
+
+@dataclass(frozen=True, slots=True)
+class ChatEvent:
+    """A platform-neutral event envelope.
+
+    Event IDs only need to be stable within a source. Platform-specific data
+    stays in ``payload`` so the core model can evolve independently of SDKs.
+    """
+
+    id: str
+    source: str
+    kind: str
+    occurred_at: datetime
+    capture_mode: CaptureMode
+    payload: Mapping[str, Any] = field(default_factory=dict)
+    actor_id: str | None = None
+    conversation_id: str | None = None
+    url: str | None = None
+    cursor: str | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("id", "source", "kind"):
+            if not getattr(self, name).strip():
+                raise ValueError(f"{name} must not be empty")
+        if self.occurred_at.tzinfo is None or self.occurred_at.utcoffset() is None:
+            raise ValueError("occurred_at must be timezone-aware")
+
+    @property
+    def dedupe_key(self) -> str:
+        """Return the default stable key used to suppress duplicate delivery."""
+
+        return f"{self.source}:{self.id}"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-compatible representation of the envelope."""
+
+        return {
+            "id": self.id,
+            "source": self.source,
+            "kind": self.kind,
+            "occurred_at": self.occurred_at.isoformat(),
+            "capture_mode": self.capture_mode.value,
+            "payload": dict(self.payload),
+            "actor_id": self.actor_id,
+            "conversation_id": self.conversation_id,
+            "url": self.url,
+            "cursor": self.cursor,
+        }
+

chatevent-0.0.1/src/chatevent/monitor.py

@@ -0,0 +1,21 @@
+"""Extension protocol for event capture adapters."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Protocol
+
+from .model import CaptureMode, ChatEvent
+
+
+class EventMonitor(Protocol):
+    """An asynchronous source of normalized events."""
+
+    source: str
+    mode: CaptureMode
+
+    def events(self, *, cursor: str | None = None) -> AsyncIterator[ChatEvent]:
+        """Yield new events, optionally continuing from a source cursor."""
+
+        ...
+

chatevent-0.0.1/src/chatevent/py.typed

@@ -0,0 +1 @@
+

chatevent-0.0.1/src/chatevent.egg-info/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: chatevent
+Version: 0.0.1
+Summary: Normalized events and async capture interfaces for collaboration platforms
+Author-email: Rex Wang <1073853456@qq.com>
+License-Expression: MIT
+Keywords: agent,event,webhook,zulip,discourse,gitea
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# ChatEvent
+
+`chatevent` provides a small, typed event envelope and capture interface for
+collaboration platforms such as Zulip, Discourse, Gitea, GitHub, and blogs.
+
+It is intended to sit at the Event Capture boundary of an agent system:
+
+```text
+platform events -> ChatEvent -> gateway/router -> agent execution
+```
+
+## Install
+
+```bash
+pip install chatevent
+```
+
+## Define a normalized event
+
+```python
+from datetime import datetime, timezone
+
+from chatevent import CaptureMode, ChatEvent
+
+event = ChatEvent(
+    id="42",
+    source="gitea",
+    kind="issue.opened",
+    occurred_at=datetime.now(timezone.utc),
+    capture_mode=CaptureMode.PUSH,
+    conversation_id="owner/repo#42",
+    payload={"title": "Investigate event routing"},
+)
+
+assert event.dedupe_key == "gitea:42"
+```
+
+## Implement a monitor
+
+An adapter exposes an asynchronous stream. It may receive pushed events or
+poll a platform with an incremental cursor.
+
+```python
+from collections.abc import AsyncIterator
+
+from chatevent import CaptureMode, ChatEvent, EventMonitor
+
+
+class GiteaMonitor:
+    source = "gitea"
+    mode = CaptureMode.PULL
+
+    async def events(self, *, cursor: str | None = None) -> AsyncIterator[ChatEvent]:
+        if False:  # Replace with incremental API reads.
+            yield
+
+
+monitor: EventMonitor = GiteaMonitor()
+```
+
+The initial release deliberately contains no platform SDK or runtime
+dependency. Platform adapters, persistence, filtering, and delivery guarantees
+can evolve independently around this stable boundary.
+

chatevent-0.0.1/src/chatevent.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/chatevent/__init__.py
+src/chatevent/model.py
+src/chatevent/monitor.py
+src/chatevent/py.typed
+src/chatevent.egg-info/PKG-INFO
+src/chatevent.egg-info/SOURCES.txt
+src/chatevent.egg-info/dependency_links.txt
+src/chatevent.egg-info/requires.txt
+src/chatevent.egg-info/top_level.txt
+tests/test_model.py

chatevent-0.0.1/src/chatevent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

chatevent-0.0.1/src/chatevent.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=8

chatevent-0.0.1/src/chatevent.egg-info/top_level.txt

@@ -0,0 +1 @@
+chatevent

chatevent-0.0.1/tests/test_model.py

@@ -0,0 +1,45 @@
+from datetime import datetime, timezone
+import unittest
+
+from chatevent import CaptureMode, ChatEvent
+
+
+class ChatEventTests(unittest.TestCase):
+    def test_event_has_stable_dedupe_key_and_serializes(self) -> None:
+        event = ChatEvent(
+            id="42",
+            source="gitea",
+            kind="issue.opened",
+            occurred_at=datetime(2026, 8, 18, tzinfo=timezone.utc),
+            capture_mode=CaptureMode.PUSH,
+            payload={"title": "Investigate event routing"},
+        )
+
+        self.assertEqual(event.dedupe_key, "gitea:42")
+        self.assertEqual(event.to_dict()["capture_mode"], "push")
+        self.assertEqual(event.to_dict()["occurred_at"], "2026-08-18T00:00:00+00:00")
+
+    def test_event_rejects_naive_datetime(self) -> None:
+        with self.assertRaisesRegex(ValueError, "timezone-aware"):
+            ChatEvent(
+                id="42",
+                source="gitea",
+                kind="issue.opened",
+                occurred_at=datetime(2026, 8, 18),
+                capture_mode=CaptureMode.PULL,
+            )
+
+    def test_event_rejects_empty_identity_fields(self) -> None:
+        with self.assertRaisesRegex(ValueError, "source must not be empty"):
+            ChatEvent(
+                id="42",
+                source=" ",
+                kind="issue.opened",
+                occurred_at=datetime(2026, 8, 18, tzinfo=timezone.utc),
+                capture_mode=CaptureMode.PULL,
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()
+