fastpilot 0.1.0__py3-none-any.whl

fastpilot/__init__.py

@@ -0,0 +1,171 @@
+"""FastPilot：Python 业务对象的控制、观察与远程访问协议。"""
+
+from typing import TYPE_CHECKING
+
+from fastpilot.core import Runtime, RuntimeHandle, make_runtime
+from fastpilot.driver import CommandSurface, Driver
+from fastpilot.observation import (
+    HistoryStore,
+    HistoryStoreFactory,
+    MemoryHistoryStore,
+    Predicate,
+    PredicateLike,
+    RuntimeHistoryStores,
+    SQLiteSpoolHistoryStore,
+    Subscription,
+    temporary_sqlite_history,
+)
+from fastpilot.protocol import (
+    Advance,
+    AllOf,
+    AnyOf,
+    AtTime,
+    CancelEntry,
+    CapabilityError,
+    Command,
+    CommandEffect,
+    CommandOutcome,
+    CommandQueued,
+    CommandReceipt,
+    Commit,
+    DomainCommandHandled,
+    DraftConflictError,
+    Enqueue,
+    Event,
+    Fact,
+    FastPilotError,
+    HostedRuntimeView,
+    Immediately,
+    MoveEntry,
+    OnFact,
+    OnStateEntered,
+    Pause,
+    Paused,
+    QueueEntryStatus,
+    QueueEntryView,
+    QueueSnapshot,
+    Reject,
+    Resume,
+    Resumed,
+    RuntimeUpdate,
+    SetSpeed,
+    Snapshot,
+    Start,
+    Started,
+    StateEntered,
+    Stop,
+    Stopped,
+    TransitionDraft,
+    TransitionView,
+    Trigger,
+    WhenState,
+    command,
+    fact,
+    framework_protocol,
+)
+from fastpilot.state import (
+    DataParticipant,
+    ParticipantContext,
+    RuntimeParticipant,
+    StateChart,
+    StatefulParticipant,
+    TickParticipant,
+    emits,
+    handles,
+    participant_protocol,
+)
+
+if TYPE_CHECKING:
+    from fastpilot.remote import RemoteRuntime
+
+__version__ = "0.1.0"
+
+
+def connect(
+    base_url: str,
+    *,
+    connect_timeout: float = 3.0,
+    command_timeout: float = 30.0,
+) -> "RemoteRuntime":
+    """连接独立 FastPilot 服务，并延迟加载远程可选依赖。"""
+    from fastpilot.remote import connect as remote_connect
+
+    return remote_connect(
+        base_url,
+        connect_timeout=connect_timeout,
+        command_timeout=command_timeout,
+    )
+
+
+__all__ = [
+    "Advance",
+    "AllOf",
+    "AnyOf",
+    "AtTime",
+    "CancelEntry",
+    "CapabilityError",
+    "Command",
+    "CommandQueued",
+    "CommandOutcome",
+    "CommandEffect",
+    "CommandReceipt",
+    "CommandSurface",
+    "Commit",
+    "DomainCommandHandled",
+    "DataParticipant",
+    "DraftConflictError",
+    "Driver",
+    "Enqueue",
+    "Event",
+    "Fact",
+    "FastPilotError",
+    "HistoryStore",
+    "HistoryStoreFactory",
+    "HostedRuntimeView",
+    "Immediately",
+    "MemoryHistoryStore",
+    "MoveEntry",
+    "OnFact",
+    "OnStateEntered",
+    "ParticipantContext",
+    "Pause",
+    "Paused",
+    "Predicate",
+    "PredicateLike",
+    "QueueEntryStatus",
+    "QueueEntryView",
+    "QueueSnapshot",
+    "Reject",
+    "Resume",
+    "Resumed",
+    "Runtime",
+    "RuntimeHandle",
+    "RuntimeHistoryStores",
+    "RuntimeParticipant",
+    "RuntimeUpdate",
+    "SetSpeed",
+    "Snapshot",
+    "SQLiteSpoolHistoryStore",
+    "Start",
+    "Started",
+    "StateEntered",
+    "StatefulParticipant",
+    "StateChart",
+    "Stop",
+    "Stopped",
+    "Subscription",
+    "TickParticipant",
+    "TransitionDraft",
+    "TransitionView",
+    "Trigger",
+    "WhenState",
+    "command",
+    "emits",
+    "fact",
+    "framework_protocol",
+    "handles",
+    "participant_protocol",
+    "temporary_sqlite_history",
+    "connect",
+    "make_runtime",
+]

