agent-learning 0.4.1__tar.gz → 0.4.3__tar.gz

{agent_learning-0.4.1/src/agent_learning.egg-info → agent_learning-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-learning
-Version: 0.4.1
+Version: 0.4.3
 Summary: Native, in-process reinforcement learning SDK for AI agents — in-memory and local-file storage by default.
 Author: Chris Tava
 License: MIT License
@@ -67,16 +67,16 @@ Dynamic: license-file
 
 # agent-learning
 
-Native reinforcement learning SDK for AI agents. An in-process learner optimizes a small, interpretable policy over discrete agent choices (understand intent and complete task by choosing the right outcome).
+Native reinforcement learning SDK for AI agents. An in-process Learner optimizes a small, interpretable TaskPolicy over discrete agent choices (understand intent and complete task by choosing the right outcome).
 
 ## How it works
 
 The SDK improves agents without LLM weight fine-tuning. There are no GPU fine-tune jobs and no opaque update cycles — just three pieces that run in your existing Python process:
 
-1. The **policy** is a softmax distribution over `N` discrete actions (e.g., "take action A", "take action B", "take action C"). It lives in Python and updates in milliseconds.
+1. **TaskPolicy** is a softmax distribution over `N` discrete actions (e.g., "take action A", "take action B", "take action C"). It lives in Python and updates in milliseconds.
 
-2. Each episode is **evaluated** by three AI Evaluation evaluators — `IntentResolutionEvaluator`, `TaskAdherenceEvaluator`, and `TaskCompletionEvaluator` — whose scores are combined into a single scalar reward.
+2. **Score** evaluates each episode on-device with three stdlib scorers for intent resolution, task adherence, and task completion. Their scores are combined into a single scalar reward with no scoring endpoint or environment variables required. Azure AI evaluators remain available as an opt-in.
 
-3. A **REINFORCE-with-baseline** learner updates the policy logits directly from logged episodes. Updates are tiny gradient steps that run on local compute and persist through a pluggable store — in-memory or local files by default, with Azure Cosmos DB optional.
+3. **Learner** applies REINFORCE-with-baseline to update TaskPolicy logits directly from logged episodes. Updates are tiny gradient steps that run on local compute and persist through a pluggable store — in-memory or local files by default, with Azure Cosmos DB optional.
 
 Every episode, reward, run, and deployment is captured by the configured store — in-memory or local files by default, or Azure Cosmos DB — giving you a complete lineage and audit trail of how the policy evolved over time.

agent_learning-0.4.3/PYPI.md

@@ -0,0 +1,15 @@
+# agent-learning
+
+Native reinforcement learning SDK for AI agents. An in-process Learner optimizes a small, interpretable TaskPolicy over discrete agent choices (understand intent and complete task by choosing the right outcome).
+
+## How it works
+
+The SDK improves agents without LLM weight fine-tuning. There are no GPU fine-tune jobs and no opaque update cycles — just three pieces that run in your existing Python process:
+
+1. **TaskPolicy** is a softmax distribution over `N` discrete actions (e.g., "take action A", "take action B", "take action C"). It lives in Python and updates in milliseconds.
+
+2. **Score** evaluates each episode on-device with three stdlib scorers for intent resolution, task adherence, and task completion. Their scores are combined into a single scalar reward with no scoring endpoint or environment variables required. Azure AI evaluators remain available as an opt-in.
+
+3. **Learner** applies REINFORCE-with-baseline to update TaskPolicy logits directly from logged episodes. Updates are tiny gradient steps that run on local compute and persist through a pluggable store — in-memory or local files by default, with Azure Cosmos DB optional.
+
+Every episode, reward, run, and deployment is captured by the configured store — in-memory or local files by default, or Azure Cosmos DB — giving you a complete lineage and audit trail of how the policy evolved over time.

{agent_learning-0.4.1 → agent_learning-0.4.3}/README.md

@@ -1,29 +1,30 @@
 # agent-learning
 
 Native reinforcement learning SDK for AI agents. An in-process
-learner optimizes a small, interpretable policy over discrete agent choices (e.g., "take action A", "take action B", "take action C") using AI Evaluation scores as the reward
-signal.
+Learner optimizes a small, interpretable TaskPolicy over discrete agent choices (e.g., "take action A", "take action B", "take action C") using on-device evaluation scores as the reward
+signal by default.
 
 <p align="center">
-   <img src="images/agent-learning-loop.svg" alt="Animated loop: Policy chooses an action, Score evaluates the episode, and Learner updates the policy" width="960" style="max-width:100%; height:auto;" />
+   <img src="images/agent-learning-loop.svg" alt="Animated TaskPolicy Score Learner loop: TaskPolicy chooses a task action, Score evaluates the episode, and Learner updates TaskPolicy" width="960" style="max-width:100%; height:auto;" />
 </p>
 
 ## How it works
 
 The SDK improves agents without LLM weight fine-tuning. There are no GPU fine-tune jobs and no opaque update cycles — just three pieces that run in your existing Python process:
 
-1. The **policy** is a softmax distribution over `N` discrete
+1. **TaskPolicy** is a softmax distribution over `N` discrete
    actions (e.g., "take action A", "take action B", "take action C"). It lives in Python and updates in milliseconds.
 
-   <img src="images/0f85e08d0c47cd01.png" alt="Policy selects one of N discrete actions" width="360" style="max-width:100%; height:auto;" />
+   <img src="images/0f85e08d0c47cd01.png" alt="TaskPolicy selects one of N discrete actions" width="360" style="max-width:100%; height:auto;" />
 
-2. Each episode is **evaluated** by three AI Evaluation
-   evaluators — `IntentResolutionEvaluator`, `TaskAdherenceEvaluator`,
-   and `TaskCompletionEvaluator` — whose scores are combined into a single scalar reward.
+2. **Score** evaluates each episode locally with three stdlib scorers for intent
+   resolution, task adherence, and task completion. Their scores are combined
+   into one scalar reward. No scoring endpoint or environment variable is
+   required. Configured Azure AI evaluators remain available as an opt-in.
 
    <img src="images/246d112f995b785a.png" alt="Three evaluator scores feed a single scalar reward" width="360" style="max-width:100%; height:auto;" />
 
-3. A **Reinforce-with-baseline** learner updates the policy logits
+3. **Learner** applies REINFORCE-with-baseline to update TaskPolicy logits
    directly from stored episodes. Updates are tiny gradient steps
    that run on local compute and persist through a pluggable store — in-memory
    or local files by default, with Azure Cosmos DB optional.
@@ -54,14 +55,16 @@ agent-learn.exe --help
 Released versions are published to PyPI:
 <https://pypi.org/project/agent-learning/>.
 
+## Functional Testing
+
+A good way to see the SDK in action is to run the
+interactive capture scenario first, followed by the offline batch update:
+
 ```powershell
-py -m pip install agent-learning
-agent-learn.exe --help
+python tests/functional_cli_interactive.py
+python tests/functional_cli_batch.py
 ```
 
-`pip` installs `agent-learn.exe` into the active Python environment's
-`Scripts` directory.
-
 ## Usage
 
 The `agent-learn` CLI provides the current task-learning-loop operations:
@@ -69,19 +72,11 @@ The `agent-learn` CLI provides the current task-learning-loop operations:
 ```text
 agent-learn list
 agent-learn tasks-list <agent_id>
-agent-learn task-episodes-count <agent_id> [--task-id <task_id>]
-agent-learn task-episodes-list <agent_id> [--task-id <task_id>] [--limit <1-500>] [--include-incomplete]
+agent-learn task-episodes-count <agent_id> [--task-id <task_id>] [--start-date <date>] [--end-date <date>]
+agent-learn task-episodes-list <agent_id> [--task-id <task_id>] [--limit <1-500>] [--include-incomplete] [--start-date <date>] [--end-date <date>]
 agent-learn task-policy-init --agent-id <agent_id> --task-id <task_id> --actions ./actions.json
 agent-learn task-episode-register --agent-id <agent_id> --task-id <task_id> --episode ./episode.json
 agent-learn score --agent-id <agent_id> [--task-id <task_id>] [--limit <1-500>]
-agent-learn train --agent-id <agent_id> [--task-id <task_id>] [--limit <1-500>] [--start-date <date>] [--end-date <date>] [--skip-scoring]
+agent-learn train --agent-id <agent_id> [--task-id <task_id>] [--limit <1-500>] [--min-episodes <1-500>] [--start-date <date>] [--end-date <date>] [--skip-scoring]
 agent-learn task-policy --agent-id <agent_id> --task-id <task_id>
 ```
-
-The subprocess-level functional workflow uses an isolated local store. Run the
-interactive capture scenario first, followed by the offline batch update:
-
-```powershell
-python tests/functional_cli_interactive.py
-python tests/functional_cli_batch.py
-```

{agent_learning-0.4.1 → agent_learning-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-learning"
-version = "0.4.1"
+version = "0.4.3"
 description = "Native, in-process reinforcement learning SDK for AI agents — in-memory and local-file storage by default."
 readme = "PYPI.md"
 requires-python = ">=3.10"

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/__init__.py

@@ -7,9 +7,9 @@ native, in-process learner. The SDK is organised into five layers:
   ``Reward``, ``PolicySnapshot``, ...).
 - ``agent_learning.storage``  - pluggable persistence (Cosmos DB,
   local file system, and in-memory).
-- ``agent_learning.metrics``  - score-based metrics that wrap the
-  Azure AI Evaluation evaluators for Intent Resolution, Task
-  Adherence, and Task Completion.
+- ``agent_learning.metrics``  - on-device stdlib metrics by default,
+    with optional Azure AI evaluators for Intent Resolution, Task
+    Adherence, and Task Completion.
 - ``agent_learning.rewards``  - reward shaping + persistence.
 - ``agent_learning.policy``   - discrete softmax bandit policy.
 - ``agent_learning.learners`` - REINFORCE-with-baseline learner.

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.3"

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/cli.py

@@ -8,6 +8,7 @@ import logging
 import sys
 import uuid
 from collections import Counter
+from datetime import datetime, timezone
 from typing import Any
 
 from .policy.softmax_bandit import SoftmaxPolicy
@@ -27,6 +28,16 @@ def _episode_limit(value: str) -> int:
     return limit
 
 
+def _iso_date(value: str) -> str:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"invalid ISO 8601 date: {value!r}") from exc
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc).isoformat()
+
+
 def _build_arg_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="agent-learn", description="Native RL CLI for AI agents.")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -42,6 +53,8 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     )
     count.add_argument("agent_id")
     count.add_argument("--task-id")
