capability-runtime 0.1.0__py3-none-any.whl

capability_runtime/protocol/context.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+"""执行上下文——跨能力状态传递和调用链管理。"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any, Dict, List, Optional
+
+
+class RecursionLimitError(Exception):
+    """嵌套深度超限。"""
+
+
+class CancellationToken:
+    """协作取消 token（不强制打断正在运行的步骤）。"""
+
+    def __init__(self) -> None:
+        import asyncio
+
+        self._event = asyncio.Event()
+
+    @property
+    def is_cancelled(self) -> bool:
+        """是否已被标记为取消。"""
+
+        return self._event.is_set()
+
+    def cancel(self) -> None:
+        """标记为取消。"""
+
+        self._event.set()
+
+    async def wait(self) -> None:
+        """等待取消发生。"""
+
+        await self._event.wait()
+
+
+@dataclass
+class ExecutionContext:
+    """
+    执行上下文。
+
+    参数：
+    - run_id: 顶层运行 ID
+    - parent_context: 父上下文（用于追溯调用链）
+    - depth: 当前嵌套深度（从 0 开始）
+    - max_depth: 最大嵌套深度
+    - guards: per-run 执行守卫（如全局 loop 熔断计数器）
+    - bag: 全局数据袋（浅拷贝传递）
+    - step_outputs: 当前层级的步骤输出缓存（step_id → output）
+    - call_chain: 调用链记录（能力 ID 列表）
+    """
+
+    run_id: str
+    parent_context: Optional[ExecutionContext] = None
+    depth: int = 0
+    max_depth: int = 10
+    guards: Any = None
+    cancel_token: Optional[CancellationToken] = None
+    bag: MappingProxyType[str, Any] = field(default_factory=lambda: MappingProxyType({}))
+    step_outputs: Dict[str, Any] = field(default_factory=dict)
+    # step_id -> {status, output, error, report}（面向编排的执行证据；不落盘）
+    step_results: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    call_chain: List[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        """
+        运行时强约束：bag 必须为不可变映射（MappingProxyType）。
+
+        说明：
+        - 调用方（包括 adapters/engines/tests）可能仍传入 dict；
+        - 这里统一转换为 MappingProxyType(dict(...))，保证 `context.bag[k] = v` 会抛 TypeError。
+        """
+
+        if isinstance(self.bag, MappingProxyType):
+            return
+        if isinstance(self.bag, Mapping):
+            self.bag = MappingProxyType(dict(self.bag))
+            return
+        self.bag = MappingProxyType({})
+
+    def with_bag_overlay(self, **updates: Any) -> ExecutionContext:
+        """
+        返回带 bag 覆盖的新 ExecutionContext（不修改原对象）。
+
+        设计目标：
+        - 用于 workflow_id/step_id/branch_id 等"临时 hint"注入；
+        - 共享 step_outputs/step_results 引用，保证执行证据链可持续累积；
+        - bag 为不可变映射，所有修改必须通过 overlay 创建新 context。
+
+        并发安全警告：
+        - 本方法共享 step_outputs 引用（顺序执行设计）；
+        - 并发分支（如 ParallelStep）必须用 `ExecutionContext(step_outputs=dict(...))` 显式创建副本。
+        """
+
+        base = dict(self.bag)
+        base.update(updates)
+        return ExecutionContext(
+            run_id=self.run_id,
+            parent_context=self.parent_context,
+            depth=self.depth,
+            max_depth=self.max_depth,
+            guards=self.guards,
+            cancel_token=self.cancel_token,
+            bag=MappingProxyType(base),
+            step_outputs=self.step_outputs,
+            step_results=self.step_results,
+            call_chain=self.call_chain,
+        )
+
+    def with_guards(self, guards: Any) -> ExecutionContext:
+        """
+        返回带有新 guards 的 ExecutionContext 副本。
+
+        设计目标：
+        - 确保 per-run guards 隔离，避免计数器跨 run 串扰；
+        - 复制可变容器（step_outputs/step_results/call_chain），避免共享引用。
+
+        参数：
+        - guards：新的 ExecutionGuards 实例
+        """
+
+        return ExecutionContext(
+            run_id=self.run_id,
+            parent_context=self.parent_context,
+            depth=self.depth,
+            max_depth=self.max_depth,
+            guards=guards,
+            cancel_token=self.cancel_token,
+            bag=self.bag,
+            step_outputs=dict(self.step_outputs),
+            step_results=dict(self.step_results),
+            call_chain=list(self.call_chain),
+        )
+
+    def child(self, capability_id: str) -> ExecutionContext:
+        """
+        创建子上下文。
+
+        行为：
+        - depth + 1；超过 max_depth 抛 RecursionLimitError
+        - bag 生成快照（不可变映射视图；修改需通过 with_bag_overlay 返回新 context）
+        - step_outputs 清空（子 context 有独立的步骤输出空间）
+        - call_chain 追加当前 capability_id
+        """
+
+        new_depth = self.depth + 1
+        if new_depth > self.max_depth:
+            raise RecursionLimitError(
+                f"Recursion depth {new_depth} exceeds max {self.max_depth}. "
+                f"Call chain: {self.call_chain + [capability_id]}"
+            )
+        return ExecutionContext(
+            run_id=self.run_id,
+            parent_context=self,
+            depth=new_depth,
+            max_depth=self.max_depth,
+            guards=self.guards,
+            cancel_token=self.cancel_token,
+            bag=MappingProxyType(dict(self.bag)),
+            step_outputs={},
+            step_results={},
+            call_chain=self.call_chain + [capability_id],
+        )
+
+    def resolve_mapping(self, expression: str) -> Any:
+        """
+        解析映射表达式，从 context 中提取数据。
+
+        支持：
+        - "context.{key}" → self.bag[key]
+        - "previous.{key}" → 最后一个 step_output 的 [key]
+        - "step.{step_id}.{key}" → self.step_outputs[step_id][key]
+        - "step.{step_id}" → self.step_outputs[step_id]（整体）
+        - "result.{step_id}" → self.step_results[step_id]（整体）
+        - "result.{step_id}.status" → self.step_results[step_id]["status"]
+        - "result.{step_id}.report.status" → self.step_results[step_id]["report"].status（若存在）
+        - "literal.{value}" → 字面量字符串
+        - "item" → self.bag["__current_item__"]
+        - "item.{key}" → self.bag["__current_item__"][key]
+
+        找不到时返回 None（不抛异常）。
+        """
+
+        def _resolve_one(obj: Any, key: str) -> Any:
+            """对 dict/对象做一层 key/attribute 解析；取不到返回 None。"""
+
+            if obj is None:
+                return None
+            if isinstance(obj, dict):
+                return obj.get(key)
+            return getattr(obj, key, None)
+
+        if expression.startswith("context."):
+            key = expression[len("context.") :]
+            return self.bag.get(key)
+
+        if expression.startswith("previous."):
+            key = expression[len("previous.") :]
+            if not self.step_outputs:
+                return None
+            last_key = list(self.step_outputs.keys())[-1]
+            last_out = self.step_outputs[last_key]
+            if isinstance(last_out, dict):
+                return last_out.get(key)
+            return None
+
+        if expression.startswith("step."):
+            rest = expression[len("step.") :]
+            parts = rest.split(".", 1)
+            step_id = parts[0]
+            step_key = parts[1] if len(parts) > 1 else None
+            out = self.step_outputs.get(step_id)
+            if step_key is None:
+                return out
+            if isinstance(out, dict):
+                return out.get(step_key)
+            return None
+
+        if expression.startswith("result."):
+            rest = expression[len("result.") :]
+            parts = rest.split(".")
+            step_id = parts[0]
+            cur: Any = self.step_results.get(step_id)
+            for key in parts[1:]:
+                cur = _resolve_one(cur, key)
+            return cur
+
+        if expression.startswith("literal."):
+            return expression[len("literal.") :]
+
+        if expression == "item":
+            return self.bag.get("__current_item__")
+
+        if expression.startswith("item."):
+            key = expression[len("item.") :]
+            item = self.bag.get("__current_item__")
+            if isinstance(item, dict):
+                return item.get(key)
+            return None
+
+        return None

capability_runtime/protocol/workflow.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+"""Workflow 元能力声明。"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Union
+
+from .capability import CapabilityRef, CapabilitySpec
+
+
+@dataclass(frozen=True)
+class InputMapping:
+    """
+    输入映射——定义步骤输入字段的数据来源。
+
+    参数：
+    - source: 数据源表达式
+    - target_field: 目标输入字段名
+    """
+
+    source: str
+    target_field: str
+
+
+@dataclass(frozen=True)
+class Step:
+    """
+    基础步骤——执行单个能力。
+
+    参数：
+    - id: 步骤 ID（在 Workflow 内唯一）
+    - capability: 要调用的能力引用
+    - input_mappings: 输入映射列表
+    """
+
+    id: str
+    capability: CapabilityRef
+    input_mappings: List[InputMapping] = field(default_factory=list)
+    timeout_s: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class LoopStep:
+    """
+    循环步骤——对集合中每个元素执行能力。
+
+    参数：
+    - id: 步骤 ID
+    - capability: 每次循环调用的能力引用
+    - iterate_over: 数据源表达式（解析后应为 List）
+    - item_input_mappings: 循环内的输入映射（可用 "item"/"item.{key}" 前缀）
+    - max_iterations: 单步最大循环次数
+    - collect_as: 结果收集字段名
+    - fail_strategy: "abort" | "skip" | "collect"
+    """
+
+    id: str
+    capability: CapabilityRef
+    iterate_over: str
+    item_input_mappings: List[InputMapping] = field(default_factory=list)
+    max_iterations: int = 100
+    collect_as: str = "results"
+    fail_strategy: str = "abort"
+    timeout_s: Optional[float] = None
+
+
+@dataclass(frozen=True)
+class ParallelStep:
+    """
+    并行步骤——同时执行多个能力。
+
+    参数：
+    - id: 步骤 ID
+    - branches: 并行执行的步骤列表
+    - join_strategy: "all_success" | "any_success" | "best_effort"
+    """
+
+    id: str
+    branches: List["WorkflowStep"] = field(default_factory=list)
+    join_strategy: str = "all_success"
+
+
+@dataclass(frozen=True)
+class ConditionalStep:
+    """
+    条件步骤——根据条件选择执行路径。
+
+    参数：
+    - id: 步骤 ID
+    - condition_source: 条件值的数据源表达式
+    - branches: 条件值 → 步骤的映射
+    - default: 无匹配时的默认步骤
+    """
+
+    id: str
+    condition_source: str
+    branches: Dict[str, "WorkflowStep"] = field(default_factory=dict)
+    default: Optional["WorkflowStep"] = None
+
+
+WorkflowStep = Union[Step, LoopStep, ParallelStep, ConditionalStep]
+
+
+@dataclass(frozen=True)
+class WorkflowSpec:
+    """
+    Workflow 声明。
+
+    参数：
+    - base: 公共能力字段
+    - steps: 步骤列表（按声明顺序执行，ParallelStep 内部并行）
+    - context_schema: 初始 context bag 的 schema（可选）
+    - output_mappings: 输出映射（从 context/step_outputs 构造最终输出）
+    """
+
+    base: CapabilitySpec
+    steps: List[WorkflowStep] = field(default_factory=list)
+    context_schema: Optional[Dict[str, str]] = None
+    output_mappings: List[InputMapping] = field(default_factory=list)

