wanbot 0.0.1__tar.gz

wanbot-0.0.1/.gitignore

@@ -0,0 +1,25 @@
+.assets
+.env
+*.pyc
+dist/
+build/
+docs/
+*.egg-info/
+*.egg
+*.pyc
+*.pyo
+*.pyd
+*.pyw
+*.pyz
+*.pywz
+*.pyzz
+.venv/
+__pycache__/
+poetry.lock
+.pytest_cache/
+tests/
+botpy.log
+.idea/
+uv.lock
+.idea/
+.ruff_cache/

wanbot-0.0.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: wanbot
+Version: 0.0.1
+Summary: A personal AI assistant framework.
+Requires-Python: >=3.12
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: typer>=0.24.1

wanbot-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "wanbot"
+version = "0.0.1"
+description = "A personal AI assistant framework."
+requires-python = ">=3.12"
+dependencies = [
+    "loguru>=0.7.3",
+    "pydantic>=2.12.5",
+    "typer>=0.24.1",
+]
+
+
+
+
+[project.scripts]
+wanbot = "wanbot.cli.commands:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.ruff]
+line-length = 110
+target-version = "py312"
+
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.15.8",
+]

wanbot-0.0.1/wanbot/__main__.py

@@ -0,0 +1,4 @@
+from wanbot.cli.commands import app
+
+if __name__ == '__main__':
+    app()

wanbot-0.0.1/wanbot/__version__.py

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

wanbot-0.0.1/wanbot/agent/loop.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+from wanbot.bus import MessageBus
+
+
+class AgentLoop:
+    """
+    Core process engine
+    It:
+    1. Receives messages from the bus
+    2. Builds context with history, memory, skills
+    3. Call the LLM
+    4. Execute tool calls
+    4. Sends responses back
+    """
+
+    _TOOL_RESULT_MAX_CHARS = 16_000
+
+    def __init__(
+            self,
+            bus: MessageBus,
+            provider: LLMProvider,
+            workspace: Path,
+            model: str | None = None,
+            max_iterations: int | None = 50,
+            context_window_tokens: int | None = 65536,
+    ):
+        pass

wanbot-0.0.1/wanbot/bus/__init__.py

@@ -0,0 +1,4 @@
+from wanbot.bus.events import InboundMessage, OutboundMessage
+from wanbot.bus.queue import MessageBus
+
+__all__ = ["MessageBus","InboundMessage","OutboundMessage"]

wanbot-0.0.1/wanbot/bus/events.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class InboundMessage:
+    channel: str  # weixin, feishu
+    sender_id: str  # User identifier
+    chat_id: str  # Chat/Channel identifier
+    content: str  # Message text
+    timestamp: datetime = field(default_factory=datetime.now)
+    media: list[str] = field(default_factory=list)  # Media urls
+    metadata: dict[str, Any] = field(default_factory=dict)  # Channel-specific data
+    session_key_override: str | None = None  # Optional override for thread_scoped sessions
+
+    @property
+    def session_key(self) -> str:
+        """Unique key for session identification."""
+        return self.session_key_override or f"{self.channel}:{self.chat_id}"
+
+
+@dataclass
+class OutboundMessage:
+    channel: str
+    chat_id: str
+    content: str
+    reply_to: str | None = None
+    media: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)

wanbot-0.0.1/wanbot/bus/queue.py

@@ -0,0 +1,39 @@
+import asyncio
+
+from wanbot.bus.events import InboundMessage, OutboundMessage
+
+
+class MessageBus:
+    """
+    Async messages bus that decouples chat channels from the agent core.
+
+    Channel push messages to the inbound queue, and the agent process them and pushes responses to the outbound queue.
+    """
+
+    def __init__(self):
+        self.inbound: asyncio.Queue[InboundMessage] = asyncio.Queue()
+        self.outbound: asyncio.Queue[OutboundMessage] = asyncio.Queue()
+
+    async def publish_inbound(self, msg: InboundMessage) -> None:
+        await self.inbound.put(msg)
+
+    async def consume_inbound(self) -> InboundMessage:
+        """Consume the next inbound message (blocks until available)."""
+        return await self.inbound.get()
+
+    async def publish_outbound(self, msg: OutboundMessage) -> None:
+        await self.outbound.put(msg)
+
+    async def consume_outbound(self) -> OutboundMessage:
+        """Consume the next outbound message (blocks until available)."""
+        return await self.outbound.get()
+
+    @property
+    def inbound_size(self) -> int:
+        """Number of pending inbound messages."""
+        return self.inbound.qsize()
+
+    @property
+    def outbound_size(self) -> int:
+        """Number of pending outbound messages."""
+        return self.outbound.qsize()

