synth-ai 0.2.4.dev5__py3-none-any.whl → 0.2.4.dev7__py3-none-any.whl

synth_ai/environments/examples/wordle/engine.py

@@ -0,0 +1,398 @@
+from __future__ import annotations
+
+import random
+import string
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any
+
+from synth_ai.environments.environment.rewards.core import RewardComponent, RewardStack
+from synth_ai.environments.environment.shared_engine import (
+    GetObservationCallable,
+    InternalObservation,
+)
+from synth_ai.environments.reproducibility.core import IReproducibleEngine
+from synth_ai.environments.stateful.engine import StatefulEngine, StatefulEngineSnapshot
+from synth_ai.environments.tasks.core import TaskInstance
+
+DEFAULT_SOLUTIONS = [
+    "cigar",
+    "rebut",
+    "sissy",
+    "humph",
+    "awake",
+    "blush",
+    "focal",
+    "evade",
+    "naval",
+    "serve",
+    "heath",
+    "dwarf",
+    "model",
+    "karma",
+    "stink",
+    "grade",
+    "quiet",
+    "bench",
+    "abate",
+    "feign",
+    "major",
+    "death",
+    "fresh",
+    "crust",
+    "stool",
+    "colon",
+    "abase",
+    "marry",
+    "react",
+    "batty",
+    "pride",
+    "floss",
+    "helix",
+    "croak",
+    "staff",
+    "paper",
+    "unfed",
+    "whelp",
+    "trawl",
+    "outdo",
+    "adobe",
+    "crazy",
+    "sower",
+    "repay",
+    "digit",
+    "crate",
+    "cluck",
+    "spike",
+    "mimic",
+    "pound",
+]
+
+
+def _sanitize(word: str) -> str:
+    w = word.strip().lower()
+    if not w or not all(c in string.ascii_lowercase for c in w):
+        raise ValueError("word must contain only a–z letters")
+    return w
+
+
+def _score_guess(guess: str, target: str) -> str:
+    res = ["B"] * len(target)
+    counts = Counter(target)
+    for i, ch in enumerate(guess):
+        if ch == target[i]:
+            res[i] = "G"
+            counts[ch] -= 1
+    for i, ch in enumerate(guess):
+        if res[i] == "G":
+            continue
+        if counts.get(ch, 0) > 0:
+            res[i] = "Y"
+            counts[ch] -= 1
+    return "".join(res)
+
+
+@dataclass
+class WordlePublicState:
+    word_length: int
+    remaining_guesses: int
+    max_guesses: int
+    guesses: list[str]
+    feedback: list[str]  # Parallel to guesses; strings of 'G/Y/B'
+    last_feedback: str | None
+    last_guess: str | None
+    terminated: bool
+    status: str  # "in_progress" | "won" | "lost"
+
+    @property
+    def board_text(self) -> str:
+        if not self.guesses:
+            return "(no guesses yet)"
+        lines = []
+        for g, fb in zip(self.guesses, self.feedback, strict=False):
+            spaced = " ".join(list(fb))
+            lines.append(f"{g.upper()} | {spaced}")
+        return "\n".join(lines)
+
+
+@dataclass
+class WordlePrivateState:
+    reward_last: float
+    total_reward: float
+    terminated: bool
+    truncated: bool
+
+
+@dataclass
+class WordleEngineSnapshot(StatefulEngineSnapshot):
+    task_instance_dict: dict
+    engine_snapshot: dict
+
+
+class WordleWinComponent(RewardComponent):
+    async def score(self, state: WordlePublicState, action: Any) -> float:
+        return 1.0 if state.status == "won" else 0.0
+
+
+class WordleInvalidGuessComponent(RewardComponent):
+    def __init__(self) -> None:
+        self.invalid_attempted = False
+
+    async def score(self, state: WordlePublicState, action: Any) -> float:
+        if self.invalid_attempted:
+            self.invalid_attempted = False
+            return -1.0
+        return 0.0
+
+
+class WordleEngine(StatefulEngine, IReproducibleEngine):
+    def __init__(self, task_instance: TaskInstance):
+        self.task_instance = task_instance
+
+        # Read config from metadata
+        md = getattr(task_instance, "metadata", None)
+        self.word_length: int = getattr(md, "word_length", 5) if md else 5
+        self.max_guesses: int = getattr(md, "max_guesses", 6) if md else 6
+        self.enforce_wordlist: bool = getattr(md, "enforce_wordlist", False) if md else False
+        # Toggle: whether invalid actions consume a turn (default True)
+        self.consume_invalid_attempts: bool = (
+            getattr(md, "consume_invalid_attempts", True) if md else True
+        )
+
+        self.base_word_list: list[str] = [
+            w for w in DEFAULT_SOLUTIONS if len(w) == self.word_length
+        ] or [w for w in DEFAULT_SOLUTIONS if len(w) == 5]
+
+        # Target selection: prefer explicit target_word in metadata; else pick deterministically by seed
+        self.fixed_target: str | None = (
+            _sanitize(getattr(md, "target_word", ""))
+            if md and getattr(md, "target_word", None)
+            else None
+        )
+        self.seed: int | None = getattr(md, "seed", None) if md else None
+
+        # Runtime state
+        self.target: str | None = None
+        self.guesses: list[str] = []
+        self.feedback: list[str] = []
+        self.remaining_guesses: int = self.max_guesses
+        self.status: str = "in_progress"
+        self.terminated: bool = False
+        self.total_reward: float = 0.0
+
+        # Rewards
+        self.invalid_component = WordleInvalidGuessComponent()
+        self.reward_stack = RewardStack([WordleWinComponent(), self.invalid_component])
+
+    async def _reset_engine(
+        self, *, seed: int | None = None
+    ) -> tuple[WordlePrivateState, WordlePublicState]:
+        if seed is None:
+            seed = self.seed
+        if seed is not None and self.fixed_target is None:
+            random.seed(seed)
+        self.target = self.fixed_target or random.choice(self.base_word_list)
+        self.guesses = []
+        self.feedback = []
+        self.remaining_guesses = self.max_guesses
+        self.status = "in_progress"
+        self.terminated = False
+        self.total_reward = 0.0
+
+        pub = WordlePublicState(
+            word_length=self.word_length,
+            remaining_guesses=self.remaining_guesses,
+            max_guesses=self.max_guesses,
+            guesses=[],
+            feedback=[],
+            last_feedback=None,
+            last_guess=None,
+            terminated=False,
+            status=self.status,
+        )
+        priv = WordlePrivateState(
+            reward_last=0.0,
+            total_reward=0.0,
+            terminated=False,
+            truncated=False,
+        )
+        return priv, pub
+
+    async def _step_engine(self, action: str) -> tuple[WordlePrivateState, WordlePublicState]:
+        assert self.target is not None
+        guess = _sanitize(action)
+
+        # Validate
+        if len(guess) != self.word_length or (
+            self.enforce_wordlist and guess not in self.base_word_list
+        ):
+            # Penalize invalid action; do not consume a guess
+            self.invalid_component.invalid_attempted = True
+            if self.consume_invalid_attempts:
+                # consume a turn on invalid guesses
+                if self.remaining_guesses > 0:
+                    self.remaining_guesses -= 1
+                if self.remaining_guesses == 0:
+                    self.status = "lost"
+                    self.terminated = True
+            pub = WordlePublicState(
+                word_length=self.word_length,
+                remaining_guesses=self.remaining_guesses,
+                max_guesses=self.max_guesses,
+                guesses=self.guesses.copy(),
+                feedback=self.feedback.copy(),
+                last_feedback=self.feedback[-1] if self.feedback else None,
+                last_guess=self.guesses[-1] if self.guesses else None,
+                terminated=self.terminated,
+                status=self.status,
+            )
+            reward = await self.reward_stack.step_reward(pub, action)
+            self.total_reward += reward
+            priv = WordlePrivateState(
+                reward_last=reward,
+                total_reward=self.total_reward,
+                terminated=self.terminated,
+                truncated=False,
+            )
+            return priv, pub
+
+        fb = _score_guess(guess, self.target)
+        self.guesses.append(guess)
+        self.feedback.append(fb)
+        self.remaining_guesses -= 1
+
+        if guess == self.target:
+            self.status = "won"
+            self.terminated = True
+        elif self.remaining_guesses == 0:
+            self.status = "lost"
+            self.terminated = True
+        else:
+            self.status = "in_progress"
+
+        pub = WordlePublicState(
+            word_length=self.word_length,
+            remaining_guesses=self.remaining_guesses,
+            max_guesses=self.max_guesses,
+            guesses=self.guesses.copy(),
+            feedback=self.feedback.copy(),
+            last_feedback=fb,
+            last_guess=guess,
+            terminated=self.terminated,
+            status=self.status,
+        )
+
+        reward = await self.reward_stack.step_reward(pub, action)
+        self.total_reward += reward
+        priv = WordlePrivateState(
+            reward_last=reward,
+            total_reward=self.total_reward,
+            terminated=self.terminated,
+            truncated=False,
+        )
+        return priv, pub
+
+    async def _serialize_engine(self) -> WordleEngineSnapshot:
+        return WordleEngineSnapshot(
+            task_instance_dict=await self.task_instance.serialize(),
+            engine_snapshot={
+                "word_length": self.word_length,
+                "max_guesses": self.max_guesses,
+                "enforce_wordlist": self.enforce_wordlist,
+                "consume_invalid_attempts": self.consume_invalid_attempts,
+                "base_word_list": self.base_word_list,
+                "fixed_target": self.fixed_target,
+                "seed": self.seed,
+                "target": self.target,
+                "guesses": self.guesses,
+                "feedback": self.feedback,
+                "remaining_guesses": self.remaining_guesses,
+                "status": self.status,
+                "terminated": self.terminated,
+                "total_reward": self.total_reward,
+            },
+        )
+
+    @classmethod
+    async def _deserialize_engine(cls, snapshot: WordleEngineSnapshot) -> WordleEngine:
+        task_instance = await TaskInstance.deserialize(snapshot.task_instance_dict)
+        engine = cls(task_instance)
+        s = snapshot.engine_snapshot
+        engine.word_length = s["word_length"]
+        engine.max_guesses = s["max_guesses"]
+        engine.enforce_wordlist = s["enforce_wordlist"]
+        engine.consume_invalid_attempts = s.get("consume_invalid_attempts", True)
+        engine.base_word_list = s.get("base_word_list", engine.base_word_list)
+        engine.fixed_target = s.get("fixed_target")
+        engine.seed = s.get("seed")
+        engine.target = s.get("target")
+        engine.guesses = s.get("guesses", [])
+        engine.feedback = s.get("feedback", [])
+        engine.remaining_guesses = s.get("remaining_guesses", engine.max_guesses)
+        engine.status = s.get("status", "in_progress")
+        engine.terminated = s.get("terminated", False)
+        engine.total_reward = s.get("total_reward", 0.0)
+        return engine
+
+    def get_current_states_for_observation(self) -> tuple[WordlePrivateState, WordlePublicState]:
+        pub = WordlePublicState(
+            word_length=self.word_length,
+            remaining_guesses=self.remaining_guesses,
+            max_guesses=self.max_guesses,
+            guesses=self.guesses.copy(),
+            feedback=self.feedback.copy(),
+            last_feedback=self.feedback[-1] if self.feedback else None,
+            last_guess=self.guesses[-1] if self.guesses else None,
+            terminated=self.terminated,
+            status=self.status,
+        )
+        priv = WordlePrivateState(
+            reward_last=0.0,
+            total_reward=self.total_reward,
+            terminated=self.terminated,
+            truncated=False,
+        )
+        return priv, pub
+
+
+class SynthWordleObservationCallable(GetObservationCallable):
+    async def get_observation(
+        self, pub: WordlePublicState, priv: WordlePrivateState
+    ) -> InternalObservation:
+        header = f"WORDLE ({pub.word_length} letters, {pub.max_guesses} max guesses)"
+        lines = [
+            header,
+            "Submit a single English word (letters only).",
+            "",
+            pub.board_text,
+            "",
+        ]
+        if pub.status == "in_progress":
+            lines.append(f"You have {pub.remaining_guesses} guesses left.")
+        elif pub.status == "won":
+            lines.append("You guessed the word! ✅")
+        else:
+            lines.append("Out of guesses. ❌")
+
+        return {
+            "text": "\n".join(lines),
+            "status": pub.status,
+            "remaining_guesses": pub.remaining_guesses,
+            "guesses": pub.guesses,
+            "feedback": pub.feedback,
+            "reward_last": priv.reward_last,
+            "total_reward": priv.total_reward,
+            "terminated": pub.terminated,
+        }
+
+
+class SynthWordleCheckpointObservationCallable(GetObservationCallable):
+    async def get_observation(
+        self, pub: WordlePublicState, priv: WordlePrivateState
+    ) -> InternalObservation:
+        return {
+            "board_text_final": pub.board_text,
+            "status_final": pub.status,
+            "total_reward": priv.total_reward,
+            "terminated": pub.terminated,
+        }

