capability-runtime 0.1.0__py3-none-any.whl

capability_runtime/manifest.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+"""Runtime canonical capability manifest / descriptor helpers."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from .protocol.agent import AgentSpec
+from .protocol.capability import CapabilityKind, CapabilityRef, CapabilitySpec
+from .protocol.workflow import ConditionalStep, LoopStep, ParallelStep, Step, WorkflowSpec, WorkflowStep
+
+
+class CapabilityVisibility(str, Enum):
+    """能力可见性。"""
+
+    PUBLIC = "public"
+    INTERNAL = "internal"
+
+
+@dataclass(frozen=True)
+class CapabilityManifestEntry:
+    """
+    manifest entry：描述一个 capability 的宿主可消费元数据。
+
+    参数：
+    - capability_id：能力唯一 ID，必须与 spec.base.id 对齐
+    - kind：能力类型
+    - version：能力版本
+    - name/description：宿主展示用摘要
+    - tags：能力标签
+    - visibility：可见性（public/internal）
+    - expose：是否默认出现在对外发现列表
+    - source：注册来源
+    - metadata：扩展字段
+    """
+
+    capability_id: str
+    kind: CapabilityKind
+    version: str
+    name: str | None = None
+    description: str | None = None
+    tags: list[str] = field(default_factory=list)
+    visibility: CapabilityVisibility = CapabilityVisibility.PUBLIC
+    expose: bool = True
+    source: str = "runtime.register"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class CapabilityDescriptor:
+    """
+    descriptor：manifest entry + spec + 依赖的统一描述结构。
+
+    参数：
+    - entry：manifest 元数据
+    - spec：原始 AgentSpec / WorkflowSpec；仅注册 manifest entry 时允许为空
+    - dependencies：收敛后的 capability refs
+    """
+
+    entry: CapabilityManifestEntry
+    spec: AgentSpec | WorkflowSpec | None = None
+    dependencies: list[CapabilityRef] = field(default_factory=list)
+
+
+def build_manifest_entry_from_spec(
+    spec: AgentSpec | WorkflowSpec,
+    *,
+    source: str = "runtime.register",
+) -> CapabilityManifestEntry:
+    """
+    基于 spec.base 构造默认 manifest entry。
+
+    参数：
+    - spec：AgentSpec 或 WorkflowSpec
+    - source：注册来源
+
+    返回：
+    - 衍生出的默认 CapabilityManifestEntry
+    """
+
+    base = spec.base
+    return CapabilityManifestEntry(
+        capability_id=base.id,
+        kind=base.kind,
+        version=base.version,
+        name=base.name,
+        description=base.description,
+        tags=list(base.tags),
+        source=source,
+        metadata=dict(base.metadata),
+    )
+
+
+def collect_capability_dependencies(spec: AgentSpec | WorkflowSpec | None) -> list[CapabilityRef]:
+    """
+    从 spec 收敛 capability 依赖引用。
+
+    参数：
+    - spec：AgentSpec 或 WorkflowSpec；为空时返回空列表
+
+    返回：
+    - 去重且保持首次出现顺序的 CapabilityRef 列表
+    """
+
+    if spec is None:
+        return []
+
+    collected: list[CapabilityRef] = []
+    seen: set[tuple[str, CapabilityKind | None]] = set()
+
+    def add_ref(ref: CapabilityRef) -> None:
+        key = (ref.id, ref.kind)
+        if key in seen:
+            return
+        seen.add(key)
+        collected.append(ref)
+
+    if isinstance(spec, AgentSpec):
+        for ref in spec.collaborators:
+            add_ref(ref)
+        for ref in spec.callable_workflows:
+            add_ref(ref)
+        return collected
+
+    def walk_workflow_step(step: WorkflowStep) -> None:
+        if isinstance(step, (Step, LoopStep)):
+            add_ref(step.capability)
+            return
+        if isinstance(step, ParallelStep):
+            for branch in step.branches:
+                walk_workflow_step(branch)
+            return
+        if isinstance(step, ConditionalStep):
+            for branch in step.branches.values():
+                walk_workflow_step(branch)
+            if step.default is not None:
+                walk_workflow_step(step.default)
+
+    for workflow_step in spec.steps:
+        walk_workflow_step(workflow_step)
+    return collected
+
+
+def validate_manifest_entry_matches_spec(entry: CapabilityManifestEntry, spec: AgentSpec | WorkflowSpec) -> None:
+    """
+    校验显式 manifest entry 与 spec.base 的关键字段一致。
+
+    参数：
+    - entry：宿主声明的 manifest entry
+    - spec：要注册的能力声明
+
+    异常：
+    - ValueError：entry 与 spec.base 不一致
+    """
+
+    base: CapabilitySpec = spec.base
+    if entry.capability_id != base.id:
+        raise ValueError(
+            f"Manifest entry capability_id mismatch: {entry.capability_id!r} != {base.id!r}"
+        )
+    if entry.kind != base.kind:
+        raise ValueError(f"Manifest entry kind mismatch: {entry.kind!r} != {base.kind!r}")
+
+
+__all__ = [
+    "CapabilityVisibility",
+    "CapabilityManifestEntry",
+    "CapabilityDescriptor",
+    "build_manifest_entry_from_spec",
+    "collect_capability_dependencies",
+    "validate_manifest_entry_matches_spec",
+]

capability_runtime/output_validator.py

@@ -0,0 +1,139 @@
+"""Output 校验组件：包装 output_validator 并写入 NodeReport.meta。"""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+import json
+from typing import Any, Callable, Dict, Optional
+
+from .config import OutputValidationMode
+from .structured_output import apply_structured_output_summary, validate_structured_output
+from .types import NodeReport
+
+
+class OutputValidator:
+    """输出校验器（mode + validator callback 的组合封装）。"""
+
+    def __init__(self, *, mode: OutputValidationMode, validator: Optional[Callable[..., Any]]) -> None:
+        """
+        构造输出校验器。
+
+        参数：
+        - mode：`off/warn/error`
+        - validator：可选校验回调（推荐 keyword-only 签名）
+        """
+
+        self._mode = mode
+        self._validator = validator
+
+    def _invoke_validator(self, *, final_output: Any, report: NodeReport, context: Dict[str, Any]) -> Any:
+        """
+        调用 validator，并只在“签名确实不匹配”时回退到 positional。
+
+        说明：
+        - 不用 `except TypeError` 直接判定签名不匹配，避免把 validator 内部 bug 误吞；
+        - 优先走推荐的 keyword-only 契约：`(*, final_output, node_report, context)`。
+        """
+
+        validator = self._validator
+        assert validator is not None
+
+        keyword_args = {"final_output": final_output, "node_report": report, "context": context}
+        try:
+            signature = inspect.signature(validator)
+        except (TypeError, ValueError):
+            return validator(final_output, report, context)
+
+        try:
+            signature.bind_partial(**keyword_args)
+        except TypeError as keyword_bind_error:
+            try:
+                signature.bind_partial(final_output, report, context)
+            except TypeError:
+                raise keyword_bind_error
+            return validator(final_output, report, context)
+        return validator(**keyword_args)
+
+    def validate(
+        self,
+        *,
+        final_output: Any,
+        report: NodeReport,
+        context: Dict[str, Any],
+        output_schema: Optional[Any] = None,
+    ) -> None:
+        """
+        调用 output_validator 并把“最小披露”摘要写入 NodeReport.meta。
+
+        行为：
+        - mode=off：不调用
+        - mode=warn：记录摘要但不覆盖状态
+        - mode=error：validator 返回 ok=False 时覆盖为 failed（可回归护栏）
+        """
+
+        capability_id = str(context.get("capability_id") or "")
+        if output_schema is not None and getattr(output_schema, "fields", None):
+            validation = validate_structured_output(
+                final_output=final_output,
+                output_schema=output_schema,
+                capability_id=capability_id,
+                mode=self._mode,
+            )
+            apply_structured_output_summary(
+                report=report,
+                validation=validation,
+                fail_on_error=self._mode == "error",
+            )
+
+        if self._mode == "off" or self._validator is None:
+            return
+
+        try:
+            raw = self._invoke_validator(final_output=final_output, report=report, context=context)
+        except Exception as exc:
+            # validator 自身异常：作为可观测信息记录；不强行失败（避免“验证器把系统打挂”）。
+            report.meta["output_validation"] = {
+                "mode": self._mode,
+                "ok": False,
+                "error": f"validator_exception:{type(exc).__name__}",
+            }
+            if self._mode == "error":
+                report.status = "failed"
+                report.reason = "output_validation_error"
+                report.meta["output_validation_overrode_status"] = True
+            return
+
+        if not isinstance(raw, dict):
+            report.meta["output_validation"] = {
+                "mode": self._mode,
+                "ok": True,
+                "note": "validator_return_not_dict",
+            }
+            return
+
+        ok = bool(raw.get("ok", True))
+        schema_id = raw.get("schema_id") if isinstance(raw.get("schema_id"), str) else None
+        errors = raw.get("errors") if isinstance(raw.get("errors"), list) else []
+
+        summary: Dict[str, Any] = {"mode": self._mode, "ok": ok}
+        if schema_id:
+            summary["schema_id"] = schema_id
+        if errors:
+            # errors 期望是可披露的摘要条目（path/kind/message）
+            summary["errors"] = errors
+
+        normalized_payload = raw.get("normalized_payload")
+        if isinstance(normalized_payload, dict):
+            payload_text = json.dumps(normalized_payload, ensure_ascii=False, separators=(",", ":"))
+            digest = hashlib.sha256(payload_text.encode("utf-8")).hexdigest()
+            summary["normalized_payload_sha256"] = digest
+            summary["normalized_payload_bytes"] = len(payload_text.encode("utf-8"))
+            summary["normalized_payload_top_keys"] = sorted(list(normalized_payload.keys()))[:20]
+
+        report.meta["output_validation"] = summary
+
+        if (not ok) and self._mode == "error":
+            report.status = "failed"
+            report.reason = "output_validation_error"
+            report.meta["output_validation_overrode_status"] = True

capability_runtime/protocol/__init__.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+"""Protocol 层：纯能力类型定义，不依赖任何上游模块。"""
+
+from .agent import AgentIOSchema, AgentSpec
+from .capability import (
+    CapabilityKind,
+    CapabilityRef,
+    CapabilityResult,
+    CapabilitySpec,
+    CapabilityStatus,
+)
+from .chat_backend import ChatBackendProtocol
+from .context import ExecutionContext, RecursionLimitError
+from .workflow import (
+    ConditionalStep,
+    InputMapping,
+    LoopStep,
+    ParallelStep,
+    Step,
+    WorkflowSpec,
+    WorkflowStep,
+)
+
+__all__ = [
+    "CapabilityKind",
+    "CapabilityRef",
+    "CapabilitySpec",
+    "CapabilityStatus",
+    "CapabilityResult",
+    "AgentSpec",
+    "AgentIOSchema",
+    "ChatBackendProtocol",
+    "WorkflowSpec",
+    "Step",
+    "LoopStep",
+    "ParallelStep",
+    "ConditionalStep",
+    "InputMapping",
+    "WorkflowStep",
+    "ExecutionContext",
+    "RecursionLimitError",
+]

capability_runtime/protocol/agent.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+"""Agent 元能力声明。"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .capability import CapabilityRef, CapabilitySpec
+
+
+@dataclass(frozen=True)
+class AgentIOSchema:
+    """
+    轻量 IO schema——描述 Agent 的输入/输出字段。
+
+    参数：
+    - fields: 字段名 → 类型描述（如 {"synopsis": "str", "score": "int"}）
+    - required: 必填字段列表
+    """
+
+    fields: Dict[str, str] = field(default_factory=dict)
+    required: List[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    """
+    Agent 声明。
+
+    参数：
+    - base: 公共能力字段
+    - tools: 注册的 Tool 名称列表
+    - collaborators: 可协作的其他 Agent 引用
+    - callable_workflows: 可调用的 Workflow 引用
+    - input_schema: 输入 schema（可选）
+    - output_schema: 输出 schema（可选）
+    - loop_compatible: 是否可被 LoopStep 循环调用
+    - llm_config: LLM 覆盖配置
+    - prompt_template: 可选的 prompt 模板（支持 {field} 占位符）
+    - system_prompt: 可选的“Agent 级 system message”（用于该 Agent 的提示词组织）
+
+      注意：
+      - 这不是 Host 的 system/developer 级策略提示词注入通道；
+      - Host 级策略提示词应通过上游 `skills_runtime` 的 prompt/config overlays 注入（避免 `initial_history` 漂移）。
+    """
+
+    base: CapabilitySpec
+    tools: List[str] = field(default_factory=list)
+    # skills：仅声明“希望使用的 skill 名称”，注入与执行由上游 skills_runtime 完成。
+    skills: List[str] = field(default_factory=list)
+    # skills_mention_map：把 skill_name 映射为 SDK 可识别的严格 mention。
+    # - legacy（≤0.1.4.post2）："$[account:domain].skill_name"
+    # - v0.1.5+："$[namespace].skill_name"（namespace 可为 "a:b:c" 多段）
+    skills_mention_map: Dict[str, str] = field(default_factory=dict)
+    collaborators: List[CapabilityRef] = field(default_factory=list)
+    callable_workflows: List[CapabilityRef] = field(default_factory=list)
+    input_schema: Optional[AgentIOSchema] = None
+    output_schema: Optional[AgentIOSchema] = None
+    loop_compatible: bool = False
+    llm_config: Optional[Dict[str, Any]] = None
+    prompt_template: Optional[str] = None
+    system_prompt: Optional[str] = None

capability_runtime/protocol/capability.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+"""
+两种能力原语（Agent / Workflow）共享的统一接口。
+
+说明：
+- 本仓对外承诺的能力原语仅包含 `agent` 与 `workflow`（见 `CapabilityKind`）。
+- skills 的发现/治理/执行引擎属于上游 `skills_runtime`；本仓不把 `skill` 做成公共协议原语。
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from ..types import NodeReport
+
+
+class CapabilityKind(str, Enum):
+    """能力种类。"""
+
+    AGENT = "agent"
+    WORKFLOW = "workflow"
+
+
+@dataclass(frozen=True)
+class CapabilityRef:
+    """
+    能力引用——在组合中引用另一个能力。
+
+    参数：
+    - id: 被引用能力的唯一 ID
+    - kind: 可选的类型提示（用于校验，不设则运行时从 Registry 推断）
+    """
+
+    id: str
+    kind: Optional[CapabilityKind] = None
+
+
+@dataclass(frozen=True)
+class CapabilitySpec:
+    """
+    能力声明的公共字段。
+
+    参数：
+    - id: 全局唯一 ID（如 "MA-013"、"WF-001D"）
+    - kind: 能力种类（agent/workflow）
+    - name: 人类可读名称（如 "单角色设计师"）
+    - description: 描述（可为空）
+    - version: 语义化版本（默认 "0.1.0"）
+    - tags: 标签列表（用于分类和搜索）
+    - metadata: 自由扩展字段（框架不解读，业务可用于存储额外信息）
+    """
+
+    id: str
+    kind: CapabilityKind
+    name: str
+    description: str = ""
+    version: str = "0.1.0"
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class CapabilityStatus(str, Enum):
+    """能力执行状态。"""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class CapabilityResult:
+    """
+    所有能力执行后返回此结构。
+
+    参数：
+    - status: 执行状态
+    - output: 执行输出（类型由具体能力决定，通常是 dict 或 str）
+    - error: 错误信息（仅 FAILED 时非 None）
+    - error_code: 机器可处理的错误码（SCREAMING_SNAKE_CASE，可选）
+    - report: 执行报告（可选；历史字段，建议优先使用 node_report）
+    - node_report: 控制面强结构报告（桥接模式下产出；Workflow/Host 编排优先读取）
+    - artifacts: 产出的文件路径列表
+    - duration_ms: 执行耗时（毫秒，可选）
+    - metadata: 扩展信息
+    """
+
+    status: CapabilityStatus
+    output: Any = None
+    error: Optional[str] = None
+    error_code: Optional[str] = None
+    report: Optional[Any] = None
+    node_report: Optional[NodeReport] = None
+    artifacts: List[str] = field(default_factory=list)
+    duration_ms: Optional[float] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)

capability_runtime/protocol/chat_backend.py

@@ -0,0 +1,38 @@
+"""
+ChatBackend 协议定义。
+
+提供类型安全的 ChatBackend 接口，用于 backend wrapper 的静态类型检查。
+"""
+
+from __future__ import annotations
+
+from typing import AsyncGenerator, Protocol, runtime_checkable
+
+from skills_runtime.llm.chat_sse import ChatStreamEvent
+from skills_runtime.llm.protocol import ChatRequest
+
+
+@runtime_checkable
+class ChatBackendProtocol(Protocol):
+    """
+    ChatBackend 协议：定义流式聊天后端的接口。
+
+    说明：
+    - 与 `skills_runtime.llm.protocol.ChatBackend` 对齐
+    - 用于 backend wrapper 的类型注解，减少 `Any` 使用
+    """
+
+    def stream_chat(self, request: ChatRequest) -> AsyncGenerator[ChatStreamEvent, None]:
+        """
+        发起流式聊天请求。
+
+        参数：
+        - request：ChatRequest 或兼容对象
+
+        返回：
+        - ChatStreamEvent 异步生成器
+        """
+        ...
+
+
+__all__ = ["ChatBackendProtocol"]