initial toolkit

.importlinter

@@ -3,12 +3,13 @@ root_package = pbs_client
 include_external_packages = True
 
 [importlinter:contract:pbs-client-layers]
-name = pbs-client layers: sync sits on http+db, query sits on db only
+name = pbs-client layers: toolkit sits on db, sync sits on http+db
 type = layers
 layers =
     pbs_client.cli
     pbs_client.sync
-    pbs_client.query
+    pbs_client.toolkit.integrations
+    pbs_client.toolkit.analytics
+    pbs_client.toolkit.core
     pbs_client.db
     pbs_client.http
-

src/pbs_client/cli/__init__.py

@@ -3,4 +3,3 @@
 from pbs_client.cli.main import app, main
 
 __all__ = ["app", "main"]
-

src/pbs_client/http/__init__.py

@@ -3,4 +3,3 @@
 from pbs_client.http.client import GlobalRateLimiter, Page, PBSClient, TransportResponse
 
 __all__ = ["GlobalRateLimiter", "PBSClient", "Page", "TransportResponse"]
-

src/pbs_client/sync/__init__.py

@@ -3,4 +3,3 @@
 from pbs_client.sync.orchestrator import SyncOrchestrator, SyncResult, mirror_status, upsert_records
 
 __all__ = ["SyncOrchestrator", "SyncResult", "mirror_status", "upsert_records"]
-

src/pbs_client/toolkit/__init__.py

@@ -0,0 +1 @@
+"""PBS-native navigation and indication-candidate helpers."""

src/pbs_client/toolkit/analytics/__init__.py

@@ -0,0 +1,5 @@
+"""PBS-native composed analytics over toolkit core primitives."""
+
+from pbs_client.toolkit.analytics.indications import IndicationCandidate, indication_candidates
+
+__all__ = ["IndicationCandidate", "indication_candidates"]

src/pbs_client/toolkit/analytics/indications.py

@@ -0,0 +1,49 @@
+"""Indication-candidate composition for PBS items."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from sqlalchemy.orm import Session
+
+from pbs_client.db.model import Item, Schedule
+from pbs_client.toolkit.core import IndicationText, find_items, get_item_indication_text
+
+
+@dataclass(frozen=True, slots=True)
+class IndicationCandidate:
+    """A PBS item, its schedule, and one traceable indication value."""
+
+    item: Item
+    schedule: Schedule
+    indication: IndicationText
+
+
+def indication_candidates(
+    session: Session,
+    item_code: str,
+    *,
+    as_of: date | datetime | str | None = None,
+) -> list[IndicationCandidate]:
+    """Resolve an item code to all structured or fallback indications.
+
+    With ``as_of``, item lookup is restricted to the schedule effective on
+    that date. Without it, every matching historical schedule remains
+    distinct. The local mirror's schedule row is paired using the item's
+    opaque ``schedule_code`` rather than schedule-code magnitude.
+    """
+
+    candidates: list[IndicationCandidate] = []
+    for item in find_items(session, item_code, as_of=as_of):
+        schedule = session.get(Schedule, item.schedule_code)
+        if schedule is None:
+            continue
+        candidates.extend(
+            IndicationCandidate(item=item, schedule=schedule, indication=indication)
+            for indication in get_item_indication_text(session, item)
+        )
+    return candidates
+
+
+__all__ = ["IndicationCandidate", "indication_candidates"]

src/pbs_client/query/__init__.py → src/pbs_client/toolkit/core/__init__.py

@@ -1,12 +1,15 @@
-"""Offline query helpers for the local PBS mirror."""
+"""Foundational, local-only navigation over the PBS mirror."""
 
-from pbs_client.query.service import (
+from pbs_client.toolkit.core.service import (
+    BenefitTypeCode,
+    IndicationText,
     ItemExpansion,
     RestrictionExpansion,
     expand_item,
     find_items,
     get_item,
     get_item_atc_codes,
+    get_item_indication_text,
     get_item_restrictions,
     item_atc_codes,
     item_restrictions,
@@ -15,16 +18,18 @@
 )
 
 __all__ = [
+    "BenefitTypeCode",
+    "IndicationText",
     "ItemExpansion",
     "RestrictionExpansion",
     "expand_item",
     "find_items",
     "get_item",
     "get_item_atc_codes",
+    "get_item_indication_text",
     "get_item_restrictions",
     "item_atc_codes",
     "item_restrictions",
     "lookup_item",
     "resolve_schedule",
 ]
-