synth_ai/environments/examples/wordle/environment.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from synth_ai.environments.environment.shared_engine import (
+    GetObservationCallable,
+    InternalObservation,
+)
+from synth_ai.environments.environment.tools import (
+    AbstractTool,
+    EnvToolCall,
+    ToolResult,
+)
+from synth_ai.environments.reproducibility.core import ReproducibleEnvironment
+from synth_ai.environments.stateful.core import StatefulEnvironment
+from synth_ai.environments.tasks.core import TaskInstance
+
+from .engine import (
+    SynthWordleCheckpointObservationCallable,
+    SynthWordleObservationCallable,
+    WordleEngine,
+    WordleEngineSnapshot,
+    WordlePrivateState,
+    WordlePublicState,
+)
+
+
+class WordleActionInput(BaseModel):
+    guess: str = Field(..., description="Your word guess (letters only)")
+
+
+class WordleInteractTool(AbstractTool):
+    name = "interact"
+    description = "Submit a word guess to the Wordle environment."
+    call_schema = WordleActionInput
+    result_schema = ToolResult
+
+    def __init__(self, engine: WordleEngine):
+        self.engine = engine
+
+    async def __call__(self, call: EnvToolCall) -> ToolResult:
+        try:
+            validated = self.call_schema(**call.args)
+            priv, pub = await self.engine._step_engine(validated.guess)
+            return ToolResult(ok=True, payload={"public_state": pub, "private_state": priv})
+        except Exception as e:
+            # Return current state with error message
+            priv, pub = self.engine.get_current_states_for_observation()
+            return ToolResult(
+                ok=False, error=str(e), payload={"public_state": pub, "private_state": priv}
+            )
+
+
+class WordleEnvironment(StatefulEnvironment, ReproducibleEnvironment[WordleEngine]):
+    def __init__(
+        self,
+        task_instance: TaskInstance,
+        custom_step_obs: GetObservationCallable | None = None,
+        custom_ckpt_obs: GetObservationCallable | None = None,
+    ) -> None:
+        self.name = "Wordle"
+        self.task_instance = task_instance
+        self.custom_step_observation_callable = custom_step_obs or SynthWordleObservationCallable()
+        self.custom_checkpoint_observation_callable = (
+            custom_ckpt_obs or SynthWordleCheckpointObservationCallable()
+        )
+        self.engine = WordleEngine(task_instance)
+        self._interact_tool = WordleInteractTool(self.engine)
+
+    async def initialize(self) -> InternalObservation:
+        priv, pub = await self.engine._reset_engine()
+        return await self._to_observation(priv, pub, self.custom_step_observation_callable)
+
+    async def step(self, tool_calls) -> InternalObservation:
+        validated_call = self.validate_tool_calls(tool_calls)
+        result = await self._interact_tool(validated_call)
+        if result.ok:
+            priv = result.payload["private_state"]
+            pub = result.payload["public_state"]
+            return await self._to_observation(priv, pub, self.custom_step_observation_callable)
+        else:
+            priv, pub = self.engine.get_current_states_for_observation()
+            return await self._to_observation(
+                priv, pub, self.custom_step_observation_callable, extra_obs={"error": result.error}
+            )
+
+    async def checkpoint(self) -> InternalObservation:
+        priv, pub = self.engine.get_current_states_for_observation()
+        return await self._to_observation(priv, pub, self.custom_checkpoint_observation_callable)
+
+    async def terminate(self) -> InternalObservation:
+        priv, pub = self.engine.get_current_states_for_observation()
+        pub.terminated = True
+        priv.terminated = True
+        return await self._to_observation(priv, pub, self.custom_checkpoint_observation_callable)
+
+    def validate_tool_calls(self, tool_calls) -> EnvToolCall:
+        # Accept EnvToolCall, dict-like, or list formats similar to other envs
+        if isinstance(tool_calls, EnvToolCall):
+            validated = tool_calls
+        elif isinstance(tool_calls, dict):
+            if "tool" in tool_calls:
+                validated = EnvToolCall(tool=tool_calls["tool"], args=tool_calls.get("args", {}))
+            elif "name" in tool_calls:
+                validated = EnvToolCall(
+                    tool=tool_calls["name"], args=tool_calls.get("parameters", {})
+                )
+            elif "function" in tool_calls:
+                validated = EnvToolCall(
+                    tool=tool_calls["function"]["name"],
+                    args=tool_calls["function"].get("arguments", {}),
+                )
+            else:
+                # Treat remaining keys as args; default tool name
+                validated = EnvToolCall(tool="interact", args=tool_calls)
+        elif isinstance(tool_calls, list):
+            if len(tool_calls) == 0:
+                raise ValueError("Empty tool calls list")
+            validated = self.validate_tool_calls(tool_calls[0])
+        else:
+            # Assume it's a raw guess string
+            validated = EnvToolCall(tool="interact", args={"guess": str(tool_calls)})
+
+        if validated.tool != "interact":
+            raise ValueError(f"Unknown tool: {validated.tool}")
+        # Normalize: allow 'action' key synonymous with 'guess'
+        args = validated.args
+        if "action" in args and "guess" not in args:
+            args = {"guess": args["action"]}
+        return EnvToolCall(tool="interact", args=args)
+
+    async def _to_observation(
+        self,
+        priv: WordlePrivateState,
+        pub: WordlePublicState,
+        obs_cb: GetObservationCallable | None,
+        extra_obs: dict[str, Any] | None = None,
+    ) -> InternalObservation:
+        if obs_cb:
+            obs = await obs_cb.get_observation(pub, priv)
+        else:
+            obs: InternalObservation = {}
+        if extra_obs and isinstance(obs, dict):
+            obs.update(extra_obs)
+        return obs
+
+    async def _serialize_engine(self) -> WordleEngineSnapshot:
+        return await self.engine._serialize_engine()
+
+    @classmethod
+    async def _deserialize_engine(
+        cls, snapshot: WordleEngineSnapshot, task_instance: TaskInstance
+    ) -> WordleEnvironment:
+        env = cls(task_instance)
+        env.engine = await WordleEngine._deserialize_engine(snapshot)
+        env._interact_tool = WordleInteractTool(env.engine)
+        return env

synth_ai/environments/examples/wordle/helpers/generate_instances_wordfreq.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""
+Generate a fixed Wordle instances.json using the "wordfreq" package.
+
+Usage:
+  pip install wordfreq
+  python -m synth_ai.environments.examples.wordle.helpers.generate_instances_wordfreq \
+      --count 500 --min-zipf 3.0 --outfile synth_ai/environments/examples/wordle/instances.json
+
+This script writes a deterministic list of 5-letter English words ranked by frequency.
+Commit the resulting instances.json to remove runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+
+from wordfreq import top_n_list, zipf_frequency
+
+
+def build_word_list(count: int, length: int, min_zipf: float, wordlist: str = "large") -> list[str]:
+    n_candidates = max(count * 20, 5000)
+    cands = [w.lower() for w in top_n_list("en", n_candidates, wordlist=wordlist)]
+    cands = [w for w in cands if len(w) == length and re.fullmatch(r"[a-z]+", w)]
+    scored = [(w, zipf_frequency(w, "en")) for w in cands]
+    scored = [p for p in scored if p[1] >= float(min_zipf)]
+    scored.sort(key=lambda t: (-t[1], t[0]))
+    out: list[str] = []
+    seen = set()
+    for w, _ in scored:
+        if w in seen:
+            continue
+        seen.add(w)
+        out.append(w)
+        if len(out) >= count:
+            break
+    if len(out) < count:
+        raise RuntimeError(
+            f"Insufficient {length}-letter words from wordfreq after filtering ({len(out)} < {count})."
+        )
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--count", type=int, default=500)
+    ap.add_argument("--length", type=int, default=5)
+    ap.add_argument("--min-zipf", type=float, default=3.0)
+    ap.add_argument("--wordlist", type=str, default="large")
+    ap.add_argument("--outfile", type=str, required=True)
+    args = ap.parse_args()
+
+    words = build_word_list(args.count, args.length, args.min_zipf, args.wordlist)
+
+    data = {
+        "name": f"Wordle Fixed TaskSet ({args.count} English words)",
+        "description": f"{len(words)} {args.length}-letter English words ranked by frequency (wordfreq).",
+        "defaults": {
+            "word_length": args.length,
+            "max_guesses": 6,
+            "enforce_wordlist": True,
+            "consume_invalid_attempts": True,
+        },
+        "instances": [{"target_word": w} for w in words],
+    }
+
+    with open(args.outfile, "w") as f:
+        json.dump(data, f, indent=2)
+    print(f"Wrote {len(words)} words to {args.outfile}")
+
+
+if __name__ == "__main__":
+    main()