synth-ai 0.2.14__py3-none-any.whl → 0.4.4__py3-none-any.whl

synth_ai/environments/examples/wordle/engine.py

@@ -1,398 +0,0 @@
-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

@@ -1,159 +0,0 @@
-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

@@ -1,75 +0,0 @@
-#!/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()