whiletrue 0.1.0__py3-none-any.whl

whiletrue/control/map_.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, cast
+
+from pydantic import BaseModel, Field
+
+from whiletrue.control.chain import run_chain
+from whiletrue.core import (
+    CompositeContext,
+    ConfigIssue,
+    Emit,
+    PipelineNode,
+    Strategy,
+    ValidateContext,
+    define_strategy,
+    parse_expr,
+)
+from whiletrue.core.expr import ExprError
+from whiletrue.core.module import PortValues
+
+#: Variables a `map`/`switch` expression may use.
+EXPR_VARIABLES = frozenset({"run", "item", "iter", "input"})
+
+
+class MapConfig(BaseModel):
+    #: CEL expression yielding a list. Each element is `iter.value` for one pass over the children.
+    over: str = Field(min_length=1)
+    #: How many elements run at once (each pass gets its own `iter`). Results keep element order.
+    parallel: int = Field(default=1, ge=1)
+
+
+def check_expr(name: str, source: str) -> list[ConfigIssue]:
+    try:
+        problems = parse_expr(source).check(EXPR_VARIABLES)
+    except ExprError as error:
+        problems = [str(error)]
+    return [ConfigIssue("error", f"`{name}`: {p}") for p in problems]
+
+
+def _validate(config: MapConfig, _vctx: ValidateContext) -> list[ConfigIssue]:
+    return check_expr("map.over", config.over)
+
+
+async def _run(
+    children: list[PipelineNode], input: PortValues, ctx: CompositeContext[MapConfig]
+) -> Emit:
+    scope = {**ctx.scope.snapshot(), "input": input.get("in")}
+    values = parse_expr(ctx.config.over).eval(scope)
+    if not isinstance(values, list):
+        return Emit("fail", {"error": f"`map.over` must be a list, got {type(values).__name__}"})
+    elements = cast(list[Any], values)
+    if ctx.config.parallel > 1:
+        return await _run_parallel(children, input, ctx, elements)
+    results: list[Any] = []
+    for index, value in enumerate(elements, start=1):
+        if ctx.signal.aborted:
+            return Emit("fail", {"error": "cancelled"})
+        ctx.scope.set("iter", {"index": index, "value": value, "previous": ""})
+        emit = await run_chain(children, input, ctx)
+        if emit.port != "ok":
+            return emit
+        results.append(emit.value)
+    return Emit("ok", results)
+
+
+async def _run_parallel(
+    children: list[PipelineNode],
+    input: PortValues,
+    ctx: CompositeContext[MapConfig],
+    elements: list[Any],
+) -> Emit:
+    slots = asyncio.Semaphore(ctx.config.parallel)
+    stop = asyncio.Event()
+
+    async def one(index: int, value: Any) -> Emit | None:
+        async with slots:
+            if stop.is_set() or ctx.signal.aborted:
+                return None
+            scope = ctx.scope.child()
+            scope.set("iter", {"index": index, "value": value, "previous": ""})
+            emit = await run_chain(children, input, ctx, scope)
+            if emit.port != "ok":
+                stop.set()
+            return emit
+
+    emits = await asyncio.gather(*(one(i, v) for i, v in enumerate(elements, start=1)))
+    for emit in emits:
+        if emit is not None and emit.port != "ok":
+            return emit
+    if any(e is None for e in emits):
+        return Emit("fail", {"error": "cancelled"})
+    return Emit("ok", [e.value for e in emits if e is not None])
+
+
+#: Runs the children once per element of `over` (one after another, or `parallel` at once) and
+#: returns the list of results.
+#: The first element that doesn't succeed stops the map and its outcome is returned.
+map_strategy: Strategy[Any] = define_strategy(
+    Strategy(id="map", config=MapConfig, validate=_validate, run=_run)
+)

