fg-env 0.3.0__py3-none-any.whl

fg_env/__init__.py

@@ -0,0 +1,113 @@
+"""fg-env: the Environment SDK for LLM agents. A JSON contract describes an environment; the engine runs it.
+
+    import fg_env
+
+    issues = fg_env.check("shop.json")                      # every problem with its path and a fix
+    result = fg_env.run("shop.json", {"shopper": "policy:thrifty"}, seed=1)
+    print(result.summary())
+
+    env = fg_env.load("shop.json", seed=7)                  # full control: preview, run, snapshot, fork
+    exp = fg_env.experiment("shop.json", runs=20, arms=["control", "promo"])
+
+``fg_env.guide()`` is the core authoring guide, mapping every other part (``fg_env.guide("all")`` is everything);
+``fg_env.new("game", "my_game.json")`` writes a ready-to-run contract to start from. The earlier template-based kernel API lives in
+:mod:`fg_env.legacy`.
+"""
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+try:
+    __version__ = _dist_version("fg-env")
+except _PackageNotFoundError:  # a source checkout on PYTHONPATH, not installed
+    __version__ = "0+unknown"
+
+# Environment SDK public API. Everything a user needs is importable from ``fg_env``.
+from .sdk.api import check, expand, load, parse, run
+from .sdk.branch import Branch
+from .sdk.fork import fork
+from .sdk.game import Game, GameState, game
+from .sdk.game.conformance import conformance
+from .sdk.game.pettingzoo import pettingzoo_aec, pettingzoo_parallel
+from .sdk.game.playthrough import playthrough
+from .sdk.gym import GymEnv, gym
+from .sdk.contract import Contract
+from .sdk.errors import ContractError, InputError, InvariantViolation, Issue, RunError, SnapshotError
+from .sdk.experiment import ExperimentResult, experiment
+from .sdk.guide import guide, schema
+from .sdk.scaffold import new
+from .sdk.measure import RunResult
+from .sdk.runtime import Env
+from .sdk.session import ToolResult, Wake
+from .sdk import participants
+from .sdk import analysis
+from .sdk.analysis import (backtest, behavior_checks, calibrate, chain, compare, drivers, highlights, narrative,
+                           optimise, precision, score, sensitivity, sweep, validate)
+from .sdk.tournament import tournament
+from .sdk.describe import describe
+from .sdk.patterns.fit import FitResult, fit_patterns
+from .sdk.patterns.decompose import Decomposition, decompose
+from .sdk.report import Report, report
+from .sdk.trace import trace
+from .sdk.evaluate import evaluate
+
+__all__ = [
+    "__version__",
+    "load",
+    "run",
+    "check",
+    "parse",
+    "expand",
+    "experiment",
+    "fork",
+    "game",
+    "gym",
+    "Branch",
+    "Game",
+    "GameState",
+    "GymEnv",
+    "guide",
+    "schema",
+    "new",
+    "Env",
+    "Contract",
+    "RunResult",
+    "ExperimentResult",
+    "Wake",
+    "ToolResult",
+    "Issue",
+    "ContractError",
+    "InputError",
+    "RunError",
+    "InvariantViolation",
+    "SnapshotError",
+    "participants",
+    "analysis",
+    "sweep",
+    "sensitivity",
+    "calibrate",
+    "optimise",
+    "fit_patterns",
+    "FitResult",
+    "decompose",
+    "Decomposition",
+    "report",
+    "Report",
+    "score",
+    "backtest",
+    "validate",
+    "precision",
+    "behavior_checks",
+    "highlights",
+    "narrative",
+    "drivers",
+    "compare",
+    "chain",
+    "tournament",
+    "describe",
+    "trace",
+    "evaluate",
+    "conformance",
+    "playthrough",
+    "pettingzoo_aec",
+    "pettingzoo_parallel",
+]

fg_env/__main__.py