fastpilot/contrib/__init__.py

@@ -0,0 +1,30 @@
+"""用于验证 FastPilot 公共协议的具体参与者。"""
+
+from fastpilot.contrib.echo import Echo, Echoed, EchoMessage, make_echo
+from fastpilot.contrib.robot import (
+    ROBOT_STATECHART,
+    ContinueWalking,
+    Obstacle,
+    Rest,
+    RobotParticipant,
+    SetEnergy,
+    Wake,
+    Walk,
+    make_robot,
+)
+
+__all__ = [
+    "Echo",
+    "EchoMessage",
+    "Echoed",
+    "ROBOT_STATECHART",
+    "ContinueWalking",
+    "Obstacle",
+    "Rest",
+    "RobotParticipant",
+    "SetEnergy",
+    "Wake",
+    "Walk",
+    "make_echo",
+    "make_robot",
+]

fastpilot/contrib/echo.py

@@ -0,0 +1,61 @@
+"""Echo：用最小类型化 Command/Fact 展示事件驱动业务。"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from fastpilot.core import Runtime, make_runtime
+from fastpilot.protocol import Command, Fact, command, fact
+from fastpilot.protocol.values import freeze_mapping
+from fastpilot.state import ParticipantContext, emits, handles
+
+
+@command("fastpilot.contrib.echo.message")
+@dataclass(frozen=True, slots=True)
+class EchoMessage(Command):
+    """一条由 Echo 记录并原样发布的领域消息。"""
+
+    name: str
+    payload: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "payload", freeze_mapping(self.payload))
+
+
+@fact("fastpilot.contrib.echo.echoed")
+@dataclass(frozen=True, slots=True)
+class Echoed(Fact):
+    """Echo 已经接收并保存一条消息。"""
+
+    name: str
+    payload: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "payload", freeze_mapping(self.payload))
+
+
+class Echo:
+    """把最近一次输入定义为 Echo 的领域状态，并发布对应领域事实。
+
+    ``last_message`` 与 ``last_payload`` 由 Echo 在回调中主动写入。这个选择
+    属于 Echo 的领域模型，使 Snapshot 可以回答“最近回显了什么”。
+    """
+
+    @handles
+    @emits(Echoed)
+    def echo(
+        self,
+        context: ParticipantContext,
+        command: EchoMessage,
+    ) -> None:
+        context.write_data("last_message", command.name)
+        context.write_data("last_payload", dict(command.payload))
+        context.emit(Echoed(command.name, command.payload))
+
+
+def make_echo() -> Runtime:
+    """创建一个可在 IPython 中直接驱动的 Echo Runtime。"""
+
+    return make_runtime(Echo())
+
+
+__all__ = ["Echo", "EchoMessage", "Echoed", "make_echo"]

fastpilot/contrib/robot.py

@@ -0,0 +1,168 @@
+"""散步机器人：证明状态图、逻辑时间和草稿站的厚业务参与者。"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from fastpilot.core import Runtime, make_runtime
+from fastpilot.protocol import Command, TransitionDraft, command
+from fastpilot.state import ParticipantContext, StateChart, handles
+
+ROBOT_STATECHART = StateChart.create(
+    initial="IDLE",
+    transitions={
+        "IDLE": frozenset({"WALKING"}),
+        "WALKING": frozenset({"THINKING", "RESTING", "CHARGING"}),
+        "THINKING": frozenset({"WALKING", "RESTING"}),
+        "RESTING": frozenset({"WALKING"}),
+        "CHARGING": frozenset({"WALKING"}),
+    },
+)
+
+
+@command("fastpilot.contrib.robot.walk")
+@dataclass(frozen=True, slots=True)
+class Walk(Command):
+    """请求空闲 Robot 建立进入 WALKING 的转换草稿。"""
+
+
+@command("fastpilot.contrib.robot.obstacle")
+@dataclass(frozen=True, slots=True)
+class Obstacle(Command):
+    """报告行走路径出现障碍。"""
+
+
+@command("fastpilot.contrib.robot.rest")
+@dataclass(frozen=True, slots=True)
+class Rest(Command):
+    """请求思考中的 Robot 进入休息状态。"""
+
+
+@command("fastpilot.contrib.robot.continue_walking")
+@dataclass(frozen=True, slots=True)
+class ContinueWalking(Command):
+    """请求思考中的 Robot 继续行走。"""
+
+
+@command("fastpilot.contrib.robot.wake")
+@dataclass(frozen=True, slots=True)
+class Wake(Command):
+    """请求休息中的 Robot 重新行走。"""
+
+
+@command("fastpilot.contrib.robot.set_energy")
+@dataclass(frozen=True, slots=True)
+class SetEnergy(Command):
+    """把 Robot 的领域能量设置为一个明确数值。"""
+
+    value: float
+
+
+@dataclass(frozen=True, slots=True)
+class RobotParticipant:
+    """以位置、能量和状态边展示完整 Runtime 能力。"""
+
+    @property
+    def statechart(self) -> StateChart:
+        return ROBOT_STATECHART
+
+    @property
+    def initial_data(self) -> Mapping[str, object]:
+        return {"position": 0.0, "energy": 100.0, "mood": "happy"}
+
+    def on_tick(
+        self,
+        context: ParticipantContext,
+        delta: float,
+    ) -> TransitionDraft | None:
+        if context.state == "WALKING":
+            position = _as_float(context.read_data("position", 0.0)) + delta
+            energy = _as_float(context.read_data("energy", 100.0)) - delta
+            context.write_data("position", position)
+            context.write_data("energy", energy)
+            if energy <= 20:
+                return context.propose("CHARGING", "energy_low", {"energy": energy})
+        if context.state == "RESTING" and delta > 0:
+            energy = min(100.0, _as_float(context.read_data("energy", 100.0)) + delta * 2)
+            context.write_data("energy", energy)
+        if context.state == "CHARGING" and delta > 0:
+            energy = min(100.0, _as_float(context.read_data("energy", 0.0)) + delta * 5)
+            context.write_data("energy", energy)
+            if energy >= 100:
+                return context.propose("WALKING", "charged")
+        return None
+
+    @handles
+    def set_energy(self, context: ParticipantContext, command: SetEnergy) -> None:
+        context.write_data("energy", float(command.value))
+
+    @handles
+    def walk(self, context: ParticipantContext, command: Walk) -> TransitionDraft | None:
+        del command
+        if context.state == "IDLE":
+            return context.propose("WALKING", "walk_command")
+        return None
+
+    @handles
+    def obstacle(
+        self,
+        context: ParticipantContext,
+        command: Obstacle,
+    ) -> TransitionDraft | None:
+        del command
+        if context.state == "WALKING":
+            return context.propose(
+                "THINKING",
+                "obstacle",
+                {"position": context.read_data("position", 0.0)},
+            )
+        return None
+
+    @handles
+    def rest(self, context: ParticipantContext, command: Rest) -> TransitionDraft | None:
+        del command
+        if context.state == "THINKING":
+            return context.propose("RESTING", "driver_decision")
+        return None
+
+    @handles
+    def continue_walking(
+        self,
+        context: ParticipantContext,
+        command: ContinueWalking,
+    ) -> TransitionDraft | None:
+        del command
+        if context.state == "THINKING":
+            return context.propose("WALKING", "driver_decision")
+        return None
+
+    @handles
+    def wake(self, context: ParticipantContext, command: Wake) -> TransitionDraft | None:
+        del command
+        if context.state == "RESTING":
+            return context.propose("WALKING", "wake_command")
+        return None
+
+
+def make_robot() -> Runtime:
+    """创建散步机器人 Runtime。"""
+    return make_runtime(RobotParticipant())
+
+
+def _as_float(value: object) -> float:
+    if not isinstance(value, (int, float)):
+        return 0.0
+    result = float(value)
+    return result if result == result and abs(result) != float("inf") else 0.0
+
+
+__all__ = [
+    "ROBOT_STATECHART",
+    "ContinueWalking",
+    "Obstacle",
+    "Rest",
+    "RobotParticipant",
+    "SetEnergy",
+    "Wake",
+    "Walk",
+    "make_robot",
+]