+    count.add_argument("--start-date", type=_iso_date)
+    count.add_argument("--end-date", type=_iso_date)
 
     episodes = sub.add_parser(
         "task-episodes-list",
@@ -51,13 +64,16 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     episodes.add_argument("--task-id")
     episodes.add_argument("--limit", type=_episode_limit, default=_MAX_EPISODES)
     episodes.add_argument("--include-incomplete", action="store_true")
+    episodes.add_argument("--start-date", type=_iso_date)
+    episodes.add_argument("--end-date", type=_iso_date)
 
     train = sub.add_parser("train", help="Run one offline learning batch.")
     train.add_argument("--agent-id", required=True)
     train.add_argument("--task-id")
     train.add_argument("--limit", type=_episode_limit, default=200)
-    train.add_argument("--start-date")
-    train.add_argument("--end-date")
+    train.add_argument("--min-episodes", type=_episode_limit, default=1)
+    train.add_argument("--start-date", type=_iso_date)
+    train.add_argument("--end-date", type=_iso_date)
     train.add_argument(
         "--skip-scoring",
         action="store_true",
@@ -118,6 +134,8 @@ def _cmd_agents_episodes_count(args: argparse.Namespace) -> int:
         args.agent_id,
         task_id=args.task_id,
         full_only=True,
+        start_date=args.start_date,
+        end_date=args.end_date,
     )
     print(count)
     return 0
@@ -129,6 +147,8 @@ def _cmd_agents_episodes_list(args: argparse.Namespace) -> int:
         args.agent_id,
         task_id=args.task_id,
         limit=_MAX_EPISODES,
+        start_date=args.start_date,
+        end_date=args.end_date,
     )
     if not args.include_incomplete:
         episodes = [episode for episode in episodes if episode.is_full]
