agstack 2.1.0__tar.gz → 2.3.0__tar.gz

{agstack-2.1.0 → agstack-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 2.1.0
+Version: 2.3.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-2.1.0 → agstack-2.3.0}/agstack/llm/client.py

@@ -14,6 +14,7 @@ from openai.types.chat import ChatCompletionMessageParam
 
 from ..contexts import get_request_id
 from ..exceptions import AppException
+from .hooks import CallMeta, StreamSummary, has_llm_hooks, run_after_call, run_before_call
 
 
 if TYPE_CHECKING:
@@ -207,12 +208,24 @@ class LLMClient:
         model_name = model
         # 内部调用类型标记（vision 经由 chat 转发时传入，不透传给推理后端）
         usage_kind = kwargs.pop("usage_kind", "chat")
+        # 调用方附带给 LLM 钩子的上下文（Agent 传 agent / turn / retry / context），不透传给推理后端
+        hook_extra: dict[str, Any] = kwargs.pop("hook_meta", None) or {}
+        stream_kind = "chat_stream" if usage_kind == "chat" else usage_kind
+        meta = CallMeta(
+            model=model_name,
+            kind=stream_kind if stream else usage_kind,
+            stream=stream,
+            request_id=get_request_id(),
+            extra=hook_extra,
+        )
+        # F6 before 链：请求发出前改写消息；钩子异常即失败（fail closed），不包进 LLMError 以保留原异常类型
+        if has_llm_hooks():
+            messages = await run_before_call(messages, kwargs.get("tools"), meta)
 
         try:
             if stream:
-                stream_kind = "chat_stream" if usage_kind == "chat" else usage_kind
                 return self._chat_stream(
-                    messages, model_name, temperature, max_tokens, start, usage_kind=stream_kind, **kwargs
+                    messages, model_name, temperature, max_tokens, start, usage_kind=stream_kind, meta=meta, **kwargs
                 )
 
             @autoretry(
@@ -242,6 +255,8 @@ class LLMClient:
             else:
                 logger.info(f"LLM: model={model_name}, duration={duration_ms}ms")
             _emit_usage(model_name, usage_kind, usage, duration_ms)
+            if has_llm_hooks():
+                await run_after_call(response, meta)
 
             return response
 
@@ -324,10 +339,12 @@ class LLMClient:
         max_tokens: int | None,
         start_time: float,
         usage_kind: str = "chat_stream",
+        meta: CallMeta | None = None,
         **kwargs: Any,
     ) -> AsyncIterator["ChatCompletionChunk"]:
         """流式响应"""
         final_usage = None
+        finish_reason: str | None = None
 
         try:
             # noinspection PyTypeChecker
@@ -346,6 +363,8 @@ class LLMClient:
                 # 收集 token 统计（usage 通常在末尾 chunk 返回）
                 if chunk.usage:
                     final_usage = chunk.usage
+                if chunk.choices and chunk.choices[0].finish_reason:
+                    finish_reason = chunk.choices[0].finish_reason
 
                 yield chunk
 
@@ -354,6 +373,8 @@ class LLMClient:
             total_tokens = final_usage.total_tokens if final_usage else 0
             logger.info(f"LLM stream: model={model}, tokens={total_tokens}, duration={duration_ms}ms")
             _emit_usage(model, usage_kind, final_usage, duration_ms)
+            if meta is not None and has_llm_hooks():
+                await run_after_call(StreamSummary(usage=final_usage, finish_reason=finish_reason), meta)
 
         except APITimeoutError as e:
             logger.error(f"LLM stream timeout: {e}")

{agstack-2.1.0 → agstack-2.3.0}/agstack/llm/flow/agent.py

@@ -34,6 +34,7 @@ class Agent:
         *,
         tool_choice: str = "auto",
         on_max_turns: str = "finalize",
+        retry_empty_response: bool = False,
         label: str | None = None,
         echo: bool = False,
     ):
@@ -47,6 +48,8 @@ class Agent:
         :param max_tokens: 最大 token 数
         :param max_turns: 最大轮次
         :param on_max_turns: max_turns 耗尽时的行为，"finalize"（降级输出并标记 truncated）或 "error"（抛出异常）
