@tangle-network/starter-foundry 0.7.2 → 0.13.0

package/registry/families/agent-eval-harness-py/files/src/eval/sandbox_runner.py

@@ -0,0 +1,194 @@
+"""Sandbox-driven scenario runner.
+
+Spins a Tangle Sandbox (``tangle_sandbox.Sandbox``), deploys an agent
+bundle, runs scenarios via ``box.task()``, then deletes the sandbox.
+Designed to be passed to :func:`eval.runner.run_scenarios` as the
+``sandbox_runner`` arg.
+
+Lifecycle:
+
+1. ``__enter__`` / ``__init__`` — read API key + base URL from env, lazy-import
+   ``tangle_sandbox`` (so dry-runs work without the SDK installed), build
+   ``CreateSandboxOptions``, call ``client.create()``, wait for ``running``.
+2. ``run(spec)`` — call ``box.task(spec["input"])``; return the response
+   string. Raises ``RuntimeError`` on task failure (the runner converts to
+   a flow-level error, not a process exit).
+3. ``__exit__`` / ``close`` — best-effort ``box.delete()``. Always swallow
+   errors at teardown so a flaky teardown doesn't blow away the scorecard.
+
+The bundle layout follows the existing ``scripts/python/starter_foundry``
+loader (``load_agent_bundle`` → ``to_agent_profile`` → ``box.files.write``).
+We intentionally do not duplicate that loader here; instead we either reuse
+``starter_foundry.agent_bundle`` if available, or accept a pre-built profile
+dict. This keeps the eval harness aligned with the deploy script.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+DEFAULT_BASE_URL_ENVS = ("TANGLE_SANDBOX_BASE_URL", "SANDBOX_BASE_URL")
+
+
+def _resolve_sandbox_base_url(explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    for env in DEFAULT_BASE_URL_ENVS:
+        v = os.environ.get(env)
+        if v:
+            return v
+    raise RuntimeError(
+        "GAP: sandbox base URL not set (pass explicitly or set "
+        f"{' / '.join(DEFAULT_BASE_URL_ENVS)})"
+    )
+
+
+@dataclass
+class SandboxDriver:
+    """Manages the lifetime of one sandbox across an eval run.
+
+    Use as a context manager::
+
+        with SandboxDriver(bundle_dir=Path("./bundle")) as drv:
+            scorecard = run_scenarios(cfg, sandbox_runner=drv)
+    """
+
+    bundle_dir: Path | None = None
+    profile: dict[str, Any] | None = None
+    image: str = "node:20"
+    name: str = "eval-harness"
+    api_key_env: str = "TANGLE_SANDBOX_API_KEY"
+    base_url: str | None = None
+    workspace_root: str = "/home/agent"
+    workspace_files: list[Any] = field(default_factory=list)
+
+    _client: Any | None = field(default=None, init=False, repr=False)
+    _box: Any | None = field(default=None, init=False, repr=False)
+
+    # ------------------------------------------------------------------
+    # Bundle resolution
+    # ------------------------------------------------------------------
+
+    def _resolve_profile(self) -> tuple[dict[str, Any], list[Any], str]:
+        """Return ``(profile, workspace_files, workspace_root)`` for create+write."""
+        if self.profile is not None:
+            return self.profile, list(self.workspace_files), self.workspace_root
+        if self.bundle_dir is None:
+            raise ValueError(
+                "SandboxDriver: provide either bundle_dir or profile"
+            )
+        # Lazy-import the existing Python bundle loader to keep this module
+        # importable in environments where starter_foundry isn't installed.
+        try:
+            from starter_foundry.agent_bundle import (  # type: ignore[import-not-found]
+                load_agent_bundle,
+                resolve_workspace_root,
+                to_agent_profile,
+                to_workspace_files,
+            )
+        except ImportError as err:
+            raise RuntimeError(
+                "GAP: starter_foundry.agent_bundle not importable; "
+                "either install it or pass an explicit profile= dict."
+            ) from err
+
+        bundle = load_agent_bundle(self.bundle_dir)
+        return (
+            to_agent_profile(bundle, self.bundle_dir),
+            to_workspace_files(bundle, self.bundle_dir),
+            resolve_workspace_root(bundle),
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def open(self) -> None:
+        """Create the sandbox and write the bundle's workspace files."""
+        try:
+            from tangle_sandbox import (  # type: ignore[import-not-found]
+                BackendConfig,
+                CreateSandboxOptions,
+                Sandbox,
+            )
+        except ImportError as err:
+            raise RuntimeError(
+                "GAP: tangle_sandbox is not installed; "
+                "`pip install tangle-sandbox` or use --driver local/http."
+            ) from err
+
+        api_key = os.environ.get(self.api_key_env)
+        if not api_key:
+            raise RuntimeError(
+                f"GAP: env var {self.api_key_env} is unset; cannot reach Tangle sandbox API"
+            )
+        base_url = _resolve_sandbox_base_url(self.base_url)
+
+        profile, workspace_files, workspace_root = self._resolve_profile()
+        self.workspace_root = workspace_root
+
+        self._client = Sandbox(api_key=api_key, base_url=base_url)
+        self._box = self._client.create(
+            CreateSandboxOptions(
+                name=self.name,
+                image=self.image,
+                backend=BackendConfig(profile=profile),
+            )
+        )
+
+        wait_for = getattr(self._box, "wait_for", None)
+        if callable(wait_for):
+            wait_for("running")
+
+        for f in workspace_files:
+            # Workspace-file objects from agent_bundle have ``targetPath`` + ``content``;
+            # be liberal in what we accept (a dict with the same keys, too).
+            target = getattr(f, "targetPath", None) or (
+                f.get("targetPath") if isinstance(f, dict) else None
+            )
+            content = getattr(f, "content", None) or (
+                f.get("content") if isinstance(f, dict) else None
+            )
+            if not target or content is None:
+                continue
+            self._box.files.write(target, content)
+
+    def close(self) -> None:
+        """Best-effort sandbox delete; swallow errors so teardown never crashes."""
+        if self._box is None:
+            return
+        try:
+            self._box.delete()
+        except Exception:  # noqa: BLE001 — teardown
+            pass
+        self._box = None
+        self._client = None
+
+    def __enter__(self) -> "SandboxDriver":
+        self.open()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Runner adapter
+    # ------------------------------------------------------------------
+
+    def run(self, spec: dict[str, Any]) -> str:
+        """Execute one scenario inside the sandbox; return the agent's response."""
+        if self._box is None:
+            raise RuntimeError("SandboxDriver.run called before open()")
+        result = self._box.task(spec["input"])
+        if not getattr(result, "success", False):
+            err = getattr(result, "error", None) or "unknown error"
+            raise RuntimeError(f"sandbox task failed: {err}")
+        response = getattr(result, "response", None)
+        if not isinstance(response, str):
+            raise RuntimeError(
+                f"sandbox task returned non-str response: {type(response).__name__}"
+            )
+        return response

package/registry/families/agent-eval-harness-py/files/src/eval/scorecard.py

@@ -0,0 +1,192 @@
+"""Scorecard models — cross-language contract with the TS sibling.
+
+The shape mirrors `.evolve/scorecard.json` exactly, with these invariants
+enforced at the model layer:
+
+- ``value``, ``target``, ``aggregate`` rounded to 4 decimals.
+- ``status`` is one of {``pass``, ``fail``, ``unmeasured``, ``gap``}.
+- ``direction`` is one of {``higher-better``, ``lower-better``}.
+- ``aggregate`` = unweighted mean of pass-fraction across measurable flows
+  (``status in {pass, fail}``); ``unmeasured`` and ``gap`` flows are excluded
+  from the denominator (matches ``buildScorecard`` in the TS sibling).
+
+A flow's ``status`` is computed from ``value`` vs ``target`` + ``direction``:
+
+- ``higher-better``: pass iff value >= target.
+- ``lower-better``:  pass iff value <= target.
+- ``value is None``: status forced to ``unmeasured``.
+
+Use :func:`aggregate_score` to (re)compute the aggregate after editing flows.
+Use :func:`write_scorecard` to persist; it normalises rounding before write
+so byte-equal cross-language diffs are possible.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+FlowStatus = Literal["pass", "fail", "unmeasured", "gap"]
+FlowDirection = Literal["higher-better", "lower-better"]
+
+_ROUND_DECIMALS = 4
+
+
+def _round(v: float | int | None) -> float | None:
+    """Match the TS sibling's ``Number(x.toFixed(4))`` semantics."""
+    if v is None:
+        return None
+    return round(float(v), _ROUND_DECIMALS)
+
+
+class ScorecardInput(BaseModel):
+    """Provenance entry — a file the scorecard is derived from."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    mtime: str  # ISO-8601
+
+
+class ScorecardFlow(BaseModel):
+    """One measured flow — the unit of cross-language comparison.
+
+    Field order matches the TS sibling's emit order; pydantic v2 preserves
+    declaration order in ``model_dump()``.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    value: float | None
+    target: float
+    status: FlowStatus
+    productValueClaim: str = Field(
+        ..., description="One sentence: what does this flow's pass mean for the user?"
+    )
+    direction: FlowDirection
+    notes: str | None = None
+
+    @field_validator("value", "target", mode="after")
+    @classmethod
+    def _round_numeric(cls, v: float | None) -> float | None:
+        return _round(v)
+
+    @model_validator(mode="after")
+    def _coerce_status(self) -> ScorecardFlow:
+        """Force status=unmeasured when value is None.
+
+        We do not auto-derive pass/fail from value+target+direction here —
+        callers may have richer context (timeouts, judge errors, etc) and
+        should set ``status`` explicitly. We only enforce the floor.
+        """
+        if self.value is None and self.status not in {"unmeasured", "gap"}:
+            object.__setattr__(self, "status", "unmeasured")
+        return self
+
+
+def derive_status(
+    value: float | None, target: float, direction: FlowDirection
+) -> FlowStatus:
+    """Compute pass/fail/unmeasured from raw inputs. Mirrors TS ``deriveStatus``."""
+    if value is None:
+        return "unmeasured"
+    if direction == "higher-better":
+        return "pass" if value >= target else "fail"
+    return "pass" if value <= target else "fail"
+
+
+def aggregate_score(flows: list[ScorecardFlow]) -> float:
+    """Unweighted mean of pass fraction across measurable flows.
+
+    ``unmeasured`` and ``gap`` are excluded — they don't move the aggregate
+    in either direction. Returns 0.0 when no flows are measurable (matches
+    the TS sibling's behaviour rather than NaN, which serialises poorly).
+    """
+    measurable = [f for f in flows if f.status in {"pass", "fail"}]
+    if not measurable:
+        return 0.0
+    passes = sum(1 for f in measurable if f.status == "pass")
+    return _round(passes / len(measurable)) or 0.0
+
+
+class Scorecard(BaseModel):
+    """Top-level scorecard — the cross-language artifact."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    product: str
+    timestamp: str
+    coverage: str
+    aggregate: float
+    inputs: list[ScorecardInput] = Field(default_factory=list)
+    flows: list[ScorecardFlow] = Field(default_factory=list)
+
+    @field_validator("aggregate", mode="after")
+    @classmethod
+    def _round_aggregate(cls, v: float) -> float:
+        return _round(v) or 0.0
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        product: str,
+        flows: list[ScorecardFlow],
+        inputs: list[ScorecardInput] | None = None,
+        declared_count: int | None = None,
+        timestamp: str | None = None,
+    ) -> Scorecard:
+        """Construct a scorecard with derived ``coverage`` + ``aggregate``."""
+        ts = timestamp or datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace(
+            "+00:00", "Z"
+        )
+        measured = sum(1 for f in flows if f.status in {"pass", "fail"})
+        declared = declared_count if declared_count is not None else len(flows)
+        coverage = f"{measured}/{declared} flows measured"
+        return cls(
+            product=product,
+            timestamp=ts,
+            coverage=coverage,
+            aggregate=aggregate_score(flows),
+            inputs=inputs or [],
+            flows=flows,
+        )
+
+
+def write_scorecard(scorecard: Scorecard, path: str | Path) -> Path:
+    """Persist with deterministic field order + 2-space indent.
+
+    Matches the TS sibling's ``JSON.stringify(card, null, 2)`` byte-for-byte
+    for the field-name set we share. ``ensure_ascii=False`` preserves
+    non-ASCII codepoints (em dashes, unicode arrows in productValueClaim).
+
+    Required fields (``value``) are always emitted even when ``None`` so the
+    JSON survives a round-trip through :func:`load_scorecard`. Optional
+    fields (``notes``) are dropped when ``None`` to match the TS sibling
+    (``undefined`` keys are absent in JSON.stringify output).
+    """
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    payload: dict[str, Any] = scorecard.model_dump(mode="json")
+    # Strip only the optional-and-None fields. ``value`` is required (None is
+    # legal for unmeasured/gap flows), so it stays.
+    for flow in payload.get("flows", []):
+        if flow.get("notes") is None:
+            flow.pop("notes", None)
+    with p.open("w", encoding="utf-8") as fh:
+        json.dump(payload, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+    return p
+
+
+def load_scorecard(path: str | Path) -> Scorecard:
+    """Parse a scorecard JSON file. Validates against the model."""
+    p = Path(path)
+    with p.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    return Scorecard.model_validate(data)

package/registry/families/agent-eval-harness-py/files/tests/test_regression.py

@@ -0,0 +1,266 @@
+"""Regression-gate math tests.
+
+Anchors the bootstrap CI / Cohen's d / Welch t-test math against
+hand-checked numeric values, so the gate verdict is byte-stable across
+language ports (TS sibling validates against the same anchor numbers).
+
+Specific regressions these protect against:
+
+- ``cohens_d`` sign inversion (positive = head higher; we depend on this
+  to decide ``higher-better`` vs ``lower-better`` regression).
+- Bootstrap CI not honouring the ``alpha`` parameter (regression: a
+  hardcoded 95% would block ``--alpha 0.01`` audits).
+- Regression gate firing on either-or instead of and-and (regression:
+  either-or made the gate flap on tiny samples).
+- Sample-size floor (<8 → ValueError, not a fake CI).
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+import pytest
+
+from eval.regression import (
+    DEFAULT_RESAMPLES,
+    DEFAULT_SEED,
+    bootstrap_ci,
+    cohens_d,
+    regression_gate,
+    welch_t_test,
+)
+
+
+# ---------------------------------------------------------------------------
+# bootstrap CI
+# ---------------------------------------------------------------------------
+
+
+def test_bootstrap_ci_mean_matches_sample_mean() -> None:
+    """The reported ``mean`` field is the empirical mean (not the bootstrap mean)."""
+    samples = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]
+    ci = bootstrap_ci(samples, seed=42)
+    assert math.isclose(ci.mean, np.mean(samples)), ci
+
+
+def test_bootstrap_ci_seed_reproducibility() -> None:
+    """Same seed → same CI bounds, byte-equal."""
+    s = [0.1, 0.5, 0.9, 0.2, 0.4, 0.7, 0.6, 0.3, 0.8, 0.5]
+    a = bootstrap_ci(s, seed=DEFAULT_SEED)
+    b = bootstrap_ci(s, seed=DEFAULT_SEED)
+    assert a.low == b.low and a.high == b.high
+
+
+def test_bootstrap_ci_alpha_is_honoured() -> None:
+    """Tighter alpha widens the CI."""
+    s = [0.1, 0.5, 0.9, 0.2, 0.4, 0.7, 0.6, 0.3, 0.8, 0.5]
+    ci_95 = bootstrap_ci(s, alpha=0.05)
+    ci_99 = bootstrap_ci(s, alpha=0.01)
+    assert (ci_99.high - ci_99.low) >= (ci_95.high - ci_95.low)
+
+
+def test_bootstrap_ci_rejects_under_8_samples() -> None:
+    with pytest.raises(ValueError, match=r"≥8 samples"):
+        bootstrap_ci([0.1, 0.2, 0.3])
+
+
+def test_bootstrap_ci_rejects_nan() -> None:
+    with pytest.raises(ValueError, match="non-finite"):
+        bootstrap_ci([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, float("nan")])
+
+
+# ---------------------------------------------------------------------------
+# Cohen's d
+# ---------------------------------------------------------------------------
+
+
+def test_cohens_d_known_value() -> None:
+    """Anchor against a hand-checked value.
+
+    baseline = [0,0,0,0,0,0,0,0,0,0]   (mean 0, var 0)
+    head     = [1,1,1,1,1,1,1,1,1,1]   (mean 1, var 0)
+    pooled std = 0 → returns 0.0 (constant samples have no detectable effect).
+    """
+    a = [0.0] * 10
+    b = [1.0] * 10
+    assert cohens_d(a, b) == 0.0
+
+
+def test_cohens_d_sign_convention() -> None:
+    """Positive d means head > baseline (regardless of better/worse)."""
+    rng = np.random.default_rng(0)
+    a = rng.normal(0.5, 0.1, 50).tolist()
+    b = rng.normal(0.7, 0.1, 50).tolist()
+    d = cohens_d(a, b)
+    assert d > 0, f"expected positive d, got {d}"
+
+
+def test_cohens_d_anchor_two_normals() -> None:
+    """For two normals (mean diff 1, std 1, n large) Cohen's d ≈ 1.0."""
+    rng = np.random.default_rng(123)
+    a = rng.normal(0.0, 1.0, 500).tolist()
+    b = rng.normal(1.0, 1.0, 500).tolist()
+    d = cohens_d(a, b)
+    assert 0.85 < d < 1.15, f"expected d~1.0, got {d}"
+
+
+def test_cohens_d_rejects_under_2_samples() -> None:
+    with pytest.raises(ValueError):
+        cohens_d([0.5], [0.6, 0.7])
+
+
+# ---------------------------------------------------------------------------
+# Welch's t-test
+# ---------------------------------------------------------------------------
+
+
+def test_welch_t_test_significant_difference() -> None:
+    rng = np.random.default_rng(7)
+    a = rng.normal(0.5, 0.05, 50).tolist()
+    b = rng.normal(0.7, 0.05, 50).tolist()
+    _, p = welch_t_test(a, b)
+    assert p < 0.001
+
+
+def test_welch_t_test_no_difference() -> None:
+    rng = np.random.default_rng(7)
+    a = rng.normal(0.5, 0.1, 50).tolist()
+    b = rng.normal(0.5, 0.1, 50).tolist()
+    _, p = welch_t_test(a, b)
+    assert p > 0.05
+
+
+# ---------------------------------------------------------------------------
+# regression_gate (and-and rule)
+# ---------------------------------------------------------------------------
+
+
+def test_gate_higher_better_clear_regression_flags() -> None:
+    rng = np.random.default_rng(11)
+    base = rng.normal(0.85, 0.02, 50).tolist()
+    head = rng.normal(0.55, 0.02, 50).tolist()
+    v = regression_gate(
+        flow="quality",
+        baseline=base,
+        head=head,
+        direction="higher-better",
+    )
+    assert v.regressed is True
+    assert v.cohen_d < -1.0
+    assert v.welch_p < 0.001
+
+
+def test_gate_higher_better_improvement_does_not_flag() -> None:
+    """Improvements (head higher) on higher-better flows are NOT regressions."""
+    rng = np.random.default_rng(13)
+    base = rng.normal(0.6, 0.02, 50).tolist()
+    head = rng.normal(0.85, 0.02, 50).tolist()
+    v = regression_gate(
+        flow="quality",
+        baseline=base,
+        head=head,
+        direction="higher-better",
+    )
+    assert v.regressed is False, v.reason
+    assert v.cohen_d > 1.0  # positive d, but it's improvement, not regression
+
+
+def test_gate_lower_better_flips_direction() -> None:
+    """For lower-better flows, head GROWING is the regression."""
+    rng = np.random.default_rng(17)
+    # latency went from 0.2s to 0.5s — a regression
+    base = rng.normal(0.2, 0.02, 50).tolist()
+    head = rng.normal(0.5, 0.02, 50).tolist()
+    v = regression_gate(
+        flow="latency_p50",
+        baseline=base,
+        head=head,
+        direction="lower-better",
+    )
+    assert v.regressed is True
+    assert v.cohen_d > 1.0
+
+
+def test_gate_requires_both_d_and_p() -> None:
+    """Tiny d but tiny p (huge n) should NOT flag — d gate prevents flap."""
+    rng = np.random.default_rng(19)
+    # std=1 → effect is 0.05 sigma → tiny d, but n=2000 makes p < 0.05
+    base = rng.normal(0.5, 1.0, 2000).tolist()
+    head = rng.normal(0.45, 1.0, 2000).tolist()
+    v = regression_gate(
+        flow="quality",
+        baseline=base,
+        head=head,
+        direction="higher-better",
+    )
+    # p might be small here, but |d| should be < 0.2 → no regression
+    assert abs(v.cohen_d) < 0.2
+    assert v.regressed is False, v.reason
+
+
+def test_gate_includes_diff_ci_in_verdict() -> None:
+    rng = np.random.default_rng(23)
+    base = rng.normal(0.85, 0.02, 50).tolist()
+    head = rng.normal(0.85, 0.02, 50).tolist()
+    v = regression_gate(
+        flow="quality",
+        baseline=base,
+        head=head,
+        direction="higher-better",
+    )
+    # Both arms are noise around the same mean ⇒ diff CI must span 0.
+    # Pre-fix this asserted the head-mean fell inside head's own CI, which
+    # was tautological (the bug being measured was that the field said
+    # "diff" while computing "head-mean"). Now we assert the actual
+    # treatment-vs-baseline interval.
+    assert v.diff_ci_low < 0 < v.diff_ci_high
+    assert abs(v.delta) < 0.05  # tiny mean shift in noise
+    assert v.resamples == DEFAULT_RESAMPLES
+    assert v.seed == DEFAULT_SEED
+
+
+def test_diff_ci_recovers_known_lift() -> None:
+    """Cross-language parity check: large lift ⇒ diff CI brackets it."""
+    from eval.regression import bootstrap_diff_ci
+
+    base = [0.5] * 30
+    head = [0.7] * 30
+    low, high = bootstrap_diff_ci(base, head, seed=DEFAULT_SEED)
+    # Zero-variance arms ⇒ degenerate CI exactly at the point estimate 0.2.
+    assert abs(low - 0.2) < 1e-9
+    assert abs(high - 0.2) < 1e-9
+
+
+def test_diff_ci_does_not_collapse_to_head_mean_ci() -> None:
+    """Regression: pre-fix `regression_gate` returned the head-MEAN CI,
+    not the delta CI. With baseline ≪ head, the head-mean CI lives near
+    head_mean (~0.85) while the delta CI lives near delta (~0.15). The
+    fields must report the latter.
+    """
+    rng = np.random.default_rng(99)
+    base = rng.normal(0.70, 0.02, 30).tolist()
+    head = rng.normal(0.85, 0.02, 30).tolist()
+    v = regression_gate(
+        flow="quality",
+        baseline=base,
+        head=head,
+        direction="higher-better",
+    )
+    # Diff CI must be near 0.15, NOT near 0.85.
+    assert 0.10 < v.diff_ci_low < 0.20
+    assert 0.10 < v.diff_ci_high < 0.20
+    # Sanity: not regressed (head moved up significantly, but in
+    # higher-better direction → "improvement", which the gate codes as
+    # not-regressed).
+    assert v.regressed is False
+
+
+def test_gate_invalid_direction_raises() -> None:
+    with pytest.raises(ValueError, match="invalid direction"):
+        regression_gate(
+            flow="x",
+            baseline=[0.5] * 10,
+            head=[0.5] * 10,
+            direction="sideways",
+        )