whiletrue/control/parallel.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from whiletrue.core import (
+    CompositeContext,
+    Emit,
+    EmptyConfig,
+    PipelineNode,
+    Strategy,
+    define_strategy,
+    resolve_outcome,
+)
+from whiletrue.core.module import PortValues
+
+
+async def _run(
+    children: list[PipelineNode], input: PortValues, ctx: CompositeContext[EmptyConfig]
+) -> Emit:
+    emits = await asyncio.gather(*(ctx.run(child, input) for child in children))
+    for emit in emits:
+        if resolve_outcome(emit.port, {}, ctx.policy).action != "continue":
+            return emit
+    return Emit("ok", [emit.value for emit in emits])
+
+
+#: Runs every child at the same time on the same input and returns the list of their results in
+#: order. If any child doesn't succeed, the first such outcome (in child order) is returned.
+parallel_strategy: Strategy[Any] = define_strategy(
+    Strategy(id="parallel", config=EmptyConfig, run=_run)
+)

whiletrue/control/retry.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Literal
+
+from pydantic import BaseModel, PositiveFloat, PositiveInt
+
+from whiletrue.control.chain import run_chain
+from whiletrue.control.loop import describe
+from whiletrue.core import (
+    CompositeContext,
+    ConfigIssue,
+    Emit,
+    PipelineNode,
+    Strategy,
+    ValidateContext,
+    define_strategy,
+    parse_duration,
+)
+from whiletrue.core.module import PortValues
+
+
+class RetryConfig(BaseModel):
+    max: PositiveInt = 3
+    #: Delay before the second attempt, e.g. "2s". Grows by `factor` each further attempt.
+    backoff: str | int | float | None = None
+    factor: PositiveFloat = 1.0
+    #: Expose the previous failure as `{{iter.previous}}` to the next attempt.
+    feedback: bool = True
+    #: What happens when every attempt failed. Default: park the item for a human.
+    on_exhausted: Literal["needs_human", "fail"] = "needs_human"
+
+
+def _validate(config: RetryConfig, _vctx: ValidateContext) -> list[ConfigIssue]:
+    if config.backoff is None:
+        return []
+    try:
+        parse_duration(config.backoff)
+    except ValueError as error:
+        return [ConfigIssue("error", f"`retry.backoff`: {error}")]
+    return []
+
+
+async def _sleep(ctx: CompositeContext[Any], ms: float) -> None:
+    if ms <= 0:
+        return
+    waiter = asyncio.ensure_future(ctx.signal.wait())
+    try:
+        await asyncio.wait({waiter}, timeout=ms / 1000)
+    finally:
+        waiter.cancel()
+
+
+async def _run(
+    children: list[PipelineNode], input: PortValues, ctx: CompositeContext[RetryConfig]
+) -> Emit:
+    cfg = ctx.config
+    delay = parse_duration(cfg.backoff) if cfg.backoff is not None else 0
+    last = Emit("ok")
+    for attempt in range(1, cfg.max + 1):
+        if ctx.signal.aborted:
+            return Emit("fail", {"error": "cancelled"})
+        previous = describe(last.value) if cfg.feedback and attempt > 1 else ""
+        ctx.scope.set("iter", {"index": attempt, "previous": previous, "value": None})
+        last = await run_chain(children, input, ctx)
+        if last.port != "fail":
+            return last
+        ctx.log("warn", f"retry attempt {attempt}/{cfg.max} failed", None)
+        if attempt < cfg.max:
+            await _sleep(ctx, delay * cfg.factor ** (attempt - 1))
+    error = {"error": f"retry gave up after {cfg.max} attempts", "last": last.value}
+    return Emit(cfg.on_exhausted, error)
+
+
+#: Re-runs its children when they `fail`, up to `max` attempts, with optional backoff. Other
+#: outcomes pass straight through. When attempts run out, the item is parked as `needs_human`
+#: (or `fail` with `on_exhausted: fail`).
+retry_strategy: Strategy[Any] = define_strategy(
+    Strategy(id="retry", config=RetryConfig, validate=_validate, run=_run)
+)
+
+
+class TryConfig(BaseModel):
+    #: Outcome to fire instead of `fail`: `skip` carries on with the previous value, `ok` yields
+    #: the error object as the value.
+    emit: Literal["skip", "ok"] = "skip"
+
+
+async def _try(
+    children: list[PipelineNode], input: PortValues, ctx: CompositeContext[TryConfig]
+) -> Emit:
+    result = await run_chain(children, input, ctx)
+    if result.port != "fail" or ctx.signal.aborted:
+        return result
+    ctx.log("warn", "try swallowed a failure", {"error": describe(result.value)})
+    return Emit("ok", result.value) if ctx.config.emit == "ok" else Emit("skip")
+
+
+#: Runs its children and turns a `fail` into `skip` (or `ok`) so optional steps never stop the item.
+try_strategy: Strategy[Any] = define_strategy(Strategy(id="try", config=TryConfig, run=_try))

