agent-learning 0.4.2__tar.gz → 0.5.0__tar.gz

{agent_learning-0.4.2/src/agent_learning.egg-info → agent_learning-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-learning
-Version: 0.4.2
+Version: 0.5.0
 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,24 @@ 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).
+
+TaskPolicies model reusable decisions among executable alternatives such as
+models, skills, tools, workflows, or workloads. Factual questions, ordinary
+chat, reporting, and learning automation are not policy tasks.
 
 ## 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. **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.
 
-2. Each episode is **evaluated** on-device by 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.
 
-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.
+`task-policy-decide` closes the loop at execution time by returning the selected
+action plus historical correctness, reward, result summaries, and per-metric
+quality feedback for the agent to use on its next delegated decision.
 
 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.5.0/PYPI.md

@@ -0,0 +1,23 @@
+# 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).
+
+TaskPolicies model reusable decisions among executable alternatives such as
+models, skills, tools, workflows, or workloads. Factual questions, ordinary
+chat, reporting, and learning automation are not policy tasks.
+
+## 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.
+
+`task-policy-decide` closes the loop at execution time by returning the selected
+action plus historical correctness, reward, result summaries, and per-metric
+quality feedback for the agent to use on its next delegated decision.
+
+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.2 → agent_learning-0.5.0}/README.md

@@ -1,36 +1,45 @@
 # 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 on-device evaluation scores as the reward
+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.
 
+TaskPolicies represent reusable **decisions among executable alternatives**.
+They are not conversation logs: factual questions, ordinary chat, reporting,
+and agent-learning automation are not policy tasks.
+
 <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** locally by three stdlib scorers for intent
+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.
 
    <img src="images/cc970c453583c982.png" alt="Policy quality improves with every batch of episodes" width="360" style="max-width:100%; height:auto;" />
 
+Before the next delegated execution, `task-policy-decide` samples the learned
+policy and returns the selected action together with correctness rate, mean
+reward, recent result summaries, and intent/adherence/completion scores. Agents
+consume that feedback rather than training a policy that is never used.
+
 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