fastpilot/core/__init__.py

@@ -0,0 +1,7 @@
+"""FastPilot 核心运行时、托管句柄与装配入口。"""
+
+from fastpilot.core.factory import make_runtime
+from fastpilot.core.handle import RuntimeHandle
+from fastpilot.core.runtime import Runtime
+
+__all__ = ["Runtime", "RuntimeHandle", "make_runtime"]

fastpilot/core/children.py

@@ -0,0 +1,105 @@
+"""父子 Runtime 的托管树与稳定路径解析。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from fastpilot.core.handle import RuntimeHandle
+from fastpilot.protocol.contracts import Fact
+from fastpilot.protocol.events import Event
+from fastpilot.protocol.hosting import HostedRuntimeView
+from fastpilot.protocol.system_facts import ChildAttached, ChildDetached
+
+if TYPE_CHECKING:
+    from fastpilot.core.runtime import Runtime
+
+type EmitEvent = Callable[[Fact], Event]
+
+
+class ChildRegistry:
+    """维护一个 Runtime 直接托管的子 Runtime 与递归数字路径。"""
+
+    def __init__(self, owner: Runtime, emit: EmitEvent) -> None:
+        self._owner = owner
+        self._emit = emit
+        self._children: dict[int, RuntimeHandle] = {}
+        self._next_id = 1
+
+    def attach(self, child: Runtime, name: str | None = None) -> RuntimeHandle:
+        """登记子 Runtime，并验证托管树保持单父级、非自指和无环。"""
+        if self._owner.status == "stopped":
+            raise RuntimeError("已停止的 Runtime 不能再托管子 Runtime")
+        if child is self._owner:
+            raise ValueError("运行时不能托管自己")
+        if child._parent is not None:
+            raise RuntimeError("子 Runtime 已经被其他父 Runtime 托管")
+        if self._contains_ancestor(child):
+            raise ValueError("托管关系会形成循环")
+        child_id = self._next_id
+        self._next_id += 1
+        handle = RuntimeHandle(child_id, name or f"child-{child_id}", child)
+        self._children[child_id] = handle
+        child._parent = self._owner
+        self._emit(ChildAttached(child_id, handle.name))
+        return handle
+
+    def handles(self) -> tuple[RuntimeHandle, ...]:
+        """读取直接子 Runtime 的稳定句柄。"""
+        return tuple(self._children.values())
+
+    def views(self) -> tuple[HostedRuntimeView, ...]:
+        """读取可嵌入父快照的子 Runtime 投影。"""
+        return tuple(handle.view() for handle in self._children.values())
+
+    def resolve(self, path: str) -> Runtime:
+        """沿 ``1/2/...`` 数字路径解析递归子 Runtime。"""
+        current = self._owner
+        for segment in filter(None, path.split("/")):
+            try:
+                child_id = int(segment)
+            except ValueError as exc:
+                raise KeyError(f"子 Runtime 编号无效：{segment}") from exc
+            with current._lock:
+                handle = current._children.get(child_id)
+                current = handle._runtime
+        return current
+
+    def get(self, child_id: int) -> RuntimeHandle:
+        """按稳定编号读取一个直接子 Runtime 句柄。"""
+        handle = self._children.get(child_id)
+        if handle is None:
+            raise KeyError(f"子 Runtime 不存在：{child_id}")
+        return handle
+
+    def detach(self, child_id: int, *, stop: bool = False) -> HostedRuntimeView:
+        """移除子 Runtime，并返回解除关系前的投影。"""
+        handle = self._children.get(child_id)
+        if handle is None:
+            raise KeyError(f"不存在的子运行时：{child_id}")
+        child_runtime = handle.open()
+        if stop and child_runtime.snapshot().status != "stopped":
+            child_runtime.stop()
+        child = handle._runtime
+        child._parent = None
+        del self._children[child_id]
+        self._emit(ChildDetached(child_id, handle.name))
+        return handle.view()
+
+    def stop_all(self) -> None:
+        """沿每个子 Runtime 的控制面传播父级终止。"""
+        for handle in tuple(self._children.values()):
+            child = handle.open()
+            if child.snapshot().status != "stopped":
+                child.stop()
+
+    def _contains_ancestor(self, candidate: Runtime) -> bool:
+        cursor: Runtime | None = self._owner
+        while cursor is not None:
+            if cursor is candidate:
+                return True
+            cursor = cursor._parent
+        return False
+
+
+__all__ = ["ChildRegistry"]

fastpilot/core/factory.py

@@ -0,0 +1,34 @@
+"""根据参与者实际能力创建 FastPilot Runtime。"""
+
+from collections.abc import Mapping
+
+from fastpilot.core.runtime import Runtime
+from fastpilot.observation.runtime_history import HistoryStoreFactory
+from fastpilot.protocol import framework_protocol
+from fastpilot.state import DataParticipant, StateMachine, participant_protocol
+
+
+def make_runtime(
+    participant: object,
+    *,
+    history: HistoryStoreFactory | None = None,
+) -> Runtime:
+    """把一个领域参与者装配成可控制、可观察的 Runtime。
+
+    工厂根据参与者提供的数据、时间与状态能力组装 Runtime。参与者表达领域
+    规则，Runtime 组织命令、时间、队列、事件和草稿边界。
+    """
+    initial_data: Mapping[str, object] = (
+        participant.initial_data if isinstance(participant, DataParticipant) else {}
+    )
+    protocol = framework_protocol().merge(participant_protocol(participant))
+    history_stores = None if history is None else history(protocol)
+    return Runtime(
+        StateMachine.from_participant(participant),
+        dict(initial_data),
+        protocol=protocol,
+        history_stores=history_stores,
+    )
+
+
+__all__ = ["make_runtime"]

fastpilot/core/handle.py

@@ -0,0 +1,59 @@
+"""父子 Runtime 之间的位置句柄。
+
+父 Runtime 把子 Runtime 登记到托管树中，并通过句柄获得稳定编号、名称和
+观察投影。``open()`` 进入子 Runtime 自己的控制面，因此每一层都沿自己的
+时钟、锁、历史和安全边界推进。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastpilot.protocol.hosting import HostedRuntimeView
+
+if TYPE_CHECKING:
+    from fastpilot.core.runtime import Runtime
+
+
+class RuntimeHandle:
+    """父 Runtime 持有的子 Runtime 位置句柄。"""
+
+    __slots__ = ("_id", "_name", "_runtime")
+
+    def __init__(self, entry_id: int, name: str, runtime: Runtime) -> None:
+        self._id = entry_id
+        self._name = name
+        self._runtime = runtime
+
+    @property
+    def id(self) -> int:
+        """读取托管树中的稳定子 Runtime 编号。"""
+        return self._id
+
+    @property
+    def name(self) -> str:
+        """读取父 Runtime 用于展示和诊断的子 Runtime 名称。"""
+        return self._name
+
+    def open(self) -> Runtime:
+        """进入子 Runtime 自己的完整控制面。
+
+        句柄表达父级托管树中的位置与名称；``open()`` 返回孩子自身拥有的
+        完整 Runtime。
+        """
+
+        return self._runtime
+
+    def view(self) -> HostedRuntimeView:
+        """把子 Runtime 快照压缩成可嵌入父快照的只读投影。"""
+        snapshot = self._runtime.snapshot()
+        return HostedRuntimeView(
+            self._id,
+            self._name,
+            snapshot.status,
+            snapshot.time,
+            snapshot.state,
+        )
+
+    def __repr__(self) -> str:
+        return f"RuntimeHandle(id={self._id}, name={self._name!r})"