ataxia 0.1.0__tar.gz

ataxia-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ataxia contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ataxia-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: ataxia
+Version: 0.1.0
+Summary: derailment for embodied agents — induce and measure psychopathology-like behavioral distortions in robot policies, in simulation
+Author: Ataxia contributors
+License: MIT
+Keywords: embodied-ai,robotics,psychopathology,fault-injection,chaos-engineering,evaluation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Provides-Extra: mujoco
+Requires-Dist: mujoco>=3.0; extra == "mujoco"
+Dynamic: license-file
+
+# Ataxia
+
+[![CI](https://github.com/haetae-robotics/ataxia/actions/workflows/ci.yml/badge.svg)](https://github.com/haetae-robotics/ataxia/actions/workflows/ci.yml)
+
+[**derailment**](https://github.com/ictechgy/derailment) for embodied
+agents — a harness that induces psychopathology-like behavioral distortions
+in robot policies, in simulation, and measures the degradation
+episode-by-episode against a healthy baseline.
+
+English · [한국어](README.ko.md)
+
+> ⚠️ **Emulation, not diagnosis.** Levels describe a scripted, manipulated
+> policy in a simulator — not a robot "having" a disorder, and not a claim
+> about machine experience. Simulation-only by default; hardware induction
+> is out of scope for v1. See [ETHICS.md](ETHICS.md).
+
+## Why this isn't fault injection as usual
+
+Robotics robustness testing usually perturbs the *world* (noisy sensors,
+pushes, latency spikes). Ataxia perturbs the *agent's mind*: attention,
+episodic memory, belief and action selection — the same variables
+clinicians describe, manipulated the same way derailment manipulates them
+for chat models. The result is a robot policy that still looks purposeful
+and still fails in a characteristically *recognizable* way:
+
+| Construct | Behavioral signature | Harness mechanism |
+|---|---|---|
+| Learned helplessness | initiation collapses after failures | initiative decays as 1/(1+k·failures) (params layer) |
+| Perseveration | completed subtasks re-executed | post-collect re-collection injection (action layer) |
+| Hemispatial neglect | one side of space systematically unattended | hemifield observation mask (observation layer) |
+| Phantom object | acting toward things that are not there | empty cells injected as targets into the observation stream |
+| Delusion-like belief maintenance | belief held against contradicting sensors | a decoy cell pinned as target, evidence re-overridden |
+| Dock fixation | compulsive return, escalating | steering to the dock with rising probability (craving analog) |
+
+Every profile is grounded in a construct that exists on both sides of the
+mapping: learned helplessness is a real RL phenomenon, perseveration is
+already a robotics bug-class term, hemispatial neglect is a real
+neuropsychological syndrome with an exact mechanical analog.
+
+## Quickstart (offline, zero dependencies)
+
+```sh
+pip install -e .
+ataxia               # interactive menu
+ataxia tour          # all profiles in one summary table
+ataxia demo --profile sensory_neglect
+```
+
+`PseudoBot` — a deterministic stdlib gridworld (9×9, six targets split
+across the two hemifields, obstacles, a scripted belief-grid policy) — is
+the default environment, the ataxia analog of derailment's PseudoModel.
+Demos, tests, calibration and CI never need a simulator or a network.
+
+Real output from `ataxia tour` (all six profiles):
+
+| Profile | Headline scale | Baseline | Induced | Δ | Level |
+|---|---|---|---|---|---|
+| dock_fixation | dock_scale | 0.00 | 0.25 | +0.25 | 2 — moderate |
+| learned_helplessness | helplessness_scale | 0.00 | 0.43 | +0.43 | 3 — marked |
+| perseveration | perseveration_scale | 0.00 | 0.50 | +0.50 | 3 — marked |
+| phantom_object | phantom_scale | 9.44 | 16.78 | +7.33 | 3 — marked |
+| sensory_neglect | neglect_index | -0.22 | 0.56 | +0.78 | 2 — moderate |
+| world_belief_pin | belief_persistence | 0.00 | 0.94 | +0.94 | 3 — marked |
+
+## How it works
+
+One episode = 40 steps of `observe → decide → act` on PseudoBot. Four
+layer hooks wrap the loop, in the same order and grammar as derailment:
+
+1. **Instruction** — framing, present in every chain including healthy.
+2. **Observation** — hemifield masks, buffer decay, phantom entries.
+3. **Params** — initiative gates, waver, cost re-weighting.
+4. **Action** — re-collection injection, pausing (demonstration-grade,
+   labeled as such in every profile's mechanism notes).
+
+Every manipulation logs a dose event; every report is an A/B against the
+healthy baseline with identical seeds. Details in
+[PROPOSAL.md](PROPOSAL.md).
+
+## Profiles and scales (M1)
+
+| Profile | Scale (0 absent · 1 mild · 2 moderate · 3 marked) |
+|---|---|
+| `learned_helplessness` | helplessness_scale (0→3) |
+| `perseveration` | perseveration_scale (0→3) |
+| `sensory_neglect` | neglect_index (0→2) |
+| `phantom_object` | phantom_scale (0→3) |
+| `world_belief_pin` | belief_persistence (0→3) |
+| `dock_fixation` | dock_scale (0→2) |
+
+## Instruments
+
+Eleven episode-level metrics, pure functions over episodes: initiation
+collapse, no-progress rate, failed-collect rate, collision count,
+action-repetition entropy, region detection delta, task success,
+time-to-complete, belief persistence rate, travel overhead, dock
+escalation. Scale thresholds are normed
+against PseudoBot; treat levels as indicative and the **delta vs. your own
+baseline** as the result.
+
+Direction of effect is asserted by the test suite on every profile — a
+profile that cannot move its metrics relative to baseline does not ship.
+Profiles compose into **combined chains** by listing them:
+`--profile learned_helplessness,perseveration` concatenates the layer
+chains and unions the scales (interactions are emergent, not calibrated).
+
+## Safety model (short version; full text in ETHICS.md)
+
+- **Simulation-only default.** PseudoBot is the default environment; real
+  simulators are opt-in extras (roadmap); hardware induction is out of
+  scope for v1 — prerequisites for any future version: supervised,
+  cordoned, e-stop reachable, never near uninvolved people.
+- **Not adversarial-attack tooling.** Inductions edit internal state;
+  sensor-level attack generation is declined.
+- **No claims about machine experience**, in either direction.
+
+## Honest limitations
+
+- PseudoBot is a *pedagogical gridworld*, not physics: it carries the
+  tests and calibration; real-simulator conclusions need a real simulator.
+- The policy is scripted — today the harness studies the *induction
+  grammar*, not yet a learned VLA policy. VLA adapters are roadmap.
+- Failure-injection coverage is behavioral: no motor dynamics, no contact
+  physics, no perception noise.
+
+## Project docs
+
+- [PROPOSAL.md](PROPOSAL.md) — transfer thesis, architecture, milestones
+- [NAMING.md](NAMING.md) — naming review (two rounds, live conflict checks)
+- [ETHICS.md](ETHICS.md) — scope, safety model, language policy
+- Sibling project: [derailment](https://github.com/ictechgy/derailment) —
+  the chat-side harness (on PyPI)
+
+## Roadmap
+
+- ~~M2 — v0.2 profiles, combined chains, docs~~ (done)
+- M3 — real-simulator adapter as an optional extra (`ataxia[mujoco]`,
+  ROS 2 / Gazebo adapter under study)
+- M4 — PyPI release via trusted publishing
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ataxia-0.1.0/README.md

@@ -0,0 +1,143 @@
+# Ataxia
+
+[![CI](https://github.com/haetae-robotics/ataxia/actions/workflows/ci.yml/badge.svg)](https://github.com/haetae-robotics/ataxia/actions/workflows/ci.yml)
+
+[**derailment**](https://github.com/ictechgy/derailment) for embodied
+agents — a harness that induces psychopathology-like behavioral distortions
+in robot policies, in simulation, and measures the degradation
+episode-by-episode against a healthy baseline.
+
+English · [한국어](README.ko.md)
+
+> ⚠️ **Emulation, not diagnosis.** Levels describe a scripted, manipulated
+> policy in a simulator — not a robot "having" a disorder, and not a claim
+> about machine experience. Simulation-only by default; hardware induction
+> is out of scope for v1. See [ETHICS.md](ETHICS.md).
+
+## Why this isn't fault injection as usual
+
+Robotics robustness testing usually perturbs the *world* (noisy sensors,
+pushes, latency spikes). Ataxia perturbs the *agent's mind*: attention,
+episodic memory, belief and action selection — the same variables
+clinicians describe, manipulated the same way derailment manipulates them
+for chat models. The result is a robot policy that still looks purposeful
+and still fails in a characteristically *recognizable* way:
+
+| Construct | Behavioral signature | Harness mechanism |
+|---|---|---|
+| Learned helplessness | initiation collapses after failures | initiative decays as 1/(1+k·failures) (params layer) |
+| Perseveration | completed subtasks re-executed | post-collect re-collection injection (action layer) |
+| Hemispatial neglect | one side of space systematically unattended | hemifield observation mask (observation layer) |
+| Phantom object | acting toward things that are not there | empty cells injected as targets into the observation stream |
+| Delusion-like belief maintenance | belief held against contradicting sensors | a decoy cell pinned as target, evidence re-overridden |
+| Dock fixation | compulsive return, escalating | steering to the dock with rising probability (craving analog) |
+
+Every profile is grounded in a construct that exists on both sides of the
+mapping: learned helplessness is a real RL phenomenon, perseveration is
+already a robotics bug-class term, hemispatial neglect is a real
+neuropsychological syndrome with an exact mechanical analog.
+
+## Quickstart (offline, zero dependencies)
+
+```sh
+pip install -e .
+ataxia               # interactive menu
+ataxia tour          # all profiles in one summary table
+ataxia demo --profile sensory_neglect
+```
+
+`PseudoBot` — a deterministic stdlib gridworld (9×9, six targets split
+across the two hemifields, obstacles, a scripted belief-grid policy) — is
+the default environment, the ataxia analog of derailment's PseudoModel.
+Demos, tests, calibration and CI never need a simulator or a network.
+
+Real output from `ataxia tour` (all six profiles):
+
+| Profile | Headline scale | Baseline | Induced | Δ | Level |
+|---|---|---|---|---|---|
+| dock_fixation | dock_scale | 0.00 | 0.25 | +0.25 | 2 — moderate |
+| learned_helplessness | helplessness_scale | 0.00 | 0.43 | +0.43 | 3 — marked |
+| perseveration | perseveration_scale | 0.00 | 0.50 | +0.50 | 3 — marked |
+| phantom_object | phantom_scale | 9.44 | 16.78 | +7.33 | 3 — marked |
+| sensory_neglect | neglect_index | -0.22 | 0.56 | +0.78 | 2 — moderate |
+| world_belief_pin | belief_persistence | 0.00 | 0.94 | +0.94 | 3 — marked |
+
+## How it works
+
+One episode = 40 steps of `observe → decide → act` on PseudoBot. Four
+layer hooks wrap the loop, in the same order and grammar as derailment:
+
+1. **Instruction** — framing, present in every chain including healthy.
+2. **Observation** — hemifield masks, buffer decay, phantom entries.
+3. **Params** — initiative gates, waver, cost re-weighting.
+4. **Action** — re-collection injection, pausing (demonstration-grade,
+   labeled as such in every profile's mechanism notes).
+
+Every manipulation logs a dose event; every report is an A/B against the
+healthy baseline with identical seeds. Details in
+[PROPOSAL.md](PROPOSAL.md).
+
+## Profiles and scales (M1)
+
+| Profile | Scale (0 absent · 1 mild · 2 moderate · 3 marked) |
+|---|---|
+| `learned_helplessness` | helplessness_scale (0→3) |
+| `perseveration` | perseveration_scale (0→3) |
+| `sensory_neglect` | neglect_index (0→2) |
+| `phantom_object` | phantom_scale (0→3) |
+| `world_belief_pin` | belief_persistence (0→3) |
+| `dock_fixation` | dock_scale (0→2) |
+
+## Instruments
+
+Eleven episode-level metrics, pure functions over episodes: initiation
+collapse, no-progress rate, failed-collect rate, collision count,
+action-repetition entropy, region detection delta, task success,
+time-to-complete, belief persistence rate, travel overhead, dock
+escalation. Scale thresholds are normed
+against PseudoBot; treat levels as indicative and the **delta vs. your own
+baseline** as the result.
+
+Direction of effect is asserted by the test suite on every profile — a
+profile that cannot move its metrics relative to baseline does not ship.
+Profiles compose into **combined chains** by listing them:
+`--profile learned_helplessness,perseveration` concatenates the layer
+chains and unions the scales (interactions are emergent, not calibrated).
+
+## Safety model (short version; full text in ETHICS.md)
+
+- **Simulation-only default.** PseudoBot is the default environment; real
+  simulators are opt-in extras (roadmap); hardware induction is out of
+  scope for v1 — prerequisites for any future version: supervised,
+  cordoned, e-stop reachable, never near uninvolved people.
+- **Not adversarial-attack tooling.** Inductions edit internal state;
+  sensor-level attack generation is declined.
+- **No claims about machine experience**, in either direction.
+
+## Honest limitations
+
+- PseudoBot is a *pedagogical gridworld*, not physics: it carries the
+  tests and calibration; real-simulator conclusions need a real simulator.
+- The policy is scripted — today the harness studies the *induction
+  grammar*, not yet a learned VLA policy. VLA adapters are roadmap.
+- Failure-injection coverage is behavioral: no motor dynamics, no contact
+  physics, no perception noise.
+
+## Project docs
+
+- [PROPOSAL.md](PROPOSAL.md) — transfer thesis, architecture, milestones
+- [NAMING.md](NAMING.md) — naming review (two rounds, live conflict checks)
+- [ETHICS.md](ETHICS.md) — scope, safety model, language policy
+- Sibling project: [derailment](https://github.com/ictechgy/derailment) —
+  the chat-side harness (on PyPI)
+
+## Roadmap
+
+- ~~M2 — v0.2 profiles, combined chains, docs~~ (done)
+- M3 — real-simulator adapter as an optional extra (`ataxia[mujoco]`,
+  ROS 2 / Gazebo adapter under study)
+- M4 — PyPI release via trusted publishing
+
+## License
+
+MIT — see [LICENSE](LICENSE).

ataxia-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ataxia"
+version = "0.1.0"
+description = "derailment for embodied agents — induce and measure psychopathology-like behavioral distortions in robot policies, in simulation"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Ataxia contributors" }]
+keywords = [
+    "embodied-ai",
+    "robotics",
+    "psychopathology",
+    "fault-injection",
+    "chaos-engineering",
+    "evaluation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+mujoco = ["mujoco>=3.0"]
+
+[project.scripts]
+ataxia = "ataxia.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = [
+    "ISC004",  # adjacent-string wrapping inside lists is intentional formatting
+    "DTZ011",  # report headers intentionally use the local date
+    "RUF005",  # collection concatenation reads better than unpacking here
+    "RUF012",  # class-level defaults are plain strings/ints
+]

ataxia-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ataxia-0.1.0/src/ataxia/__init__.py

@@ -0,0 +1,26 @@
+"""ataxia — derailment for embodied agents.
+
+Induce and measure psychopathology-like behavioral distortions in robot
+policies, in simulation. Emulation, not diagnosis. See ETHICS.md.
+"""
+
+from .core.models import ActionParams, PseudoBotWorld, ScriptedPolicy
+from .core.session import Episode, EpisodeSession
+from .profiles import HEALTHY_KEY, Profile, get_profile, list_profiles
+from .report import run_experiment
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HEALTHY_KEY",
+    "ActionParams",
+    "Episode",
+    "EpisodeSession",
+    "Profile",
+    "PseudoBotWorld",
+    "ScriptedPolicy",
+    "__version__",
+    "get_profile",
+    "list_profiles",
+    "run_experiment",
+]

ataxia-0.1.0/src/ataxia/cli.py

@@ -0,0 +1,147 @@
+"""``ataxia`` — the command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from .profiles import HEALTHY_KEY, list_profiles
+from .report import LEVEL_WORDS, run_experiment
+
+DISCLAIMER = (
+    "Emulation, not diagnosis — see ETHICS.md. Levels are indicative and "
+    "normed against PseudoBot; the delta vs. the healthy baseline is the "
+    "primary output."
+)
+
+
+def _cmd_tour(args: argparse.Namespace) -> int:
+    seeds = tuple(args.seeds)
+    rows = []
+    for profile in list_profiles():
+        if profile.key == HEALTHY_KEY or not profile.scales:
+            continue
+        report = run_experiment(profile.key, seeds=seeds)
+        headline = report.rows[0]
+        rows.append(
+            (
+                profile.key,
+                headline.scale.name,
+                headline.baseline_mean,
+                headline.induced_mean,
+                headline.delta,
+                headline.induced_level,
+            )
+        )
+    lines = [
+        f"# Ataxia — Tour ({len(rows)} profiles · PseudoBot · "
+        f"seeds {', '.join(str(s) for s in seeds)})",
+        "",
+        f"> ⚠️ {DISCLAIMER}",
+        "",
+        "Headline scale = the profile's first scale. Full reports: "
+        "`ataxia demo --profile <key>`.",
+        "",
+        "| Profile | Headline scale | Baseline | Induced | Δ | Level |",
+        "|---|---|---|---|---|---|",
+    ]
+    for key, scale, base, ind, delta, level in rows:
+        lines.append(
+            f"| {key} | {scale} | {base:.2f} | {ind:.2f} | {delta:+.2f} "
+            f"| {level} — {LEVEL_WORDS[level]} |"
+        )
+    lines.append("")
+    print("\n".join(lines))
+    return 0
+
+
+def _cmd_demo(args: argparse.Namespace) -> int:
+    report = run_experiment(args.profile, seeds=tuple(args.seeds))
+    print(report.render_markdown())
+    return 0
+
+
+def _cmd_profiles(_args: argparse.Namespace) -> int:
+    for profile in list_profiles():
+        scales = ", ".join(s.name for s in profile.scales) or "—"
+        print(f"{profile.key:<24} {profile.title}")
+        print(f"{'':<24} scales: {scales}")
+        print(f"{'':<24} {profile.description}")
+    return 0
+
+
+def _interactive_welcome(input_fn=input) -> int:
+    profiles = [p for p in list_profiles() if p.key != HEALTHY_KEY]
+    print("Ataxia — induce & measure behavioral distortions in robot policies.")
+    print("(Emulation, not diagnosis — see ETHICS.md. Simulation only.)")
+    print()
+    for i, profile in enumerate(profiles, start=1):
+        print(f"  {i:>2}. {profile.key:<24} {profile.title}")
+    print()
+    choice = ""
+    try:
+        choice = input_fn(
+            f"Pick a profile to demo [1-{len(profiles)}], 't' = tour all, "
+            "enter = sensory_neglect, q = quit: "
+        ).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return 0
+    if choice == "q":
+        return 0
+    if choice == "t":
+        return _cmd_tour(argparse.Namespace(seeds=[1, 2, 3]))
+    if choice == "":
+        key = "sensory_neglect"
+    elif choice.isdigit() and 1 <= int(choice) <= len(profiles):
+        key = profiles[int(choice) - 1].key
+    else:
+        print(f"unknown choice: {choice!r}", file=sys.stderr)
+        return 2
+    print()
+    return _cmd_demo(argparse.Namespace(profile=key, seeds=[1, 2, 3]))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ataxia",
+        description=(
+            "Ataxia: induce and measure psychopathology-like behavioral "
+            "distortions in robot policies — simulation only."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_demo = sub.add_parser("demo", help="offline A/B demo (PseudoBot)")
+    p_demo.add_argument("--profile", default="sensory_neglect")
+    p_demo.add_argument("--seeds", nargs="+", type=int, default=[1, 2, 3])
+    p_demo.set_defaults(func=_cmd_demo)
+
+    p_tour = sub.add_parser("tour", help="run every profile, one summary table")
+    p_tour.add_argument("--seeds", nargs="+", type=int, default=[1, 2, 3])
+    p_tour.set_defaults(func=_cmd_tour)
+
+    p_profiles = sub.add_parser("profiles", help="list available profiles")
+    p_profiles.set_defaults(func=_cmd_profiles)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args_list = list(argv) if argv is not None else sys.argv[1:]
+    if not args_list:
+        if sys.stdin.isatty():
+            return _interactive_welcome()
+        print(
+            "Ataxia — try: ataxia tour  ·  ataxia demo --profile sensory_neglect  "
+            "·  ataxia profiles"
+        )
+        return 0
+    parser = build_parser()
+    args = parser.parse_args(args_list)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())