praisonai-bot 0.0.2__tar.gz

praisonai_bot-0.0.2/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: praisonai-bot
+Version: 0.0.2
+Summary: Bots, gateway, and channel CLI for PraisonAI — messaging platforms and WebSocket control plane extracted from the praisonai wrapper.
+Author: Mervin Praison
+License: MIT
+Project-URL: Homepage, https://docs.praison.ai
+Project-URL: Repository, https://github.com/mervinpraison/PraisonAI
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: praisonaiagents>=1.6.117
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12.0
+Requires-Dist: click>=8.4.2
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: aiohttp>=3.8.0
+Provides-Extra: gateway
+Requires-Dist: fastapi>=0.115.0; extra == "gateway"
+Requires-Dist: uvicorn>=0.34.0; extra == "gateway"
+Requires-Dist: sse-starlette>=1.6.0; extra == "gateway"
+Requires-Dist: websockets>=12.0; extra == "gateway"
+Requires-Dist: watchdog>=3.0.0; extra == "gateway"
+Requires-Dist: redis>=5.0.0; extra == "gateway"
+Provides-Extra: bot
+Requires-Dist: python-telegram-bot>=20.0; extra == "bot"
+Requires-Dist: discord.py>=2.0.0; extra == "bot"
+Requires-Dist: slack_sdk>=3.0.0; extra == "bot"
+Requires-Dist: slack-bolt>=1.18.0; extra == "bot"
+Requires-Dist: brotlicffi>=1.0.0; extra == "bot"
+Requires-Dist: psutil>=5.9.0; extra == "bot"
+Requires-Dist: ddgs>=9.0.0; extra == "bot"
+Provides-Extra: bot-whatsapp-web
+Requires-Dist: neonize>=0.3.14; extra == "bot-whatsapp-web"
+Requires-Dist: qrcode>=7.0; extra == "bot-whatsapp-web"
+Provides-Extra: all
+Requires-Dist: praisonai-bot[bot,gateway]; extra == "all"
+
+# praisonai-bot
+
+Bots, gateway, and channel CLI for PraisonAI.
+
+```bash
+pip install praisonai-bot[gateway,bot]
+praisonai-bot gateway start --config gateway.yaml
+praisonai-bot bot start --config bot.yaml
+```
+
+Protocols live in `praisonaiagents`; this package holds platform adapters and the WebSocket gateway server.

praisonai_bot-0.0.2/README.md

@@ -0,0 +1,11 @@
+# praisonai-bot
+
+Bots, gateway, and channel CLI for PraisonAI.
+
+```bash
+pip install praisonai-bot[gateway,bot]
+praisonai-bot gateway start --config gateway.yaml
+praisonai-bot bot start --config bot.yaml
+```
+
+Protocols live in `praisonaiagents`; this package holds platform adapters and the WebSocket gateway server.

praisonai_bot-0.0.2/praisonai_bot/__init__.py

@@ -0,0 +1,24 @@
+"""PraisonAI bots and gateway runtime package."""
+
+from __future__ import annotations
+
+__version__ = "0.0.1"
+
+_LAZY_EXPORTS = {
+    "Bot": ("praisonai_bot.bots.bot", "Bot"),
+    "BotOS": ("praisonai_bot.bots.botos", "BotOS"),
+    "WebSocketGateway": ("praisonai_bot.gateway.server", "WebSocketGateway"),
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_EXPORTS:
+        mod_path, attr = _LAZY_EXPORTS[name]
+        import importlib
+
+        mod = importlib.import_module(mod_path)
+        return getattr(mod, attr)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["Bot", "BotOS", "WebSocketGateway", "__version__"]

praisonai_bot-0.0.2/praisonai_bot/__main__.py

@@ -0,0 +1,18 @@
+"""Console entry: ``praisonai-bot``."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> None:
+    from praisonai_bot.cli.app import app
+
+    args = argv if argv is not None else sys.argv[1:]
+    if not args:
+        args = ["--help"]
+    app(args=args, prog_name="praisonai-bot")
+
+
+if __name__ == "__main__":
+    main()

praisonai_bot-0.0.2/praisonai_bot/_async_bridge.py

@@ -0,0 +1,279 @@
+"""
+Async bridge module - single source of truth for running coroutines synchronously.
+
+This module provides a safe way to run async functions from sync contexts,
+handling nested event loop scenarios without creating a new event loop
+on every call (which is expensive and breaks multi-agent workflows).
+"""
+import asyncio
+import atexit
+import contextlib
+import contextvars
+import os
+import threading
+import concurrent.futures
+from concurrent.futures import CancelledError as FutureCancelledError, Future
+from typing import Awaitable, Iterator, Optional, TypeVar
+
+T = TypeVar("T")
+
+_DEFAULT_TIMEOUT = float(os.environ.get("PRAISONAI_RUN_SYNC_TIMEOUT", "300"))
+
+class AsyncBridge:
+    """Per-instance async runner. The module-level `run_sync()` keeps the
+    historical shared default; embedders/services should construct their own."""
+
+    def __init__(self) -> None:
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._lock = threading.Lock()
+        # Permanently-closed flag. Set by ``shutdown(permanent=True)`` for
+        # scope-owned bridges so a leaked context (e.g. an ``asyncio.Task`` that
+        # copied the ContextVar inside a ``scoped_bridge`` block) cannot silently
+        # resurrect an orphaned loop+thread after the scope exits. The shared
+        # default is never marked permanent so its only teardown is the atexit
+        # hook at process exit.
+        self._closed = False
+        # Identity of the thread currently holding ``self._lock``. Set under the
+        # lock by ``get()``/``submit()`` so ``_spawn_locked()`` can verify the
+        # *caller* (not merely *someone*) owns the lock.
+        self._lock_owner: int | None = None
+
+    def _spawn_locked(self) -> asyncio.AbstractEventLoop:
+        """Create the loop+thread; caller must hold ``self._lock``.
+
+        The thread is marked ``daemon=True`` so that short-lived scripts
+        (e.g. CLI commands, smoke tests) exit cleanly without waiting on
+        the background loop to be shut down explicitly. Long-running
+        server processes should call :meth:`shutdown` explicitly to cancel
+        in-flight tasks before process exit.
+        """
+        # Enforce the "caller must hold the lock" contract. We compare the
+        # recorded lock owner against the current thread so the check detects
+        # both an unlocked lock *and* a lock held by a different thread (a bare
+        # non-blocking acquire could only prove the lock was free for *anyone*).
+        if self._lock_owner != threading.get_ident():
+            raise AssertionError(
+                "_spawn_locked() must be called while holding self._lock"
+            )
+        # Refuse to resurrect a permanently-closed (scope-owned) bridge. This
+        # guards the case where a context copied inside ``scoped_bridge`` outlives
+        # the ``with`` block and later tries to run work through the now-shut-down
+        # bridge: instead of silently starting an orphaned loop+thread that no
+        # scope or atexit hook owns, fail loudly.
+        if self._closed:
+            raise RuntimeError(
+                "AsyncBridge has been shut down and cannot be reused; "
+                "this usually means a context outlived its scoped_bridge() block"
+            )
+        if self._loop is None or self._loop.is_closed():
+            self._loop = asyncio.new_event_loop()
+            self._thread = threading.Thread(
+                target=self._loop.run_forever,
+                name="praisonai-async",
+                daemon=True,
+            )
+            self._thread.start()
+        return self._loop
+
+    def get(self) -> asyncio.AbstractEventLoop:
+        with self._lock:
+            self._lock_owner = threading.get_ident()
+            try:
+                return self._spawn_locked()
+            finally:
+                self._lock_owner = None
+
+    def submit(self, coro):
+        """Atomically (re)spawn loop if needed and submit coro. Returns concurrent.futures.Future."""
+        with self._lock:
+            self._lock_owner = threading.get_ident()
+            try:
+                loop = self._spawn_locked()
+                return asyncio.run_coroutine_threadsafe(coro, loop)
+            finally:
+                self._lock_owner = None
+
+    def run_sync(self, coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) -> T:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+        else:
+            raise RuntimeError(
+                "run_sync() cannot be called from a running event loop"
+            )
+        fut = self.submit(coro)
+        try:
+            return fut.result(timeout=timeout)
+        except (TimeoutError, concurrent.futures.TimeoutError):
+            fut.cancel()
+            try:
+                fut.exception(timeout=1.0)
+            except (
+                TimeoutError,
+                concurrent.futures.TimeoutError,
+                asyncio.CancelledError,
+                FutureCancelledError,
+            ):
+                pass
+            raise
+        except BaseException:
+            fut.cancel()
+            raise
+
+    def shutdown(self, timeout: float = 5.0, *, permanent: bool = False) -> None:
+        """Tear down the loop+thread.
+
+        Args:
+            timeout: Seconds to wait for in-flight tasks to cancel and the
+                background thread to join.
+            permanent: When ``True`` the bridge is marked closed and may not be
+                reused; a later ``run_sync``/``submit`` raises ``RuntimeError``
+                rather than silently resurrecting an orphaned loop. Used by
+                :func:`scoped_bridge` for the bridges it owns. The shared default
+                is shut down with ``permanent=False`` so it never poisons callers.
+        """
+        # Snapshot loop and thread outside lock to avoid holding lock during wait
+        with self._lock:
+            if permanent:
+                self._closed = True
+            loop, thread = self._loop, self._thread
+            if loop is None:
+                return
+            # Clear references immediately to prevent new submissions
+            self._loop = None
+            self._thread = None
+        
+        # Now do the actual shutdown without holding the lock
+        async def _cancel_all() -> None:
+            self_task = asyncio.current_task()
+            tasks = [t for t in asyncio.all_tasks(loop) 
+                     if not t.done() and t is not self_task]
+            for t in tasks:
+                t.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+        
+        try:
+            asyncio.run_coroutine_threadsafe(_cancel_all(), loop).result(timeout)
+        finally:
+            loop.call_soon_threadsafe(loop.stop)
+            if thread is not None:
+                thread.join(timeout)
+            if not loop.is_closed():
+                loop.close()
+
+# Backwards-compatible module-level shared default.
+#
+# The shared bridge's lifecycle is owned exclusively by the process (via the
+# ``atexit`` hook registered on first use). It is intentionally NOT exposed as a
+# public ``shutdown()`` on the module surface: in a multi-agent / multi-tenant
+# process every ``run_sync()`` caller shares this single loop+thread, so allowing
+# any one caller to tear it down would silently cancel in-flight work belonging
+# to every other agent/session. Embedders that need explicit lifecycle control
+# must construct and own their own :class:`AsyncBridge` instance and pass it via
+# dependency injection.
+
+# Single stable shared instance. It is created eagerly (cheap: no loop/thread is
+# spawned until the first ``run_sync()`` call) so the reference never has to be
+# rebound. Keeping the *same* object means callers that captured ``_BG`` always
+# observe its live state, and only the process-exit hook tears it down.
+_BG: AsyncBridge = AsyncBridge()
+
+
+# Context-scoped override. When set (via :func:`scoped_bridge`), callers in that
+# context — and any code they transitively invoke, including async tasks that
+# copy the context — resolve to the scoped bridge instead of the shared default.
+# This lets server/gateway/managed callers bind a per-session loop+thread
+# without rewriting internal modules that import ``run_sync`` directly.
+_bridge_var: contextvars.ContextVar[Optional[AsyncBridge]] = contextvars.ContextVar(
+    "praisonai_async_bridge", default=None
+)
+
+
+def _default_bridge() -> AsyncBridge:
+    """Resolve the active bridge: context-scoped override, else shared default."""
+    scoped = _bridge_var.get()
+    if scoped is not None:
+        return scoped
+    return _BG
+
+
+def current_bridge() -> AsyncBridge:
+    """Return the :class:`AsyncBridge` active in the current context.
+
+    Returns the bridge bound by an enclosing :func:`scoped_bridge` block, or the
+    process-wide shared default when no scope is active. Prefer this over reaching
+    for the module-level ``_BG`` so embedders can override the bridge via
+    dependency injection.
+    """
+    return _default_bridge()
+
+
+@contextlib.contextmanager
+def scoped_bridge(bridge: Optional[AsyncBridge] = None) -> Iterator[AsyncBridge]:
+    """Bind a per-scope :class:`AsyncBridge` for the duration of the ``with`` block.
+
+    Server callers (``praisonai serve``, gateway, managed agents) can isolate a
+    session's sync→async work onto its own loop+thread so a stuck coroutine in one
+    session does not park the shared default loop for every other session::
+
+        with scoped_bridge() as bridge:
+            run_sync(some_coro())   # uses ``bridge`` instead of the global default
+            ...
+        # bridge is shut down automatically on exit when created here.
+
+    Args:
+        bridge: An existing bridge to bind. When ``None`` a fresh bridge is created
+            for the scope and shut down on exit. A caller-provided bridge is left
+            untouched (the caller owns its lifecycle).
+    """
+    owns = bridge is None
+    if bridge is None:
+        bridge = AsyncBridge()
+    token = _bridge_var.set(bridge)
+    try:
+        yield bridge
+    finally:
+        _bridge_var.reset(token)
+        if owns:
+            # ``permanent=True`` poisons the bridge so a context that copied the
+            # ContextVar inside this block cannot resurrect it after we exit.
+            bridge.shutdown(permanent=True)
+
+
+def _shutdown_default() -> None:
+    """Private process-exit hook: tear down the shared default bridge.
+
+    Registered with :mod:`atexit`. This is the ONLY sanctioned way the shared
+    default is shut down; it is deliberately absent from the public module
+    surface so a single caller cannot terminate async work for the whole
+    process. Embedders needing explicit lifecycle control own their own
+    :class:`AsyncBridge` instance.
+    """
+    _BG.shutdown()
+
+
+atexit.register(_shutdown_default)
+
+
+def run_sync(coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) -> T:
+    """
+    Run a coroutine synchronously using the background loop.
+    
+    IMPORTANT: This function cannot be called from within a running event loop
+    as it would cause deadlock. Use 'await coro' directly from async contexts.
+    
+    Args:
+        coro: The coroutine to run
+        timeout: Maximum time to wait for completion (seconds)
+        
+    Returns:
+        The result of the coroutine
+        
+    Raises:
+        RuntimeError: If called from within a running event loop
+        TimeoutError: If timeout is exceeded
+        Any exception raised by the coroutine
+    """
+    return _default_bridge().run_sync(coro, timeout=timeout)

praisonai_bot-0.0.2/praisonai_bot/_bootstrap.py

@@ -0,0 +1,37 @@
+"""Monorepo bootstrap for ``praisonai_bot`` and optional ``praisonai_code``."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def ensure_praisonai_bot() -> None:
+    """Ensure ``praisonai_bot`` is importable in monorepo dev layouts."""
+    try:
+        import praisonai_bot  # noqa: F401
+        return
+    except ImportError:
+        pass
+
+    here = Path(__file__).resolve().parents[1]  # .../src/praisonai-bot
+    if (here / "praisonai_bot").is_dir():
+        root = str(here)
+        if root not in sys.path:
+            sys.path.insert(0, root)
+
+
+def ensure_praisonai_code() -> None:
+    """Optional code-tier imports (tool resolver, llm env) when co-installed."""
+    try:
+        import praisonai_code  # noqa: F401
+        return
+    except ImportError:
+        pass
+
+    bot_src = Path(__file__).resolve().parents[1]
+    code_src = bot_src.parent / "praisonai-code"
+    if (code_src / "praisonai_code").is_dir():
+        root = str(code_src)
+        if root not in sys.path:
+            sys.path.insert(0, root)

praisonai_bot-0.0.2/praisonai_bot/_code_bridge.py

@@ -0,0 +1,28 @@
+"""Lazy access from praisonai-bot to optional praisonai-code modules."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from praisonai_bot._bootstrap import ensure_praisonai_code
+
+
+def code_available() -> bool:
+    ensure_praisonai_code()
+    try:
+        import praisonai_code  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def import_code_module(name: str) -> Any:
+    ensure_praisonai_code()
+    try:
+        return importlib.import_module(name)
+    except ImportError as exc:
+        raise ImportError(
+            f"Optional code module {name!r} requires praisonai-code. "
+            "Install with: pip install praisonai-code"
+        ) from exc

praisonai_bot-0.0.2/praisonai_bot/_lockmap.py

@@ -0,0 +1,142 @@
+"""Per-key asyncio.Lock map with bounded LRU eviction and optional TTL.
+
+Use this anywhere you need 'a lock per (user_id|chat_id|key)' instead of
+re-implementing the dict-of-Lock pattern.
+"""
+from __future__ import annotations
+import asyncio
+import threading
+import time
+import weakref
+from collections import OrderedDict
+from typing import Hashable, Dict
+
+
+class LockMap:
+    """Asyncio-safe per-key asyncio.Lock map with automatic cleanup.
+    
+    Provides a lock per key with LRU eviction and TTL-based cleanup to prevent
+    unbounded memory growth in long-running applications.
+    
+    Buckets are keyed by event loop (one loop per OS thread). Structural
+    mutations of the bucket/loop maps are guarded by a ``threading.Lock`` so
+    the same instance can be safely shared across multiple OS threads, each
+    running its own event loop. Per-loop buckets are only ever touched from
+    their owning loop, so intra-loop access remains lock-free.
+    """
+
+    def __init__(self, *, max_entries: int = 10_000, ttl_seconds: float = 3600.0):
+        """Initialize LockMap with bounds.
+        
+        Args:
+            max_entries: Maximum number of locks to cache (LRU eviction)
+            ttl_seconds: Time-to-live for unused locks in seconds
+        """
+        # Bucket locks by event loop to avoid cross-loop issues
+        self._buckets: Dict[int, "OrderedDict[Hashable, tuple[asyncio.Lock, float]]"] = {}
+        self._loop_refs: Dict[int, weakref.ref] = {}
+        # Guards structural mutations of _buckets / _loop_refs across OS threads.
+        self._struct_lock = threading.Lock()
+        self._max = max_entries
+        self._ttl = ttl_seconds
+
+    def get(self, key: Hashable) -> asyncio.Lock:
+        """Get or create a lock for the given key.
+        
+        Args:
+            key: The key to get a lock for
+            
+        Returns:
+            asyncio.Lock for the key
+        """
+        # Get the current running loop
+        loop = asyncio.get_running_loop()
+        loop_id = id(loop)
+
+        # Fast path: a bucket for this loop already exists. The bucket is only
+        # ever mutated by its owning loop's thread, so a single dict read is
+        # safe under CPython's GIL without taking the cross-thread struct lock.
+        bucket = self._buckets.get(loop_id)
+        if bucket is None:
+            # Slow path: structural mutation shared across threads needs the lock.
+            with self._struct_lock:
+                # Clean up dead loops (only on first-touch to avoid per-call cost)
+                self._cleanup_dead_loops_locked()
+
+                # Re-check after acquiring the lock (another thread may have raced).
+                bucket = self._buckets.get(loop_id)
+                if bucket is None:
+                    bucket = OrderedDict()
+                    self._buckets[loop_id] = bucket
+                    self._loop_refs[loop_id] = weakref.ref(loop)
+
+        # From here on only this loop's owning thread touches the bucket.
+        now = time.monotonic()
+        
+        entry = bucket.get(key)
+        if entry is not None:
+            lock, _ = entry
+            # Move to end (most recently used) and update timestamp
+            bucket.move_to_end(key)
+            bucket[key] = (lock, now)
+            return lock
+        
+        # Create new lock + insert + LRU/TTL evict
+        lock = asyncio.Lock()
+        bucket[key] = (lock, now)
+        self._evict_stale_from_bucket(bucket, now)
+        return lock
+
+    def _evict_stale_from_bucket(self, bucket: "OrderedDict", now: float) -> None:
+        """Evict expired and excess entries from a bucket."""
+        # Expire by TTL (only if not currently locked)
+        expired = [
+            k for k, (lock, ts) in bucket.items()
+            if (now - ts) > self._ttl and not lock.locked()
+        ]
+        for k in expired:
+            bucket.pop(k, None)
+        
+        # Cap by LRU (don't evict locks currently held)
+        seen = set()
+        while len(bucket) > self._max:
+            k, (lock, _) = next(iter(bucket.items()))
+            if k in seen:
+                # All remaining locks are held; give up to avoid infinite loop
+                break
+            if lock.locked():
+                # Don't evict locks currently held; bump them to the end
+                bucket.move_to_end(k)
+                seen.add(k)
+                # Continue trying to evict other unlocked entries
+                continue
+            bucket.popitem(last=False)
+    
+    def _cleanup_dead_loops_locked(self) -> None:
+        """Remove buckets for event loops that no longer exist.
+
+        Caller must hold ``self._struct_lock``.
+        """
+        dead_loops = [
+            loop_id
+            for loop_id, ref in self._loop_refs.items()
+            if (loop := ref()) is None or loop.is_closed()
+        ]
+        for loop_id in dead_loops:
+            self._loop_refs.pop(loop_id, None)
+            self._buckets.pop(loop_id, None)
+
+    def drop(self, key: Hashable) -> None:
+        """Manually remove a lock for the given key."""
+        # Get the current running loop
+        loop = asyncio.get_running_loop()
+        loop_id = id(loop)
+        with self._struct_lock:
+            bucket = self._buckets.get(loop_id)
+        if bucket is not None:
+            bucket.pop(key, None)
+
+    def size(self) -> int:
+        """Return current number of cached locks across all buckets."""
+        with self._struct_lock:
+            return sum(len(bucket) for bucket in self._buckets.values())

praisonai_bot-0.0.2/praisonai_bot/_registry.py

@@ -0,0 +1,22 @@
+"""Plugin registry base for praisonai-bot (lazy code-bridge import)."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from praisonai_code._registry import PluginRegistry, create_lazy_getattr
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["PluginRegistry", "create_lazy_getattr", "logger"]
+
+
+def __getattr__(name: str):
+    if name in ("PluginRegistry", "create_lazy_getattr"):
+        from praisonai_bot._code_bridge import import_code_module
+
+        registry = import_code_module("praisonai_code._registry")
+        return getattr(registry, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

praisonai_bot-0.0.2/praisonai_bot/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

praisonai_bot-0.0.2/praisonai_bot/_wrapper_bridge.py

@@ -0,0 +1,31 @@
+"""Lazy access from praisonai-bot to optional praisonai wrapper modules."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any, Optional
+
+
+def wrapper_available() -> bool:
+    try:
+        import praisonai  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def import_wrapper_module(name: str) -> Any:
+    if not wrapper_available():
+        raise ImportError(
+            f"Optional wrapper module {name!r} requires the praisonai package. "
+            "Install with: pip install praisonai"
+        )
+    return importlib.import_module(name)
+
+
+def optional_wrapper_attr(module: str, attr: str, default: Any = None) -> Any:
+    try:
+        mod = import_wrapper_module(module)
+        return getattr(mod, attr)
+    except ImportError:
+        return default