wanbot-0.0.1/wanbot/channels/__init__.py

@@ -0,0 +1,4 @@
+from wanbot.channels.base import BaseChannel
+from wanbot.channels.manager import ChannelManager
+
+__all__ = ["BaseChannel", "ChannelManager"]

wanbot-0.0.1/wanbot/channels/base.py

@@ -0,0 +1,149 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from wanbot.bus import InboundMessage, MessageBus, OutboundMessage
+
+
+class BaseChannel(ABC):
+    """
+    Abstract base class for chat channel implementations.
+    Each channel should implement this interface to integrate with wanbot message bus.
+    """
+
+    name: str = "base"
+    display_name: str = "Base"
+    transcription_api_key: str = ""
+
+    def __init__(self, config: Any, bus: MessageBus):
+        self.config = config
+        self.bus = bus
+        self._running = False
+
+    async def transcribe_audio(self, file_path: str | Path) -> str:
+        """
+        Transcribe an audio file via Groq Whisper.
+        Return empty string on failure.
+        """
+        if not self.transcription_api_key:
+            return ""
+        try:
+            from wanbot.providers.transcription import GroqTranscriptionProvider
+
+            provider = GroqTranscriptionProvider(api_key=self.transcription_api_key)
+            return await provider.transcribe(file_path)
+        except Exception as e:
+            logger.warning(f"{self.name}: audio transcription failed: {e}")
+            return ""
+
+    async def login(self, force: bool = False) -> bool:
+        """
+        Perform channel-specific interactive login. (e.g. QR code scan).
+
+        Returns True if already authenticated or login succeed.
+        Override in subclass that support interactive login.
+        """
+        return True
+
+    @abstractmethod
+    async def start(self) -> None:
+        """
+        Start the channel and begin listening for messages.
+        This should be a long-running async task that:
+        1. Connects to the chat platform.
+        2. Listens for incoming messages.
+        3. Forwards messages to the bus via _handle_message().
+        """
+        pass
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the channel and clean up resources."""
+        pass
+
+    @abstractmethod
+    async def send(self, message: OutboundMessage) -> None:
+        """Send message through this channel"""
+        pass
+
+    async def send_delta(
+        self, chat_id: str, delta: str, metadata: dict[str, Any] | None = None
+    ) -> None:
+        """Deliver a streaming next chunk.
+        Override in subclass to enable streaming.
+        Implementations should raise on delivery failure so the channel manager can retry.
+
+        Streaming contract: `_stream_delta` is chunk, `_stream_end` ends the current segment,and stateful implementations must key buffers by `stream_id` rather than only by `chat_id`.
+        """
+        pass
+
+    @property
+    def supports_streaming(self) -> bool:
+        cfg = self.config
+        streaming = (
+            cfg.get("streaming", False)
+            if isinstance(cfg, dict)
+            else getattr(cfg, "streaming", False)
+        )
+        return bool(streaming) and type(self).send_delta is not BaseChannel.send_delta
+
+    def is_allowed(self, sender_id: str) -> bool:
+        """Check if *sender_id* is permitted.
+        Empty list -> deny all; ``*`` -> allow all.
+        """
+        allow_list = getattr(self.config, "allow_from", [])
+        if not allow_list:
+            logger.warning(f"{self.name}: allow_from is empty - all access denied.")
+            return False
+        if "*" in allow_list:
+            return True
+        return str(sender_id) in allow_list
+
+    async def _handle_message(
+        self,
+        sender_id: str,
+        chat_id: str,
+        content: str,
+        media: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        session_key: str | None = None,
+    ) -> None:
+        """
+        Handle an income message from the chat flatform
+        This method checks permissions and forwards the bus
+        """
+
+        if not self.is_allowed(sender_id):
+            logger.warning(
+                f"Access denied for sender {sender_id} on channel {self.name}."
+                "Add them to allowFrom list in config to grant access."
+            )
+            return
+
+        meta = metadata or {}
+
+        if self.supports_streaming:
+            meta = {**meta, "_want_stream": True}
+
+        msg = InboundMessage(
+            channel=self.name,
+            sender_id=sender_id,
+            chat_id=chat_id,
+            content=content,
+            media=media,
+            metadata=meta,
+            session_key_override=session_key,
+        )
+
+        await self.bus.publish_inbound(msg)
+
+    @classmethod
+    def default_config(cls) -> dict[str, Any]:
+        """Return default config for onboard. Override in plugins to auto-populate config.json"""
+        return {"enabled": False}
+
+    @property
+    def is_running(self) -> bool:
+        return self._running

wanbot-0.0.1/wanbot/channels/manager.py

@@ -0,0 +1,205 @@
+"""Channel Manager"""
+
+import asyncio
+
+from loguru import logger
+
+from wanbot.bus import MessageBus, OutboundMessage
+from wanbot.channels import BaseChannel
+from wanbot.config.schema import Config
+
+
+class ChannelManager:
+    """
+    Manages chat channels and coordinates message routing.
+
+    Responsibilities:
+    1. Initialize enabled channels
+    2. Start/Stop channels
+    3. Route outbound messages
+    """
+
+    def __init__(self, config: Config, bus: MessageBus):
+        self.config = config
+        self.bus = bus
+        self.channels: dict[str, BaseChannel] = {}
+        self._dispatch_task: asyncio.Task | None = None
+
+        self._init_channels()
+
+    def _init_channels(self) -> None:
+        from wanbot.channels.registry import discover_all
+
+        groq_key = self.config.providers.groq.groq_key
+
+        for name, cls in discover_all().items():
+            channel_cfg = getattr(self.config.channels, name, None)
+            if channel_cfg is None:
+                continue
+            enabled = (
+                channel_cfg.get("enabled", False)
+                if isinstance(channel_cfg, dict)
+                else getattr(channel_cfg, "enabled", False)
+            )
+            if not enabled:
+                continue
+
+            try:
+                channel = cls(channel_cfg, self.bus)
+                channel.transcription_api_key = groq_key
+                self.channels[name] = channel
+                logger.info(f"Initialized channel {name}")
+            except Exception as e:
+                logger.warning(f"{name} channel not available: {e}")
+
+    async def _start_channel(self, name: str, channel: BaseChannel) -> None:
+        try:
+            await channel.start()
+        except Exception as e:
+            logger.error(f"Failed to start channel {name}: {e}")
+
+    async def start_all(self) -> None:
+        if not self.channels:
+            logger.warning("No channels configured")
+            return
+        # Start outbound dispatcher
+        self._dispatch_task = asyncio.create_task(self._dispatch_outbound())
+
+        # Start channels
+        tasks = []
+        for name, channel in self.channels.items():
+            logger.info(f"Starting channel {name}")
+            tasks.append(asyncio.create_task(self._start_channel(name, channel)))
+        # Wait for all to complete (they should run forever)
+        await asyncio.gather(*tasks)
+
+    async def stop_all(self) -> None:
+        """Stop all channels"""
+
+        # stop dispatcher
+
+        if self._dispatch_task:
+            self._dispatch_task.cancel()
+            try:
+                await self._dispatch_task
+            except asyncio.CancelledError:
+                pass
+
+        # Stop all channels
+
+        for name, channel in self.channels.items():
+            try:
+                await channel.stop()
+                logger.info(f"Stopped channel {name}")
+            except Exception as e:
+                logger.error(f"Failed to stop channel {name}: {e}")
+
+    async def _dispatch_outbound(self) -> None:
+        """Dispatch outbound messages to appropriate channel."""
+        logger.info("Outbound dispatcher started.")
+
+        # Buffer
+        # 问题背景：为什么会用到Buffer?
+        # 当合并连续的流式消息（_stream_delta）时，可能会遇到不属于当前流的消息。这些消息需要暂时保存，以便在合并完成后继续处理。
+        # 1. 队列中有消息：[delta1, delta2, other_msg, delta3]
+        # 2. delta1 和 delta2 属于同一个流，可以合并
+        # 3. other_msg 属于不同的流，不能合并
+        # 4. delta3 属于第一个流，应该与 delta1+delta2 合并
+        #
+        # asyncio.Queue不支持push_front
+        # 但是 asyncio.Queue 无法将 other_msg 放回前端，只能放到末尾（put()），这会改变消息顺序。
+
+        # 1. 初始化
+        pending: list[OutboundMessage] = []
+
+        while True:
+            try:
+                # 2. 消息获取策略
+                # 优先处理pending中缓存的消息
+                if pending:
+                    msg = pending.pop(0)
+                else:
+                    # 等待消息队列，超时1秒检查取消信号
+                    msg = await asyncio.wait_for(self.bus.consume_outbound(), timeout=1.0)
+                # 3. 消息过滤
+                # 过滤逻辑：
+                # 进度提示：LLM
+                # 思考过程中的中间状态
+                # 工具提示：AI
+                # 调用工具时的提示信息
+                # 根据配置决定是否发送这些辅助信息
+                if msg.metadata.get("_progress"):
+                    if msg.metadata.get("_tool_hint") and not self.config.channels.send_tool_hints:
+                        continue
+                    if not msg.metadata.get("_tool_hint") and not self.config.channels.send_progress:
+                        continue
+
+                # 4. 流式消息合并判断
+                # 合并相同（频道，聊天id）的连续流增量消息
+                # Coalesce consecutive _stream_delta messages for the same (channel,chat_id)
+                # to reduce API calls and improve streaming latency
+                if msg.metadata.get("_stream_delta") and not msg.metadata.get("_stream_end"):
+                    msg, extra_pending = self._coalesce_stream_deltas(msg)
+                    pending.extend(extra_pending)
+
+                # 5. 流式消息合并判断
+                channel = self.channels.get(msg.channel)
+
+                if channel:
+                    await self._send_with_retry(channel, msg)
+                else:
+                    logger.warning(f"Unknown channel: {msg.channel}")
+
+            except asyncio.TimeoutError:
+                continue
+            except asyncio.CancelledError:
+                break
+
+    def _coalesce_stream_deltas(
+        self, first_msg: OutboundMessage
+    ) -> tuple[OutboundMessage, list[OutboundMessage]]:
+        """Merge consecutive _steam_delta messages for the same (channel,chat_id)"""
+        # 步骤1：初始化合并参数
+        target_key = (first_msg.channel, first_msg.chat_id)
+        combined_content = first_msg.content
+        final_metadata = dict(first_msg.metadata or {})
+        non_matching: list[OutboundMessage] = []
+
+        # Only merge consecutive deltas. As soon as we hit any other message,
+        # stop and hand that boundary back to the dispatcher via `pending`.
+        # 只合并连续的delta。一旦我们遇到任何其他消息，停止并通过‘ pending ’将该边界交还给调度程序。
+        # 步骤2：循环合并后续消息
+        while True:
+            try:
+                next_msg = self.bus.outbound.get_nowait()
+            except asyncio.QueueEmpty:
+                break
+
+            # Check if the message belongs to the same stream
+            # 步骤3：消息匹配检查
+            # 1. 相同通道和聊天 ID 2.是流式 delta 消息  3.当前流未结束（final_metadata.get("_stream_end") 为假）
+            is_same_target = (next_msg.channel, next_msg.chat_id) == target_key
+            is_delta = next_msg.metadata and next_msg.metadata.get("_stream_delta")
+            is_end = next_msg.metadata and next_msg.metadata.get("_stream_end")
+
+            # 步骤4：合并决策树
+            if is_same_target and is_delta and not final_metadata.get("_stream_end"):
+                # 条件1：可以合并
+                combined_content += next_msg.content  # 内容累加
+                # If we see _stream_end, remember it and stop coalescing this stream
+                if is_end:
+                    final_metadata["_stream_end"] = True
+                    # Stream ended - stop coalescing this stream
+                    break
+            else:
+                # First non-matching message defines the coalescing boundary.
+                non_matching.append(next_msg)
+                break
+
+        merged = OutboundMessage(
+            channel=first_msg.channel,
+            chat_id=first_msg.chat_id,
+            content=combined_content,
+            metadata=final_metadata,
+        )
+        return merged, non_matching

wanbot-0.0.1/wanbot/channels/registry.py

@@ -0,0 +1,75 @@
+"""Auto-discovery for built-in channel modules and external plugins"""
+
+import importlib
+import pkgutil
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from wanbot.channels.base import BaseChannel
+
+_INTERNAL = frozenset({"base", "manager", "registry"})
+
+
+def discover_channel_names() -> list[str]:
+    """Return all built-in channel module names by scanning the package (zero imports)."""
+    import wanbot.channels as pkg
+
+    return [
+        name
+        for _, name, ispkg in pkgutil.iter_modules(pkg.__path__)
+        if name not in _INTERNAL and not ispkg  # 过滤_INTERNAL 和 子包not ispkg
+    ]
+
+
+def load_channel_class(module_name: str) -> type[BaseChannel]:
+    """Import *module_name* and return the first BaseChannel subclass found."""
+    from wanbot.channels.base import BaseChannel as _Base
+
+    mod = importlib.import_module(f"wanbot.channels.{module_name}")
+    for attr in dir(mod):
+        obj = getattr(mod, attr)
+        # 1.检查是否为类 2. 检查是否为 BaseChannel 的子类 3. 排除 BaseChannel 自身
+        if isinstance(obj, type) and issubclass(obj, _Base) and obj is not _Base:
+            return obj
+    raise ImportError(f"No BaseChannel subclass in wanbot.channels.'{module_name}'")
+
+
+def discover_plugins() -> dict[str, type[BaseChannel]]:
+    """
+    Discover external channel plugins registered via entry_points.
+    发现通过 entry_points 注册的外部通道插件。
+    1. 用途：这是 Python 标准库（Python 3.8+）提供的模块，用于访问已安装包的元数据。
+    2. 原理：Python 包在安装时（通过 setup.py 或 pyproject.toml），可以声明自己提供了某些“入口点”。主程序可以通过查询这些入口点来找到第三方包提供的函数或类，而无需硬编码 import 语句。
+    3. 分组 (group)：代码中指定了 group="wanbot.channels"。这意味着只有那些在配置中明确声明属于 wanbot.channels 组的入口点才会被加载。这是一种命名空间隔离，防止加载无关的插件。
+    """
+    from importlib.metadata import entry_points
+
+    plugins: dict[str, type[BaseChannel]] = {}
+    for ep in entry_points(group="wanbot.channels"):
+        try:
+            cls = ep.load()
+            plugins[ep.name] = cls
+        except Exception as e:
+            logger.warning(f"Failed to load channel plugin {ep.name}: {e}")
+    return plugins
+
+
+def discover_all() -> dict[str, type[BaseChannel]]:
+    """Return all channels: built-in (pkgutil) merged with external (entry_points).)
+    Built-in channels take priority - an external plugin cannot shadow a built-in channel.
+    """
+    builtin: dict[str, type[BaseChannel]] = {}
+    for modname in discover_channel_names():
+        try:
+            builtin[modname] = load_channel_class(modname)
+        except ImportError as exc:
+            logger.warning(f"Skipping built-in channel {modname}: {exc}")
+
+    external = discover_plugins()
+    shadowed = set(external) & set(builtin)
+    if shadowed:
+        logger.warning(f"Plugin(s) shadowed by built-in channels (ignored): {shadowed}")
+
+    return {**external, **builtin}

wanbot-0.0.1/wanbot/cli/commands.py

@@ -0,0 +1,16 @@
+import typer
+from rich.console import Console
+
+# =========================================================================
+# CLI APP
+# =========================================================================
+
+app = typer.Typer(
+    name="wanbot",
+    context_settings=dict(help_option_names=["-h", "--help"]),
+    help="Wanbot CLI",
+    no_args_is_help=True,
+)
+
+console = Console()
+EXIT_COMMANDS = {"exit", "quit", "/exit", "/quit", ":q"}

wanbot-0.0.1/wanbot/config/schema.py

@@ -0,0 +1,7 @@
+# =========================================================================
+# ROOT CONFIG
+# =========================================================================
+
+
+class Config:
+    pass