soliplex 0.77.2__tar.gz → 0.78.1__tar.gz

{soliplex-0.77.2/src/soliplex.egg-info → soliplex-0.78.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soliplex
-Version: 0.77.2
+Version: 0.78.1
 Summary: An AI-powered Retrieval-Augmented Generation (RAG) system with a modern web interface.
 Author-email: Enfold <info@enfoldsystems.net>
 Classifier: Programming Language :: Python :: 3

{soliplex-0.77.2 → soliplex-0.78.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "soliplex"
-version = "0.77.2"
+version = "0.78.1"
 description = "An AI-powered Retrieval-Augmented Generation (RAG) system with a modern web interface."
 authors = [{ name = "Enfold", email = "info@enfoldsystems.net" }]
 readme = "README.md"

{soliplex-0.77.2 → soliplex-0.78.1}/src/soliplex/agents.py

@@ -144,18 +144,11 @@ def get_default_agent_from_configs(
         if isinstance(capability, HR_VisionCapabilities):
             capability.vision = agent_config.multimodal
 
-    # A single model-facing capability loads eagerly so its tools are visible;
-    #
-    # Multiple stay deferred so the model routes between them via
-    # 'load_capability'.
-    routing_capabilities = [
-        capability
-        for capability in capabilities
-        if _is_routing_capability(capability)
-    ]
-    defer_loading = len(routing_capabilities) > 1
-    for capability in routing_capabilities:
-        capability.defer_loading = defer_loading
+    # A hook-only capability is never deferred:  nothing would load it, and
+    # its hooks only fire once loaded.
+    for capability in capabilities:
+        if not _is_routing_capability(capability):
+            capability.defer_loading = False
 
     return pydantic_ai.Agent(
         model=model,

{soliplex-0.77.2 → soliplex-0.78.1}/src/soliplex/cli/audit.py

@@ -568,22 +568,39 @@ async def _list_admin_discriminators(dburi):
         return await policy.list_admin_user_discriminators()
 
 
-def _room_authz_groups(the_installation):
-    """Bucket configured rooms by authorization state; collect stale rows."""
-    configured = sorted(the_installation._config.room_configs)
+def _room_policies(the_installation) -> tuple[list, str | None]:
+    """Return ``(policies, error)`` for the stored room policies.
+
+    ``policies`` holds the unchecked policy models read via
+    'RoomAuthorizationPolicy.list_room_policies' and ``error`` is ``None``
+    on success. A RAM-based authz DB can hold no persisted rows, so it
+    short-circuits to ``([], None)`` without touching the database.
+
+    When the database itself cannot be reached -- e.g. its DBURI names a
+    Postgres server that isn't listening -- ``policies`` is empty and
+    ``error`` carries the exception message, so the audit can report the
+    unreachable DB instead of dying on the traceback.
+    """
     dburi = the_installation.authorization_dburi_async
 
     if dburi in cli_util._RAM_DBURIS:
-        return {
-            "default": list(configured),
-            "public": [],
-            "private": [],
-            "stale": [],
-        }
+        return [], None
+
+    try:
+        return list(asyncio.run(_list_room_policies(dburi))), None
+    except Exception as exc:
+        return [], f"{type(exc).__name__}: {exc}"
+
+
+def _room_authz_groups(the_installation, room_policies):
+    """Bucket configured rooms by authorization state; collect stale rows.
+
+    ``room_policies`` is the policy list from '_room_policies'.
+    """
+    configured = sorted(the_installation._config.room_configs)
 
     policies = {
-        policy.room_id: policy.default_allow_deny
-        for policy in asyncio.run(_list_room_policies(dburi))
+        policy.room_id: policy.default_allow_deny for policy in room_policies
     }
 
     configured_set = set(configured)
@@ -606,26 +623,21 @@ def _room_authz_groups(the_installation):
     }
 
 
-def _invalid_acl_json_paths(the_installation) -> dict:
+def _invalid_acl_json_paths(room_policies) -> dict:
     """Collect ACL entries whose stored 'json_path' fails to validate.
 
-    Reads every room policy via 'RoomAuthorizationPolicy.list_room_policies'
-    -- which returns the unchecked models, tolerating entries that would
-    fail 'policy.as_model' -- and re-validates each surfaced 'json_path'
-    against the currently-loaded JSONPath environment. Typically an
-    entry lands here when it was authored under a meta-config that
-    registered filter functions which are no longer present.
+    ``room_policies`` is the policy list from '_room_policies' -- the
+    unchecked models, which tolerate entries that would fail
+    'policy.as_model'. Each surfaced 'json_path' is re-validated against
+    the currently-loaded JSONPath environment. Typically an entry lands
+    here when it was authored under a meta-config that registered filter
+    functions which are no longer present.
 
     Returns a dict mapping 'room_id' to a list of '(json_path, error)'
-    pairs. A RAM-based authz DB has no persisted rows and returns '{}'.
+    pairs.
     """
-    dburi = the_installation.authorization_dburi_async
-
-    if dburi in cli_util._RAM_DBURIS:
-        return {}
-
     invalid: dict = {}
-    for policy in asyncio.run(_list_room_policies(dburi)):
+    for policy in room_policies:
         for entry in policy.acl_entries:
             if entry.json_path is None:
                 continue
@@ -651,7 +663,13 @@ def _audit_room_authz_section(
     tc_rule("Configured rooms by authorization state")
     tc_line()
 
-    groups = _room_authz_groups(the_installation)
+    room_policies, db_error = _room_policies(the_installation)
+    if db_error is not None:
+        tc_print(f"ERROR: authorization database unreachable: {db_error}")
+        tc_line()
+        return {"room_authz": {"unreachable": db_error}}
+
+    groups = _room_authz_groups(the_installation, room_policies)
 
     for label, room_ids in (
         (
@@ -677,7 +695,7 @@ def _audit_room_authz_section(
         tc_print("  (none)")
     tc_line()
 
-    invalid_acls = _invalid_acl_json_paths(the_installation)
+    invalid_acls = _invalid_acl_json_paths(room_policies)
     tc_print("ACL entries with invalid JSONPath:")
     if invalid_acls:
         for room_id in sorted(invalid_acls):
@@ -699,36 +717,47 @@ def _audit_room_authz_section(
     return errors
 
 
-def _admin_user_json_paths(the_installation) -> list[str]:
-    """Return every stored 'AdminUser.json_path', in insertion order.
-
-    Reads them via
-    'AdminUserPolicy.list_admin_user_discriminators'. Returns an
-    empty list when the authz DB is RAM-based (no persisted rows can
-    exist).
+def _admin_user_json_paths(
+    the_installation,
+) -> tuple[list[str], str | None]:
+    """Return ``(json_paths, error)`` for the stored admin rows.
+
+    ``json_paths`` holds every stored 'AdminUser.json_path', in insertion
+    order, read via 'AdminUserPolicy.list_admin_user_discriminators';
+    ``error`` is ``None`` on success. A RAM-based authz DB can hold no
+    persisted rows, so it short-circuits to ``([], None)`` without
+    touching the database.
+
+    When the database itself cannot be reached -- e.g. its DBURI names a
+    Postgres server that isn't listening -- ``json_paths`` is empty and
+    ``error`` carries the exception message, so the audit can report the
+    unreachable DB instead of dying on the traceback.
     """
     dburi = the_installation.authorization_dburi_async
 
     if dburi in cli_util._RAM_DBURIS:
-        return []
+        return [], None
 
-    return asyncio.run(_list_admin_discriminators(dburi))
+    try:
+        return list(asyncio.run(_list_admin_discriminators(dburi))), None
+    except Exception as exc:
+        return [], f"{type(exc).__name__}: {exc}"
 
 
 def _invalid_admin_user_json_paths(
-    the_installation,
+    json_paths,
 ) -> list[tuple[str, str]]:
     """Collect admin entries whose 'json_path' fails to validate.
 
     Same intent as '_invalid_acl_json_paths' but for the 'AdminUser'
     table: a row typically lands here when it was authored under a
     meta-config that registered filter functions which are no longer
-    present.
+    present. ``json_paths`` is the list from '_admin_user_json_paths'.
 
     Returns a list of '(json_path, error)' pairs.
     """
     invalid: list[tuple[str, str]] = []
-    for json_path in _admin_user_json_paths(the_installation):
+    for json_path in json_paths:
         try:
             authz.validate_json_path(json_path)
         except authz.InvalidJSONPath as exc:
@@ -749,7 +778,12 @@ def _audit_admin_users_section(
     tc_rule("Configured admin users")
     tc_line()
 
-    json_paths = _admin_user_json_paths(the_installation)
+    json_paths, db_error = _admin_user_json_paths(the_installation)
+    if db_error is not None:
+        tc_print(f"ERROR: authorization database unreachable: {db_error}")
+        tc_line()
+        return {"admin_users": {"unreachable": db_error}}
+
     tc_print(f"Admin users ({len(json_paths)}):")
     if json_paths:
         for json_path in json_paths:
@@ -763,7 +797,7 @@ def _audit_admin_users_section(
         tc_print("  (none)")
     tc_line()
 
-    invalid = _invalid_admin_user_json_paths(the_installation)
+    invalid = _invalid_admin_user_json_paths(json_paths)
     tc_print("Admin users with invalid JSONPath:")
     if invalid:
         for json_path, error in invalid:

{soliplex-0.77.2 → soliplex-0.78.1}/src/soliplex/config/agents.py

@@ -271,6 +271,16 @@ class AgentConfig:
         else:  # pragma: NO COVER
             pass
 
+    @property
+    def llm_model_name(self) -> str | None:
+        model_name = self.model_name
+        i_config = self._installation_config
+
+        if i_config is not None:
+            model_name = i_config.interpolate_environment(model_name)
+
+        return model_name
+
     @property
     def llm_provider_base_url(self) -> str | None:
         ic = self._installation_config
@@ -324,7 +334,7 @@ class AgentConfig:
         return {
             "id": self.id,
             "kind": self.kind,
-            "model_name": self.model_name,
+            "model_name": self.model_name,  # not interpolated
             "retries": self.retries,
             "system_prompt": prompt,
             "model_settings": self.model_settings,
@@ -478,6 +488,7 @@ def get_model_from_config(
     provider_kw = agent_config.llm_provider_kw
 
     model_settings_kw = {}
+    model_name = agent_config.llm_model_name
 
     if agent_config.model_settings:
         model_settings_kw["settings"] = ai_settings.ModelSettings(
@@ -487,7 +498,7 @@ def get_model_from_config(
     if agent_config.provider_type == LLMProviderType.GOOGLE:
         provider = google_providers.GoogleProvider(**provider_kw)
         return google_models.GoogleModel(
-            model_name=agent_config.model_name,
+            model_name=model_name,
             provider=provider,
             **model_settings_kw,
         )
@@ -496,7 +507,7 @@ def get_model_from_config(
         provider_kw["api_key"] = "dummy"
         provider = ollama_providers.OllamaProvider(**provider_kw)
         return openai_models.OpenAIChatModel(
-            model_name=agent_config.model_name,
+            model_name=model_name,
             provider=provider,
             profile=_OPENAI_COMPAT_PROFILE,
             **model_settings_kw,
@@ -510,7 +521,7 @@ def get_model_from_config(
         )
         provider = openai_providers.OpenAIProvider(**provider_kw)
         return openai_models.OpenAIChatModel(
-            model_name=agent_config.model_name,
+            model_name=model_name,
             provider=provider,
             **profile_kw,
             **model_settings_kw,

{soliplex-0.77.2 → soliplex-0.78.1}/src/soliplex/config/skills.py

@@ -179,6 +179,22 @@ class FilesystemSkillConfig:
     def extra_parameters(self) -> dict[str, pathlib.Path]:
         return {"path": self.path}
 
+    def with_defer_loading(self, defer_loading: bool) -> FilesystemSkillConfig:
+        """A copy whose capability loads as a room asked.
+
+        Installation skill configs are shared between the rooms which name
+        them, so a room's choice cannot be written onto the capability.
+        """
+        if defer_loading == self._capability.defer_loading:
+            return self
+        return dataclasses.replace(
+            self,
+            _capability=dataclasses.replace(
+                self._capability,
+                defer_loading=defer_loading,
+            ),
+        )
+
 
 @dataclasses.dataclass(kw_only=True)
 class _HaikuRAGCapabilityConfig(
@@ -192,6 +208,8 @@ class _HaikuRAGCapabilityConfig(
     state_type: typing.ClassVar[type[pydantic.BaseModel]]
     source: typing.ClassVar[SkillKind] = SkillKind.NATIVE
 
+    defer_loading: bool = False
+
     @classmethod
     def from_yaml(
         cls,
@@ -230,7 +248,7 @@ class _HaikuRAGCapabilityConfig(
         return type(self).capability_factory(
             db_path=self.rag_lancedb_path,
             config=self.haiku_rag_config,
-            defer_loading=True,
+            defer_loading=self.defer_loading,
         )
 
     @property
@@ -239,7 +257,10 @@ class _HaikuRAGCapabilityConfig(
 
     @property
     def as_yaml(self) -> dict:
-        result = {"kind": self.kind}
+        result = {
+            "kind": self.kind,
+            "defer_loading": self.defer_loading,
+        }
         if self.rag_lancedb_stem is not None:
             result["rag_lancedb_stem"] = self.rag_lancedb_stem
         else:
@@ -383,6 +404,7 @@ class BwrapSandboxSkillConfig:
     allowed_environments: bwrap_sandbox.AllowedEnvironments = None
     sandbox_config: bs_config.Config = None
     volumes: bs_models.VolumeMap = _default_dict_field()
+    defer_loading: bool = False
 
     @classmethod
     def from_yaml(
@@ -420,6 +442,7 @@ class BwrapSandboxSkillConfig:
             sandbox_config=self.sandbox_config,
             volumes=self.volumes,
             installation_config=self._installation_config,
+            defer_loading=self.defer_loading,
         )
 
     @property
@@ -427,6 +450,7 @@ class BwrapSandboxSkillConfig:
         result = {
             "kind": self.kind,
             "default_environment": self.default_environment,
+            "defer_loading": self.defer_loading,
         }
         if self.id is not None:
             result["id"] = self.id
@@ -475,6 +499,7 @@ class EntrypointCapabilityConfig:
 
     name: str
     params: dict[str, typing.Any] = _default_dict_field()
+    defer_loading: bool = True
 
     def __post_init__(self) -> None:
         # Register the capability's typed AG-UI state feature so the room can
@@ -500,10 +525,13 @@ class EntrypointCapabilityConfig:
         params = dict(config_dict)
         params.pop("kind", None)
         name = params.pop("name", None)
+        # Soliplex's own flag, not one of the plugin's parameters.
+        defer_loading = params.pop("defer_loading", True)
         try:
             return cls(
                 name=name,
                 params=params,
+                defer_loading=defer_loading,
                 _installation_config=installation_config,
                 _config_path=config_path,
             )
@@ -521,7 +549,7 @@ class EntrypointCapabilityConfig:
     @property
     def capability(self) -> ai_capabilities.AbstractCapability:
         return self._module.create_capability(
-            defer_loading=True, **self.params
+            defer_loading=self.defer_loading, **self.params
         )
 
     @property
@@ -543,7 +571,12 @@ class EntrypointCapabilityConfig:
 
     @property
     def as_yaml(self) -> dict:
-        return {"kind": self.kind, "name": self.name, **self.params}
+        return {
+            "kind": self.kind,
+            "name": self.name,
+            "defer_loading": self.defer_loading,
+            **self.params,
+        }
 
     @property
     def extra_parameters(self) -> dict[str, typing.Any]:
@@ -611,24 +644,57 @@ def extract_skill_configs(
     return skill_configs
 
 
+@dataclasses.dataclass(kw_only=True)
+class InstallationSkillRef:
+    """A room's reference to one of the installation's skills.
+
+    Spelled as a bare name, or as a mapping when the room sets a flag.
+    """
+
+    name: str
+    defer_loading: bool = True
+
+    @classmethod
+    def from_yaml(cls, entry: str | dict | InstallationSkillRef):
+        if isinstance(entry, cls):
+            return entry
+        if isinstance(entry, str):
+            return cls(name=entry)
+        return cls(**entry)
+
+    @property
+    def as_yaml(self) -> str | dict:
+        return {"name": self.name, "defer_loading": self.defer_loading}
+
+
 @dataclasses.dataclass(kw_only=True)
 class RoomSkillsConfig:
     """Select native capabilities for a room."""
 
-    installation_skill_names: list[str] = _default_list_field()
+    installation_skill_names: list[InstallationSkillRef] = (
+        _default_list_field()
+    )
     _skill_configs: SkillConfigMap = _default_dict_field()
     _installation_config: config_installation.InstallationConfig = (
         _no_repr_no_compare_none()
     )
     _config_path: pathlib.Path = None
 
+    def __post_init__(self) -> None:
+        # Callers which build the config directly, rather than via
+        # 'from_yaml', may spell the entries as bare names.
+        self.installation_skill_names = [
+            InstallationSkillRef.from_yaml(entry)
+            for entry in self.installation_skill_names
+        ]
+
     @staticmethod
     def _check_installation_skills(
         installation_config: config_installation.InstallationConfig,
         config_path: pathlib.Path,
-        config_dict: dict,
+        refs: typing.Sequence[InstallationSkillRef],
     ) -> None:
-        requested = set(config_dict.get("installation_skill_names", ()))
+        requested = {ref.name for ref in refs}
         available = set(installation_config.skill_configs)
         if missing := requested - available:
             raise MissingSkillNames(
@@ -645,11 +711,16 @@ class RoomSkillsConfig:
         config_dict: dict,
     ):
         try:
+            refs = [
+                InstallationSkillRef.from_yaml(entry)
+                for entry in config_dict.get("installation_skill_names", ())
+            ]
             cls._check_installation_skills(
                 installation_config,
                 config_path,
-                config_dict,
+                refs,
             )
+            config_dict["installation_skill_names"] = refs
             config_dict["_skill_configs"] = extract_skill_configs(
                 installation_config,
                 config_path,
@@ -671,7 +742,9 @@ class RoomSkillsConfig:
     def as_yaml(self) -> dict:
         result = {}
         if self.installation_skill_names:
-            result["installation_skill_names"] = self.installation_skill_names
+            result["installation_skill_names"] = [
+                ref.as_yaml for ref in self.installation_skill_names
+            ]
         if self._skill_configs:
             result["skill_configs"] = [
                 config.as_yaml for config in self._skill_configs.values()
@@ -682,8 +755,10 @@ class RoomSkillsConfig:
     def skill_configs(self) -> SkillConfigMap:
         installation_configs = self._installation_config.skill_configs
         return {
-            name: installation_configs[name]
-            for name in self.installation_skill_names
+            ref.name: installation_configs[ref.name].with_defer_loading(
+                ref.defer_loading
+            )
+            for ref in self.installation_skill_names
         } | self._skill_configs
 
     @property

{soliplex-0.77.2 → soliplex-0.78.1}/src/soliplex/installation.py

@@ -178,7 +178,7 @@ class Installation:
                 type_info = found.setdefault(provider_type, {})
                 base_url = agent_config.llm_provider_base_url
                 url_models = type_info.setdefault(base_url, set())
-                url_models.add(agent_config.model_name)
+                url_models.add(agent_config.llm_model_name)
 
         return found
 

{soliplex-0.77.2 → soliplex-0.78.1}/src/soliplex/models.py

@@ -174,7 +174,7 @@ ConfiguredSkills = dict[str, Skill]
 
 class DefaultAgent(pydantic.BaseModel):
     id: str
-    model_name: str
+    model_name: str | None
     retries: int
     system_prompt: str | None
     provider_type: config_agents.LLMProviderType  # enum, not dataclass
@@ -187,7 +187,7 @@ class DefaultAgent(pydantic.BaseModel):
         llm_provider_kw = agent_config.llm_provider_kw
         return cls(
             id=agent_config.id,
-            model_name=agent_config.model_name,
+            model_name=agent_config.llm_model_name,
             retries=agent_config.retries,
             system_prompt=agent_config.get_system_prompt(),
             provider_type=agent_config.provider_type,

{soliplex-0.77.2 → soliplex-0.78.1}/src/soliplex/quizzes.py

@@ -52,7 +52,7 @@ def get_quiz_judge_agent(quiz: config_quizzes.QuizConfig):
         model_provider = ollama_providers.OllamaProvider(**llm_provider_kw)
 
     ollama_model = openai_models.OpenAIChatModel(
-        model_name=quiz.judge_agent.model_name,
+        model_name=quiz.judge_agent.llm_model_name,
         provider=model_provider,
     )
 

{soliplex-0.77.2 → soliplex-0.78.1}/src/soliplex/skills/bwrap_sandbox/SKILL.md

@@ -55,11 +55,30 @@ Do NOT use the sandbox if **any** of these is true:
 - `run_python(script, environment_name=None, timeout=None)` — run a Python
   script. `script` is the full source as one string.
 
-When calling `run` and `run_python`, `environment_name` and `timeout` are both
-optional and fall back to the values this skill was configured with.
-Always pass `environment_name` explicitly, using a name that
-`list_environments` returned — the configured default is not visible to you
-and may not be the environment you want.
+## Environment names come only from `list_environments`
+
+**Never guess an environment name.** The only values `environment_name`
+accepts are the exact `name` strings that a `list_environments` call
+returned **to you, in this conversation**.
+
+- Call `list_environments` before the first `run` or `run_python` of a
+  turn. It is cheap; skipping it is the most common way this skill fails.
+- Every environment name written in this document is a placeholder —
+  `<name from list_environments>` — standing in for a name you have yet to
+  look up. No placeholder names a real environment.
+- A name that appears in a task, a filename, a library you plan to import,
+  or an earlier conversation is not an environment name. Neither is the
+  name of a package: an environment's `name` and its `dependencies` are
+  different things, and are usually spelled differently.
+- Passing a name that was not in the `list_environments` result fails the
+  call. The failure names the environments you may actually use — call
+  `list_environments` and retry with one of those, rather than guessing
+  again.
+
+`environment_name` and `timeout` are both optional and fall back to the
+values this skill was configured with. Always pass `environment_name`
+explicitly: the configured default is not visible to you and may not be
+the environment you want.
 
 ## Workflow
 
@@ -68,9 +87,9 @@ and may not be the environment you want.
 
    ```python
    {
-      "name": "pandas",
-      "description": "Minimal Python with Pandas",
-      "dependencies": ["pandas"],
+      "name": "<name from list_environments>",
+      "description": "<what this environment is for>",
+      "dependencies": ["<installed package>"],
    }
    ```
 
@@ -78,10 +97,11 @@ and may not be the environment you want.
    - If the list is empty, stop and tell the user the skill
      is not configured — do not proceed.
    - If the list contains exactly one environment, use its `name`.
-   - Otherwise, pick the `name` of the first environment whose `dependencies`
-     include a library the task needs (e.g. `pandas` for tabular data,
-     `numpy` for numeric work, `pillow` for images).  If no environments
-     match, use the `name` of the first entry in the list.
+   - Otherwise, compare the task against each entry's `dependencies` —
+     a `pandas` dependency suits tabular data, `numpy` numeric work,
+     `pillow` images — and use the `name` of the first entry that matches.
+     Use the entry's `name`, not the name of the dependency that matched.
+     If no entry matches, use the `name` of the first entry in the list.
 
 2. **List files in both volumes.**  This step is mandatory — do not skip it,
    even if the task seems to involve one volume.  Run both:
@@ -113,7 +133,7 @@ and may not be the environment you want.
 
    ```python
    run(command=["head", "-n", "5", "/sandbox/volumes/thread/orders.csv"],
-       environment_name="<selected-environment>")
+       environment_name="<name from list_environments>")
    ```
 
    (or `["wc", "-l", <path>]`, `["file", <path>]`, etc.).  For anything
@@ -125,7 +145,8 @@ and may not be the environment you want.
    argument to `run_python`:
 
    ```python
-   run_python(script="<python source>", environment_name="<selected-environment>")
+   run_python(script="<python source>",
+              environment_name="<name from list_environments>")
    ```
 
    Write the whole program as a single string, and use real newlines between
@@ -147,7 +168,10 @@ and may not be the environment you want.
    ```
 
 5. **On failure.**
-   - Change exactly one thing per retry.
+   - If the failure says the environment is not available, you guessed a
+     name. Call `list_environments` and retry with a name it returned —
+     do not try a different guess.
+   - Otherwise change exactly one thing per retry.
    - After 3 failed runs, stop. Report the error to the user (paste the
      `Exited with code: <N>` line and any traceback), instead of retrying
      further.
@@ -168,8 +192,10 @@ and may not be the environment you want.
 Task: user uploads `orders.csv` and asks "what's the total order value?".
 A full run looks like:
 
-1. `list_environments()` — shows one environment named `pandas`
-   with `pandas` in its dependencies. Use it.
+1. `list_environments()` — returns exactly one environment, whose
+   `dependencies` include `pandas`. Use that entry's `name`; in step 3 it
+   is written as `<name from list_environments>`, because what the name
+   actually is can only be read off this call's result.
 
 2. `list_volume_files("thread")` — returns
    `["/sandbox/volumes/thread/orders.csv"]`.
@@ -184,7 +210,7 @@ A full run looks like:
    df = pd.read_csv('/sandbox/volumes/thread/orders.csv')
    print(f"Total: {df['amount'].sum():.2f}")
    """,
-       environment_name="pandas",
+       environment_name="<name from list_environments>",
    )
    ```