whiletrue/control/sequence.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+from whiletrue.control.chain import run_chain
+from whiletrue.core import (
+    CompositeContext,
+    Emit,
+    EmptyConfig,
+    PipelineNode,
+    Strategy,
+    define_strategy,
+)
+from whiletrue.core.module import PortValues
+
+
+async def _run(
+    children: list[PipelineNode], input: PortValues, ctx: CompositeContext[EmptyConfig]
+) -> Emit:
+    return await run_chain(children, input, ctx)
+
+
+#: Runs children one after another; each `out` feeds the next `in`.
+sequence_strategy: Strategy[Any] = define_strategy(
+    Strategy(id="sequence", chain=True, config=EmptyConfig, run=_run)
+)
+
+
+async def _tap(
+    children: list[PipelineNode], input: PortValues, ctx: CompositeContext[EmptyConfig]
+) -> Emit:
+    emit = await run_chain(children, input, ctx)
+    # On success the original input flows on, so a side branch (a fix) does not replace it.
+    return Emit("ok", input.get("in")) if emit.port == "ok" else emit
+
+
+#: Runs children like `sequence`, then passes its own input through unchanged.
+tap_strategy: Strategy[Any] = define_strategy(
+    Strategy(id="tap", chain=True, config=EmptyConfig, run=_tap)
+)

whiletrue/control/switch.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from whiletrue.control.map_ import check_expr
+from whiletrue.core import (
+    CompositeContext,
+    ConfigIssue,
+    Emit,
+    PipelineNode,
+    Strategy,
+    ValidateContext,
+    define_strategy,
+    parse_expr,
+)
+from whiletrue.core.module import PortValues
+
+
+class SwitchConfig(BaseModel):
+    #: CEL expression; its value (strings as-is, anything else as JSON) selects a case.
+    on: str = Field(min_length=1)
+    #: Case value -> id of a child step.
+    cases: dict[str, str] = Field(default_factory=lambda: {})
+    #: Child step id used when no case matches. Without it, no match fires `skip`.
+    default: str | None = None
+
+
+def _validate(config: SwitchConfig, _vctx: ValidateContext) -> list[ConfigIssue]:
+    return check_expr("switch.on", config.on)
+
+
+def _validate_node(
+    config: SwitchConfig, node: PipelineNode, _vctx: ValidateContext
+) -> list[ConfigIssue]:
+    ids = {c.id for c in node.children}
+    targets = [*config.cases.items(), *([("default", config.default)] if config.default else [])]
+    return [
+        ConfigIssue("error", f'`switch` case "{case}" targets unknown step "{target}"')
+        for case, target in targets
+        if target not in ids
+    ]
+
+
+def _key(value: Any) -> str:
+    return value if isinstance(value, str) else json.dumps(value, separators=(",", ":"))
+
+
+async def _run(
+    children: list[PipelineNode], input: PortValues, ctx: CompositeContext[SwitchConfig]
+) -> Emit:
+    value = parse_expr(ctx.config.on).eval({**ctx.scope.snapshot(), "input": input.get("in")})
+    target = ctx.config.cases.get(_key(value), ctx.config.default)
+    child = next((c for c in children if c.id == target), None)
+    if child is None:
+        return Emit("skip")
+    return await ctx.run(child, input)
+
+
+#: Runs exactly one child, chosen by evaluating `on` and looking it up in `cases`.
+switch_strategy: Strategy[Any] = define_strategy(
+    Strategy(
+        id="switch", config=SwitchConfig, validate=_validate, validate_node=_validate_node, run=_run
+    )
+)