+        :param retry_empty_response: 一轮既无文字也无 tool_calls 时（如推理模型把输出预算耗尽在 reasoning 上）
+            以 ``request_overrides(..., retry=True)`` 的覆盖参数重试一次
         :param label: 面向用户的展示名称（控制 STEP 进度事件可见性）
         :param echo: 是否转发 TEXT_MESSAGE 给用户
         """
@@ -59,6 +62,7 @@ class Agent:
         self.max_turns = max_turns
         self.tool_choice = tool_choice
         self.on_max_turns = on_max_turns
+        self.retry_empty_response = retry_empty_response
         self.label = label
         self.echo = echo
 
@@ -70,6 +74,27 @@ class Agent:
         """获取工具 schema"""
         return [tool.to_openai_tool() for tool in self.tools]
 
+    def request_overrides(self, context: "FlowContext", turn: int, *, retry: bool = False) -> dict[str, Any]:
+        """按轮覆盖本次模型请求参数的钩子（子类实现，默认不覆盖）
+
+        返回值合并进 ``client.chat`` 的 kwargs：``extra_body`` 按键合并，其余键直接覆盖。
+        典型用法：决策轮 / 作答轮分别设置 ``extra_body={"enable_thinking": ...}`` 与 ``max_tokens``；
+        ``retry=True`` 表示上一次请求空响应后的重试。
+
+        :param turn: 本 agent 本次运行内的轮次，从 1 起
+        """
+        return {}
+
+    @staticmethod
+    def _apply_overrides(kwargs: dict[str, Any], overrides: dict[str, Any]) -> None:
+        for key, value in overrides.items():
+            if key == "extra_body" and isinstance(value, dict):
+                merged = dict(kwargs.get("extra_body") or {})
+                merged.update(value)
+                kwargs["extra_body"] = merged
+            else:
+                kwargs[key] = value
+
     def get_tool_by_name(self, name: str) -> "Tool | None":
         """根据名称获取工具"""
         for tool in self.tools:
@@ -265,7 +290,7 @@ class Agent:
 
         # Agent 循环
         assistant_content = ""
-        for _ in range(self.max_turns):
+        for turn in range(1, self.max_turns + 1):
             # 协作式取消检查点：不再开始新的 LLM 轮次
             if context.is_cancelled:
                 if not context.get_variable("_cancel_emitted"):
@@ -275,96 +300,107 @@ class Agent:
 
             context.increment_turn()
 
-            # 调用模型
-            assistant_content = ""
-            tool_calls: list[dict[str, Any]] = []
-            tool_calls_buffer: dict[int, dict[str, Any]] = {}
+            # 调用模型；空响应（无文字无 tool_calls）且开启 retry_empty_response 时以重试覆盖参数再请求一次
+            attempt = 0
+            while True:
+                assistant_content = ""
+                tool_calls: list[dict[str, Any]] = []
+                tool_calls_buffer: dict[int, dict[str, Any]] = {}
+
+                try:
+                    kwargs: dict[str, Any] = {
+                        "messages": messages,
+                        "model": self.model,
+                        "temperature": self.temperature,
+                    }
 
-            try:
-                kwargs: dict[str, Any] = {
-                    "messages": messages,
-                    "model": self.model,
-                    "temperature": self.temperature,
-                }
-
-                if self.max_tokens:
-                    kwargs["max_tokens"] = self.max_tokens
-
-                if tools_schema:
-                    kwargs["tools"] = tools_schema
-                    kwargs["tool_choice"] = self.tool_choice
-
-                stream = await client.chat(stream=True, **kwargs)
-
-                async for chunk in stream:
-                    if not chunk.choices:
-                        continue
-
-                    choice = chunk.choices[0]
-                    delta = choice.delta
-
-                    # 内容增量 - AG-UI: TEXT_MESSAGE_CONTENT
-                    if delta.content:
-                        assistant_content += delta.content
-                        yield event.text_message_content(
-                            message_id=msg_id,
-                            delta=delta.content,
-                        )
-
-                    # 工具调用
-                    if delta.tool_calls:
-                        for tool_call_delta in delta.tool_calls:
-                            idx = tool_call_delta.index  # noqa
-                            if idx not in tool_calls_buffer:
-                                tool_calls_buffer[idx] = {
-                                    "id": tool_call_delta.id or "",  # noqa
-                                    "name": "",
-                                    "arguments": "",
-                                }
-
-                            if tool_call_delta.id:  # noqa
-                                tool_calls_buffer[idx]["id"] = tool_call_delta.id  # noqa
-                            if tool_call_delta.function and tool_call_delta.function.name:  # noqa
-                                tool_calls_buffer[idx]["name"] = tool_call_delta.function.name  # noqa
-                            if tool_call_delta.function and tool_call_delta.function.arguments:  # noqa
-                                tool_calls_buffer[idx]["arguments"] += tool_call_delta.function.arguments  # noqa
-
-                    # 完成
-                    if choice.finish_reason:
-                        # AG-UI: 工具调用事件
-                        for tool_call_data in tool_calls_buffer.values():
-                            tool_calls.append(tool_call_data)
-
-                            # TOOL_CALL_START
-                            yield event.tool_call_start(
-                                tool_call_id=tool_call_data["id"],
-                                tool_call_name=tool_call_data["name"],
-                            )
+                    if self.max_tokens:
+                        kwargs["max_tokens"] = self.max_tokens
+
+                    if tools_schema:
+                        kwargs["tools"] = tools_schema
+                        kwargs["tool_choice"] = self.tool_choice
+
+                    self._apply_overrides(kwargs, self.request_overrides(context, turn, retry=attempt > 0) or {})
+                    # F6 LLM 钩子的调用方上下文（client 弹出，不透传给推理后端）
+                    kwargs["hook_meta"] = {"agent": self.name, "turn": turn, "retry": attempt > 0, "context": context}
 
-                            # TOOL_CALL_ARGS
-                            yield event.tool_call_args(
-                                tool_call_id=tool_call_data["id"],
-                                delta=tool_call_data["arguments"],
+                    stream = await client.chat(stream=True, **kwargs)
+
+                    async for chunk in stream:
+                        if not chunk.choices:
+                            continue
+
+                        choice = chunk.choices[0]
+                        delta = choice.delta
+
+                        # 内容增量 - AG-UI: TEXT_MESSAGE_CONTENT
+                        if delta.content:
+                            assistant_content += delta.content
+                            yield event.text_message_content(
+                                message_id=msg_id,
+                                delta=delta.content,
                             )
 
-                            # TOOL_CALL_END
-                            yield event.tool_call_end(tool_call_id=tool_call_data["id"])
+                        # 工具调用
+                        if delta.tool_calls:
+                            for tool_call_delta in delta.tool_calls:
+                                idx = tool_call_delta.index  # noqa
+                                if idx not in tool_calls_buffer:
+                                    tool_calls_buffer[idx] = {
+                                        "id": tool_call_delta.id or "",  # noqa
+                                        "name": "",
+                                        "arguments": "",
+                                    }
+
+                                if tool_call_delta.id:  # noqa
+                                    tool_calls_buffer[idx]["id"] = tool_call_delta.id  # noqa
+                                if tool_call_delta.function and tool_call_delta.function.name:  # noqa
+                                    tool_calls_buffer[idx]["name"] = tool_call_delta.function.name  # noqa
+                                if tool_call_delta.function and tool_call_delta.function.arguments:  # noqa
+                                    tool_calls_buffer[idx]["arguments"] += tool_call_delta.function.arguments  # noqa
+
+                        # 完成
+                        if choice.finish_reason:
+                            # AG-UI: 工具调用事件
+                            for tool_call_data in tool_calls_buffer.values():
+                                tool_calls.append(tool_call_data)
+
+                                # TOOL_CALL_START
+                                yield event.tool_call_start(
+                                    tool_call_id=tool_call_data["id"],
+                                    tool_call_name=tool_call_data["name"],
+                                )
 
-                        # 更新 usage
-                        if hasattr(chunk, "usage") and chunk.usage:
-                            context.add_usage(
-                                Usage(
-                                    prompt_tokens=chunk.usage.prompt_tokens or 0,
-                                    completion_tokens=chunk.usage.completion_tokens or 0,
-                                    total_tokens=chunk.usage.total_tokens or 0,
+                                # TOOL_CALL_ARGS
+                                yield event.tool_call_args(
+                                    tool_call_id=tool_call_data["id"],
+                                    delta=tool_call_data["arguments"],
                                 )
-                            )
 
-            except Exception as e:
-                error_msg = str(e)
-                # AG-UI: RUN_ERROR
-                yield event.run_error(message=error_msg)
-                raise FlowError("AGENT_EXECUTION_FAILED", 500, {"error": error_msg}) from e
+                                # TOOL_CALL_END
+                                yield event.tool_call_end(tool_call_id=tool_call_data["id"])
+
+                            # 更新 usage
+                            if hasattr(chunk, "usage") and chunk.usage:
+                                context.add_usage(
+                                    Usage(
+                                        prompt_tokens=chunk.usage.prompt_tokens or 0,
+                                        completion_tokens=chunk.usage.completion_tokens or 0,
+                                        total_tokens=chunk.usage.total_tokens or 0,
+                                    )
+                                )
+
+                except Exception as e:
+                    error_msg = str(e)
+                    # AG-UI: RUN_ERROR
+                    yield event.run_error(message=error_msg)
+                    raise FlowError("AGENT_EXECUTION_FAILED", 500, {"error": error_msg}) from e
+
+                if self.retry_empty_response and attempt == 0 and not tool_calls and not assistant_content.strip():
+                    attempt = 1
+                    continue
+                break
 
             # 保存 assistant 消息（tool_calls 转为 OpenAI 标准格式）
             if tool_calls:

{agstack-2.1.0 → agstack-2.3.0}/agstack/llm/flow/registry.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 import copy
 from typing import Any, cast
 
+from ..hooks import LLMCallHook, clear_llm_hooks, register_llm_hook
 from .agent import Agent
 from .tool import Tool, ToolHook, clear_tool_hooks, register_tool_hook
 
@@ -58,6 +59,17 @@ class FlowRegistry:
         """清空全局工具钩子（测试隔离用）"""
         clear_tool_hooks()
 
+    def register_llm_hook(self, hook: LLMCallHook, *, prepend: bool = False) -> None:
+        """注册全局 LLM 调用钩子（F6）：before_call 按注册顺序改写消息，after_call 逆序观察
+
+        钩子链存于 ``llm.hooks``（保持 registry → hooks 单向导入），此处仅转发注册。
+        """
+        register_llm_hook(hook, prepend=prepend)
+
+    def clear_llm_hooks(self) -> None:
+        """清空全局 LLM 调用钩子（测试隔离用）"""
+        clear_llm_hooks()
+
     def register_agent(
         self, name: str, agent_class: type[Agent], *, label: str | None = None, echo: bool = False
     ) -> None:

{agstack-2.1.0 → agstack-2.3.0}/agstack/llm/flow/tool.py

@@ -5,7 +5,7 @@
 import json
 import logging
 import time
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable
 
 
@@ -26,6 +26,8 @@ class ToolResult:
     error: str | None = None
     content: str | None = None
     summary: str | None = None
+    #: 钩子 / 工具附带的结构化信息（如 spill 落盘引用），不喂给模型
+    metadata: dict[str, Any] = field(default_factory=dict)
 
 
 class Deny:
@@ -61,6 +63,10 @@ class ToolHook:
         execution_records 三个出口同时生效。抛异常记日志并放行原结果
         （fail open：审计钩子的 bug 不毁掉主流程）。
         Deny 产生的失败结果同样穿过 post 链（审计要看到被拒绝的调用）。
+
+        进入 post 链时 ``result.content``（喂给模型的字符串）已按 result_formatter 算好：
+        钩子可直接改写 content（spill / 截断）；钩子若换掉 ``result.result`` 而未动 content，
+        Tool 会按新 result 重算 content（2.3 起；2.1 的「改 result 即改 content」语义保留）。
         """
         return result
 
