chatevent 0.0.1__py3-none-any.whl

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/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/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/py.typed

@@ -0,0 +1 @@
+

chatevent-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+chatevent/__init__.py,sha256=DSK53htIX9Nh6TAbJVbCIvunqvQ4utX2laICGHLBADc,188
+chatevent/model.py,sha256=FV8BN6g-ArfCUaJKSjj8G4o6bAO6Fk78KufLDyMKjFY,1948
+chatevent/monitor.py,sha256=xSLKPkcAFkZtjYna_27e5kmKF7Dg0cs1hcuQSDcqdFY,500
+chatevent/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+chatevent-0.0.1.dist-info/licenses/LICENSE,sha256=sDWCc1XORwxjrZIzXJaEMOxFIwBJDFa4CyGc6WQBA6g,1066
+chatevent-0.0.1.dist-info/METADATA,sha256=ud2SUB0KF5sOoVi3eWHXMCOn1GZhjW312sJeOFuEvAQ,2257
+chatevent-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+chatevent-0.0.1.dist-info/top_level.txt,sha256=5STX44ckdRG83SMXX5UaHoeLkXv2wdoXBYDHVGPf9CM,10
+chatevent-0.0.1.dist-info/RECORD,,

chatevent-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chatevent-0.0.1.dist-info/licenses/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.dist-info/top_level.txt

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