@@ -183,6 +203,17 @@ def _cmd_train(args: argparse.Namespace) -> int:
         if episode_limit == 0:
             skipped.append({"task_id": task_id, "reason": "no episodes in selected batch"})
             continue
+        if episode_limit < args.min_episodes:
+            skipped.append(
+                {
+                    "task_id": task_id,
+                    "reason": (
+                        f"selected batch has {episode_limit} episodes; "
+                        f"minimum is {args.min_episodes}"
+                    ),
+                }
+            )
+            continue
         policy = SoftmaxPolicy.from_snapshot(snapshot)
         runner = LearningRunner(store=store, policy=policy)
         run = runner.run_offline_batch(
@@ -216,11 +247,11 @@ def _cmd_score(args: argparse.Namespace) -> int:
     )
     scored = 0
     for episode in episodes:
-        existing = store.get_rewards_for_episode(episode.id, args.agent_id)
-        if existing:
+        if runner.has_usable_reward(episode):
             continue
-        runner.score_and_record(episode)
-        scored += 1
+        rewards = runner.score_and_record(episode)
+        if any(reward.source == RewardSource.AGGREGATE for reward in rewards):
+            scored += 1
     print(json.dumps({"episodes_seen": len(episodes), "newly_scored": scored}, indent=2))
     return 0
 

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/learners/reinforce.py

