methodic-research 0.35.0__tar.gz → 0.36.0__tar.gz

{methodic_research-0.35.0/src/methodic_research.egg-info → methodic_research-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodic-research
-Version: 0.35.0
+Version: 0.36.0
 Summary: Python client for the Chronicle experiment platform
 License-Expression: Apache-2.0
 Project-URL: Documentation, https://docs.methodiclabs.ai

{methodic_research-0.35.0 → methodic_research-0.36.0}/pyproject.toml

@@ -8,7 +8,7 @@ name = "methodic-research"
 # methodic-lib-publish.yml overwrites this from versions.toml at build
 # time, so the published artifact has a single source of truth. Kept
 # here for local `pip install -e conductor/`.
-version = "0.35.0"
+version = "0.36.0"
 description = "Python client for the Chronicle experiment platform"
 requires-python = ">=3.11"
 license = "Apache-2.0"

{methodic_research-0.35.0 → methodic_research-0.36.0}/src/methodic/__init__.py

@@ -18,6 +18,7 @@ from methodic.errors import (
     ServerError,
 )
 from methodic.experiments import Experiment, ExperimentsAPI
+from methodic.feed import FeedAPI
 from methodic.feedback import FeedbackAPI
 from methodic.pending import PendingAPI
 from methodic.publications import PublicationsAPI
@@ -37,6 +38,8 @@ from methodic.types import (
     ExperimentDetail,
     ExperimentListPage,
     ExperimentSummary,
+    FeedEvent,
+    FeedPage,
     GitBranch,
     GitStatus,
     GitToken,
@@ -81,6 +84,9 @@ __all__ = [
     "ExperimentListPage",
     "ExperimentSummary",
     "ExperimentsAPI",
+    "FeedAPI",
+    "FeedEvent",
+    "FeedPage",
     "FeedbackAPI",
     "GitBranch",
     "GitStatus",

{methodic_research-0.35.0 → methodic_research-0.36.0}/src/methodic/chronicle.py

@@ -25,6 +25,7 @@ from methodic.datasets import DatasetsAPI
 from methodic.errata import ErrataAPI
 from methodic.errors import ChronicleConfigError
 from methodic.experiments import Experiment, ExperimentsAPI
+from methodic.feed import FeedAPI
 from methodic.feedback import FeedbackAPI
 from methodic.imports import ImportsAPI
 from methodic.me import MeAPI
@@ -274,6 +275,9 @@ class Chronicle:
         # Attention feed — the caller's actionable queue + event stream.
         self.pending = PendingAPI(self._transport, self)
         self.activity = ActivityAPI(self._transport, self)
+        # Unified event feed (event-stream.md §6): activity + needs-you + inbox
+        # + research, with an explicit per-section pointer (see FeedAPI.seen).
+        self.feed = FeedAPI(self._transport, self)
 
     @property
     def organization_id(self) -> str | None:

methodic_research-0.36.0/src/methodic/feed.py

@@ -0,0 +1,170 @@
+"""Feed namespace — the caller's unified event feed.
+
+Wraps ``GET /v1/feed`` (the JSON page) and ``POST /v1/feed/seen`` (the
+per-section cursor) — the unified event stream that subsumes activity, the
+actionable "needs you" items (blocked / report_approval / invites), new
+reports, and research recommendations (event-stream.md §6).
+
+Two cross-cutting lenses are preset filters, not separate calls:
+
+- **needs-you** — ``list(actionable=True, open=True)``: blocked agents +
+  approvals + invites still awaiting you.
+- **inbox** — ``list(recipient="me")``: items addressed to you specifically.
+
+The list is ACL-bounded server-side (the same enumeration authorization the
+experiment listing uses). Pagination is a keyset on ``seq``: the JSON body is a
+bare array, the server signals more via ``X-Has-More`` and this read's
+unseen/open count via ``X-Unseen-Count``, and the next (older) page is fetched
+with ``before=<seq>``.
+
+**Pointer contract (event-stream.md §4).** Reading never advances your pointer.
+After you have *durably processed* the events you read, advance it explicitly
+with :meth:`seen` — at-least-once: a crash between read and ack re-delivers,
+never drops. (The web UI advances automatically on view; an agent must ack
+deliberately.)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Iterator
+
+from methodic.pending import _has_more
+from methodic.transport import Transport
+from methodic.types import FeedPage
+
+if TYPE_CHECKING:
+    from methodic.chronicle import Chronicle
+
+logger = logging.getLogger(__name__)
+
+
+def _unseen_count(headers: Any) -> int:
+    """Read the ``X-Unseen-Count`` response header as an int (default 0)."""
+    try:
+        return int(str(headers.get("X-Unseen-Count", "0")).strip() or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _bool_param(value: bool) -> str:
+    """Serialize a bool for the query string as serde expects (``true``/``false``)."""
+    return "true" if value else "false"
+
+
+class FeedAPI:
+    """The caller's unified event feed (activity + needs-you + inbox + research)."""
+
+    def __init__(self, transport: Transport, chronicle: Chronicle) -> None:
+        self._t = transport
+        self._chronicle = chronicle
+
+    def list(
+        self,
+        *,
+        category: str | list[str] | None = None,
+        actionable: bool | None = None,
+        open: bool | None = None,
+        recipient: str | None = None,
+        experiment: str | None = None,
+        kind: str | None = None,
+        severity: str | None = None,
+        after_seq: int | None = None,
+        before: int | None = None,
+        limit: int | None = None,
+        order: str | None = None,
+    ) -> FeedPage:
+        """One page of feed events, newest-first (or ``score``-first for research).
+
+        Filters mirror ``GET /v1/feed``: ``category`` (a string or list of
+        categories), the ``actionable`` / ``open`` lens, ``recipient="me"`` for
+        the inbox, plus ``experiment`` / ``kind`` / ``severity``. Page with
+        ``limit`` + ``before=<seq>`` (older), or poll forward with
+        ``after_seq=<seq>``. ``order`` is ``"seq"`` (default) or ``"score"``.
+
+        The result carries ``unseen_count`` (this section's unseen/open badge)
+        and a ``next_page_token`` (the last event's ``seq``) when more remain;
+        pass it back as ``before``, or use :meth:`iter` to walk every page.
+        Reading does **not** advance your pointer — call :meth:`seen` after you
+        act.
+        """
+        params: dict[str, Any] = {}
+        if category is not None:
+            params["category"] = (
+                ",".join(category) if isinstance(category, list) else category
+            )
+        if actionable is not None:
+            params["actionable"] = _bool_param(actionable)
+        if open is not None:
+            params["open"] = _bool_param(open)
+        if recipient is not None:
+            params["recipient"] = recipient
+        if experiment is not None:
+            params["experiment"] = experiment
+        if kind is not None:
+            params["kind"] = kind
+        if severity is not None:
+            params["severity"] = severity
+        if after_seq is not None:
+            params["after_seq"] = after_seq
+        if before is not None:
+            params["before"] = before
+        if limit is not None:
+            params["limit"] = limit
+        if order is not None:
+            params["order"] = order
+        rows, headers = self._t.get_with_headers("/feed", params=params or None)
+        return FeedPage.from_list(
+            rows, has_more=_has_more(headers), unseen_count=_unseen_count(headers)
+        )
+
+    def iter(
+        self,
+        *,
+        category: str | list[str] | None = None,
+        actionable: bool | None = None,
+        open: bool | None = None,
+        recipient: str | None = None,
+        experiment: str | None = None,
+        kind: str | None = None,
+        severity: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+    ) -> Iterator[Any]:
+        """Yield every matching feed event, paging server-side as needed.
+
+        Walks oldest-ward via the ``before=<seq>`` cursor. Forward polling
+        (``after_seq``) is a single-call concern, so it is intentionally not a
+        parameter here — use :meth:`list` for incremental tailing.
+        """
+        token: int | None = None
+        while True:
+            page = self.list(
+                category=category,
+                actionable=actionable,
+                open=open,
+                recipient=recipient,
+                experiment=experiment,
+                kind=kind,
+                severity=severity,
+                before=token,
+                limit=limit,
+                order=order,
+            )
+            yield from page.results
+            if page.next_page_token is None:
+                return
+            token = int(page.next_page_token)
+
+    def seen(self, *, section: str, through_seq: int) -> None:
+        """Advance your pointer for one section to a seq you have FINISHED handling.
+
+        ``section`` is ``blocked`` / ``approvals`` / ``research`` / ``passive``
+        (see each event's section); ``through_seq`` is the highest event ``seq``
+        you've durably processed. Monotonic — a lower seq is a no-op. Call this
+        only *after* acting on the events (at-least-once); reading never advances
+        the pointer.
+        """
+        self._t.post(
+            "/feed/seen", json={"section": section, "through_seq": through_seq}
+        )

{methodic_research-0.35.0 → methodic_research-0.36.0}/src/methodic/types.py

@@ -425,7 +425,7 @@ class ExperimentListPage:
         )
 
 
-# ── Attention feed (pending + activity) ───────────────────────────────────
+# ── Attention feed (pending + activity + unified feed) ─────────────────────
 
 
 @dataclass
@@ -545,6 +545,78 @@ class ActivityPage:
         return cls(results=results, next_page_token=next_token)
 
 
+@dataclass
+class FeedEvent:
+    """One row of the unified event feed from `GET /v1/feed` (event-stream.md).
+
+    The feed unifies activity, the actionable "needs you" items (``blocked`` /
+    ``report_approval`` / invites), new reports, and research recommendations
+    under one stream. `seq` is the global monotonic cursor key — the value you
+    pass to :meth:`FeedAPI.seen` (as ``through_seq``) and to ``before`` /
+    ``after_seq`` for paging. `category` is the granular content type and rolls
+    up into a `section` (``blocked`` / ``approvals`` / ``research`` /
+    ``passive``) — the unit the cursor is keyed on. `actionable` items stay open
+    until `resolved_at` is set. `recipient_principal_id` is set when the event is
+    addressed to a specific principal (the inbox lens); broadcast/resource items
+    use `audience` + `experiment_id` instead. `payload` is the event-specific
+    "what changed" blob.
+    """
+
+    seq: int
+    id: str
+    category: str
+    kind: str
+    created_at: str
+    via: str
+    audience: str
+    actionable: bool
+    severity: str
+    payload: dict[str, Any]
+    actor_subject: str | None = None
+    resource_type: str | None = None
+    resource_id: str | None = None
+    experiment_id: str | None = None
+    recipient_principal_id: str | None = None
+    resolved_at: str | None = None
+    resolved_by: str | None = None
+    resolving_seq: int | None = None
+    score: float | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FeedEvent:
+        return _from_dict(cls, data)
+
+
+@dataclass
+class FeedPage:
+    """One page of `feed.list` results plus the section unseen count + a cursor.
+
+    The server returns a **bare array** and carries page metadata in headers:
+    ``X-Has-More`` (it over-fetches one row to decide) and ``X-Unseen-Count``
+    (this read's unseen/open count for the queried section). The SDK reads both;
+    when more remain it builds ``next_page_token`` from the last event's ``seq``
+    — the ``?before`` cursor the server consumes for the next (older) page.
+    ``next_page_token`` is ``None`` on the last page. Use :meth:`FeedAPI.iter` to
+    walk every page.
+    """
+
+    results: list[FeedEvent]
+    unseen_count: int = 0
+    next_page_token: str | None = None
+
+    @classmethod
+    def from_list(
+        cls, rows: Any, *, has_more: bool, unseen_count: int = 0
+    ) -> FeedPage:
+        results = [FeedEvent.from_dict(r) for r in (rows or [])]
+        next_token = None
+        if has_more and results:
+            next_token = str(results[-1].seq)
+        return cls(
+            results=results, unseen_count=unseen_count, next_page_token=next_token
+        )
+
+
 @dataclass
 class BulkApproveResult:
     """Per-asset outcome within a `BulkApproveResponse`.

{methodic_research-0.35.0 → methodic_research-0.36.0/src/methodic_research.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodic-research
-Version: 0.35.0
+Version: 0.36.0
 Summary: Python client for the Chronicle experiment platform
 License-Expression: Apache-2.0
 Project-URL: Documentation, https://docs.methodiclabs.ai

{methodic_research-0.35.0 → methodic_research-0.36.0}/src/methodic_research.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/methodic/datasets.py
 src/methodic/errata.py
 src/methodic/errors.py
 src/methodic/experiments.py
+src/methodic/feed.py
 src/methodic/feedback.py
 src/methodic/imports.py
 src/methodic/me.py
@@ -42,6 +43,7 @@ tests/test_config.py
 tests/test_datasets.py
 tests/test_distill.py
 tests/test_experiments.py
+tests/test_feed.py
 tests/test_feedback.py
 tests/test_imports.py
 tests/test_pending.py

methodic_research-0.36.0/tests/test_feed.py

@@ -0,0 +1,135 @@
+"""Tests for the Feed namespace (the caller's unified event feed)."""
+
+from methodic import Chronicle
+
+BASE = "http://localhost:8080"
+
+
+def _chronicle():
+    return Chronicle(server_url=BASE, api_key="sk_user_test")
+
+
+def _event(**overrides):
+    base = {
+        "seq": 42,
+        "id": "11111111-1111-1111-1111-111111111111",
+        "category": "activity",
+        "kind": "run.succeeded",
+        "created_at": "2026-06-02T12:00:00Z",
+        "via": "direct",
+        "audience": "experiment_readers",
+        "actionable": False,
+        "severity": "info",
+        "payload": {"foo": "bar"},
+        "experiment_id": "exp-1",
+        "recipient_principal_id": "auth0|alice",
+    }
+    base.update(overrides)
+    return base
+
+
+def test_list_returns_typed_events_and_unseen_count(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        json=[_event()],
+        headers={"X-Has-More": "false", "X-Unseen-Count": "3"},
+    )
+
+    page = _chronicle().feed.list(category="activity")
+
+    assert page.next_page_token is None
+    assert page.unseen_count == 3
+    assert len(page.results) == 1
+    ev = page.results[0]
+    assert ev.seq == 42
+    assert ev.category == "activity"
+    assert ev.kind == "run.succeeded"
+    assert ev.payload == {"foo": "bar"}
+    assert ev.recipient_principal_id == "auth0|alice"
+
+
+def test_list_omits_optional_fields(requests_mock):
+    """Optional resolution/score fields absent on the wire → None."""
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        json=[_event()],
+        headers={"X-Has-More": "false"},
+    )
+
+    ev = _chronicle().feed.list().results[0]
+    assert ev.resolved_at is None
+    assert ev.resolving_seq is None
+    assert ev.score is None
+    # Missing X-Unseen-Count header defaults to 0.
+    assert _chronicle().feed.list().unseen_count == 0
+
+
+def test_list_builds_cursor_from_seq(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        json=[_event(seq=42)],
+        headers={"X-Has-More": "true", "X-Unseen-Count": "1"},
+    )
+
+    page = _chronicle().feed.list()
+    assert page.next_page_token == "42"
+
+
+def test_list_threads_filters_and_lenses(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        json=[],
+        headers={"X-Has-More": "false"},
+    )
+
+    _chronicle().feed.list(
+        category=["report_approval", "experiment_invite"],
+        actionable=True,
+        open=True,
+        recipient="me",
+        experiment="exp-1",
+        kind="invite.received",
+        severity="warning",
+        after_seq=10,
+        limit=25,
+        order="score",
+    )
+
+    qs = requests_mock.last_request.qs
+    assert qs["category"] == ["report_approval,experiment_invite"]
+    assert qs["actionable"] == ["true"]
+    assert qs["open"] == ["true"]
+    assert qs["recipient"] == ["me"]
+    assert qs["experiment"] == ["exp-1"]
+    assert qs["kind"] == ["invite.received"]
+    assert qs["severity"] == ["warning"]
+    assert qs["after_seq"] == ["10"]
+    assert qs["limit"] == ["25"]
+    assert qs["order"] == ["score"]
+
+
+def test_seen_posts_section_and_through_seq(requests_mock):
+    requests_mock.post(f"{BASE}/v1/feed/seen", status_code=204)
+
+    _chronicle().feed.seen(section="passive", through_seq=42)
+
+    assert requests_mock.last_request.json() == {
+        "section": "passive",
+        "through_seq": 42,
+    }
+
+
+def test_iter_walks_before_cursor(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        [
+            {"json": [_event(seq=42)], "headers": {"X-Has-More": "true"}},
+            {"json": [_event(seq=40)], "headers": {"X-Has-More": "false"}},
+        ],
+    )
+
+    seqs = [e.seq for e in _chronicle().feed.iter()]
+    assert seqs == [42, 40]
+    assert requests_mock.call_count == 2
+    second = requests_mock.request_history[1]
+    assert second.qs["before"] == ["42"]