whiletrue/core/__init__.py

@@ -0,0 +1,260 @@
+"""whiletrue core: module/port/cap model, config, validation, runtime. Imports no agent or VCS."""
+
+from whiletrue.abort import AbortSignal
+from whiletrue.core.caps import CapError, CapRegistry, CapValidation, create_builtin_caps
+from whiletrue.core.comments import (
+    REPLY_PREFIX,
+    CommentsContext,
+    CommentsProvider,
+    IncomingComment,
+    sync_comments,
+    with_prefix,
+)
+from whiletrue.core.composite import expand_composites
+from whiletrue.core.config import (
+    AgentDefinition,
+    CompositeDefinition,
+    ConfigError,
+    ParamSpec,
+    PipelineConfig,
+    PipelineNode,
+    SourceLoc,
+    load_agent_definition,
+    load_composite,
+    load_pipeline,
+    parse_agent_definition,
+    parse_composite,
+    parse_pipeline,
+)
+from whiletrue.core.context import (
+    CompositeContext,
+    Locks,
+    Resource,
+    Scope,
+    StepContext,
+    create_step_context,
+)
+from whiletrue.core.duration import parse_duration
+from whiletrue.core.events import EventBus, WtEvent
+from whiletrue.core.expr import Expr, ExprError, parse_expr
+from whiletrue.core.history import (
+    CommentRecord,
+    Decision,
+    EffectRecord,
+    LearningRecord,
+    LearningStatus,
+    ParkRecord,
+    SteerRecord,
+)
+from whiletrue.core.lock import (
+    LOCK_FILE,
+    LockError,
+    check_lock,
+    collect_file_hashes,
+    read_lock,
+    sha256_file,
+    write_lock,
+)
+from whiletrue.core.memory_store import MemoryStore
+from whiletrue.core.module import (
+    EFFECTS,
+    ActionModule,
+    ConfigIssue,
+    Effect,
+    Emit,
+    EmptyConfig,
+    ModuleDefinitionError,
+    Ports,
+    PortSpec,
+    Strategy,
+    ValidateContext,
+    define_action,
+    define_strategy,
+    is_effect,
+)
+from whiletrue.core.outcomes import (
+    OUTCOME_PORTS,
+    InvalidTransition,
+    ItemState,
+    OnFail,
+    OutcomePolicy,
+    Resolution,
+    can_transition,
+    is_outcome_port,
+    item_state_for,
+    resolve_outcome,
+    transition,
+)
+from whiletrue.core.registry import Plugin, PluginApi, Registry, RegistryError, SimplePlugin
+from whiletrue.core.replay import Recording, ReplayData, ReplayError, load_recording
+from whiletrue.core.runner import (
+    AgentLimits,
+    AgentRequest,
+    AgentResult,
+    RunContext,
+    Runner,
+    RunnerCapabilities,
+)
+from whiletrue.core.runtime import (
+    ItemOutcome,
+    RunItem,
+    RunResult,
+    find_dependency_cycles,
+    hash_pipeline,
+    run_pipeline,
+)
+from whiletrue.core.source import SourceError, SourceProvider, fetch_items, source_spec
+from whiletrue.core.store import (
+    ItemRecord,
+    RunRecord,
+    StateStore,
+    StepRecord,
+)
+from whiletrue.core.template import TemplateError, render_deep, render_template
+from whiletrue.core.validate import Diagnostic, format_diagnostic, has_errors, validate_pipeline
+from whiletrue.core.wake import (
+    WakeChecker,
+    WakeCondition,
+    WakeContext,
+    WakeResult,
+    WakeSpec,
+    evaluate_wake,
+    parse_wake,
+    wake_to_dict,
+)
+from whiletrue.core.workspace import (
+    Workspace,
+    WorkspaceError,
+    WorkspaceProvider,
+    resolve_workspace,
+    workspace_spec,
+)
+
+__all__ = [
+    "EFFECTS",
+    "LOCK_FILE",
+    "OUTCOME_PORTS",
+    "REPLY_PREFIX",
+    "AbortSignal",
+    "ActionModule",
+    "AgentDefinition",
+    "AgentLimits",
+    "AgentRequest",
+    "AgentResult",
+    "CapError",
+    "CapRegistry",
+    "CapValidation",
+    "CommentRecord",
+    "CommentsContext",
+    "CommentsProvider",
+    "CompositeContext",
+    "CompositeDefinition",
+    "ConfigError",
+    "ConfigIssue",
+    "Decision",
+    "Diagnostic",
+    "Effect",
+    "EffectRecord",
+    "Emit",
+    "EmptyConfig",
+    "EventBus",
+    "Expr",
+    "ExprError",
+    "IncomingComment",
+    "InvalidTransition",
+    "ItemOutcome",
+    "ItemRecord",
+    "ItemState",
+    "LearningRecord",
+    "LearningStatus",
+    "LockError",
+    "Locks",
+    "MemoryStore",
+    "ModuleDefinitionError",
+    "OnFail",
+    "OutcomePolicy",
+    "ParamSpec",
+    "ParkRecord",
+    "PipelineConfig",
+    "PipelineNode",
+    "Plugin",
+    "PluginApi",
+    "PortSpec",
+    "Ports",
+    "Recording",
+    "Registry",
+    "RegistryError",
+    "ReplayData",
+    "ReplayError",
+    "Resolution",
+    "Resource",
+    "RunContext",
+    "RunItem",
+    "RunRecord",
+    "RunResult",
+    "Runner",
+    "RunnerCapabilities",
+    "Scope",
+    "SimplePlugin",
+    "SourceError",
+    "SourceLoc",
+    "SourceProvider",
+    "StateStore",
+    "SteerRecord",
+    "StepContext",
+    "StepRecord",
+    "Strategy",
+    "TemplateError",
+    "ValidateContext",
+    "WakeChecker",
+    "WakeCondition",
+    "WakeContext",
+    "WakeResult",
+    "WakeSpec",
+    "Workspace",
+    "WorkspaceError",
+    "WorkspaceProvider",
+    "WtEvent",
+    "can_transition",
+    "check_lock",
+    "collect_file_hashes",
+    "create_builtin_caps",
+    "create_step_context",
+    "define_action",
+    "define_strategy",
+    "evaluate_wake",
+    "expand_composites",
+    "fetch_items",
+    "find_dependency_cycles",
+    "format_diagnostic",
+    "has_errors",
+    "hash_pipeline",
+    "is_effect",
+    "is_outcome_port",
+    "item_state_for",
+    "load_agent_definition",
+    "load_composite",
+    "load_pipeline",
+    "load_recording",
+    "parse_agent_definition",
+    "parse_composite",
+    "parse_duration",
+    "parse_expr",
+    "parse_pipeline",
+    "parse_wake",
+    "read_lock",
+    "render_deep",
+    "render_template",
+    "resolve_outcome",
+    "resolve_workspace",
+    "run_pipeline",
+    "sha256_file",
+    "source_spec",
+    "sync_comments",
+    "transition",
+    "validate_pipeline",
+    "wake_to_dict",
+    "with_prefix",
+    "workspace_spec",
+    "write_lock",
+]