capability_runtime/registry.py

@@ -0,0 +1,287 @@
+"""能力注册表——所有 Spec 的中央存储和查询。"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Set, Union
+
+from .manifest import (
+    CapabilityDescriptor,
+    CapabilityManifestEntry,
+    CapabilityVisibility,
+    build_manifest_entry_from_spec,
+    collect_capability_dependencies,
+    validate_manifest_entry_matches_spec,
+)
+from .protocol.agent import AgentSpec
+from .protocol.capability import CapabilityKind, CapabilitySpec
+from .protocol.workflow import ConditionalStep, LoopStep, ParallelStep, Step, WorkflowSpec
+
+AnySpec = Union[AgentSpec, WorkflowSpec]
+
+
+def _get_base(spec: AnySpec) -> CapabilitySpec:
+    """
+    从具体 Spec 中提取公共 base。
+
+    参数：
+    - spec：AgentSpec 或 WorkflowSpec
+
+    返回：
+    - CapabilitySpec（公共字段）
+    """
+
+    return spec.base
+
+
+class CapabilityRegistry:
+    """
+    能力注册表。
+
+    线程安全说明：当前为单线程设计（asyncio 单事件循环）。
+    """
+
+    def __init__(self) -> None:
+        self._store: Dict[str, AnySpec] = {}
+        self._manifest_store: Dict[str, CapabilityManifestEntry] = {}
+
+    def register(self, spec: AnySpec) -> None:
+        """
+        注册一个能力。
+
+        参数：
+        - spec：能力声明（AgentSpec/WorkflowSpec）
+
+        说明：
+        - 重复注册同一 ID 会覆盖（last-write-wins）。
+        """
+
+        self.register_with_manifest(spec)
+
+    def register_with_manifest(
+        self,
+        spec: AnySpec,
+        *,
+        entry: CapabilityManifestEntry | None = None,
+    ) -> CapabilityManifestEntry:
+        """
+        注册能力并同步维护 manifest entry。
+
+        参数：
+        - spec：能力声明（AgentSpec/WorkflowSpec）
+        - entry：可选显式 manifest entry；为空时基于 spec.base 自动生成
+
+        返回：
+        - 实际存储的 manifest entry
+        """
+
+        base = _get_base(spec)
+        manifest_entry = entry or build_manifest_entry_from_spec(spec)
+        validate_manifest_entry_matches_spec(manifest_entry, spec)
+        self._store[base.id] = spec
+        self._manifest_store[base.id] = manifest_entry
+        return manifest_entry
+
+    def register_manifest_entry(self, entry: CapabilityManifestEntry) -> CapabilityManifestEntry:
+        """
+        仅注册 manifest entry（允许尚未存在 spec）。
+
+        参数：
+        - entry：manifest 元数据
+
+        返回：
+        - 原样返回已存储 entry
+        """
+
+        self._manifest_store[entry.capability_id] = entry
+        return entry
+
+    def get(self, capability_id: str) -> Optional[AnySpec]:
+        """
+        查找能力，不存在返回 None。
+
+        参数：
+        - capability_id：能力 ID
+        """
+
+        return self._store.get(capability_id)
+
+    def get_or_raise(self, capability_id: str) -> AnySpec:
+        """
+        查找能力，不存在抛 KeyError。
+
+        参数：
+        - capability_id：能力 ID
+        """
+
+        spec = self.get(capability_id)
+        if spec is None:
+            raise KeyError(f"Capability not found: {capability_id!r}")
+        return spec
+
+    def list_all(self) -> List[AnySpec]:
+        """列出所有已注册能力。"""
+
+        return list(self._store.values())
+
+    def list_by_kind(self, kind: CapabilityKind) -> List[AnySpec]:
+        """
+        列出指定种类的所有能力。
+
+        参数：
+        - kind：能力类型
+        """
+
+        return [s for s in self._store.values() if _get_base(s).kind == kind]
+
+    def list_ids(self) -> List[str]:
+        """列出所有已注册能力的 ID。"""
+
+        return list(self._store.keys())
+
+    def get_manifest_entry(self, capability_id: str) -> CapabilityManifestEntry | None:
+        """
+        查找 manifest entry，不存在返回 None。
+
+        参数：
+        - capability_id：能力 ID
+        """
+
+        entry = self._manifest_store.get(capability_id)
+        if entry is not None:
+            return entry
+        spec = self._store.get(capability_id)
+        if spec is None:
+            return None
+        entry = build_manifest_entry_from_spec(spec)
+        self._manifest_store[capability_id] = entry
+        return entry
+
+    def get_descriptor(self, capability_id: str) -> CapabilityDescriptor | None:
+        """
+        查询 capability descriptor。
+
+        参数：
+        - capability_id：能力 ID
+        """
+
+        entry = self.get_manifest_entry(capability_id)
+        if entry is None:
+            return None
+        spec = self._store.get(capability_id)
+        return CapabilityDescriptor(
+            entry=entry,
+            spec=spec,
+            dependencies=collect_capability_dependencies(spec),
+        )
+
+    def list_descriptors(
+        self,
+        *,
+        visibility: CapabilityVisibility | None = None,
+        exposed_only: bool = False,
+    ) -> list[CapabilityDescriptor]:
+        """
+        列出 capability descriptors。
+
+        参数：
+        - visibility：可选可见性过滤
+        - exposed_only：仅返回 `entry.expose=True` 的能力
+        """
+
+        ids: list[str] = list(self._manifest_store.keys())
+        for capability_id in self._store.keys():
+            if capability_id not in self._manifest_store:
+                ids.append(capability_id)
+
+        descriptors: list[CapabilityDescriptor] = []
+        for capability_id in ids:
+            descriptor = self.get_descriptor(capability_id)
+            if descriptor is None:
+                continue
+            if visibility is not None and descriptor.entry.visibility != visibility:
+                continue
+            if exposed_only and not descriptor.entry.expose:
+                continue
+            descriptors.append(descriptor)
+        return descriptors
+
+    def has(self, capability_id: str) -> bool:
+        """
+        检查能力是否已注册。
+
+        参数：
+        - capability_id：能力 ID
+        """
+
+        return capability_id in self._store
+
+    def unregister(self, capability_id: str) -> bool:
+        """
+        注销能力。
+
+        参数：
+        - capability_id：能力 ID
+
+        返回：
+        - True 表示存在并已删除；False 表示不存在
+        """
+
+        if capability_id in self._store:
+            del self._store[capability_id]
+            removed = True
+        else:
+            removed = False
+        if capability_id in self._manifest_store:
+            del self._manifest_store[capability_id]
+            return True
+        return removed
+
+    def validate_dependencies(self) -> List[str]:
+        """
+        校验所有能力的依赖是否已注册。
+
+        检查范围：
+        - AgentSpec.collaborators / callable_workflows 中引用的能力 ID
+        - WorkflowSpec 中所有 Step/LoopStep 的 capability.id
+        - ParallelStep.branches 内的步骤
+        - ConditionalStep.branches/default 内的步骤
+
+        返回：
+        - 缺失的 ID 列表（空列表表示全部满足）
+        """
+
+        missing: Set[str] = set()
+
+        for spec in self._store.values():
+            if isinstance(spec, AgentSpec):
+                for ref in spec.collaborators:
+                    if ref.id not in self._store:
+                        missing.add(ref.id)
+                for ref in spec.callable_workflows:
+                    if ref.id not in self._store:
+                        missing.add(ref.id)
+
+            elif isinstance(spec, WorkflowSpec):
+                self._collect_step_deps(spec.steps, missing)
+
+        return sorted(missing)
+
+    def _collect_step_deps(self, steps: list, missing: Set[str]) -> None:
+        """
+        递归收集步骤中的能力依赖。
+
+        参数：
+        - steps：步骤列表（可能包含嵌套步骤）
+        - missing：缺失依赖的能力 ID（原地写入）
+        """
+
+        for step in steps:
+            if isinstance(step, (Step, LoopStep)):
+                if step.capability.id not in self._store:
+                    missing.add(step.capability.id)
+            elif isinstance(step, ParallelStep):
+                # WorkflowAdapter 支持在 branches 中嵌套任意 WorkflowStep，因此依赖校验必须递归覆盖。
+                self._collect_step_deps(list(step.branches), missing)
+            elif isinstance(step, ConditionalStep):
+                self._collect_step_deps(list(step.branches.values()), missing)
+                if step.default is not None:
+                    self._collect_step_deps([step.default], missing)

capability_runtime/reporting/__init__.py

@@ -0,0 +1,2 @@
+"""NodeReport（控制面强结构）聚合与输出。"""
+