@@ -49,14 +49,14 @@ class ReinforceLearner(Learner):
 
         # Index rewards by episode id - we only consume aggregate rewards
         episode_list = list(episodes)
-        aggregate_rewards: Dict[str, float] = {}
+        aggregate_rewards: Dict[str, Reward] = {}
         for r in rewards:
             if r.source != RewardSource.AGGREGATE:
                 continue
-            # Keep the most recent aggregate per episode (sorted by created_at desc)
+            # Rescoring may append a replacement aggregate. Keep the newest.
             current = aggregate_rewards.get(r.episode_id)
-            if current is None:
-                aggregate_rewards[r.episode_id] = r.value
+            if current is None or r.created_at > current.created_at:
+                aggregate_rewards[r.episode_id] = r
 
         snapshot = policy.snapshot()
         baseline_before = snapshot.baseline
@@ -72,9 +72,10 @@ class ReinforceLearner(Learner):
         for episode in episode_list:
             if episode.action_id is None or episode.action_id not in action_index:
                 continue
-            reward_value = aggregate_rewards.get(episode.id)
-            if reward_value is None:
+            reward = aggregate_rewards.get(episode.id)
+            if reward is None:
                 continue
+            reward_value = reward.value
             advantage = reward_value - baseline_before
 
             # Importance sampling weight when the episode was logged under a

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/metrics/__init__.py

@@ -1,18 +1,19 @@
 """Score-based evaluation metrics for native RL reward shaping.
 
-Each metric is a thin wrapper around an evaluator from
-``azure-ai-evaluation``. The wrapper normalises the raw evaluator score
-into the ``[0, 1]`` range expected by the reward shaper.
+Metrics use on-device stdlib scorers by default. Configured Azure AI
+evaluators remain available for remote LLM scoring.
 """
 
 from .base import MetricEvaluator, MetricRequest
 from .intent_resolution import IntentResolutionMetric
