Update README to match Container Yard behavior

README.md

@@ -24,7 +24,7 @@ Port container yards are critical logistics infrastructure where thousands of co
 
 ### How It Works
 1. **Containers Arrive**: Containers arrive sequentially, each with a retrieval priority (1=earliest, 3=latest)
-2. **Placement Decision**: Agent must choose which stack (0-9) to place the current container
+2. **Placement Decision**: Agent must choose a valid stack index (0 to num_stacks-1) for the current task
 3. **Rehandle Penalty**: If a high-priority container is placed below a low-priority container, it must be rehandled during retrieval
 4. **Reward Signal**: Agent receives immediate feedback based on placement efficiency
 
@@ -232,22 +232,31 @@ The deployed space includes:
 ## Environment Details
 
 ### Action
-**ContainerYardAction**: Contains a single field
-- `message` (str) - The message to echo back
+**ContainerYardAction**: Contains a single required field
+- `stack_index` (int) - Index of the stack to place the current container into
 
 ### Observation
-**ContainerYardObservation**: Contains the echo response and metadata
-- `echoed_message` (str) - The message echoed back
-- `message_length` (int) - Length of the message
-- `reward` (float) - Reward based on message length (length × 0.1)
-- `done` (bool) - Always False for echo environment
-- `metadata` (dict) - Additional info like step count
+**ContainerYardObservation**:
+- `stacks` (List[List[int]]) - Current stack states as container IDs
+- `containers_placed` (int) - Number of placed containers
+- `total_containers` (int) - Episode container count
+- `current_container_id` (int) - Next container to place, `-1` if done
+- `current_container_priority` (int) - Priority in range `1..3`
+- `rehandles_so_far` (int) - Accumulated rehandles
+- `num_stacks` (int) - Number of stacks in the current task
+- `max_stack_height` (int) - Capacity per stack
+- `action_error` (Optional[str]) - Validation error for invalid/full stack actions
+- `reward` (float) - Step reward
+- `done` (bool) - Whether episode is complete
 
 ### Reward
-The reward is calculated as: `message_length × 0.1`
-- "Hi" → reward: 0.2
-- "Hello, World!" → reward: 1.3
-- Empty message → reward: 0.0
+The reward is calculated per valid placement:
+- `+0.1` base reward for a valid placement
+- `-0.5 * rehandles_caused` penalty for new rehandles introduced by this move
+- `+0.3` bonus when placement causes zero rehandles
+- `+0.2` bonus when the container is stacked on same-priority container
+
+Invalid actions (out-of-range index or full stack) return `reward=0.0` and set `action_error`.
 
 ## Advanced Usage
 
@@ -257,13 +266,14 @@ If you already have a Container Yard environment server running, you can connect
 
 ```python
 from Container_Yard import ContainerYardEnv
+from models import ContainerYardAction
 
 # Connect to existing server
 Container_Yardenv = ContainerYardEnv(base_url="<ENV_HTTP_URL_HERE>")
 
 # Use as normal
 result = Container_Yardenv.reset()
-result = Container_Yardenv.step(ContainerYardAction(message="Hello!"))
+result = Container_Yardenv.step(ContainerYardAction(stack_index=0))
 ```
 
 Note: When connecting to an existing server, `Container_Yardenv.close()` will NOT stop the server.
@@ -278,11 +288,15 @@ from Container_Yard import ContainerYardAction, ContainerYardEnv
 # Connect with context manager (auto-connects and closes)
 with ContainerYardEnv(base_url="http://localhost:8000") as env:
     result = env.reset()
-    print(f"Reset: {result.observation.echoed_message}")
+    print(f"Current container: {result.observation.current_container_id}")
     # Multiple steps with low latency
-    for msg in ["Hello", "World", "!"]:
-        result = env.step(ContainerYardAction(message=msg))
-        print(f"Echoed: {result.observation.echoed_message}")
+    for _ in range(3):
+        result = env.step(ContainerYardAction(stack_index=0))
+        print(
+            f"Placed={result.observation.containers_placed} "
+            f"rehandles={result.observation.rehandles_so_far} "
+            f"reward={result.reward:.2f}"
+        )
 ```
 
 The client uses WebSocket connections for:
@@ -314,9 +328,15 @@ from concurrent.futures import ThreadPoolExecutor
 def run_episode(client_id: int):
     with ContainerYardEnv(base_url="http://localhost:8000") as env:
         result = env.reset()
-        for i in range(10):
-            result = env.step(ContainerYardAction(message=f"Client {client_id}, step {i}"))
-        return client_id, result.observation.message_length
+        while not result.done:
+            # Simple policy: choose first non-full stack
+            obs = result.observation
+            next_stack = next(
+                idx for idx, stack in enumerate(obs.stacks)
+                if len(stack) < obs.max_stack_height
+            )
+            result = env.step(ContainerYardAction(stack_index=next_stack))
+        return client_id, result.observation.rehandles_so_far
 
 # Run 4 episodes concurrently
 with ThreadPoolExecutor(max_workers=4) as executor: