pine-assistant 0.2.0__tar.gz → 0.3.1__tar.gz

{pine_assistant-0.2.0/src/pine_assistant.egg-info → pine_assistant-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pine-assistant
-Version: 0.2.0
+Version: 0.3.1
 Summary: Pine AI SDK — Let Pine AI handle your digital chores. Socket.IO + REST client.
 Author: Pine AI
 License-Expression: MIT
@@ -20,7 +20,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: python-socketio[asyncio]>=5.11.0
+Requires-Dist: python-socketio>=5.11.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic>=2.0.0
 Provides-Extra: cli

{pine_assistant-0.2.0 → pine_assistant-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pine-assistant"
-version = "0.2.0"
+version = "0.3.1"
 description = "Pine AI SDK — Let Pine AI handle your digital chores. Socket.IO + REST client."
 readme = "README.md"
 license = "MIT"
@@ -23,7 +23,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "python-socketio[asyncio]>=5.11.0",
+    "python-socketio>=5.11.0",
     "httpx>=0.27.0",
     "pydantic>=2.0.0",
 ]

{pine_assistant-0.2.0 → pine_assistant-0.3.1}/src/pine_assistant/__init__.py

@@ -11,7 +11,7 @@ from pine_assistant.sessions import SessionsAPI
 from pine_assistant.errors import PineAIError, AuthError, SessionError, ConnectionError
 from pine_assistant.models.events import C2SEvent, S2CEvent, NotificationEvent
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"
 __all__ = [
     "PineAI",
     "AsyncPineAI",

{pine_assistant-0.2.0 → pine_assistant-0.3.1}/src/pine_assistant/chat.py

@@ -1,14 +1,11 @@
 """
-Chat engine — send messages and yield complete events via async generator.
+Chat engine — send messages and yield events via async generator.
 
-Stream buffering:
-- Tier 1: session:text_part buffered until final: true
-- Tier 2: Non-streaming events yield immediately
-- Tier 3: session:work_log_part debounced (3s silence)
+All events are dispatched immediately as they arrive from the server.
 """
 
 import asyncio
-import time
+from datetime import datetime, timedelta, timezone
 from typing import Any, AsyncGenerator, Callable, Coroutine, Optional
 
 from pine_assistant.models.events import C2SEvent, S2CEvent
@@ -16,13 +13,11 @@ from pine_assistant.transport.socketio import SocketIOManager
 
 TERMINAL_STATES = {"task_finished", "task_cancelled", "task_stale"}
 DEFAULT_IDLE_TIMEOUT_S = 120.0
+DEFAULT_RESPONSE_IDLE_TIMEOUT_S = 2.0
 
-# Events that are buffered/debounced — NOT dispatched immediately
-BUFFERED_EVENTS = {S2CEvent.SESSION_TEXT_PART, S2CEvent.SESSION_WORK_LOG_PART}
-
-# Substantive response events — track for waiting_input termination gating
 SUBSTANTIVE_EVENTS = {
-    S2CEvent.SESSION_TEXT, S2CEvent.SESSION_FORM_TO_USER,
+    S2CEvent.SESSION_TEXT, S2CEvent.SESSION_TEXT_PART,
+    S2CEvent.SESSION_FORM_TO_USER,
     S2CEvent.SESSION_ASK_FOR_LOCATION, S2CEvent.SESSION_TASK_READY,
     S2CEvent.SESSION_TASK_FINISHED, S2CEvent.SESSION_INTERACTIVE_AUTH_CONFIRMATION,
     S2CEvent.SESSION_THREE_WAY_CALL, S2CEvent.SESSION_REWARD,
@@ -44,33 +39,18 @@ class ChatEvent:
         return f"ChatEvent(type={self.type!r}, session_id={self.session_id!r})"
 
 
-class TextPartBuffer:
-    """Buffer text_part chunks per message_id, flush on final: true."""
-
-    def __init__(self) -> None:
-        self._parts: dict[str, list[str]] = {}
-
-    def collect(self, message_id: str, content: str, final: bool) -> Optional[str]:
-        if message_id not in self._parts:
-            self._parts[message_id] = []
-        if content:
-            self._parts[message_id].append(content)
-        if final:
-            merged = "".join(self._parts.pop(message_id, []))
-            return merged
-        return None
-
-
 class ChatEngine:
     def __init__(
         self,
         sio: SocketIOManager,
         check_session_state: Optional[Callable[[str], Coroutine[Any, Any, dict[str, Any]]]] = None,
         idle_timeout_s: float = DEFAULT_IDLE_TIMEOUT_S,
+        response_idle_timeout_s: float = DEFAULT_RESPONSE_IDLE_TIMEOUT_S,
     ):
         self._sio = sio
         self._check_session_state = check_session_state
         self._idle_timeout_s = idle_timeout_s
+        self._response_idle_timeout_s = response_idle_timeout_s
 
     async def join_session(self, session_id: str) -> dict[str, Any]:
         """Join a session room — spec 5.1.1.
@@ -117,14 +97,32 @@ class ChatEngine:
         """Send a message and yield events with stream buffering.
         Production handler reads payload.data as {content, attachments, ...}.
         """
+        cutoff = datetime.now(timezone.utc) - timedelta(seconds=5)
         self._sio.emit(
             C2SEvent.SESSION_MESSAGE,
             self._build_message_data(content, attachments, referenced_sessions, action),
             session_id,
         )
-        async for event in self._listen(session_id):
+        async for event in self._listen(session_id, _skip_state_precheck=True):
+            if self._is_stale_event(event, cutoff):
+                continue
             yield event
 
+    @staticmethod
+    def _is_stale_event(event: "ChatEvent", cutoff: datetime) -> bool:
+        """Return True if the event's metadata timestamp predates the cutoff."""
+        meta = event.metadata
+        if not isinstance(meta, dict):
+            return False
+        ts_str = meta.get("timestamp")
+        if not ts_str:
+            return False
+        try:
+            event_ts = datetime.fromisoformat(ts_str.replace("Z", "+00:00"))
+            return event_ts < cutoff
+        except (ValueError, TypeError):
+            return False
+
     def send_message(
         self,
         session_id: str,
@@ -141,10 +139,11 @@ class ChatEngine:
             session_id,
         )
 
-    async def _listen(self, session_id: str) -> AsyncGenerator[ChatEvent, None]:
-        """Listen for events with stream buffering."""
-        # Check session state before entering loop — don't hang on completed sessions
-        if self._check_session_state:
+    async def _listen(
+        self, session_id: str, *, _skip_state_precheck: bool = False,
+    ) -> AsyncGenerator[ChatEvent, None]:
+        """Listen for events — all events dispatched immediately."""
+        if not _skip_state_precheck and self._check_session_state:
             try:
                 session = await self._check_session_state(session_id)
                 if session.get("state") in TERMINAL_STATES:
@@ -153,79 +152,31 @@ class ChatEngine:
             except Exception:
                 pass  # best effort
 
-        text_buffer = TextPartBuffer()
         queue: asyncio.Queue[Optional[ChatEvent]] = asyncio.Queue()
         done = False
         received_agent_response = False
 
-        # Work log debounce state
-        wl_timers: dict[str, asyncio.TimerHandle] = {}
-        wl_buffers: dict[str, dict[str, Any]] = {}
-
-        def flush_wl(step_id: str) -> None:
-            buf = wl_buffers.pop(step_id, None)
-            wl_timers.pop(step_id, None)
-            if buf:
-                queue.put_nowait(ChatEvent(
-                    type=S2CEvent.SESSION_WORK_LOG_PART,
-                    session_id=session_id,
-                    data={"step_id": step_id, "text": buf.get("text", ""), "status": buf.get("status")},
-                ))
-
         def handler(event: str, raw: dict[str, Any]) -> None:
-            nonlocal done
+            nonlocal done, received_agent_response
             payload = raw.get("payload", {})
             p_session_id = payload.get("session_id")
             if p_session_id and p_session_id != session_id:
-                return  # Not our session — other handlers will process it
-
-            message_id = payload.get("message_id")
-            data = payload.get("data")
-            metadata = raw.get("metadata")
-
-            # Tier 1: text_part
-            if event == S2CEvent.SESSION_TEXT_PART:
-                if isinstance(data, dict):
-                    content = data.get("content", "")
-                    final = data.get("final", False)
-                    merged = text_buffer.collect(message_id or "unknown", content, final)
-                    if merged is not None:
-                        queue.put_nowait(ChatEvent(
-                            type=S2CEvent.SESSION_TEXT, session_id=session_id,
-                            message_id=message_id, data={"content": merged}, metadata=metadata,
-                        ))
-                return
-
-            # Tier 3: work_log_part debounce
-            if event == S2CEvent.SESSION_WORK_LOG_PART:
-                if isinstance(data, dict):
-                    step_id = data.get("step_id", "unknown")
-                    existing = wl_buffers.get(step_id, {"text": ""})
-                    existing["text"] = existing.get("text", "") + (data.get("text_delta", "") or "")
-                    if data.get("status"):
-                        existing["status"] = data["status"]
-                    wl_buffers[step_id] = existing
-                    old_timer = wl_timers.pop(step_id, None)
-                    if old_timer:
-                        old_timer.cancel()
-                    loop = asyncio.get_running_loop()
-                    wl_timers[step_id] = loop.call_later(3.0, flush_wl, step_id)
                 return
 
-            # All other events: dispatch immediately (pass-through for agent)
-            nonlocal received_agent_response
             queue.put_nowait(ChatEvent(
                 type=event, session_id=session_id,
-                message_id=message_id, data=data, metadata=metadata,
+                message_id=payload.get("message_id"),
+                data=payload.get("data"),
+                metadata=raw.get("metadata"),
             ))
             if event in SUBSTANTIVE_EVENTS:
                 received_agent_response = True
-            if event == S2CEvent.SESSION_INPUT_STATE and isinstance(data, dict):
-                if data.get("content") == "waiting_input" and received_agent_response:
+            if event == S2CEvent.SESSION_INPUT_STATE and isinstance(payload.get("data"), dict):
+                if payload["data"].get("content") == "waiting_input" and received_agent_response:
                     done = True
                     queue.put_nowait(None)
-            if event == S2CEvent.SESSION_STATE and isinstance(data, dict):
-                state = data.get("content", "")
+            if event == S2CEvent.SESSION_STATE and isinstance(payload.get("data"), dict):
+                state = payload["data"].get("content", "")
                 if state in TERMINAL_STATES:
                     done = True
                     queue.put_nowait(None)
@@ -234,10 +185,12 @@ class ChatEngine:
 
         try:
             while not done:
+                timeout = self._response_idle_timeout_s if received_agent_response else self._idle_timeout_s
                 try:
-                    evt = await asyncio.wait_for(queue.get(), timeout=self._idle_timeout_s)
+                    evt = await asyncio.wait_for(queue.get(), timeout=timeout)
                 except asyncio.TimeoutError:
-                    # Idle timeout — check session state via REST
+                    if received_agent_response:
+                        break
                     if self._check_session_state:
                         try:
                             session = await self._check_session_state(session_id)
@@ -255,8 +208,6 @@ class ChatEngine:
                 if evt is not None:
                     yield evt
         finally:
-            for t in wl_timers.values():
-                t.cancel()
             remove_handler()
 
     def send_form_response(self, session_id: str, message_id: str, form_data: dict[str, Any]) -> None:

{pine_assistant-0.2.0 → pine_assistant-0.3.1}/src/pine_assistant/client.py

@@ -158,6 +158,39 @@ class AsyncPineAI:
         async for event in self._chat._listen(session_id):  # type: ignore[union-attr]
             yield event
 
+    async def subscribe(self, session_id: str) -> AsyncGenerator[ChatEvent, None]:
+        """Persistent event stream for a session — yields events indefinitely.
+
+        Unlike listen(), this never terminates on terminal states or timeouts.
+        Designed for bidirectional REPL use where sending and receiving are
+        concurrent.
+        """
+        self._ensure_connected()
+        queue: asyncio.Queue[ChatEvent] = asyncio.Queue()
+
+        def _handler(event_type: str, raw: dict[str, Any]) -> None:
+            payload = raw.get("payload", {})
+            p_sid = payload.get("session_id")
+            if p_sid and p_sid != session_id:
+                return
+            queue.put_nowait(ChatEvent(
+                type=event_type,
+                session_id=session_id,
+                message_id=payload.get("message_id"),
+                data=payload.get("data"),
+                metadata=raw.get("metadata"),
+            ))
+
+        remove = self._sio.add_event_handler(_handler)  # type: ignore[union-attr]
+        try:
+            while self.connected:
+                try:
+                    yield await asyncio.wait_for(queue.get(), timeout=5.0)
+                except asyncio.TimeoutError:
+                    continue
+        finally:
+            remove()
+
     async def create_and_chat(self, content: str) -> AsyncGenerator[ChatEvent, None]:
         """Convenience: create session, join, chat, return events."""
         session = await self.sessions.create()

{pine_assistant-0.2.0 → pine_assistant-0.3.1/src/pine_assistant.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pine-assistant
-Version: 0.2.0
+Version: 0.3.1
 Summary: Pine AI SDK — Let Pine AI handle your digital chores. Socket.IO + REST client.
 Author: Pine AI
 License-Expression: MIT
@@ -20,7 +20,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: python-socketio[asyncio]>=5.11.0
+Requires-Dist: python-socketio>=5.11.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic>=2.0.0
 Provides-Extra: cli

{pine_assistant-0.2.0 → pine_assistant-0.3.1}/src/pine_assistant.egg-info/SOURCES.txt

@@ -31,4 +31,5 @@ src/pine_assistant/transport/__init__.py
 src/pine_assistant/transport/envelope.py
 src/pine_assistant/transport/http.py
 src/pine_assistant/transport/socketio.py
-tests/test_basics.py
+tests/test_basics.py
+tests/test_chat_engine.py

{pine_assistant-0.2.0 → pine_assistant-0.3.1}/src/pine_assistant.egg-info/requires.txt

@@ -1,4 +1,4 @@
-python-socketio[asyncio]>=5.11.0
+python-socketio>=5.11.0
 httpx>=0.27.0
 pydantic>=2.0.0
 

pine_assistant-0.3.1/tests/test_chat_engine.py

@@ -0,0 +1,194 @@
+"""Unit tests for ChatEngine — immediate dispatch, stale-event filtering, state precheck."""
+
+import asyncio
+from datetime import datetime, timedelta, timezone
+from unittest.mock import MagicMock
+
+import pytest
+
+from pine_assistant.chat import ChatEngine, ChatEvent
+from pine_assistant.models.events import S2CEvent
+
+
+def _make_sio():
+    sio = MagicMock()
+    sio.connected = True
+    sio.emit = MagicMock()
+    sio.add_event_handler = MagicMock(return_value=lambda: None)
+    return sio
+
+
+def _ts_iso(dt: datetime) -> str:
+    return dt.isoformat().replace("+00:00", "Z")
+
+
+def _inject_events(sio, session_id, events, delay=0.05):
+    """Replace add_event_handler so it injects events after a short delay."""
+    def fake_add_handler(handler):
+        async def _inject():
+            await asyncio.sleep(delay)
+            for evt_type, raw in events:
+                handler(evt_type, raw)
+        asyncio.get_running_loop().create_task(_inject())
+        return lambda: None
+    sio.add_event_handler = fake_add_handler
+
+
+def _raw(event_type, session_id, data, ts=None):
+    """Build a raw server envelope."""
+    meta = {}
+    if ts:
+        meta["timestamp"] = ts
+    return (event_type, {
+        "payload": {"session_id": session_id, "data": data},
+        "metadata": meta,
+    })
+
+
+# ── _is_stale_event ──────────────────────────────────────────────────────
+
+class TestIsStaleEvent:
+    def test_old_event_is_stale(self):
+        cutoff = datetime(2026, 2, 21, 10, 0, 0, tzinfo=timezone.utc)
+        event = ChatEvent(
+            type=S2CEvent.SESSION_WORK_LOG, session_id="s1", data={},
+            metadata={"timestamp": "2026-02-20T09:00:00Z"},
+        )
+        assert ChatEngine._is_stale_event(event, cutoff) is True
+
+    def test_fresh_event_passes(self):
+        cutoff = datetime(2026, 2, 21, 10, 0, 0, tzinfo=timezone.utc)
+        event = ChatEvent(
+            type=S2CEvent.SESSION_TEXT, session_id="s1", data={},
+            metadata={"timestamp": "2026-02-21T10:00:05Z"},
+        )
+        assert ChatEngine._is_stale_event(event, cutoff) is False
+
+    def test_no_metadata_passes(self):
+        cutoff = datetime(2026, 2, 21, 10, 0, 0, tzinfo=timezone.utc)
+        event = ChatEvent(type=S2CEvent.SESSION_WORK_LOG_PART, session_id="s1", data={})
+        assert ChatEngine._is_stale_event(event, cutoff) is False
+
+    def test_missing_timestamp_passes(self):
+        cutoff = datetime(2026, 2, 21, 10, 0, 0, tzinfo=timezone.utc)
+        event = ChatEvent(
+            type=S2CEvent.SESSION_WORK_LOG, session_id="s1", data={},
+            metadata={"source": {"role": "agent"}},
+        )
+        assert ChatEngine._is_stale_event(event, cutoff) is False
+
+    def test_malformed_timestamp_passes(self):
+        cutoff = datetime(2026, 2, 21, 10, 0, 0, tzinfo=timezone.utc)
+        event = ChatEvent(
+            type=S2CEvent.SESSION_WORK_LOG, session_id="s1", data={},
+            metadata={"timestamp": "not-a-date"},
+        )
+        assert ChatEngine._is_stale_event(event, cutoff) is False
+
+
+# ── immediate dispatch (no buffering) ─────────────────────────────────────
+
+class TestImmediateDispatch:
+    @pytest.mark.asyncio
+    async def test_text_part_dispatched_immediately(self):
+        """text_part events are yielded as-is, not buffered."""
+        sio = _make_sio()
+        now = _ts_iso(datetime.now(timezone.utc))
+
+        _inject_events(sio, "s1", [
+            _raw(S2CEvent.SESSION_TEXT_PART, "s1", {"content": "Hello "}, ts=now),
+            _raw(S2CEvent.SESSION_TEXT_PART, "s1", {"content": "world"}, ts=now),
+            _raw(S2CEvent.SESSION_STATE, "s1", {"content": "task_finished"}, ts=now),
+        ])
+
+        engine = ChatEngine(sio, idle_timeout_s=5.0)
+        events = []
+        async for event in engine._listen("s1", _skip_state_precheck=True):
+            events.append(event)
+
+        types = [e.type for e in events]
+        assert types.count(S2CEvent.SESSION_TEXT_PART) == 2
+        assert events[0].data["content"] == "Hello "
+        assert events[1].data["content"] == "world"
+
+    @pytest.mark.asyncio
+    async def test_work_log_part_dispatched_immediately(self):
+        """work_log_part events are yielded immediately, not debounced."""
+        sio = _make_sio()
+        now = _ts_iso(datetime.now(timezone.utc))
+
+        _inject_events(sio, "s1", [
+            _raw(S2CEvent.SESSION_WORK_LOG_PART, "s1",
+                 {"step_id": "1", "text_delta": "thinking..."}, ts=now),
+            _raw(S2CEvent.SESSION_STATE, "s1", {"content": "task_finished"}, ts=now),
+        ])
+
+        engine = ChatEngine(sio, idle_timeout_s=5.0)
+        events = []
+        async for event in engine._listen("s1", _skip_state_precheck=True):
+            events.append(event)
+
+        types = [e.type for e in events]
+        assert S2CEvent.SESSION_WORK_LOG_PART in types
+
+
+# ── chat() stale filtering ───────────────────────────────────────────────
+
+class TestChatStaleFiltering:
+    @pytest.mark.asyncio
+    async def test_chat_filters_old_events(self):
+        sio = _make_sio()
+        old_ts = _ts_iso(datetime.now(timezone.utc) - timedelta(hours=24))
+        fresh_ts = _ts_iso(datetime.now(timezone.utc) + timedelta(seconds=1))
+
+        _inject_events(sio, "s1", [
+            _raw(S2CEvent.SESSION_WORK_LOG, "s1",
+                 {"steps": [{"step_title": "old"}]}, ts=old_ts),
+            _raw(S2CEvent.SESSION_TEXT_PART, "s1", {"content": "Hi!"}, ts=fresh_ts),
+            _raw(S2CEvent.SESSION_STATE, "s1", {"content": "task_finished"}, ts=fresh_ts),
+        ])
+
+        engine = ChatEngine(sio, idle_timeout_s=5.0)
+        events = []
+        async for event in engine.chat("s1", "test"):
+            events.append(event)
+
+        types = [e.type for e in events]
+        assert S2CEvent.SESSION_WORK_LOG not in types
+        assert S2CEvent.SESSION_TEXT_PART in types
+
+
+# ── _listen with _skip_state_precheck ─────────────────────────────────────
+
+class TestListenSkipStatePrecheck:
+    @pytest.mark.asyncio
+    async def test_listen_without_skip_returns_on_terminal(self):
+        sio = _make_sio()
+
+        async def _check(_sid):
+            return {"state": "task_finished"}
+
+        engine = ChatEngine(sio, check_session_state=_check)
+        events = [e async for e in engine._listen("s1")]
+
+        assert len(events) == 1
+        assert events[0].data["content"] == "task_finished"
+
+    @pytest.mark.asyncio
+    async def test_listen_with_skip_enters_event_loop(self):
+        sio = _make_sio()
+        now = _ts_iso(datetime.now(timezone.utc))
+
+        async def _check(_sid):
+            return {"state": "task_finished"}
+
+        _inject_events(sio, "s1", [
+            _raw(S2CEvent.SESSION_TEXT_PART, "s1", {"content": "response"}, ts=now),
+            _raw(S2CEvent.SESSION_STATE, "s1", {"content": "task_finished"}, ts=now),
+        ])
+
+        engine = ChatEngine(sio, check_session_state=_check, idle_timeout_s=5.0)
+        events = [e async for e in engine._listen("s1", _skip_state_precheck=True)]
+
+        types = [e.type for e in events]
+        assert S2CEvent.SESSION_TEXT_PART in types