aaas 0.2.0__py3-none-any.whl

aaas/__init__.py

@@ -0,0 +1,146 @@
+"""`aaas` —— Agent as a Service 协议的 Python SDK。
+
+**一句话**：调用方在一条连接之内声明一个 Agent（职责 + 每个能力带完整参数 schema），
+服务端用模型驱动它，而**每个能力的执行体始终留在调用方进程内**。
+
+两种角色，各一个入口：
+
+``aaas.Caller``
+    你是调用方。你声明 Agent、开一轮、并在自己进程里执行 function。
+    服务端会反向发 ``aaas/invokeFunction``，:class:`~aaas.caller.Caller` 替你接住它。
+
+``aaas.Server``
+    你是服务端。你实现 :class:`~aaas.server.TurnContext` 那一段业务（接模型），
+    协议层（信封、id 分区、seq 连续、取消次序、断连收尾）由它负责。
+
+最小可跑的一段::
+
+    import asyncio, aaas
+
+    @aaas.function
+    async def search_local_index(query: str) -> str:
+        \"\"\"在调用方的本地持仓索引里检索
+
+        Args:
+            query: 检索词
+        \"\"\"
+        return f"找到 3 条匹配 {query} 的记录"
+
+    async def agent(ctx: aaas.TurnContext) -> None:
+        result = await ctx.call("search_local_index", {"query": ctx.text})
+        ctx.reply(*(p.text for p in (result.parts or ()) if p.text))
+
+    async def main() -> None:
+        server = await aaas.Server(agent).start(port=8765)
+        async with aaas.Caller("ws://127.0.0.1:8765", tools=[search_local_index]) as caller:
+            await caller.declare(aaas.AgentDefinition(
+                revision="v1",
+                instructions="你正在协助用户操作债券计算器。",
+                functions=(search_local_index.declaration,),
+            ))
+            turn = await caller.send("查一下持仓")
+            async for event in turn:
+                if event.kind == "message.completed":
+                    print([p.text for p in event.parts])
+        await server.close()
+
+    asyncio.run(main())
+
+想直接看效果：``python -m aaas``。
+"""
+
+from __future__ import annotations
+
+from .caller import OPTIONAL_FEATURES, REQUIRED_FEATURES, Caller, ConnectResult, Turn
+from .errors import (
+    AAASError,
+    AgentDefinitionInvalid,
+    AgentNotDeclared,
+    FunctionUnknown,
+    LimitExceeded,
+    Overloaded,
+    RateLimited,
+    SessionNotFound,
+    TurnLimitExceeded,
+    TurnNotFound,
+    Unauthenticated,
+    UnsupportedFeature,
+    UnsupportedVersion,
+    connection_lost,
+)
+from .function import FunctionRegistry, Tool, function
+from .server import Connection, Server, Session, TurnContext
+from .types import (
+    EVENT_KINDS,
+    AgentDefinition,
+    ErrorInfo,
+    Event,
+    FunctionCall,
+    FunctionDeclaration,
+    FunctionResult,
+    Message,
+    Part,
+    Usage,
+)
+from .wire import IdAllocator, Parsed, ParseFailure
+
+__version__ = "0.2.0"
+
+#: 协议主版本 —— 线上出现在 ``connect.params.protocolVersion``（``PROTOCOL.md`` §5.1.1）。
+PROTOCOL_VERSION = "1"
+
+#: WS 子协议名（§5.1）。它与 :data:`PROTOCOL_VERSION` 是两个不同的契约。
+SUBPROTOCOL = "aaas.v1"
+
+__all__ = [
+    # 两个入口
+    "Caller",
+    "Server",
+    # 调用方侧
+    "Turn",
+    "ConnectResult",
+    # 服务端侧
+    "TurnContext",
+    "Connection",
+    "Session",
+    # 能力
+    "function",
+    "Tool",
+    "FunctionRegistry",
+    # 数据模型
+    "AgentDefinition",
+    "FunctionDeclaration",
+    "Message",
+    "Part",
+    "Event",
+    "FunctionCall",
+    "FunctionResult",
+    "Usage",
+    "ErrorInfo",
+    "EVENT_KINDS",
+    # 错误
+    "AAASError",
+    "AgentDefinitionInvalid",
+    "AgentNotDeclared",
+    "FunctionUnknown",
+    "LimitExceeded",
+    "Overloaded",
+    "RateLimited",
+    "SessionNotFound",
+    "TurnLimitExceeded",
+    "TurnNotFound",
+    "Unauthenticated",
+    "UnsupportedFeature",
+    "UnsupportedVersion",
+    "connection_lost",
+    # 信封
+    "IdAllocator",
+    "Parsed",
+    "ParseFailure",
+    # 常量
+    "__version__",
+    "PROTOCOL_VERSION",
+    "SUBPROTOCOL",
+    "REQUIRED_FEATURES",
+    "OPTIONAL_FEATURES",
+]