+from .local import LocalScorerMetric
 from .task_adherence import TaskAdherenceMetric
 from .task_completion import TaskCompletionMetric
 from .registry import default_metrics, evaluate_all
 
 __all__ = [
     "IntentResolutionMetric",
+    "LocalScorerMetric",
     "MetricEvaluator",
     "MetricRequest",
     "TaskAdherenceMetric",

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/metrics/base.py

@@ -42,6 +42,14 @@ class MetricRequest:
             system_message=episode.system_message,
             tool_calls=_format_tool_calls(episode),
             tool_definitions=episode.metadata.get("tool_definitions"),
+            extra={
+                "action_id": episode.action_id,
+                "context_features": episode.context_features,
+                "execution_status": episode.execution_status,
+                "expected_outcome": episode.expected_outcome,
+                "metadata": episode.metadata,
+                "result_summary": episode.result_summary,
+            },
         )
 
 

agent_learning-0.4.3/src/agent_learning/metrics/local.py

@@ -0,0 +1,151 @@
+"""Metric adapters for on-device scoring backends."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from typing import Any
+
+from ..scorers.base import Scorer, ScoreResult
+from ..scorers.stdlib._text import tokenize
+from ..types import MetricName, MetricResult
+from .base import MetricEvaluator, MetricRequest
+
+logger = logging.getLogger(__name__)
+
+
+class LocalScorerMetric(MetricEvaluator):
+    """Project a local :class:`Scorer` onto the metric interface."""
+
+    NAME = MetricName.INTENT_RESOLUTION
+
+    def __init__(self, metric: MetricName, scorer: Scorer) -> None:
+        super().__init__(evaluator=scorer)
+        self.NAME = metric
+        self._scorer = scorer
+
+    def _build_evaluator(self) -> Any:  # pragma: no cover - injected in __init__
+        return self._scorer
+
+    def _build_kwargs(self, request: MetricRequest) -> dict[str, Any]:
+        metadata = request.extra.get("metadata")
+        if not isinstance(metadata, dict):
+            metadata = {}
+        context_features = request.extra.get("context_features")
+        if not isinstance(context_features, dict):
+            context_features = {}
+        contract = metadata.get("score_contract") or metadata.get("adherence_contract")
+        if not isinstance(contract, dict):
+            contract = {}
+        expected_tokens = metadata.get("expected_tokens")
+        if not isinstance(expected_tokens, Sequence) or isinstance(
+            expected_tokens, (str, bytes)
+        ):
+            expected_tokens = tokenize(str(request.extra.get("expected_outcome") or ""))
+        return {
+            "query": request.query,
+            "response": request.response,
+            "system_message": request.system_message,
+            "tool_calls": request.tool_calls,
+            "action_id": request.extra.get("action_id"),
+            "phi": context_features.get("phi"),
+            "contract": contract,
+            "expected_tokens": expected_tokens,
+        }
+
+    def _normalize(self, raw: dict[str, Any]) -> float | None:
+        value = raw.get("normalized")
+        return float(value) if value is not None else None
+
+    def evaluate(self, request: MetricRequest) -> MetricResult:
+        if not (request.query and request.response):
+            return MetricResult(
+                metric=self.NAME,
+                score=None,
+                normalized=None,
+                status="skipped",
+                reason="query or response is empty",
+                evaluator=f"local:{self._scorer.name}",
+            )
+
+        authoritative = self._authoritative_completion(request)
+        if authoritative is not None:
+            value, reason = authoritative
+            return MetricResult(
+                metric=self.NAME,
+                score=value,
+                normalized=value,
+                status="completed",
+                reason=reason,
+                evaluator="local:episode-outcome",
+            )
+
+        try:
+            result = self._scorer.score(**self._build_kwargs(request))
+        except Exception as exc:  # noqa: BLE001  # pragma: no cover
+            logger.warning("Local metric %s failed: %s", self.NAME.value, exc)
+            return MetricResult(
+                metric=self.NAME,
+                score=None,
+                normalized=None,
+                status="skipped",
+                reason=f"local scorer error: {exc}",
+                evaluator=f"local:{self._scorer.name}",
+            )
+        return _to_metric_result(self.NAME, self._scorer.name, result)
+
+    def _authoritative_completion(
+        self, request: MetricRequest
+    ) -> tuple[float, str] | None:
+        if self.NAME != MetricName.TASK_COMPLETION:
+            return None
+        metadata = request.extra.get("metadata")
+        if not isinstance(metadata, dict):
+            metadata = {}
+        action_id = request.extra.get("action_id")
+        correct_action_id = metadata.get("correct_action_id")
+        if action_id and correct_action_id:
+            return (
+                float(action_id == correct_action_id),
+                "derived from action_id and metadata.correct_action_id",
+            )
+        completed = metadata.get("task_completed")
+        if isinstance(completed, bool):
+            return float(completed), "derived from metadata.task_completed"
+        status = str(request.extra.get("execution_status") or "").lower()
+        if status == "completed":
+            return 1.0, "derived from execution_status=completed"
+        if status == "failed":
+            return 0.0, "derived from execution_status=failed"
+        if status == "partial":
+            return 0.5, "derived from execution_status=partial"
+        return None
+
+
+def _to_metric_result(
+    metric: MetricName, scorer_name: str, result: ScoreResult
+) -> MetricResult:
+    normalized = max(0.0, min(1.0, float(result.normalized)))
+    return MetricResult(
+        metric=metric,
+        score=normalized,
+        normalized=normalized,
+        status="completed",
+        reason=f"local {result.label}",
+        properties=dict(result.features),
+        evaluator=f"local:{scorer_name}",
+        metadata={"label": result.label, "confidence": result.confidence},
+    )
+
+
+def local_metrics(scorers: tuple[Scorer, Scorer, Scorer]) -> list[MetricEvaluator]:
+    """Return local metric adapters in reward-shaping order."""
+    intent, adherence, completion = scorers
+    return [
+        LocalScorerMetric(MetricName.INTENT_RESOLUTION, intent),
+        LocalScorerMetric(MetricName.TASK_ADHERENCE, adherence),
+        LocalScorerMetric(MetricName.TASK_COMPLETION, completion),
+    ]
+
+
+__all__ = ["LocalScorerMetric", "local_metrics"]

agent_learning-0.4.3/src/agent_learning/metrics/registry.py

@@ -0,0 +1,59 @@
+"""Convenience helpers to evaluate an episode across all default metrics."""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Optional
+
+from ..config import ScoreConfig, ScoreRuntimeConfig
+from ..scorers import build_scorers
+from ..types import Episode, MetricResult
+from .base import MetricEvaluator, MetricRequest
+from .intent_resolution import IntentResolutionMetric
+from .local import local_metrics
+from .task_adherence import TaskAdherenceMetric
+from .task_completion import TaskCompletionMetric
+
+
+def default_metrics(
+    score_config: Optional[ScoreConfig] = None,
+    score_runtime_config: Optional[ScoreRuntimeConfig] = None,
+) -> List[MetricEvaluator]:
+    """Return local metrics by default, or Azure metrics when configured."""
+    runtime = score_runtime_config or ScoreRuntimeConfig()
+    llm = score_config or runtime.llm
+    if score_config is not None or runtime.tier == "llm" or (
+        runtime.tier is None and llm.enabled
+    ):
+        return [
+            IntentResolutionMetric(llm),
+            TaskAdherenceMetric(llm),
+            TaskCompletionMetric(llm),
+        ]
+    if runtime.tier is None:
+        runtime.tier = "stdlib"
+    return local_metrics(build_scorers(runtime))
+
+
+def evaluate_all(
+    episode: Episode,
+    metrics: Optional[Iterable[MetricEvaluator]] = None,
+    *,
+    score_config: Optional[ScoreConfig] = None,
+    score_runtime_config: Optional[ScoreRuntimeConfig] = None,
+) -> List[MetricResult]:
+    """Evaluate one episode against every supplied metric.
+
+    Each metric is given its own try/except inside :meth:`evaluate`,
+    so a single failing scorer will not prevent the others from
+    producing scores.
+    """
+    metric_list = (
+        list(metrics)
+        if metrics is not None
+        else default_metrics(score_config, score_runtime_config)
+    )
+    request = MetricRequest.from_episode(episode)
+    return [m.evaluate(request) for m in metric_list]
+
+
+__all__ = ["default_metrics", "evaluate_all"]

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/rewards/writer.py

@@ -98,7 +98,10 @@ class RewardWriter:
             except Exception as exc:  # pragma: no cover
                 logger.warning("Failed to persist %s penalty for %s: %s", kind, episode.id, exc)
 
-        # 4) Aggregate reward consumed by the learner
+        # 4) Aggregate reward consumed by the learner. Do not turn an
+        # all-skipped evaluation into a misleading neutral reward.
+        if not shaped.metric_contributions and not shaped.penalties:
+            return stored
         aggregate = Reward(
             episode_id=episode.id,
             agent_id=episode.agent_id,

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/storage/base.py

@@ -66,8 +66,10 @@ class LearningStore(ABC):
         *,
         task_id: Optional[str] = None,
         full_only: bool = False,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
     ) -> int:
-        """Count episodes, optionally limiting the count to full episodes."""
+        """Count episodes filtered by task, completeness, or time window."""
 
     # ---- Metric results -------------------------------------------
 

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/storage/cosmos.py

@@ -272,6 +272,8 @@ class CosmosStore(LearningStore):
         *,
         task_id: Optional[str] = None,
         full_only: bool = False,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
     ) -> int:
         clauses = ["c.agent_id = @agent_id"]
         params: List[Dict[str, Any]] = [{"name": "@agent_id", "value": agent_id}]
@@ -281,6 +283,12 @@ class CosmosStore(LearningStore):
             else:
                 clauses.append("c.task_id = @task_id")
             params.append({"name": "@task_id", "value": task_id})
+        if start_date:
+            clauses.append("c.created_at >= @start_date")
+            params.append({"name": "@start_date", "value": start_date})
+        if end_date:
+            clauses.append("c.created_at <= @end_date")
+            params.append({"name": "@end_date", "value": end_date})
         if full_only:
             clauses.extend(
                 [

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/storage/local.py

@@ -212,12 +212,16 @@ class LocalFileStore(LearningStore):
         *,
         task_id: Optional[str] = None,
         full_only: bool = False,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
     ) -> int:
         return sum(
             1
             for doc in self._read_dir_docs("episodes", agent_id)
             if (task_id is None or doc.get("task_id", "default") == task_id)
             and (not full_only or Episode.from_dict(doc).is_full)
+            and (start_date is None or doc.get("created_at", "") >= start_date)
+            and (end_date is None or doc.get("created_at", "") <= end_date)
         )
 
     # ------------------------------------------------------------------

{agent_learning-0.4.1 → agent_learning-0.4.3}/src/agent_learning/storage/memory.py

@@ -93,6 +93,8 @@ class InMemoryStore(LearningStore):
         *,
         task_id: Optional[str] = None,
         full_only: bool = False,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
     ) -> int:
         return sum(
             1
@@ -100,6 +102,8 @@ class InMemoryStore(LearningStore):
             if episode.agent_id == agent_id
             and (task_id is None or episode.task_id == task_id)
             and (not full_only or episode.is_full)
+            and (start_date is None or episode.created_at >= start_date)
+            and (end_date is None or episode.created_at <= end_date)
         )
 
     # ---- Metric results -------------------------------------------