@@ -161,9 +167,13 @@ class Tool:
         if result is None:
             result = await self._execute(context, args)
 
+        # 先算 LLM 消费内容，post 钩子据此判定 / 改写（spill、截断看到的是模型将看到的字符串）
+        result.content = self._render_content(result)
+
         # post 钩子链（逆序）：可改写结果；抛异常＝放行原结果（fail open）。
         # Deny 的失败结果同样穿过 post 链，审计钩子能看到被拒绝的调用。
         for hook in reversed(_TOOL_HOOKS):
+            before_result, before_content = result.result, result.content
             try:
                 revised = await hook.post_execute(context, self, result)
             except Exception as e:
@@ -173,26 +183,16 @@ class Tool:
                 result = revised
             else:
                 logger.warning("Tool hook post_execute for %s returned %r, ignored", self.name, type(revised))
+                continue
+            # 钩子换了 result 却没给新 content（None 或原样）：按新 result 重算
+            # （保持 2.1「改 result 即改模型所见」语义）
+            if result.result is not before_result and (result.content is None or result.content == before_content):
+                result.content = self._render_content(result)
+        if result.content is None:
+            result.content = self._render_content(result)
 
         _duration_ms = int((time.perf_counter() - _t0) * 1000)
 
-        # 计算 LLM 消费内容
-        if self.result_formatter:
-            try:
-                result.content = self.result_formatter(result)
-            except Exception:
-                result.content = (
-                    json.dumps(result.result, ensure_ascii=False)
-                    if result.success
-                    else json.dumps({"error": result.error}, ensure_ascii=False)
-                )
-        else:
-            result.content = (
-                json.dumps(result.result, ensure_ascii=False)
-                if result.success
-                else json.dumps({"error": result.error}, ensure_ascii=False)
-            )
-
         # 生成面向用户的摘要
         if self.summary_fn:
             try:
@@ -215,6 +215,20 @@ class Tool:
 
         return result
 
+    def _render_content(self, result: ToolResult) -> str:
+        """按 result_formatter（失败回退 JSON）算喂给模型的内容"""
+        fallback = (
+            json.dumps(result.result, ensure_ascii=False)
+            if result.success
+            else json.dumps({"error": result.error}, ensure_ascii=False)
+        )
+        if not self.result_formatter:
+            return fallback
+        try:
+            return self.result_formatter(result)
+        except Exception:
+            return fallback
+
     async def _execute(self, context: "FlowContext", inputs: dict[str, Any]) -> ToolResult:
         """实际执行逻辑，子类应覆写此方法"""
         try:

agstack-2.3.0/agstack/llm/harness/__init__.py

@@ -0,0 +1,51 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""agstack.llm.harness——模型无关、表无关、产品无关的运行时部件
+
+- :mod:`.ports`：存储端口声明（SessionLog / SpillStore / UsageSink / KVStore）与 ``register_ports``，
+  由应用实现并在进程入口注册；
+- :mod:`.truncation`：工具结果截断设施（保头尾截断、按相关度整条丢弃），策略数值由调用方给；
+- :mod:`.spill`：超长工具结果落盘的 ToolHook（prepend 链头、按内联 token 上限判定、头尾保留 + 固定格式通知、
+  存储失败保留内联）。
+
+2.3 只收这三块零状态模块与端口声明；events / projection / tokens / AgentGuards 排 2.4，context / overflow 排 3.0。
+"""
+
+from .ports import (
+    KVStore,
+    LogEvent,
+    Ports,
+    SessionLog,
+    SpillOwner,
+    SpillRef,
+    SpillSource,
+    SpillStore,
+    TokenAnchor,
+    UsageSink,
+    clear_ports,
+    get_ports,
+    register_ports,
+)
+from .spill import SpillHook, SpillPolicy
+from .truncation import clamp_results, truncate_middle
+
+
+__all__ = [
+    "KVStore",
+    "LogEvent",
+    "Ports",
+    "SessionLog",
+    "SpillHook",
+    "SpillOwner",
+    "SpillPolicy",
+    "SpillRef",
+    "SpillSource",
+    "SpillStore",
+    "TokenAnchor",
+    "UsageSink",
+    "clamp_results",
+    "clear_ports",
+    "get_ports",
+    "register_ports",
+    "truncate_middle",
+]