aaas/__main__.py

@@ -0,0 +1,124 @@
+"""``python -m aaas`` —— 一条连接上跑完「声明 → 一轮 → 反向 function calling」。
+
+这是那个「10 分钟」判据的可执行版本。它同时是自检：四段都跑通，说明
+``connect`` / ``declareAgent`` / ``sendInput`` / ``invokeFunction`` / ``event`` 五个方法
+在两侧都接上了。
+
+    $ python -m aaas
+    [server] listening on ws://127.0.0.1:8765
+    [caller] connected  session=sess_… features=[…] history=stateless
+    [caller] declared   revision=bond-calc-v1 functions=['search_local_index']
+    [server] turn turn_… started
+    [tool  ] search_local_index({'query': '查一下持仓'}) → 找到 3 条匹配「查一下持仓」的记录
+    [caller] message.completed  找到 3 条匹配「查一下持仓」的记录
+    [caller] turn.completed     status=completed finishReason=stop calls=1
+    [caller] diagnostics        0 条
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Any
+
+import aaas
+
+#: 一个「本地」能力 —— 它的执行体只在这一个进程里（§1.2 G2）。
+HOLDINGS = {
+    "持仓": ["国债 24 附息 03", "地方债 23 粤 12", "政金债 22 国开 07"],
+}
+
+
+@aaas.function
+async def search_local_index(query: str, page_size: int = 10) -> str:
+    """在调用方的本地持仓索引里检索
+
+    Args:
+        query: 检索词
+        page_size: 每页条数
+    """
+    hits = [name for name in HOLDINGS["持仓"] if query in name or "持仓" in query]
+    hits = hits[:page_size]
+    return f"找到 {len(hits)} 条匹配「{query}」的记录：" + "、".join(hits)
+
+
+async def tiny_agent(ctx: aaas.TurnContext) -> None:
+    """一个不接模型的「模型」：它只证明链路是通的。
+
+    真实实现把这一段换成你的 LLM 调用。要发什么事件、``seq`` 怎么排、
+    调用怎么超时、取消怎么收尾 —— 都由 :class:`aaas.TurnContext` 负责。
+    """
+    print(f"[server] turn {ctx.turn_id} started  text={ctx.text!r}")
+
+    # 推理事件只在协商了 reasoning 时才会真的发出去。
+    ctx.reasoning("用户问的是本地索引，先调一次工具。")
+
+    result = await ctx.call("search_local_index", {"query": ctx.text})
+    if result.parts:
+        for part in result.parts:
+            if part.text:
+                print(f"[tool  ] search_local_index → {part.text}")
+                ctx.delta(part.text)
+                ctx.reply(part.text)
+    ctx.usage_of(output_tokens=42)
+
+
+async def main() -> int:
+    port = 8765
+    server = await aaas.Server(tiny_agent).start("127.0.0.1", port)
+    print(f"[server] listening on ws://127.0.0.1:{port}")
+
+    try:
+        async with aaas.Caller(
+            f"ws://127.0.0.1:{port}", tools=[search_local_index]
+        ) as caller:
+            info = caller.connect_result
+            assert info is not None
+            print(
+                f"[caller] connected  session={info.session_id} "
+                f"features={list(info.features)} history={info.history_mode}"
+            )
+
+            revision, names = await caller.declare(
+                aaas.AgentDefinition(
+                    revision="bond-calc-v1",
+                    instructions="你正在协助用户操作债券计算器。金额单位是万元。",
+                    functions=(search_local_index.declaration,),
+                )
+            )
+            print(f"[caller] declared   revision={revision} functions={list(names)}")
+
+            turn = await caller.send("查一下持仓")
+            async for event in turn:
+                if event.kind == "message.completed":
+                    text = "".join(p.text or "" for p in (event.parts or ()))
+                    print(f"[caller] message.completed  {text}")
+                elif event.kind == "turn.completed":
+                    calls = event.usage.calls if event.usage else None
+                    print(
+                        f"[caller] turn.completed     status={event.status} "
+                        f"finishReason={event.finish_reason} calls={calls}"
+                    )
+
+            final = await turn.end()
+            print(f"[caller] text={turn.text!r} ok={turn.ok}")
+
+            if caller.diagnostics:
+                print(f"[caller] diagnostics={len(caller.diagnostics)}")
+                for entry in caller.diagnostics:
+                    print(f"         {entry['code']}: {entry['message']}")
+            else:
+                print("[caller] diagnostics        0 条（没有观测到对端违规）")
+
+            if final.status != "completed":
+                print(f"[fail  ] 本轮没有正常完成：{final.status}", file=sys.stderr)
+                return 1
+    finally:
+        await server.close()
+
+    print("[ok] 一轮含反向 function calling 已跑完")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))

aaas/_jsonschema.py

@@ -0,0 +1,208 @@
+"""一个**故意很小**的 JSON Schema 校验器 —— 只为落实 §7 第 4 条。
+
+规范要求：``invokeFunction.arguments`` 的源头是模型输出，MUST 被调用方当作
+**不可信输入**处理，执行前按 ``FunctionDeclaration.parameters`` 校验（§7 第 4 条）。
+这条 MUST 需要一个校验器，但它不需要一个完整实现。
+
+三条设计取舍，都是为了让「宁可放过、绝不误拒」成立：
+
+1. **不认识的 keyword 一律忽略。** 声明里的 ``format`` / ``$schema`` / 自定义注解
+   不是拒绝的理由 —— 误拒合法参数比漏放一次非法参数更坏：前者会让一个健康的调用
+   永久失败，而模型无从知道为什么。
+2. **没有第三方依赖。** 引 ``jsonschema`` 会让这个包为了 150 行逻辑背上整个依赖树，
+   而 SDK 的定位是「装上就能用」。
+3. **错误带 JSON Pointer 路径。** 模型看到 ``/page_size: 期望 integer`` 才知道该改哪一格；
+   看到一句「参数不合法」它只会换个参数再撞一次。
+
+支持的关键字：``type`` ``enum`` ``const`` ``properties`` ``required``
+``additionalProperties`` ``items`` ``minimum`` ``maximum`` ``exclusiveMinimum``
+``exclusiveMaximum`` ``minLength`` ``maxLength`` ``pattern`` ``minItems`` ``maxItems``
+``anyOf`` ``oneOf`` ``allOf`` ``$ref``（仅本文件内 ``#/$defs/…``）。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+__all__ = ["validate", "SchemaSubset"]
+
+_TYPES = {
+    "object": dict,
+    "array": list,
+    "string": str,
+    "boolean": bool,
+    "null": type(None),
+}
+
+
+class SchemaSubset:
+    """校验一个实例。``validate`` 返回错误清单，空清单即通过。"""
+
+    def __init__(self, root: dict[str, Any] | None = None) -> None:
+        self.root = root or {}
+
+    def validate(self, instance: Any, schema: dict[str, Any] | None = None) -> list[str]:
+        """→ ``["/page_size: 期望 integer，收到 string"]`` 形式的错误清单。"""
+        return self._walk(instance, schema if schema is not None else self.root, "")
+
+    # ------------------------------------------------------------------ 内部
+
+    def _resolve(self, schema: dict[str, Any]) -> dict[str, Any]:
+        """只解析 ``#/$defs/…`` —— 支持外部 ``$ref`` 会把这件事变成一次网络与文件系统请求。"""
+        ref = schema.get("$ref")
+        if not isinstance(ref, str):
+            return schema
+        if not ref.startswith("#/"):
+            return {}  # 外部引用：不认识 → 按「无约束」处理（宁可放过）
+        node: Any = {"$defs": self.root.get("$defs", {})}
+        for part in ref[2:].split("/"):
+            part = part.replace("~1", "/").replace("~0", "~")
+            if not isinstance(node, dict) or part not in node:
+                return {}
+            node = node[part]
+        return node if isinstance(node, dict) else {}
+
+    def _walk(self, inst: Any, schema: dict[str, Any], path: str) -> list[str]:
+        schema = self._resolve(schema)
+        errs: list[str] = []
+        where = path or "/"
+
+        # const / enum —— 最便宜的两个先判
+        if "const" in schema and inst != schema["const"]:
+            errs.append(f"{where}: 期望 {schema['const']!r}，收到 {inst!r}")
+        if "enum" in schema and inst not in schema["enum"]:
+            errs.append(f"{where}: 必须是 {schema['enum']} 之一，收到 {inst!r}")
+
+        # type —— 注意 bool 是 int 的子类，顺序要小心
+        want = schema.get("type")
+        if isinstance(want, str):
+            if not _is_type(inst, want):
+                errs.append(f"{where}: 期望 {want}，收到 {_type_name(inst)}")
+                return errs
+        elif isinstance(want, list):
+            if not any(_is_type(inst, w) for w in want):
+                errs.append(f"{where}: 期望 {'/'.join(want)} 之一，收到 {_type_name(inst)}")
+                return errs
+
+        if isinstance(inst, str):
+            errs += self._strings(inst, schema, where)
+        if isinstance(inst, (int, float)) and not isinstance(inst, bool):
+            errs += self._numbers(inst, schema, where)
+        if isinstance(inst, dict):
+            errs += self._objects(inst, schema, path)
+        if isinstance(inst, list):
+            errs += self._arrays(inst, schema, path)
+
+        for key in ("allOf",):
+            for sub in schema.get(key, ()) if isinstance(schema.get(key), list) else ():
+                errs += self._walk(inst, sub, path)
+        if isinstance(schema.get("anyOf"), list):
+            if not any(not self._walk(inst, s, path) for s in schema["anyOf"]):
+                errs.append(f"{where}: 不满足 anyOf 中任何一支")
+        if isinstance(schema.get("oneOf"), list):
+            hits = sum(1 for s in schema["oneOf"] if not self._walk(inst, s, path))
+            if hits != 1:
+                errs.append(f"{where}: oneOf 要求恰好命中一支，实际命中 {hits} 支")
+        return errs
+
+    def _strings(self, inst: str, schema: dict[str, Any], where: str) -> list[str]:
+        errs = []
+        if "minLength" in schema and len(inst) < schema["minLength"]:
+            errs.append(f"{where}: 长度不得小于 {schema['minLength']}")
+        if "maxLength" in schema and len(inst) > schema["maxLength"]:
+            errs.append(f"{where}: 长度不得大于 {schema['maxLength']}")
+        pattern = schema.get("pattern")
+        if isinstance(pattern, str):
+            try:
+                if not re.search(pattern, inst):
+                    errs.append(f"{where}: 不匹配 {pattern}")
+            except re.error:
+                pass  # 声明里的正则本身写坏了 → 不能因此拒掉数据
+        return errs
+
+    def _numbers(self, inst: float, schema: dict[str, Any], where: str) -> list[str]:
+        errs = []
+        if "minimum" in schema and inst < schema["minimum"]:
+            errs.append(f"{where}: 不得小于 {schema['minimum']}")
+        if "maximum" in schema and inst > schema["maximum"]:
+            errs.append(f"{where}: 不得大于 {schema['maximum']}")
+        if "exclusiveMinimum" in schema and inst <= schema["exclusiveMinimum"]:
+            errs.append(f"{where}: 必须大于 {schema['exclusiveMinimum']}")
+        if "exclusiveMaximum" in schema and inst >= schema["exclusiveMaximum"]:
+            errs.append(f"{where}: 必须小于 {schema['exclusiveMaximum']}")
+        return errs
+
+    def _objects(self, inst: dict[str, Any], schema: dict[str, Any], path: str) -> list[str]:
+        errs = []
+        for name in schema.get("required", ()) if isinstance(schema.get("required"), list) else ():
+            if name not in inst:
+                errs.append(f"{path}/{name}: 必填字段缺失")
+        props = schema.get("properties")
+        props = props if isinstance(props, dict) else {}
+        for name, value in inst.items():
+            child = f"{path}/{name}"
+            if name in props:
+                errs += self._walk(value, props[name], child)
+                continue
+            extra = schema.get("additionalProperties")
+            if extra is False:
+                errs.append(f"{child}: 不允许的字段（additionalProperties: false）")
+            elif isinstance(extra, dict):
+                errs += self._walk(value, extra, child)
+        return errs
+
+    def _arrays(self, inst: list[Any], schema: dict[str, Any], path: str) -> list[str]:
+        errs = []
+        if "minItems" in schema and len(inst) < schema["minItems"]:
+            errs.append(f"{path or '/'}: 至少 {schema['minItems']} 项")
+        if "maxItems" in schema and len(inst) > schema["maxItems"]:
+            errs.append(f"{path or '/'}: 至多 {schema['maxItems']} 项")
+        items = schema.get("items")
+        if isinstance(items, dict):
+            for i, value in enumerate(inst):
+                errs += self._walk(value, items, f"{path}/{i}")
+        return errs
+
+
+def _type_name(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int):
+        return "integer"
+    if isinstance(value, float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__
+
+
+def _is_type(value: Any, want: str) -> bool:
+    if want == "integer":
+        # 3.0 是 integer：JSON 里没有 3 与 3.0 的区别，而模型常把 10 写成 10.0。
+        return isinstance(value, int) and not isinstance(value, bool) or (
+            isinstance(value, float) and value.is_integer()
+        )
+    if want == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if want == "boolean":
+        return isinstance(value, bool)
+    expected = _TYPES.get(want)
+    if expected is None:
+        return True  # 不认识的类型名 → 无约束
+    if want == "object":
+        return isinstance(value, dict)
+    if want == "array":
+        return isinstance(value, list)
+    return isinstance(value, expected)
+
+
+def validate(instance: Any, schema: dict[str, Any] | None = None) -> list[str]:
+    """便捷入口：``validate(args, decl.parameters)`` → 错误清单。"""
+    return SchemaSubset(schema).validate(instance, schema)