shuvi 0.1.0__tar.gz

shuvi-0.1.0/LICENSE

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

shuvi-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.3
+Name: shuvi
+Version: 0.1.0
+Summary: 
+License: MIT
+Author: phillychi3
+Author-email: phillychi3@gmail.com
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT 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
+Requires-Dist: hydrogen-ai (>=0.1.0,<0.2.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Description-Content-Type: text/markdown
+
+# SHUVI

shuvi-0.1.0/README.md

@@ -0,0 +1 @@
+# SHUVI

shuvi-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[tool.poetry]
+packages = [{ include = "shuvi" }]
+
+[tool.poetry.group.dev.dependencies]
+pytest-asyncio = "^1.3.0"
+python-dotenv = ">=1.0.1,<1.1.0"
+
+[project]
+name = "shuvi"
+version = "0.1.0"
+description = ""
+authors = [{ name = "phillychi3", email = "phillychi3@gmail.com" }]
+license = { text = "MIT License" }
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["pydantic (>=2.12.5,<3.0.0)", "hydrogen-ai (>=0.1.0,<0.2.0)"]
+
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["test"]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+lint.select = ["ASYNC", "ARG", "B", "C", "C4", "E", "F", "Q", "W", "I"]
+
+lint.ignore = ["F401"]
+
+lint.unfixable = ["F401"]
+
+line-length = 120

shuvi-0.1.0/shuvi/agent.py

@@ -0,0 +1,280 @@
+import asyncio
+import inspect
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence, Tuple
+
+from hai.providers.providers import ProviderText
+from hai.tool import Tool
+from shuvi.types import (
+    AGENT_OUTCOME,
+    AgentCallbacks,
+    AgentConfig,
+    AgentResult,
+    AppMessage,
+    AssistantMessage,
+    ExecutionTrace,
+    HandoffSignal,
+    LoopConfig,
+    LoopState,
+    TokenUsage,
+    ToolCall,
+    ToolCallFunction,
+    ToolCallTrace,
+    ToolMessage,
+    UserMessage,
+    VerificationRecord,
+    VerifyFn,
+)
+
+if TYPE_CHECKING:
+    from shuvi.context import ContextManager
+
+
+# C:\Users\whitecloud\Documents\code\waifu\shuvi\agent.py:39: RuntimeWarning: coroutine 'HTTPAdapter.handle.<locals>.reply_fn' was never awaited
+#  fn(*args)
+# RuntimeWarning: Enable tracemalloc to get the object allocation traceback
+async def _emit(fn: Optional[Any], *args: Any) -> None:
+    if fn is None:
+        return
+    if inspect.iscoroutinefunction(fn):
+        await fn(*args)
+    else:
+        fn(*args)
+
+
+def _to_llm(messages: Sequence[AppMessage]) -> List[Dict[str, Any]]:
+    return [m.model_dump(exclude_none=True) for m in messages]
+
+
+class Agent:
+    def __init__(self, config: AgentConfig) -> None:
+        self._provider: ProviderText = config.provider
+        self._system_prompt: str = config.system_prompt
+        self._loop: LoopConfig = config.loop
+        self._callbacks: AgentCallbacks = config.callbacks
+        self._session_id: Optional[str] = config.session_id
+        self._tools: List[Tool] = list(config.tools)
+        self._tool_map: Dict[str, Tool] = {t.name: t for t in self._tools}
+        self._message_queue: asyncio.Queue[AppMessage] = asyncio.Queue()
+        self._context_manager: Optional["ContextManager"] = config.context_manager
+        self._state = LoopState()
+
+    @property
+    def state(self) -> LoopState:
+        return self._state
+
+    def reset_state(self) -> None:
+        self._state = LoopState()
+
+    async def run(self, messages: Optional[Sequence[AppMessage]] = None) -> AgentResult:
+        """
+        If ContextManager is present, messages param is ignored — append to
+        context_manager before calling run(). Otherwise messages must be provided.
+        """
+        if self._context_manager is not None:
+            initial_messages = await self._context_manager.prepare()
+        else:
+            if messages is None:
+                raise ValueError("messages required when no ContextManager is configured")
+            initial_messages = list(messages)
+
+        start = datetime.now()
+        trace = ExecutionTrace(
+            start_time=start.isoformat(),
+            session_id=self._session_id,
+        )
+
+        current_messages = initial_messages
+        verify_fn = self._loop.verify_completion
+        max_outer = self._loop.max_outer_retries
+        handoff_target: Optional[str] = None
+
+        try:
+            while True:
+                try:
+                    final_msgs, iterations, tool_traces, usage, hit_max = await self._inner_loop(current_messages)
+                except HandoffSignal as hs:
+                    handoff_target = hs.target
+                    self._state.transition = hs.target
+                    await _emit(self._callbacks.state_update, self._state)
+                    trace.outcome = AGENT_OUTCOME.completed
+                    final_msgs = current_messages
+                    break
+
+                trace.inner_iterations += iterations
+                trace.tool_calls.extend(tool_traces)
+                trace.token_usage.input += usage.input
+                trace.token_usage.output += usage.output
+                trace.token_usage.total += usage.total
+
+                if hit_max:
+                    trace.outcome = AGENT_OUTCOME.max_iterations
+                    break
+
+                if verify_fn is None:
+                    trace.outcome = AGENT_OUTCOME.completed
+                    break
+
+                verification = await _call_verify(verify_fn, final_msgs)
+                trace.verifications.append(verification)
+
+                if verification.passed:
+                    trace.outcome = AGENT_OUTCOME.completed
+                    break
+
+                if trace.outer_retries >= max_outer:
+                    trace.outcome = AGENT_OUTCOME.verify_failed
+                    break
+
+                trace.outer_retries += 1
+
+                current_messages = final_msgs + [
+                    UserMessage(content=[{"type": "text", "text": f"驗證未通過：{verification.reason}，請修正"}])
+                ]
+
+        except Exception as e:
+            trace.outcome = AGENT_OUTCOME.error
+            await _emit(self._callbacks.error, e)
+            final_msgs = current_messages
+            if self._callbacks.error is None:
+                raise
+
+        end = datetime.now()
+        trace.end_time = end.isoformat()
+        trace.duration_ms = (end - start).total_seconds() * 1000
+
+        if self._context_manager is not None:
+            new_msgs = final_msgs[len(initial_messages) :]
+            self._context_manager.extend(new_msgs)
+
+        return AgentResult(messages=final_msgs, trace=trace, outcome=trace.outcome, handoff=handoff_target)
+
+    def queue_message(self, message: AppMessage) -> None:
+        self._message_queue.put_nowait(message)
+
+    def add_tool(self, tool: Tool) -> None:
+        self._tools.append(tool)
+        self._tool_map[tool.name] = tool
+
+    def remove_tool(self, name: str) -> None:
+        self._tools = [t for t in self._tools if t.name != name]
+        self._tool_map.pop(name, None)
+
+    def set_tools(self, tools: List[Tool]) -> None:
+        self._tools = list(tools)
+        self._tool_map = {t.name: t for t in self._tools}
+
+    async def _inner_loop(
+        self,
+        messages: Sequence[AppMessage],
+    ) -> Tuple[List[AppMessage], int, List[ToolCallTrace], TokenUsage, bool]:
+        msgs: List[AppMessage] = list(messages)
+        iterations = 0
+        tool_traces: List[ToolCallTrace] = []
+        total_usage = TokenUsage()
+        max_iter = self._loop.max_inner_iterations
+
+        while True:
+            while not self._message_queue.empty():
+                msgs.append(self._message_queue.get_nowait())
+
+            if self._state.stop_active:
+                return msgs, iterations, tool_traces, total_usage, False
+
+            if max_iter is not None and iterations >= max_iter:
+                return msgs, iterations, tool_traces, total_usage, True
+
+            turn = await self._provider.call_once(
+                messages=_to_llm(msgs),
+                tools=self._tools or None,
+                system_prompt=self._system_prompt or None,
+                on_chunk=self._callbacks.on_chunk,
+            )
+
+            total_usage.input += turn.usage.get("input", 0)
+            total_usage.output += turn.usage.get("output", 0)
+            total_usage.total += turn.usage.get("total", 0)
+
+            self._state.turn_count += 1
+            iterations += 1
+            await _emit(self._callbacks.state_update, self._state)
+
+            if turn.content:
+                await _emit(
+                    self._callbacks.assistant_message,
+                    AssistantMessage(content=turn.content),
+                )
+
+            tool_calls: Optional[List[ToolCall]] = None
+            if turn.tool_calls:
+                tool_calls = [
+                    ToolCall(
+                        id=tc["id"],
+                        function=ToolCallFunction(name=tc["function"]["name"], arguments=tc["function"]["arguments"]),
+                    )
+                    for tc in turn.tool_calls
+                ]
+                msgs.append(AssistantMessage(content=turn.content, tool_calls=tool_calls))
+            else:
+                msgs.append(AssistantMessage(content=turn.content))
+
+            if not tool_calls:
+                break
+
+            results = await asyncio.gather(*[self._execute_tool_call(tc) for tc in tool_calls])
+
+            for tc, (result, trace) in zip(tool_calls, results, strict=False):
+                tool_traces.append(trace)
+                msgs.append(ToolMessage(tool_call_id=tc.id, content=result))
+                await _emit(self._callbacks.tool_result, tc.function.name, result)
+
+            await _emit(self._callbacks.iteration_end, iterations, tool_traces)
+
+        return msgs, iterations, tool_traces, total_usage, False
+
+    async def _execute_tool_call(self, tool_call: ToolCall) -> Tuple[str, ToolCallTrace]:
+        name = tool_call.function.name
+        arguments = tool_call.function.arguments
+
+        await _emit(self._callbacks.tool_call, name, arguments)
+
+        t_start = datetime.now()
+        tool = self._tool_map.get(name)
+
+        if tool is None:
+            error = f"Tool '{name}' not found"
+            duration = (datetime.now() - t_start).total_seconds() * 1000
+            return error, ToolCallTrace(name=name, input=arguments, output=error, duration_ms=duration, error=error)
+
+        try:
+            result = await tool.call(arguments)
+        except Exception as e:
+            duration = (datetime.now() - t_start).total_seconds() * 1000
+            error_msg = f"Error executing tool '{name}': {e}"
+            await _emit(self._callbacks.on_tool_error, name, e)
+            return error_msg, ToolCallTrace(
+                name=name, input=arguments, output=error_msg, duration_ms=duration, error=error_msg
+            )
+        duration = (datetime.now() - t_start).total_seconds() * 1000
+        return result, ToolCallTrace(name=name, input=arguments, output=result, duration_ms=duration)
+
+
+async def _call_verify(verify_fn: List[VerifyFn], messages: Sequence[AppMessage]) -> VerificationRecord:
+    last: VerificationRecord = VerificationRecord(passed=True)
+    for fn in verify_fn:
+        if inspect.iscoroutinefunction(fn):
+            raw = await fn(messages)
+        else:
+            raw = fn(messages)
+
+        if isinstance(raw, VerificationRecord):
+            record = raw
+        elif isinstance(raw, dict):
+            record = VerificationRecord(**raw)
+        else:
+            record = VerificationRecord(passed=bool(raw))
+
+        if not record.passed:
+            return record
+        last = record
+    return last

shuvi-0.1.0/shuvi/context.py

@@ -0,0 +1,46 @@
+from typing import Awaitable, Callable, List, Optional
+
+from shuvi.types import AppMessage
+
+_LLM_ROLES = {"user", "assistant", "tool"}
+
+
+async def _default_convert(messages: List[AppMessage]) -> List[AppMessage]:
+    return [m for m in messages if m.role in _LLM_ROLES]
+
+
+class ContextManager:
+    """
+    Manages app-level message history and the two-step conversion to LLM format.
+
+    transform_context: trim/inject/window at the AppMessage layer before LLM call
+    convert_to_llm: filter custom message subtypes, produce the list the LLM sees
+    """
+
+    def __init__(
+        self,
+        transform_context: Optional[Callable[[List[AppMessage]], Awaitable[List[AppMessage]]]] = None,
+        convert_to_llm: Optional[Callable[[List[AppMessage]], Awaitable[List[AppMessage]]]] = None,
+    ) -> None:
+        self._transform = transform_context
+        self._convert = convert_to_llm or _default_convert
+        self._history: List[AppMessage] = []
+
+    @property
+    def history(self) -> List[AppMessage]:
+        return self._history
+
+    def append(self, message: AppMessage) -> None:
+        self._history.append(message)
+
+    def extend(self, messages: List[AppMessage]) -> None:
+        self._history.extend(messages)
+
+    def clear(self) -> None:
+        self._history.clear()
+
+    async def prepare(self) -> List[AppMessage]:
+        messages = list(self._history)
+        if self._transform:
+            messages = await self._transform(messages)
+        return await self._convert(messages)

shuvi-0.1.0/shuvi/swarm.py

@@ -0,0 +1,55 @@
+from typing import Dict, List, Optional
+
+from shuvi.agent import Agent
+from shuvi.types import AgentResult, AppMessage
+
+
+class Swarm:
+    """
+    Routes messages across multiple named agents using the handoff mechanism.
+
+    An agent signals a handoff by raising HandoffSignal(target) inside a tool call.
+    Swarm catches the result.handoff field and re-runs with the target agent,
+    passing the current message history forward.
+    """
+
+    def __init__(self, agents: Dict[str, Agent], max_handoffs: int = 10) -> None:
+        self._agents = agents
+        self._max_handoffs = max_handoffs
+
+    def add_agent(self, name: str, agent: Agent) -> None:
+        self._agents[name] = agent
+
+    async def run(
+        self,
+        entry: str,
+        messages: Optional[List[AppMessage]] = None,
+    ) -> AgentResult:
+        current_name = entry
+        current_messages = messages
+        last_result: Optional[AgentResult] = None
+        handoffs = 0
+
+        while True:
+            agent = self._agents.get(current_name)
+            if agent is None:
+                raise KeyError(f"Agent '{current_name}' not found in swarm")
+
+            if agent._context_manager is not None:
+                result = await agent.run()
+            else:
+                result = await agent.run(current_messages)
+
+            last_result = result
+
+            if result.handoff is None:
+                break
+
+            if handoffs >= self._max_handoffs:
+                break
+
+            handoffs += 1
+            current_name = result.handoff
+            current_messages = result.messages
+
+        return last_result

shuvi-0.1.0/shuvi/types.py

@@ -0,0 +1,188 @@
+from enum import Enum
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Protocol,
+    Sequence,
+    Union,
+    runtime_checkable,
+)
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from hai.providers.providers import ProviderText
+from hai.tool import Tool
+
+
+class ToolCallFunction(BaseModel):
+    name: str
+    arguments: str
+
+
+class ToolCall(BaseModel):
+    id: str
+    type: Literal["function"] = "function"
+    function: ToolCallFunction
+
+
+@runtime_checkable
+class AppMessage(Protocol):
+    @property
+    def role(self) -> str: ...
+    @property
+    def content(self) -> Any: ...
+
+    def model_dump(self, *, exclude_none: bool = False) -> Dict[str, Any]: ...
+
+
+class UserMessage(BaseModel):
+    role: Literal["user"] = "user"
+    content: List[Dict[str, Any]]
+
+    def model_dump(self, *, exclude_none: bool = False) -> Dict[str, Any]:
+        return {"role": self.role, "content": self.content}
+
+
+class AssistantMessage(BaseModel):
+    role: Literal["assistant"] = "assistant"
+    content: Optional[str] = None
+    tool_calls: Optional[List[ToolCall]] = None
+
+
+class ToolMessage(BaseModel):
+    role: Literal["tool"] = "tool"
+    content: str
+    tool_call_id: str
+
+
+class SystemMessage(BaseModel):
+    role: Literal["system"] = "system"
+    content: str
+
+
+LLMMessage = Union[UserMessage, AssistantMessage, ToolMessage]
+
+
+class AGENT_EVENT(str, Enum):
+    agent_start = "agent_start"
+    agent_end = "agent_end"
+    tool_start = "tool_start"
+    tool_end = "tool_end"
+    message_update = "message_update"
+    context_building = "context_building"
+    context_building_end = "context_building_end"
+    context_compacting = "context_compacting"
+
+
+class AGENT_OUTCOME(str, Enum):
+    completed = "completed"
+    max_iterations = "max_iterations"
+    error = "error"
+    verify_failed = "verify_failed"
+
+
+class ToolCallTrace(BaseModel):
+    name: str
+    input: str
+    output: str
+    duration_ms: float
+    error: Optional[str] = None
+
+
+class VerificationRecord(BaseModel):
+    passed: bool
+    reason: Optional[str] = None
+
+
+class TokenUsage(BaseModel):
+    input: int = 0
+    output: int = 0
+    total: int = 0
+
+
+class ExecutionTrace(BaseModel):
+    start_time: str
+    end_time: str = ""
+    duration_ms: float = 0.0
+    token_usage: TokenUsage = Field(default_factory=TokenUsage)
+    inner_iterations: int = 0
+    outer_retries: int = 0
+    outcome: AGENT_OUTCOME = AGENT_OUTCOME.completed
+    tool_calls: List[ToolCallTrace] = []
+    verifications: List[VerificationRecord] = []
+    session_id: Optional[str] = None
+
+
+class AgentResult(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    messages: List[AppMessage]
+    trace: ExecutionTrace
+    outcome: AGENT_OUTCOME
+    handoff: Optional[str] = None
+
+
+class HandoffSignal(Exception):
+    """Raised inside Agent to signal control transfer to another agent."""
+
+    def __init__(self, target: str, context: Optional[str] = None) -> None:
+        self.target = target
+        self.context = context  # optional summary passed to the next agent
+
+
+VerifyResult = Union[VerificationRecord, bool]
+VerifyFn = Union[
+    Callable[[Sequence[AppMessage]], VerifyResult],
+    Callable[[Sequence[AppMessage]], "Awaitable[VerifyResult]"],
+]
+
+
+class LoopState(BaseModel):
+    """Mutable state carried across iterations of the agent loop."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    turn_count: int = 0
+    pending_summary: Optional[str] = None  # accumulated summary for context compaction
+    stop_active: bool = False  # a stop hook / signal has fired
+    transition: Optional[str] = None  # handoff target agent name
+
+
+class LoopConfig(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    max_inner_iterations: Optional[int] = None  # None = unlimited
+    max_outer_retries: int = 3
+    verify_completion: Optional[List[VerifyFn]] = None  # fn(messages) -> VerificationRecord | bool
+
+
+class AgentCallbacks(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    tool_call: Optional[Callable[[str, str], None]] = None
+    tool_result: Optional[Callable[[str, str], None]] = None
+    on_tool_error: Optional[Union[Callable[[str, Exception], None], Callable[[str, Exception], Awaitable[None]]]] = None
+    assistant_message: Optional[Callable[[AppMessage], None]] = None
+    on_chunk: Optional[Union[Callable[[str], None], Callable[[str], Awaitable[None]]]] = (
+        None  # called per streaming token
+    )
+    iteration_end: Optional[Callable[[int, List[ToolCallTrace]], None]] = None
+    error: Optional[Callable[[Exception], None]] = None
+    state_update: Optional[Callable[["LoopState"], None]] = None  # fired after each state mutation
+
+
+class AgentConfig(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    provider: ProviderText
+    system_prompt: str = ""
+    tools: List[Tool] = []
+    loop: LoopConfig = LoopConfig()
+    callbacks: AgentCallbacks = AgentCallbacks()
+    session_id: Optional[str] = None
+    context_manager: Optional[Any] = None  # shuvi.context.ContextManager; Any avoids circular import