@@ -71,12 +80,14 @@ 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-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 --version
+agent-learn tasks-list <agent_id> [--decision-only]
+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> --decision-context <context> --actions ./actions.json
+agent-learn task-policy-decide --agent-id <agent_id> --task-id <task_id> [--history-limit <1-500>] [--greedy] [--seed <integer>]
+agent-learn task-episode-register --agent-id <agent_id> --task-id <task_id> --episode ./episode.json [--require-decision-policy]
 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>] [--decision-only] [--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>
 ```

{agent_learning-0.4.2 → agent_learning-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-learning"
-version = "0.4.2"
+version = "0.5.0"
 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.2 → agent_learning-0.5.0}/src/agent_learning/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "0.4.2"
+__version__ = "0.5.0"

{agent_learning-0.4.2 → agent_learning-0.5.0}/src/agent_learning/cli.py

@@ -5,11 +5,15 @@ from __future__ import annotations
 import argparse
 import json
 import logging
+import math
+import random
 import sys
 import uuid
 from collections import Counter
+from datetime import datetime, timezone
 from typing import Any
 
+from ._version import __version__
 from .policy.softmax_bandit import SoftmaxPolicy
 from .storage.cosmos import get_default_store
 from .training.runner import LearningRunner
@@ -18,6 +22,7 @@ from .types import Action, Episode, MetricName, PolicySnapshot, RewardSource
 logger = logging.getLogger(__name__)
 
 _MAX_EPISODES = 500
+_DECISION_POLICY_SCOPE = "delegated_decision"
 
 
 def _episode_limit(value: str) -> int:
@@ -27,14 +32,29 @@ 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.")
+    parser = argparse.ArgumentParser(
+        prog="agent-learn",
+        description=f"Native RL CLI for AI agents. SDK version {__version__}.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
 
     sub.add_parser("list", help="List discovered agent ids and names.")
 
     tasks = sub.add_parser("tasks-list", help="List tasks for an agent.")
     tasks.add_argument("agent_id")
+    tasks.add_argument("--decision-only", action="store_true")
 
     count = sub.add_parser(
         "task-episodes-count",
@@ -42,6 +62,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 +73,17 @@ 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("--decision-only", action="store_true")
+    train.add_argument("--start-date", type=_iso_date)
+    train.add_argument("--end-date", type=_iso_date)
     train.add_argument(
         "--skip-scoring",
         action="store_true",
@@ -73,12 +99,27 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     show.add_argument("--agent-id", required=True)
     show.add_argument("--task-id", required=True)
 
+    decide = sub.add_parser(
+        "task-policy-decide",
+        help="Choose a delegated decision action and return learned feedback.",
+    )
+    decide.add_argument("--agent-id", required=True)
+    decide.add_argument("--task-id", required=True)
+    decide.add_argument("--history-limit", type=_episode_limit, default=100)
+    decide.add_argument("--greedy", action="store_true")
+    decide.add_argument("--seed", type=int)
+
     init = sub.add_parser(
         "task-policy-init",
         help="Create and activate the initial policy for an agent task.",
     )
     init.add_argument("--agent-id", required=True)
     init.add_argument("--task-id", required=True)
+    init.add_argument(
+        "--decision-context",
+        required=True,
+        help="Stable description of the delegated choice this policy controls.",
+    )
     init.add_argument(
         "--actions",
         required=True,
@@ -91,6 +132,7 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     )
     register.add_argument("--agent-id", required=True)
     register.add_argument("--task-id", required=True)
+    register.add_argument("--require-decision-policy", action="store_true")
     register.add_argument(
         "--episode",
         required=True,
@@ -108,7 +150,14 @@ def _cmd_agents_list(args: argparse.Namespace) -> int:
 
 
 def _cmd_agent_tasks_list(args: argparse.Namespace) -> int:
-    tasks = get_default_store().list_agent_tasks(args.agent_id)
+    store = get_default_store()
+    tasks = store.list_agent_tasks(args.agent_id)
+    if args.decision_only:
+        tasks = [
+            task
+            for task in tasks
+            if _is_decision_policy(store.get_active_policy(args.agent_id, task.id))
+        ]
     print(json.dumps([{"id": task.id, "name": task.name} for task in tasks], indent=2))
     return 0
 
@@ -118,6 +167,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 +180,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]
@@ -179,10 +232,24 @@ def _cmd_train(args: argparse.Namespace) -> int:
         if snapshot is None:
             skipped.append({"task_id": task_id, "reason": "no active policy"})
             continue
+        if args.decision_only and not _is_decision_policy(snapshot):
+            skipped.append({"task_id": task_id, "reason": "not a delegated decision policy"})
+            continue
         episode_limit = episode_limits.get(task_id, 0)
         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(
@@ -235,6 +302,89 @@ def _policy_payload(snapshot: PolicySnapshot) -> dict[str, Any]:
     return payload
 
 
+def _is_decision_policy(snapshot: PolicySnapshot | None) -> bool:
+    return bool(
+        snapshot
+        and snapshot.metadata.get("policy_scope") == _DECISION_POLICY_SCOPE
+    )
+
+
+def _latest_aggregate(store: Any, episode: Episode) -> float | None:
+    rewards = [
+        reward
+        for reward in store.get_rewards_for_episode(episode.id, episode.agent_id)
+        if reward.source == RewardSource.AGGREGATE
+    ]
+    if not rewards:
+        return None
+    return max(rewards, key=lambda reward: reward.created_at).value
+
+
+def _decision_feedback(
+    store: Any, snapshot: PolicySnapshot, history_limit: int
+) -> dict[str, Any]:
+    stats = {
+        action.id: {
+            "attempts": 0,
+            "correctness_evaluated": 0,
+            "correct": 0,
+            "correctness_rate": None,
+            "rewarded_episodes": 0,
+            "mean_reward": None,
+            "recent_outcomes": [],
+        }
+        for action in snapshot.actions
+    }
+    reward_totals = {action.id: 0.0 for action in snapshot.actions}
+    episodes = store.query_episodes(
+        snapshot.agent_id,
+        task_id=snapshot.task_id,
+        limit=history_limit,
+    )
+    for episode in episodes:
+        action_id = episode.action_id
+        if action_id not in stats:
+            continue
+        action_stats = stats[action_id]
+        action_stats["attempts"] += 1
+        correct_action_id = episode.metadata.get("correct_action_id")
+        was_correct = None
+        if correct_action_id:
+            was_correct = action_id == correct_action_id
+            action_stats["correctness_evaluated"] += 1
+            action_stats["correct"] += int(was_correct)
+        reward = _latest_aggregate(store, episode)
+        if reward is not None:
+            action_stats["rewarded_episodes"] += 1
+            reward_totals[action_id] += reward
+        if len(action_stats["recent_outcomes"]) < 3:
+            score_breakdown = {}
+            for result in store.get_metric_results(episode.id, episode.agent_id):
+                score_breakdown[result.metric.value] = {
+                    "normalized": result.normalized,
+                    "status": result.status,
+                    "reason": result.reason,
+                }
+            action_stats["recent_outcomes"].append(
+                {
+                    "created_at": episode.created_at,
+                    "was_correct": was_correct,
+                    "reward": reward,
+                    "execution_status": episode.execution_status,
+                    "result_summary": episode.result_summary,
+                    "score_breakdown": score_breakdown,
+                }
+            )
+    for action_id, action_stats in stats.items():
+        evaluated = action_stats["correctness_evaluated"]
+        rewarded = action_stats["rewarded_episodes"]
+        if evaluated:
+            action_stats["correctness_rate"] = action_stats["correct"] / evaluated
+        if rewarded:
+            action_stats["mean_reward"] = reward_totals[action_id] / rewarded
+    return {"episodes_reviewed": len(episodes), "actions": stats}
+
+
 def _policy_difference(
     current: PolicySnapshot, previous: PolicySnapshot | None
 ) -> dict[str, Any] | None:
@@ -295,6 +445,78 @@ def _cmd_show_task_policy(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_decide_task_policy(args: argparse.Namespace) -> int:
+    store = get_default_store()
+    snapshot = store.get_active_policy(args.agent_id, args.task_id)
+    if snapshot is None:
+        print(
+            f"No active policy found for agent_id={args.agent_id!r}, "
+            f"task_id={args.task_id!r}.",
+            file=sys.stderr,
+        )
+        return 2
+    if not _is_decision_policy(snapshot):
+        print(
+            "The active policy is not marked as a delegated decision policy. "
+            "Questions, reporting tasks, and agent-learning automation are not eligible.",
+            file=sys.stderr,
+        )
+        return 2
+    rng = random.Random(args.seed) if args.seed is not None else None
+    policy = SoftmaxPolicy.from_snapshot(snapshot, rng=rng)
+    probabilities = policy.probabilities()
+    recommended_index = max(range(len(probabilities)), key=probabilities.__getitem__)
+    if args.greedy:
+        selected_index = recommended_index
+        selected_action = snapshot.actions[selected_index]
+        selected_probability = probabilities[selected_index]
+        logprob = math.log(max(selected_probability, 1e-12))
+        mode = "greedy"
+    else:
+        decision = policy.choose()
+        selected_action = decision.action
+        selected_index = next(
+            index
+            for index, action in enumerate(snapshot.actions)
+            if action.id == selected_action.id
+        )
+        selected_probability = probabilities[selected_index]
+        logprob = decision.logprob
+        mode = "sampled"
+    feedback = _decision_feedback(store, snapshot, args.history_limit)
+    selected_stats = feedback["actions"][selected_action.id]
+    recommendation = snapshot.actions[recommended_index]
+    print(
+        json.dumps(
+            {
+                "agent_id": snapshot.agent_id,
+                "task_id": snapshot.task_id,
+                "decision_context": snapshot.metadata.get("decision_context"),
+                "policy_id": snapshot.id,
+                "policy_version": snapshot.version,
+                "selection_mode": mode,
+                "selected_action": {
+                    **selected_action.to_dict(),
+                    "probability": selected_probability,
+                    "logprob": logprob,
+                },
+                "recommended_action": {
+                    **recommendation.to_dict(),
+                    "probability": probabilities[recommended_index],
+                },
+                "action_probabilities": {
+                    action.id: probability
+                    for action, probability in zip(snapshot.actions, probabilities)
+                },
+                "selected_action_feedback": selected_stats,
+                "historical_feedback": feedback,
+            },
+            indent=2,
+        )
+    )
+    return 0
+
+
 def _cmd_init_task_policy(args: argparse.Namespace) -> int:
     store = get_default_store()
     if store.get_active_policy(args.agent_id, args.task_id) is not None:
@@ -310,20 +532,35 @@ def _cmd_init_task_policy(args: argparse.Namespace) -> int:
     except (OSError, json.JSONDecodeError) as exc:
         print(f"Unable to read --actions file: {exc}", file=sys.stderr)
         return 2
-    if not isinstance(action_payloads, list) or not action_payloads:
-        print("--actions file must contain a non-empty JSON list", file=sys.stderr)
+    if not isinstance(action_payloads, list) or len(action_payloads) < 2:
+        print(
+            "--actions file must contain at least two delegated decision actions",
+            file=sys.stderr,
+        )
         return 2
     try:
         actions = [Action.from_dict(item) for item in action_payloads]
     except (KeyError, TypeError, ValueError) as exc:
         print(f"Invalid action definition: {exc}", file=sys.stderr)
         return 2
+    action_ids = [action.id for action in actions]
+    if any(not action_id.strip() for action_id in action_ids) or len(set(action_ids)) != len(
+        action_ids
+    ):
+        print("Decision action ids must be non-empty and unique", file=sys.stderr)
+        return 2
     policy = SoftmaxPolicy.from_actions(
         actions,
         agent_id=args.agent_id,
         task_id=args.task_id,
     )
     snapshot = policy.snapshot()
+    snapshot.metadata.update(
+        {
+            "policy_scope": _DECISION_POLICY_SCOPE,
+            "decision_context": args.decision_context,
+        }
+    )
     store.store_policy(snapshot)
     print(json.dumps(_policy_payload(snapshot), indent=2))
     return 0
@@ -358,6 +595,26 @@ def _cmd_register_task_episode(args: argparse.Namespace) -> int:
         print(f"Invalid episode definition: {exc}", file=sys.stderr)
         return 2
 
+    if args.require_decision_policy:
+        policy = get_default_store().get_policy(episode.policy_id or "", args.agent_id)
+        if not _is_decision_policy(policy) or policy.task_id != args.task_id:
+            print(
+                "Episode registration requires a delegated decision policy and its policy_id.",
+                file=sys.stderr,
+            )
+            return 2
+        action_ids = {action.id for action in policy.actions}
+        if episode.action_id not in action_ids:
+            print("Episode action_id is not in the delegated decision policy.", file=sys.stderr)
+            return 2
+        correct_action_id = episode.metadata.get("correct_action_id")
+        if correct_action_id is not None and correct_action_id not in action_ids:
+            print(
+                "Episode metadata.correct_action_id is not in the delegated decision policy.",
+                file=sys.stderr,
+            )
+            return 2
+
     get_default_store().store_episode(episode)
     print(json.dumps(episode.to_dict(), indent=2))
     return 0
@@ -375,6 +632,7 @@ def main(argv: list[str] | None = None) -> int:
         "train": _cmd_train,
         "score": _cmd_score,
         "task-policy": _cmd_show_task_policy,
+        "task-policy-decide": _cmd_decide_task_policy,
         "task-policy-init": _cmd_init_task_policy,
         "task-episode-register": _cmd_register_task_episode,
     }

{agent_learning-0.4.2 → agent_learning-0.5.0}/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.2 → agent_learning-0.5.0}/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.2 → agent_learning-0.5.0}/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.2 → agent_learning-0.5.0}/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 -------------------------------------------