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

{agent_learning-0.4.2/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.2
+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** 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.
+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.2 → agent_learning-0.4.3}/README.md

@@ -1,30 +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 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.
 
 <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.
@@ -72,11 +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>
 ```

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

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

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

{agent_learning-0.4.2 → 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(

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-learning
-Version: 0.4.2
+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** 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.
+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.2 → agent_learning-0.4.3}/tests/test_cli.py

@@ -54,6 +54,48 @@ def test_discovery_and_full_episode_count(monkeypatch, capsys) -> None:
     assert capsys.readouterr().out.strip() == "1"
 
 
+def test_episode_count_and_list_use_the_training_date_window(
+    monkeypatch, capsys
+) -> None:
+    store = InMemoryStore()
+    monkeypatch.setattr(cli, "get_default_store", lambda: store)
+    for index, created_at in enumerate(
+        (
+            "2026-08-09T05:40:00+00:00",
+            "2026-08-09T06:07:25+00:00",
+            "2026-08-09T06:12:23+00:00",
+            "2026-08-09T06:13:10+00:00",
+            "2026-08-09T06:13:55+00:00",
+            "2026-08-09T06:14:37+00:00",
+            "2026-08-09T06:20:00+00:00",
+        )
+    ):
+        episode = _full_episode()
+        episode.id = f"episode-{index}"
+        episode.created_at = created_at
+        store.store_episode(episode)
+
+    window = [
+        "--task-id",
+        "chat",
+        "--start-date",
+        "2026-08-09T05:42:45.258Z",
+        "--end-date",
+        "2026-08-09T06:16:07.333Z",
+    ]
+    assert cli.main(["task-episodes-count", "agent-1", *window]) == 0
+    assert capsys.readouterr().out.strip() == "5"
+    assert cli.main(["task-episodes-list", "agent-1", *window]) == 0
+    listed = json.loads(capsys.readouterr().out)
+    assert len(listed) == 5
+    assert all(
+        "2026-08-09T05:42:45.258+00:00"
+        <= item["episode"]["created_at"]
+        <= "2026-08-09T06:16:07.333+00:00"
+        for item in listed
+    )
+
+
 def test_episode_inspection_includes_scores_and_final_reward(monkeypatch, capsys) -> None:
     store = InMemoryStore()
     episode = _full_episode()
@@ -317,4 +359,51 @@ def test_agent_training_uses_one_limit_and_preserves_task_policy_history(
 
 def test_episode_limit_is_capped_at_500() -> None:
     with pytest.raises(SystemExit):
-        cli.main(["train", "--agent-id", "agent-1", "--limit", "501"])
+        cli.main(["train", "--agent-id", "agent-1", "--limit", "501"])
+
+
+def test_train_enforces_minimum_selected_episode_count(
+    monkeypatch, capsys
+) -> None:
+    store = InMemoryStore()
+    monkeypatch.setattr(cli, "get_default_store", lambda: store)
+    policy = SoftmaxPolicy.from_actions(
+        [Action(id="respond")], agent_id="agent-1", task_id="chat"
+    )
+    store.store_policy(policy.snapshot())
+    for index in range(3):
+        episode = _full_episode()
+        episode.id = f"episode-{index}"
+        store.store_episode(episode)
+        store.store_reward(
+            Reward(
+                episode_id=episode.id,
+                agent_id=episode.agent_id,
+                source=RewardSource.AGGREGATE,
+                value=0.8,
+            )
+        )
+
+    result = cli.main(
+        [
+            "train",
+            "--agent-id",
+            "agent-1",
+            "--task-id",
+            "chat",
+            "--min-episodes",
+            "5",
+            "--skip-scoring",
+        ]
+    )
+    output = json.loads(capsys.readouterr().out)
+
+    assert result == 2
+    assert output["runs"] == []
+    assert output["skipped"] == [
+        {
+            "task_id": "chat",
+            "reason": "selected batch has 3 episodes; minimum is 5",
+        }
+    ]
+    assert store.get_active_policy("agent-1", "chat").version == 0

{agent_learning-0.4.2 → agent_learning-0.4.3}/tests/test_storage_local.py

@@ -135,6 +135,9 @@ def test_query_filters_and_limit(tmp_path: Path) -> None:
     # Filter by window
     windowed = store.query_episodes("dq", start_date="2024-05-01", end_date="2024-07-01")
     assert len(windowed) == 1
+    assert store.count_episodes(
+        "dq", start_date="2024-05-01", end_date="2024-07-01"
+    ) == 1
     # Limit
     assert len(store.query_episodes("dq", limit=1)) == 1
 

agent_learning-0.4.2/PYPI.md

@@ -1,15 +0,0 @@
-# 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).
-
-## 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.
-
-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. 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.
-
-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.