agstack 2.4.0__tar.gz → 3.0.0__tar.gz

{agstack-2.4.0 → agstack-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 2.4.0
+Version: 3.0.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>
@@ -86,7 +86,7 @@ pip install agstack
 ### Basic Usage
 
 ```python
-from agstack.llm.flow import (
+from agstack.genai.flow import (
     Tool,
     FlowContext,
     registry,
@@ -130,13 +130,10 @@ agstack/
 ├── schema.py          # Base Pydantic models
 ├── registry.py        # Global component registry
 ├── exceptions.py      # Exception hierarchy
-├── llm/              # LLM and AI features
-│   ├── client.py     # LLM client
-│   └── flow/         # Flow execution framework
-│       ├── agent.py  # Agent definition
-│       ├── tool.py   # Tool definition
-│       ├── flow.py   # Flow orchestration
-│       └── ...
+├── genai/            # Generative AI, three one-way layers
+│   ├── llm/          # Model access: client, call hooks, prompts, token counting
+│   ├── flow/         # Flow execution framework (agent / tool / flow / nodes / guards)
+│   └── harness/      # Runtime: ports, events, projection, metering, overflow, context, spill
 ├── fastapi/          # FastAPI integration
 ├── infra/            # Infrastructure components
 │   ├── db/           # Database

{agstack-2.4.0 → agstack-3.0.0}/README.md

@@ -28,7 +28,7 @@ pip install agstack
 ### Basic Usage
 
 ```python
-from agstack.llm.flow import (
+from agstack.genai.flow import (
     Tool,
     FlowContext,
     registry,
@@ -72,13 +72,10 @@ agstack/
 ├── schema.py          # Base Pydantic models
 ├── registry.py        # Global component registry
 ├── exceptions.py      # Exception hierarchy
-├── llm/              # LLM and AI features
-│   ├── client.py     # LLM client
-│   └── flow/         # Flow execution framework
-│       ├── agent.py  # Agent definition
-│       ├── tool.py   # Tool definition
-│       ├── flow.py   # Flow orchestration
-│       └── ...
+├── genai/            # Generative AI, three one-way layers
+│   ├── llm/          # Model access: client, call hooks, prompts, token counting
+│   ├── flow/         # Flow execution framework (agent / tool / flow / nodes / guards)
+│   └── harness/      # Runtime: ports, events, projection, metering, overflow, context, spill
 ├── fastapi/          # FastAPI integration
 ├── infra/            # Infrastructure components
 │   ├── db/           # Database

agstack-3.0.0/agstack/genai/__init__.py

@@ -0,0 +1,10 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""agstack.genai——生成式 AI 三层（3.0）
+
+- :mod:`.llm`：模型接入（client / hooks / prompts / token），不依赖另外两层；
+- :mod:`.flow`：编排（Agent / Tool / Flow / nodes / guards），依赖 llm；
+- :mod:`.harness`：运行时纪律（ports / events / projection / metering / context / overflow / spill），依赖 llm 与 flow。
+
+依赖单向、不成环；应用对本包的依赖应集中在一处适配层。
+"""

{agstack-2.4.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/agent.py

@@ -7,7 +7,8 @@ import json
 from typing import TYPE_CHECKING, Any, AsyncIterator
 from uuid import uuid4
 
-from ..client import get_llm_client
+from ..harness.overflow import OverflowPolicy, classify_overflow, usage_tokens
+from ..llm.client import get_llm_client
 from . import event
 from .context import Usage
 from .event import EventType
@@ -22,6 +23,9 @@ if TYPE_CHECKING:
 class Agent:
     """Agent 定义"""
 
+    #: 上下文溢出恢复策略（harness.overflow；None 不恢复）。子类可按类属性给缺省，构造参数 ``overflow`` 覆盖
+    overflow: OverflowPolicy | None = None
+
     def __init__(
         self,
         name: str,
@@ -37,6 +41,7 @@ class Agent:
         retry_empty_response: bool = False,
         label: str | None = None,
         echo: bool = False,
+        overflow: OverflowPolicy | None = None,
     ):
         """初始化 Agent
 
@@ -52,6 +57,7 @@ class Agent:
             以 ``request_overrides(..., retry=True)`` 的覆盖参数重试一次
         :param label: 面向用户的展示名称（控制 STEP 进度事件可见性）
         :param echo: 是否转发 TEXT_MESSAGE 给用户
+        :param overflow: 上下文溢出恢复策略（三态判定命中后调 ``compact`` 压缩并同轮重发一次，见 harness.overflow）
         """
         self.name = name
         self.instructions = instructions or f"You are {name}, a helpful AI assistant."
@@ -65,6 +71,8 @@ class Agent:
         self.retry_empty_response = retry_empty_response
         self.label = label
         self.echo = echo
+        if overflow is not None:
+            self.overflow = overflow
 
     def get_system_message(self) -> dict[str, Any]:
         """获取系统消息"""
@@ -102,6 +110,25 @@ class Agent:
                 return tool
         return None
 
+    # ── 溢出恢复（机制；策略在 self.overflow） ──
+
+    def _max_recoveries(self) -> int:
+        return self.overflow.max_recoveries if self.overflow is not None else 0
+
+    def _overflow_kind(self, context: "FlowContext", *, error: BaseException | None = None, **usage: Any) -> str | None:
+        if self.overflow is None:
+            return None
+        if error is not None:
+            return classify_overflow(error=error)
+        return classify_overflow(context_length=self.overflow.window(context), **usage)
+
+    async def _compact_overflow(self, context: "FlowContext", kind: str) -> bool:
+        assert self.overflow is not None
+        try:
+            return bool(await self.overflow.compact(context, kind))
+        except Exception:  # noqa: BLE001 — 压缩失败不替代原错误，按原路报错
+            return False
+
     def _group_tool_calls(self, tool_calls: list[dict[str, Any]]) -> list[list[dict[str, Any]]]:
         """按声明分组：连续的 concurrency_safe 调用聚为一组并发执行，其余单独成组串行
 
@@ -290,6 +317,7 @@ class Agent:
 
         # Agent 循环
         assistant_content = ""
+        recoveries = 0  # 溢出恢复次数（每次运行上限 overflow.max_recoveries）
         for turn in range(1, self.max_turns + 1):
             # 协作式取消检查点：不再开始新的 LLM 轮次
             if context.is_cancelled:
@@ -306,6 +334,8 @@ class Agent:
                 assistant_content = ""
                 tool_calls: list[dict[str, Any]] = []
                 tool_calls_buffer: dict[int, dict[str, Any]] = {}
+                finish_reason: str | None = None
+                turn_usage: Any = None
 
                 try:
                     kwargs: dict[str, Any] = {
@@ -362,6 +392,7 @@ class Agent:
 
                         # 完成
                         if choice.finish_reason:
+                            finish_reason = choice.finish_reason
                             # AG-UI: 工具调用事件
                             for tool_call_data in tool_calls_buffer.values():
                                 tool_calls.append(tool_call_data)
@@ -383,6 +414,7 @@ class Agent:
 
                             # 更新 usage
                             if hasattr(chunk, "usage") and chunk.usage:
+                                turn_usage = chunk.usage
                                 context.add_usage(
                                     Usage(
                                         prompt_tokens=chunk.usage.prompt_tokens or 0,
@@ -392,11 +424,39 @@ class Agent:
                                 )
 
                 except Exception as e:
+                    # 上下文溢出（后端报错态）：尚未放出任何内容时压缩并同轮重发一次（harness.overflow）
+                    kind = self._overflow_kind(context, error=e) if not assistant_content and not tool_calls else None
+                    if kind and recoveries < self._max_recoveries():
+                        recoveries += 1
+                        yield event.custom(
+                            name="agent_overflow", value={"agentName": self.name, "kind": kind, "turn": turn}
+                        )
+                        if await self._compact_overflow(context, kind):
+                            messages = [self.get_system_message()] + context.history + context.get_messages(self.name)
+                            continue
                     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
 
+                # 上下文溢出（静默 / length 态）：请求成功但输入已撑爆窗口且本次没有产出，同样压缩重发一次
+                if not tool_calls and not assistant_content.strip():
+                    prompt_tokens, completion_tokens = usage_tokens(turn_usage)
+                    kind = self._overflow_kind(
+                        context,
+                        finish_reason=finish_reason,
+                        prompt_tokens=prompt_tokens,
+                        completion_tokens=completion_tokens,
+                    )
+                    if kind and recoveries < self._max_recoveries():
+                        recoveries += 1
+                        yield event.custom(
+                            name="agent_overflow", value={"agentName": self.name, "kind": kind, "turn": turn}
+                        )
+                        if await self._compact_overflow(context, kind):
+                            messages = [self.get_system_message()] + context.history + context.get_messages(self.name)
+                            continue
+
                 if self.retry_empty_response and attempt == 0 and not tool_calls and not assistant_content.strip():
                     attempt = 1
                     continue

{agstack-2.4.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/nodes/detect_node.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Any
 
 from openai.types.chat import ChatCompletionMessageParam
 
-from ...client import get_llm_client
+from ...llm.client import get_llm_client
 from ..context import Usage
 from .base import NodeHandler
 

{agstack-2.4.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/nodes/echo_node.py

@@ -5,12 +5,12 @@
 from typing import TYPE_CHECKING, Any, AsyncIterator
 from uuid import uuid4
 
-from agstack.llm.flow import event
-from agstack.llm.flow.nodes.base import NodeHandler
+from agstack.genai.flow import event
+from agstack.genai.flow.nodes.base import NodeHandler
 
 
 if TYPE_CHECKING:
-    from agstack.llm.flow.context import FlowContext
+    from agstack.genai.flow.context import FlowContext
 
 
 class EchoNodeHandler(NodeHandler):

{agstack-2.4.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/nodes/llm_chat_node.py

@@ -8,7 +8,7 @@ from uuid import uuid4
 
 from openai.types.chat import ChatCompletionMessageParam
 
-from ...client import get_llm_client
+from ...llm.client import get_llm_client
 from .. import event
 from ..context import Usage
 from .base import NodeHandler

{agstack-2.4.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/nodes/llm_embed_node.py

@@ -4,7 +4,7 @@
 
 from typing import TYPE_CHECKING, Any
 
-from ...client import get_llm_client
+from ...llm.client import get_llm_client
 from .base import NodeHandler
 
 

{agstack-2.4.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/nodes/llm_rerank_node.py

@@ -4,7 +4,7 @@
 
 from typing import TYPE_CHECKING, Any
 
-from ...client import get_llm_client
+from ...llm.client import get_llm_client
 from .base import NodeHandler
 
 

{agstack-2.4.0/agstack/llm → agstack-3.0.0/agstack/genai}/flow/registry.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 import copy
 from typing import Any, cast
 
-from ..hooks import LLMCallHook, clear_llm_hooks, register_llm_hook
+from ..llm.hooks import LLMCallHook, clear_llm_hooks, register_llm_hook
 from .agent import Agent
 from .tool import Tool, ToolHook, clear_tool_hooks, register_tool_hook
 

agstack-3.0.0/agstack/genai/harness/__init__.py

@@ -0,0 +1,120 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""agstack.genai.harness——模型无关、表无关、产品无关的运行时部件
+
+- :mod:`.ports`：存储端口声明（SessionLog / SpillStore / UsageSink / KVStore）与 ``register_ports``，
+  由应用实现并在进程入口注册；
+- :mod:`.truncation`：工具结果截断设施（保头尾截断、按相关度整条丢弃），策略数值由调用方给；
+- :mod:`.spill`：超长工具结果落盘的 ToolHook（prepend 链头、按内联 token 上限判定、头尾保留 + 固定格式通知、
+  存储失败保留内联）；
+- :mod:`.events`（2.4）：任务事件枢纽 EventHub（序号 / 快照 / 订阅 / 重放，持久化由应用注入）与「flow 事件 → 用户可见
+  事件」过滤规则表；
+- :mod:`.projection`（2.4）：「日志 → 模型历史」投影引擎（遮蔽过滤 / 事件投影 / 正文改写 / 注记 / 同角色合并，
+  规则由应用给）；
+- :mod:`.metering`（2.4，原 tokens）：估算校准（实报 / 估算钳制）与锚点增量计量；
+- :mod:`.context`（3.0）：对话上下文压缩引擎 ContextEngine（预算分层 / 快速路径 / 锚点计量 / 摘要消费与后台刷新 /
+  两遍装填），历史来源与摘要存取经 HistorySource / SummaryStore 由应用实现；
+- :mod:`.overflow`（3.0）：上下文溢出三态判定与 ``OverflowPolicy``（``Agent.stream`` 命中后调应用的压缩协程并
+  同轮重发一次）。
+
+LLM 调用钩子 :mod:`agstack.genai.llm.hooks`（F6）留在 llm 包——它织入 LLMClient，client 不能反向依赖 harness——
+这里重导出。Agent 守卫机制（AgentGuards）在 :mod:`agstack.genai.flow.guards`。
+3.0 起 llm / flow / harness 收为 ``agstack.genai`` 三层，``agstack.genai.llm`` 只留模型接入（client / hooks / prompts /
+token）；2.x 的 ``agstack.llm`` 系路径不再保留（破坏性变更，随 major）。
+"""
+
+from ..llm.hooks import CallMeta, LLMCallHook, StreamSummary, clear_llm_hooks, register_llm_hook
+from .context import (
+    ContextEngine,
+    ContextPolicy,
+    HistorySource,
+    SummaryRecord,
+    SummaryStore,
+    anchored_history_tokens,
+    fill_to_budget,
+    messages_tokens,
+    schedule_once,
+)
+from .events import EventHub, TaskSnapshot, filter_user_event
+from .metering import CalibratedCounter, anchored_estimate, calibration_from_samples, calibration_sample, clamp_ratio
+from .overflow import (
+    OVERFLOW_ERROR,
+    OVERFLOW_LENGTH,
+    OVERFLOW_RECORD,
+    OVERFLOW_SILENT,
+    OverflowPolicy,
+    classify_overflow,
+    usage_tokens,
+)
+from .ports import (
+    KVStore,
+    LogEvent,
+    Ports,
+    SessionLog,
+    SpillOwner,
+    SpillRef,
+    SpillSource,
+    SpillStore,
+    TokenAnchor,
+    UsageSink,
+    clear_ports,
+    get_ports,
+    register_ports,
+)
+from .projection import Projection, is_shadowed, merge_consecutive, select_recent
+from .spill import SpillHook, SpillPolicy
+from .truncation import clamp_results, truncate_middle
+
+
+__all__ = [
+    "ContextEngine",
+    "ContextPolicy",
+    "HistorySource",
+    "SummaryRecord",
+    "SummaryStore",
+    "anchored_history_tokens",
+    "fill_to_budget",
+    "messages_tokens",
+    "schedule_once",
+    "CallMeta",
+    "LLMCallHook",
+    "StreamSummary",
+    "clear_llm_hooks",
+    "register_llm_hook",
+    "OVERFLOW_ERROR",
+    "OVERFLOW_LENGTH",
+    "OVERFLOW_RECORD",
+    "OVERFLOW_SILENT",
+    "CalibratedCounter",
+    "EventHub",
+    "OverflowPolicy",
+    "Projection",
+    "classify_overflow",
+    "usage_tokens",
+    "TaskSnapshot",
+    "anchored_estimate",
+    "calibration_from_samples",
+    "calibration_sample",
+    "clamp_ratio",
+    "filter_user_event",
+    "is_shadowed",
+    "merge_consecutive",
+    "select_recent",
+    "KVStore",
+    "LogEvent",
+    "Ports",
+    "SessionLog",
+    "SpillHook",
+    "SpillOwner",
+    "SpillPolicy",
+    "SpillRef",
+    "SpillSource",
+    "SpillStore",
+    "TokenAnchor",
+    "UsageSink",
+    "clamp_results",
+    "clear_ports",
+    "get_ports",
+    "register_ports",
+    "truncate_middle",
+]