fix: improve error when extracted completion is not a list

README.md

@@ -24,10 +24,22 @@ Join our [Discord community](https://discord.gg/RYk7CdvDR7) to connect with othe
 
 Read more on our [documentation website](https://microsoft.github.io/agent-lightning/).
 
+## Why Tinker?
+
+- Running large scale LLM experiments locally can be difficult and resource intensive,especially for users without GPUs or complex infrastructure.
+
+- Tinker allows Agent Lightning users to offload experiment execution to a managed third party service.This removes the need for local GPU setup and reduces operational complexity.
+
+- Compared to the alternatives such as `verl`,Tinker provides a simpler API and easier integration,making it suitable for rapid experimentation and onboarding.
+
+- Use Tinker when you want fast setup and managed execution,use local backends when you need full control over infrastructure.
+
+
 <p align="center">
   <img src="docs/assets/readme-diff.svg" alt="Agent-Lightning Core Quickstart" style="width:100%"/>
 </p>
 
+
 ## ⚡ Installation
 
 ```bash

agentlightning/adapter/messages.py

@@ -254,7 +254,11 @@ def adapt(self, source: Sequence[Span], /) -> List[OpenAIMessages]:
             if not isinstance(prompt, list):
                 raise ValueError(f"Extracted prompt from trace is not a list: {prompt}")
             if not isinstance(completion, list):
-                raise ValueError(f"Extracted completion from trace is not a list: {completion}")
+                raise ValueError(
+                    f"Expected completion to be a list, got {type(completion)}. "
+                    f"Value: {repr(completion)[:200]}. "
+                    "If the trace contains a single completion, wrap it in a list before passing it."
+                )
             if not isinstance(request, dict):
                 raise ValueError(f"Extracted request from trace is not a dict: {request}")
             if not isinstance(response, dict):

docs/how-to/failed-rollouts.md

@@ -0,0 +1,16 @@
+# Handling Failed Rollouts
+
+Rollouts may fail due to transient system issues such as network errors, timeouts or external service failures.
+
+## Retry behavior
+- Rollout retries are configured via `RolloutConfig`, including settings such as `max_attempts`, retry conditions and timeouts.
+- If a rollout fails and returns `None`, it still counts as an attempt and follows the configured retry limits.
+
+## Batch behavior
+- Failed rollouts are handled at the individual rollout level.
+- There is currently no built-in mechanism to a automatically skip an entire batch when multiple rollouts fail.
+
+## Best practices
+- Retries are useful for transient failures (e.g. temporary network issues).
+- If failures occur frequently, this usually indicates an infrastructure problem rather than an issue retries can fix.
+- In such cases, it is recommended to address the underlying system issue instead of increasing retry limits.