@@ -0,0 +1,36 @@
+"""The ``fg-env`` command line: ``fg-env <command> [args...]`` (or ``python -m fg_env <command>``).
+
+``fg-env --help`` lists the Environment SDK commands (check, run, preview, experiment, tournament, evaluate,
+trace, guide, schema, ...); the earlier template API's commands are under ``fg-env legacy <command>``.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="fg-env",
+        description="Fareground Environment SDK — check, run, preview and experiment with environment contracts",
+    )
+    from . import __version__
+    from .legacy.cli import add_legacy_command
+    from .sdk.analysis.cli import add_analysis_commands
+    from .sdk.cli import add_commands
+    from .sdk.report.cli import add_report_command
+
+    parser.add_argument("--version", action="version", version=f"fg-env {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    add_commands(sub)
+    add_analysis_commands(sub)
+    add_report_command(sub)
+    add_legacy_command(sub)
+    args = parser.parse_args(argv)
+    code: int = args.func(args)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fg_env/_snapshot_copy.py

@@ -0,0 +1,44 @@
+"""Detach checkpoint trees without generic deepcopy dispatch for JSON leaves.
+
+Only exact built-in types take the fast path. Subclasses and custom objects
+retain their deepcopy protocol. One memo preserves aliases/cycles across both
+paths; no mutable value is shared with the live world or another checkpoint.
+"""
+import copy
+from typing import Any
+
+_ATOMIC = frozenset((type(None), bool, int, float, str, bytes))
+
+
+def snapshot_copy(value: Any, memo: dict | None = None) -> Any:
+    kind = type(value)
+    if kind in _ATOMIC:
+        return value
+    if memo is None:
+        memo = {}
+    identity = id(value)
+    if identity in memo:
+        return memo[identity]
+    if kind is dict:
+        result: Any = {}
+        memo[identity] = result
+        for key, item in value.items():
+            result[snapshot_copy(key, memo)] = snapshot_copy(item, memo)
+        return result
+    if kind is list:
+        result = []
+        memo[identity] = result
+        result.extend(snapshot_copy(item, memo) for item in value)
+        return result
+    if kind is tuple:
+        # Same recursion rule as deepcopy's tuple handler: a nested mutable
+        # child may have completed this tuple while traversing a cycle.
+        items = [snapshot_copy(item, memo) for item in value]
+        if identity in memo:
+            return memo[identity]
+        if all(before is after for before, after in zip(value, items)):
+            return value  # e.g. immutable RNG state; never live mutable state.
+        result = tuple(items)
+        memo[identity] = result
+        return result
+    return copy.deepcopy(value, memo)

fg_env/action.py

@@ -0,0 +1,249 @@
+"""Action definitions, preconditions, and effects."""
+from dataclasses import dataclass, field
+from enum import Enum
+import math
+from typing import Any, Dict, List, Optional
+
+
+class Operator(Enum):
+    """Precondition operators."""
+    EQ = "eq"
+    NEQ = "neq"
+    GT = "gt"
+    GTE = "gte"
+    LT = "lt"
+    LTE = "lte"
+    IN = "in"
+    HAS_RESOURCE = "has_resource"
+    AT_LOCATION = "at_location"
+    IS_ADJACENT = "is_adjacent"
+    RELATION_GTE = "relation_gte"
+    IS_ALIVE = "is_alive"
+    SAME_FACTION = "same_faction"
+    DIFFERENT_FACTION = "different_faction"
+    HAS_ITEM = "has_item"
+    HAS_ITEM_TYPE = "has_item_type"
+    INVENTORY_NOT_FULL = "inventory_not_full"
+    SKILL_GTE = "skill_gte"
+    HAS_RECIPE = "has_recipe"
+
+
+def validate_numeric_precondition(operator: str, value: Any, expr: Any = None) -> None:
+    if not expr and operator in {"gt", "gte", "lt", "lte", "has_resource", "skill_gte", "relation_gte"}:
+        if value is None and operator in {"has_resource", "skill_gte", "relation_gte"}:
+            return
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+            raise ValueError(f"{operator} requires a finite numeric value; put dynamic comparisons in expr (for example, '$actor.price >= $actor.reservation_price').")
+
+
+@dataclass
+class Precondition:
+    """A single precondition check.
+
+    Two equivalent forms:
+        Legacy:   Precondition(subject="actor", operator=Operator.GTE,
+                                field="gold", value=100)
+        Modern:   Precondition(expr="$actor.gold >= 100")
+
+    When ``expr`` is set it takes precedence and is evaluated through
+    the unified predicate engine (``fg_env.predicates``).
+    The modern form is preferred for new games — one grammar covers
+    every kind of guard.
+    """
+    subject: str = "actor"              # "actor", "target", or entity property path
+    operator: Operator = Operator.EQ
+    value: Any = None                   # The value to compare against
+    field: Optional[str] = None         # Property name (for property checks)
+    resource: Optional[str] = None      # Resource name (for has_resource)
+    relation_type: Optional[str] = None # For relation checks
+    description: str = ""
+    # New: full expression form. String ("$actor.gold >= 100") or dict.
+    # Takes precedence when truthy.
+    expr: Any = None
+
+    def __post_init__(self):
+        validate_numeric_precondition(self.operator.value, self.value, self.expr)
+
+
+class EffectOperation(Enum):
+    """Types of state changes an effect can apply.
+
+    NOTE: New ops should be added via the kernel registry
+    (``fg_env.registry.effect``), not by extending this enum.
+    The enum exists for backwards compatibility — built-in ops still
+    live here so the engine's legacy switch keeps working, but custom
+    games extend the verb set without editing kernel code."""
+    SET = "set"
+    ADD = "add"
+    SUBTRACT = "subtract"
+    MULTIPLY = "multiply"
+    TRANSFER_RESOURCE = "transfer_resource"
+    SET_RELATION = "set_relation"
+    MODIFY_RELATION = "modify_relation"
+    MOVE_TO = "move_to"
+    KILL = "kill"
+    EMIT_EVENT = "emit_event"
+    APPLY_STATUS = "apply_status"
+    REMOVE_STATUS = "remove_status"
+    SPAWN_ENTITY = "spawn_entity"
+    DESPAWN_ENTITY = "despawn_entity"
+    GIVE_ITEM = "give_item"
+    TAKE_ITEM = "take_item"
+    DROP_ITEM = "drop_item"
+    PICKUP_ITEM = "pickup_item"
+    AWARD_XP = "award_xp"
+    CRAFT_ITEM = "craft_item"
+    # Social actions
+    POST_CONTENT = "post_content"
+    SHARE_CONTENT = "share_content"
+    REACT_CONTENT = "react_content"
+    FOLLOW_ENTITY = "follow_entity"
+    UNFOLLOW_ENTITY = "unfollow_entity"
+    # Generic game tokens (Phase 1 EffectDSL — replaces per-env
+    # `jail_cards`-style counters with a declarative tokens dict).
+    GRANT_TOKEN = "grant_token"
+    CONSUME_TOKEN = "consume_token"
+    # Increment a numeric property by a value or expression. Same as
+    # ADD but exists explicitly for board-track advancement clarity.
+    ADVANCE_TRACK = "advance_track"
+    # Place a mark on a BoardModule cell (tic-tac-toe, connect-four).
+    # `field` = board_id; `value` = mark to place; condition.field == "cell"
+    # carries the cell index ($params expression).
+    PLACE_ON_BOARD = "place_on_board"
+    # Wipe all marks on a named BoardModule. Used for multi-game
+    # tic-tac-toe / connect-four / any "best-of-N" format where a game
+    # ends and the board resets for the next game.
+    # `field` = board_id.
+    RESET_BOARD = "reset_board"
+    # Draw a card from a named DeckModule and apply its `effect` list.
+    # `field` = deck_id. The drawn card's effects fire against this
+    # same actor/target/params context — so a Chance card can move the
+    # actor, pay the bank, or grant a token.
+    DRAW_FROM_DECK = "draw_from_deck"
+    # Conditional branching effect. `value` is a dict:
+    #   { "if": { subject, field, operator, value }, OR
+    #     "if_expr": "$actor.position == 30",  (expression form)
+    #     "then": [ effect_dict, ... ],
+    #     "else": [ effect_dict, ... ]   (optional) }
+    # Lets the schema express "pass-GO collects $200" or "promote pawn
+    # at back rank" without any code.
+    CONDITIONAL = "conditional"
+    # Per-player hand operations (Tier 5a — HandModule).
+    # `field` carries the hand_id (defaults to "hand"); `value` carries
+    # the number of cards (DRAW_TO_HAND) or the card_id string
+    # (DISCARD_FROM_HAND / PLAY_CARD / PASS_CARD).
+    DRAW_TO_HAND = "draw_to_hand"
+    DISCARD_FROM_HAND = "discard_from_hand"
+    PLAY_CARD = "play_card"
+    PASS_CARD = "pass_card"
+    # Worker placement (Tier 5b — SlotsModule).
+    # `field` = slots_id, `value` = slot_id to claim/release.
+    CLAIM_SLOT = "claim_slot"
+    RELEASE_SLOT = "release_slot"
+    # Use one of the entity's held (kept) cards — e.g. "get out of
+    # jail free". `field` = deck_id. Optional params['card_idx']
+    # selects which held card.
+    USE_HELD_CARD = "use_held_card"
+
+
+@dataclass
+class EffectCondition:
+    """A runtime condition that must be True for an effect to apply.
+
+    Two equivalent forms:
+        Legacy:   EffectCondition(subject="actor", field="gold",
+                                   operator="gte", value=100)
+        Modern:   EffectCondition(expr="$actor.gold >= 100")
+
+    When ``expr`` is set it takes precedence and is evaluated through
+    the unified predicate engine (``fg_env.predicates``).
+    """
+    subject: str = "actor"              # "actor", "target"
+    field: Optional[str] = None         # Property to check
+    operator: str = "gte"               # "gte", "lte", "gt", "lt", "eq", "neq"
+    value: Any = None                   # Value to compare against
+    check_type: str = "property"        # "property", "alive", "has_status"
+    # New: full expression form. Either a string ("$actor.gold >= 100")
+    # or a structured dict ({"op": "gte", ...}). Takes precedence when
+    # truthy.
+    expr: Any = None
+
+
+@dataclass
+class Effect:
+    """A single state change to apply after action resolution."""
+    target: str                         # "actor", "target", or entity_id
+    operation: EffectOperation
+    field: Optional[str] = None         # Property to modify
+    value: Any = None                   # Value for the operation
+    resource: Optional[str] = None      # Resource name
+    relation_type: Optional[str] = None
+    description: str = ""
+    condition: Optional[EffectCondition] = None  # If set, effect only applies when True
+    scale_by_magnitude: bool = False    # When True, numeric value is multiplied by success_degree
+    # JSON loaders distinguish an omitted operand from an explicit null.
+    # None retains compatibility with Effects constructed directly in Python.
+    value_supplied: Optional[bool] = None
+
+
+@dataclass
+class ActionDefinition:
+    """
+    Complete definition of an action that agents can take.
+
+    The LLM sees: name, description, parameters.
+    The engine evaluates: preconditions, resolution, effects.
+    """
+    name: str
+    description: str
+    actor_type: str                              # EntityType name that can perform this
+    target_type: Optional[str] = None            # If the action requires a target
+    parameters: List[Dict[str, Any]] = field(default_factory=list)
+    # [{name: "amount", type: "int", required: True, min: 1, max: 100}]
+
+    preconditions: List[Precondition] = field(default_factory=list)
+
+    resolution_archetype: str = "deterministic"
+    resolution_params: Dict[str, Any] = field(default_factory=dict)
+
+    effects_on_success: List[Effect] = field(default_factory=list)
+    effects_on_failure: List[Effect] = field(default_factory=list)
+    effects_on_partial: List[Effect] = field(default_factory=list)  # Applied on partial success
+
+    # Visibility: who can see this action was taken
+    broadcast: bool = True
+    range: Optional[float] = None
+
+    # Action chains
+    requires_action: Optional[str] = None       # Must have completed this action first
+    requires_action_success: bool = True         # Only if prior action succeeded
+    unlocks_actions: List[str] = field(default_factory=list)  # Unlocked on success
+    locks_actions: List[str] = field(default_factory=list)    # Locked on success
+    cooldown_rounds: int = 0                     # Can't repeat for N rounds
+
+    # Multi-round sequences
+    sequence_rounds: int = 0                     # 0 = instant, >0 = takes N rounds
+    interruptible: bool = True                   # Can be interrupted by choosing another action
+
+    # Communication
+    message_action: bool = False                 # If True, reasoning is posted as a message
+
+    # Continuous-time duration (only used in CONTINUOUS temporal mode)
+    duration: float = 0.0                        # How long this action takes in continuous time
+    # Atomic, conserved numeric-property transfers on full success. Amounts
+    # resolve once against pre-transfer state; bounds reject rather than clamp.
+    transfers: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class ActionInstance:
+    """
+    A concrete action attempt by an agent during a turn.
+    Created when an agent decides to act; consumed by the engine.
+    """
+    action_name: str
+    actor_id: str
+    target_id: Optional[str] = None
+    parameters: Dict[str, Any] = field(default_factory=dict)
+    reasoning: str = ""
+    speech: str = ""