waifucore 0.1.0__tar.gz

waifucore-0.1.0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__plugin_context7_context7__resolve-library-id",
+      "mcp__plugin_context7_context7__query-docs"
+    ]
+  }
+}

waifucore-0.1.0/.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = crlf
+charset = utf-8
+trim_trailing_whitespace = false
+insert_final_newline = false
+
+[*.yml]
+indent_size = 2

waifucore-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-main:
+    name: Publish waifucore
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Build waifu-ai
+        run: uv build --package waifu
+
+      - name: Publish waifu-ai
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  publish-sdk:
+    name: Publish waifu_sdk
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Build waifu_sdk
+        run: uv build --package waifu_sdk --wheel
+
+      - name: Publish waifu_sdk
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

waifucore-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+
+.DS_Store
+.env
+.pytest_cache
+
+*.egg-info/
+.installed.cfg
+*.egg
+/localdocs

waifucore-0.1.0/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+    "python.analysis.typeCheckingMode": "basic",
+    "python.analysis.diagnosticMode": "workspace"
+}

waifucore-0.1.0/CLAUDE.md

@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies (uv workspace)
+uv sync
+
+# Run the server (development with hot reload)
+waifu start --config config.toml --reload
+
+# Run the server with a custom FastAPI app
+waifu start --app myapp:app --host 0.0.0.0 --port 8765
+
+# Lint
+uvx ruff check waifu/ waifu_types/
+uvx ruff check --fix waifu/ waifu_types/
+
+# Format
+uvx ruff format waifu/ waifu_types/
+```
+
+Config file formats supported: `.toml`, `.yaml`/`.yml`, `.json`.
+
+## Architecture
+
+This is a **uv workspace monorepo** with three packages:
+
+- `waifu_types/` — Shared ABCs/Protocols/Pydantic models (only depends on pydantic). The source of truth for all interfaces.
+- `waifu_sdk/` — Thin re-export of `waifu_types` for third-party plugin authors.
+- `waifu/` — Server implementation (depends on `waifu_types`, `fastapi`, `hai`, `shuvi`).
+
+### Request Lifecycle
+
+```
+Adapter (WS/Discord/Telegram/HTTP)
+  → IncomingRequest
+  → GatewayCore.dispatch()
+  → Lane[conversation_id].enqueue()   ← per-conversation serial queue
+  → HookPipeline.run_pre()
+  → ContextBuilder.build()            ← assembles system_prompt + messages + tools
+  → AgentRunner.run()                 ← wraps shuvi.Agent (tool-calling loop)
+  → HookPipeline.run_post()
+  → OutgoingResponse
+  → Adapter.send()
+```
+
+### Key Modules
+
+**`waifu/waifu.py` — `Waifu` class (Composition Root)**
+The top-level class that wires everything together using a fluent builder API:
+```python
+waifu = (
+    Waifu(config)
+    .mount(WebSocketAdapter())
+    .mount(DiscordAdapter(token=TOKEN))
+    .use(RateLimitHook(max_rpm=60))
+)
+await waifu.mcp_service.add("fs", "stdio", command=[...])
+await waifu.start()
+```
+
+**`waifu/gateway/`** — Ingress layer
+- `GatewayCore`: mounts adapters, manages sessions, dispatches to lane queues
+- `SessionManager`: TTL-based session store keyed by `conversation_id`
+- `LaneManager`: one `asyncio.Queue` per `conversation_id` ensuring serial processing
+- `adapters/`: `WebSocketAdapter` (SESSION mode, chunk streaming + Live2D events), `DiscordAdapter`, `TelegramAdapter`, `HTTPAdapter` (SSE)
+
+**`waifu/hook/`** — Pre/post middleware chain
+- `BaseHook` (from `waifu_types`): `async pre(ctx)` and `async post(ctx)` with `priority` (lower = earlier)
+- `HookContext`: carries `request`, `session`, `messages`, `response`, `events`, `abort`
+- Built-in hooks in `waifu/hook/builtin.py`: `RateLimitHook`, `MemoryHook`, `EmotionHook`, `LoggingHook`, `TTSHook`
+
+**`waifu/plugin/`** — Plugin system
+- `PluginManager.load(plugin, config)` calls `plugin.on_load(ctx)` where plugins register hooks/tools/MCP adapters
+- `PluginRegistry`: holds all registered tools/MCP adapters for the `ContextBuilder`
+- Built-in plugin wrappers in `waifu/plugin/builtin.py`: `ToolPlugin`, `HookPlugin`
+
+**`waifu/mcp/`** — MCP bridge (system-level, not a plugin)
+- `MCPManager`: owns adapter lifecycle, registers tools into `PluginRegistry`
+- `StdioMCPAdapter`: spawns a subprocess (JSON-RPC over stdin/stdout)
+- `SSEMCPAdapter`: connects to HTTP SSE MCP server
+
+**`waifu/router/`** — FastAPI routers
+- `GET /health`, `WS /ws`, `POST /chat` (SSE), `GET|POST|DELETE /plugins/*`
+- `include_routers(app)` mounts all routers; uses `Depends(get_waifu)` for DI
+
+**`waifu/voice/`** — Optional voice pipeline
+- `VoiceService`: STT (Whisper-compatible) → text → TTS → audio + lipsync events
+- Enabled via `VoiceConfig` in `WaifuConfig`; WebSocket adapter handles `type:"voice"` messages
+
+### Conversation Modes
+
+| Mode | `conversation_id` key | History scope | Multi-user |
+|---|---|---|---|
+| `SESSION` | `ws:{session_token}` | Per WebSocket session | No |
+| `DIRECT` | `{source}:dm:{user_id}` | Per user, persistent | No |
+| `GROUP` | `{source}:{room/channel}:{id}` | Per room, persistent | Yes (author prefix added) |
+
+GROUP mode: history messages get `[DisplayName]:` prefix; adapter only dispatches on `@mention` or `/shuvi`.
+
+### Configuration (`WaifuConfig`)
+
+```python
+class WaifuConfig(BaseModel):
+    gateway: GatewayConfig    # host, port, session_ttl, lane_max_queue
+    context: ContextConfig    # system_prompt_template, max_history_messages, history_strategy
+    provider: ProviderConfig  # api_key, base_url, model, temperature, stream
+    voice: Optional[VoiceConfig]  # stt, tts, lipsync_fps
+```
+
+### Third-party Extension
+
+Plugin/adapter authors install `waifu-sdk` (re-exports `waifu_types`). All ABCs are in `waifu_types/waifu_types/`:
+- `BasePlugin` + `PluginContext` — `plugin.py`
+- `BaseGatewayAdapter` — `adapter.py`
+- `BaseHook` + `HookContext` — `hook.py`
+- `BaseMCPAdapter` — `mcp.py`
+- `IncomingRequest`, `OutgoingResponse`, `Attachment` — `types.py`
+
+### External Dependencies
+
+- **`hai`** — LLM providers (OpenAI/Anthropic/Google/Ollama), tools, loaders, vector/graph stores
+- **`shuvi`** — Agent inner/outer loop with tool-calling; `shuvi.Agent` takes `AgentConfig` + messages
+- **`fastapi`** + **`uvicorn`** — HTTP/WebSocket server
+- **`discord.py`** — Discord adapter (optional)
+- **`python-telegram-bot`** — Telegram adapter (optional)

waifucore-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 waifu lab
+
+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.

waifucore-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: waifucore
+Version: 0.1.0
+Author-email: phillychi3 <phillychi3@gmail.com>
+License: MIT License
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: croniter>=2.0
+Requires-Dist: fastapi<0.136.0,>=0.135.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: hydrogen-ai>=0.1.3
+Requires-Dist: loguru>=0.7
+Requires-Dist: peewee>=3.17
+Requires-Dist: python-multipart>=0.0.30
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: shuvi>=0.1.2
+Requires-Dist: textual>=0.89.1
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: all
+Requires-Dist: discord-py>=2.7.1; extra == 'all'
+Requires-Dist: python-telegram-bot>=22.7; extra == 'all'
+Provides-Extra: discord
+Requires-Dist: discord-py>=2.7.1; extra == 'discord'
+Provides-Extra: telegram
+Requires-Dist: python-telegram-bot>=22.7; extra == 'telegram'
+Description-Content-Type: text/markdown
+
+# waifu
+[English](https://github.com/waifu-lab/waifu/blob/main/README.md) | [Chinese](https://github.com/waifu-lab/waifu/blob/main/docs/README_zh.md)
+A modular, extensible AI companion server built with Python. `waifu` covers conversational AI assistants.
+
+---
+
+## Roadmap
+
+- [ ] Support for multi-agent collaboration and orchestration
+- [ ] Plugin marketplace / package repository
+- [ ] Automatic generation of OpenAPI schemas for plugin tools
+- [ ] wait...
+
+---
+
+## Development
+
+
+**Setup**
+
+```bash
+# Clone the repo
+git clone https://github.com/waifu-lab/waifu
+cd waifu
+
+# Install all workspace dependencies
+uv sync
+```
+
+**Running**
+
+```bash
+# Start the server with hot reload
+waifu start --config config.toml --reload
+```
+

waifucore-0.1.0/README.md

@@ -0,0 +1,36 @@
+# waifu
+[English](https://github.com/waifu-lab/waifu/blob/main/README.md) | [Chinese](https://github.com/waifu-lab/waifu/blob/main/docs/README_zh.md)
+A modular, extensible AI companion server built with Python. `waifu` covers conversational AI assistants.
+
+---
+
+## Roadmap
+
+- [ ] Support for multi-agent collaboration and orchestration
+- [ ] Plugin marketplace / package repository
+- [ ] Automatic generation of OpenAPI schemas for plugin tools
+- [ ] wait...
+
+---
+
+## Development
+
+
+**Setup**
+
+```bash
+# Clone the repo
+git clone https://github.com/waifu-lab/waifu
+cd waifu
+
+# Install all workspace dependencies
+uv sync
+```
+
+**Running**
+
+```bash
+# Start the server with hot reload
+waifu start --config config.toml --reload
+```
+

waifucore-0.1.0/docs/README_zh.md

@@ -0,0 +1,38 @@
+# waifu
+
+[English](https://github.com/waifu-lab/waifu/blob/main/README.md) | [中文](https://github.com/waifu-lab/waifu/blob/main/docs/README_zh.md)
+
+一個以 Python 打造的模組化、可擴展 AI 伴侶伺服器。`waifu` 涵蓋對話式 AI 助理.
+
+---
+
+## Roadmap
+
+- [ ] 多 Agent 協作編排支援
+- [ ] Plugin 市集 / 套件倉庫
+- [ ] Plugin 工具的 OpenAPI Schema 自動生成
+- [ ] wait...
+
+---
+
+## 開發
+
+
+**環境設置**
+
+```bash
+# 複製倉庫
+git clone https://github.com/waifu-lab/waifu
+cd waifu
+
+# 安裝所有 workspace 相依套件
+uv sync
+```
+
+**啟動伺服器**
+
+```bash
+# 以熱重載模式啟動
+waifu start --config config.toml --reload
+```
+

waifucore-0.1.0/install/install.ps1

@@ -0,0 +1,15 @@
+#Requires -Version 5.1
+$ErrorActionPreference = 'Stop'
+
+if (Get-Command uv -ErrorAction SilentlyContinue) {
+    uv tool install waifu-ai
+} elseif (Get-Command pip -ErrorAction SilentlyContinue) {
+    pip install waifu-ai
+} elseif (Get-Command pip3 -ErrorAction SilentlyContinue) {
+    pip3 install waifu-ai
+} else {
+    Write-Error "Neither uv nor pip found. Please install Python first."
+    exit 1
+}
+
+Write-Host "waifu installed. Run 'waifu init' to get started."

waifucore-0.1.0/install/install.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+set -e
+
+if command -v uv >/dev/null 2>&1; then
+    uv tool install waifu-ai
+elif command -v pip >/dev/null 2>&1; then
+    pip install waifu-ai
+elif command -v pip3 >/dev/null 2>&1; then
+    pip3 install waifu-ai
+else
+    echo "Error: neither uv nor pip found. Please install Python first." >&2
+    exit 1
+fi
+
+echo "waifu installed. Run 'waifu init' to get started."

waifucore-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "waifucore"
+version = "0.1.0"
+description = ""
+authors = [{ name = "phillychi3", email = "phillychi3@gmail.com" }]
+requires-python = ">=3.10"
+readme = "README.md"
+license = { text = "MIT License" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "fastapi (>=0.135.1,<0.136.0)",
+    "python-multipart>=0.0.30",
+    "httpx>=0.27",
+    "uvicorn[standard]>=0.30",
+    "textual>=0.89.1",
+    "peewee>=3.17",
+    "croniter>=2.0",
+    "tomli-w>=1.0",
+    "pyyaml>=6.0",
+    "loguru>=0.7",
+    "rich>=13.0",
+    "shuvi>=0.1.2",
+    "hydrogen-ai>=0.1.3",
+]
+
+[project.optional-dependencies]
+discord = ["discord-py>=2.7.1"]
+telegram = ["python-telegram-bot>=22.7"]
+all = ["discord-py>=2.7.1", "python-telegram-bot>=22.7"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["waifu", "waifu_types/waifu_types"]
+
+[project.scripts]
+waifu = "waifu.cli:main"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = [".", "waifu_types", "waifu_sdk"]
+testpaths = ["test"]
+
+[tool.ruff]
+lint.select = ["ASYNC", "ARG", "B", "C", "C4", "E", "F", "Q", "W", "I"]
+
+lint.ignore = ["F401"]
+
+lint.unfixable = ["F401"]
+
+line-length = 120
+
+[tool.uv.workspace]
+members = ["waifu_sdk", "waifu_types"]
+
+[dependency-groups]
+dev = [
+    "httpx>=0.27",
+    "ftfy>=6.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "discord-py>=2.7.1",
+    "python-telegram-bot>=22.7",
+]
+
+[tool.pyright]
+include = ["waifu", "waifu_sdk", "waifu_types"]
+
+pythonVersion = "3.10"
+
+typeCheckingMode = "basic"
+
+reportPrivateUsage = false

waifucore-0.1.0/test/test_flow.py

@@ -0,0 +1,105 @@
+"""
+之後刪除
+"""
+
+import uuid
+
+import pytest
+
+from waifu.plugin.builtin import ToolPlugin
+from waifu.store import AppPaths
+from waifu.tool.read import read_tool
+from waifu.tool.shell import shell_tool
+from waifu.tool.webfetch import webfetch_tool
+from waifu.tool.write import write_tool
+from waifu.waifu import Waifu
+from waifu_types import ConversationMode, IncomingRequest
+from waifu_types.types import Sender
+
+
+def _load_config():
+    """從 AppPaths 找到 config.toml 並解析"""
+    paths = AppPaths.resolve()
+    config_path = paths.config_file
+    if not config_path.exists():
+        pytest.skip(f"config not found: {config_path}")
+
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    with open(config_path, "rb") as f:
+        data = tomllib.load(f)
+
+    from waifu.config import WaifuConfig
+
+    return WaifuConfig(**data)
+
+
+@pytest.fixture(scope="module")
+def config():
+    return _load_config()
+
+
+@pytest.fixture(scope="module")
+async def waifu(config):
+    """建立真實 Waifu 實例，掛載所有基礎工具"""
+    w = Waifu(config)
+    await w.plugin(ToolPlugin("basic", [read_tool, write_tool, shell_tool, webfetch_tool]))
+    return w
+
+
+def make_request(content: str) -> IncomingRequest:
+    chunks = []
+    return IncomingRequest(
+        conversation_id=f"test:{uuid.uuid4()}",
+        mode=ConversationMode.session,
+        sender=Sender(user_id="test-user", display_name="Tester"),
+        source="test",
+        content=content,
+        reply_fn=lambda **kw: chunks.append(kw.get("chunk", "")),
+    )
+
+
+@pytest.mark.asyncio
+async def test_plain_qa(waifu):
+    """基本問答，不需要工具"""
+    req = make_request("請用一句話回答：1 + 1 等於多少？")
+    response = await waifu._dispatch(req)
+
+    assert response.content.strip() != ""
+    assert "2" in response.content
+
+
+@pytest.mark.asyncio
+async def test_tool_read(waifu, tmp_path):
+    """讓 LLM 讀取一個測試檔案，驗證 read tool 被正確呼叫"""
+    test_file = tmp_path / "secret.txt"
+    test_file.write_text("waifu_read_ok", encoding="utf-8")
+
+    req = make_request(f"請使用 read 工具讀取這個檔案並告訴我裡面的內容：{test_file}")
+    response = await waifu._dispatch(req)
+
+    assert "waifu_read_ok" in response.content
+
+
+@pytest.mark.asyncio
+async def test_tool_write(waifu, tmp_path):
+    """讓 LLM 寫入一個檔案，驗證 write tool 被正確呼叫且檔案存在"""
+    dest = tmp_path / "waifu_out.txt"
+
+    req = make_request(f"請使用 write 工具將文字 'hello_from_waifu' 寫入這個路徑：{dest}")
+    response = await waifu._dispatch(req)
+
+    assert dest.exists(), "write tool 沒有建立檔案"
+    assert "hello_from_waifu" in dest.read_text(encoding="utf-8")
+
+
+@pytest.mark.asyncio
+async def test_tool_shell(waifu):
+    """讓 LLM 執行 shell 指令，驗證 shell tool 回傳結果"""
+    req = make_request("請使用 shell 工具執行 'echo waifu_shell_test'，並告訴我輸出結果")
+    response = await waifu._dispatch(req)
+
+    assert "waifu_shell_test" in response.content