From 85c009de2bab3716e13922d92d9497e8d41e94cf Mon Sep 17 00:00:00 2001
From: natinew77-creator <nati.new77@gmail.com>
Date: Wed, 10 Dec 2025 17:23:15 -0500
Subject: [PATCH 1/2] docs: clarify installation instructions for running
 examples

This PR addresses issue #297 by updating the README to:

1. Add a prominent warning that the PyPI package may be outdated
2. Recommend installing from source as the primary method for running examples
3. Reorganize installation steps to emphasize source installation
4. Add troubleshooting note for import errors after pip install

The PyPI package (dm-acme) was last updated in February 2022, while the
GitHub repository has continued to evolve with new agents and features.
This mismatch causes import errors when users try to run the examples
after installing via pip.

Fixes #297
---
 README.md | 41 ++++++++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index fc3cc4aa01..7f127f1695 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,11 @@ in our [technical report][Paper].
 
 ## Installation
 
+> ⚠️ **Important Note**: The PyPI package (`dm-acme`) may be significantly out of
+> date compared to this repository. If you want to run the examples or use the
+> latest agents, we strongly recommend **installing from source** (see option 2
+> below).
+
 To get up and running quickly just follow the steps below:
 
 1.  While you can install Acme in your standard python environment, we
@@ -63,31 +68,41 @@ To get up and running quickly just follow the steps below:
     pip install --upgrade pip setuptools wheel
     ```
 
-1.  While the core `dm-acme` library can be pip installed directly, the set of
+2.  **Recommended: Installing from source** (required for running examples):
+
+    The examples in this repository require the latest code which may not be
+    available in the PyPI package. Install from source by cloning this repository:
+
+    ```bash
+    git clone https://github.com/google-deepmind/acme.git
+    cd acme
+    pip install -e .[jax,tf,envs]
+    ```
+
+    This installs Acme in "editable" mode, allowing you to run all examples and
+    use the latest agents.
+
+3.  **Alternative: Installing from PyPI** (may be outdated):
+
+    While the core `dm-acme` library can be pip installed directly, the set of
     dependencies included for installation is minimal. In particular, to run any
     of the included agents you will also need either [JAX] or [TensorFlow]
-    depending on the agent. As a result we recommend installing these components
-    as well, i.e.
+    depending on the agent:
 
     ```bash
     pip install dm-acme[jax,tf]
     ```
 
-1.  Finally, to install a few example environments (including [gym],
-    [dm_control], and [bsuite]):
+    To install a few example environments (including [gym], [dm_control], and
+    [bsuite]):
 
     ```bash
     pip install dm-acme[envs]
     ```
 
-1.  **Installing from github**: if you're interested in running the
-    bleeding-edge version of Acme, you can do so by cloning the Acme GitHub
-    repository and then executing following command from the main directory
-    (where `setup.py` is located):
-
-    ```bash
-    pip install .[jax,tf,testing,envs]
-    ```
+    > Note: If you encounter import errors when running examples after pip
+    > install (e.g., `cannot import name 'sac' from 'acme.agents.jax'`), please
+    > install from source using option 2 above.
 
 ## Citing Acme
 

From b74472757be9d38b430dea505218e35970485d24 Mon Sep 17 00:00:00 2001
From: natinew77-creator <nati.new77@gmail.com>
Date: Thu, 11 Dec 2025 01:19:03 -0500
Subject: [PATCH 2/2] Fix CQL learner always executing behavior cloning (#305)

The CQLLearner.step() method was hardcoding the check for 'learner_steps'
key, but the counter stores step counts using the key from get_steps_key()
which varies based on the counter's prefix configuration.

This caused the behavior cloning phase to never end when the counter was
initialized without the 'learner' prefix (e.g., in run_cql_jax.py example).

The fix uses self._counter.get_steps_key() to dynamically retrieve the
correct key, ensuring proper transition from BC to CQL training.
---
 acme/agents/jax/cql/learning.py | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/acme/agents/jax/cql/learning.py b/acme/agents/jax/cql/learning.py
index 83d21f8a75..63d51f7650 100644
--- a/acme/agents/jax/cql/learning.py
+++ b/acme/agents/jax/cql/learning.py
@@ -446,10 +446,8 @@ def step(self):
     transitions = next(self._demonstrations)
 
     counts = self._counter.get_counts()
-    if 'learner_steps' not in counts:
-      cur_step = 0
-    else:
-      cur_step = counts['learner_steps']
+    steps_key = self._counter.get_steps_key()
+    cur_step = counts.get(steps_key, 0)
     in_initial_bc_iters = cur_step < self._num_bc_iters
 
     if in_initial_bc_iters: