loom-client 0.0.1__py3-none-any.whl

loom_client/__init__.py

@@ -0,0 +1,149 @@
+"""loom_client — Python WebSocket client for the Loom Genome Browser."""
+
+from .client import LoomClient
+from .exceptions import CommandException
+from .models import (
+    AddROIAction,
+    AddROIResult,
+    AddTrackAction,
+    AnnotationFeatureSummary,
+    ClearROIAction,
+    ClearROIResult,
+    CommandArgs,
+    DataSourceConfig,
+    ErrorDetail,
+    ErrorMessage,
+    EventMessage,
+    ExportViewArgs,
+    FindROIAtLocusAction,
+    FindROIAtLocusResult,
+    FindTrackAction,
+    GetBrowserStateArgs,
+    GetVisibleROIAction,
+    GetVisibleROIResult,
+    InteractionFeatureSummary,
+    ListROIAction,
+    ListROIResult,
+    ListROISetsAction,
+    ListROISetsResult,
+    Locus,
+    LocusChangeData,
+    ManageROIsArgs,
+    ManageROIsResult,
+    ModifyTrackAction,
+    ModifyTrackActionResult,
+    ModifyTracksArgs,
+    ModifyTracksResult,
+    NavigateArgs,
+    OutboundMessage,
+    ProjectedState,
+    QueryFeaturesArgs,
+    QueryFeaturesResult,
+    ROI,
+    ROIAction,
+    ROIEventData,
+    ROIInteractionEventData,
+    ROISetConfig,
+    RemoveROIAction,
+    RemoveROIResult,
+    RemoveTrackAction,
+    RequestMessage,
+    ResponseMessage,
+    SessionConfig,
+    SetLayoutArgs,
+    SetLayoutResult,
+    SignalRange,
+    SingleTrackEventData,
+    SubscribeEventsArgs,
+    SubscribeEventsResult,
+    TrackErrorData,
+    TrackFeatureSummary,
+    TrackInteractionData,
+    TrackOrderChangedData,
+    TrackSessionConfig,
+    TrackSummary,
+    UpdateMetadataAction,
+    UpdateROIAction,
+    UpdateROIResult,
+    WigFeatureSummary,
+    WireTrackSelector,
+    ZoomLevel,
+)
+
+__all__ = [
+    "LoomClient",
+    "CommandException",
+    # Wire messages
+    "RequestMessage",
+    "ResponseMessage",
+    "ErrorDetail",
+    "ErrorMessage",
+    "EventMessage",
+    "OutboundMessage",
+    # Core genomic types
+    "Locus",
+    "ROI",
+    "ROISetConfig",
+    # Track session configs
+    "DataSourceConfig",
+    "TrackSessionConfig",
+    "SessionConfig",
+    # State projection
+    "ZoomLevel",
+    "SignalRange",
+    "WigFeatureSummary",
+    "AnnotationFeatureSummary",
+    "InteractionFeatureSummary",
+    "TrackFeatureSummary",
+    "TrackSummary",
+    "ProjectedState",
+    # Track selector
+    "WireTrackSelector",
+    # Command args
+    "CommandArgs",
+    "GetBrowserStateArgs",
+    "NavigateArgs",
+    "AddTrackAction",
+    "RemoveTrackAction",
+    "FindTrackAction",
+    "UpdateMetadataAction",
+    "ModifyTrackAction",
+    "ModifyTracksArgs",
+    "QueryFeaturesArgs",
+    "SetLayoutArgs",
+    "ExportViewArgs",
+    "AddROIAction",
+    "RemoveROIAction",
+    "UpdateROIAction",
+    "ClearROIAction",
+    "ListROIAction",
+    "ListROISetsAction",
+    "FindROIAtLocusAction",
+    "GetVisibleROIAction",
+    "ROIAction",
+    "ManageROIsArgs",
+    "SubscribeEventsArgs",
+    # Command results
+    "ModifyTrackActionResult",
+    "ModifyTracksResult",
+    "QueryFeaturesResult",
+    "SetLayoutResult",
+    "AddROIResult",
+    "RemoveROIResult",
+    "UpdateROIResult",
+    "ClearROIResult",
+    "ListROIResult",
+    "ListROISetsResult",
+    "FindROIAtLocusResult",
+    "GetVisibleROIResult",
+    "ManageROIsResult",
+    "SubscribeEventsResult",
+    # Event data
+    "LocusChangeData",
+    "SingleTrackEventData",
+    "TrackOrderChangedData",
+    "TrackErrorData",
+    "TrackInteractionData",
+    "ROIEventData",
+    "ROIInteractionEventData",
+]

loom_client/client.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Callable
+from typing import Any, Literal
+
+import websockets
+
+from .exceptions import CommandException
+from .models import (
+    AddTrackAction,
+    CommandArgs,
+    ErrorDetail,
+    ExportViewArgs,
+    FindTrackAction,
+    GetBrowserStateArgs,
+    ManageROIsArgs,
+    ModifyTrackAction,
+    ModifyTracksArgs,
+    ModifyTracksResult,
+    NavigateArgs,
+    ProjectedState,
+    QueryFeaturesArgs,
+    QueryFeaturesResult,
+    ROIAction,
+    RequestMessage,
+    SessionConfig,
+    SetLayoutArgs,
+    SetLayoutResult,
+    SubscribeEventsArgs,
+    SubscribeEventsResult,
+    TrackSessionConfig,
+)
+
+
+class LoomClient:
+    """Async WebSocket client for the Loom Genome Browser."""
+
+    def __init__(self, url: str) -> None:
+        self._url = url
+        self._ws = None
+        self._pending: dict[str, asyncio.Future] = {}
+        self._event_handlers: dict[str, list[Callable]] = {}
+        self._listener_task: asyncio.Task | None = None
+
+    # ── Connection management ─────────────────────────────────────────────────
+
+    async def connect(self) -> None:
+        """Open the WebSocket connection and start the background listener."""
+        self._ws = await websockets.connect(self._url)
+        self._listener_task = asyncio.create_task(self._listen())
+
+    async def close(self) -> None:
+        """Cancel the listener and close the WebSocket connection."""
+        if self._listener_task:
+            self._listener_task.cancel()
+        if self._ws:
+            await self._ws.close()
+
+    # ── Message routing ───────────────────────────────────────────────────────
+
+    async def _listen(self) -> None:
+        async for raw in self._ws:
+            msg = json.loads(raw)
+
+            if "event" in msg:
+                # Unsolicited server-pushed event
+                event_name = msg["event"]
+                for handler in self._event_handlers.get(event_name, []):
+                    handler(msg["data"])
+                for handler in self._event_handlers.get("*", []):
+                    handler(event_name, msg["data"])
+
+            elif "id" in msg:
+                future = self._pending.pop(msg["id"], None)
+                if future is None:
+                    continue
+                if "error" in msg:
+                    err = ErrorDetail.model_validate(msg["error"])
+                    future.set_exception(CommandException(err.code, err.message))
+                else:
+                    future.set_result(msg["result"])
+
+    # ── Sending commands ──────────────────────────────────────────────────────
+
+    async def send(self, args: CommandArgs) -> Any:
+        """Send a command and await the correlated response."""
+        req = RequestMessage(command=args.command)
+        payload = args.model_dump(by_alias=True, exclude_none=True)
+        payload.pop("command")
+        if payload:
+            req.args = payload
+
+        loop = asyncio.get_event_loop()
+        future: asyncio.Future = loop.create_future()
+        self._pending[req.id] = future
+        await self._ws.send(req.model_dump_json())
+        return await future
+
+    # ── Typed command methods ─────────────────────────────────────────────────
+
+    async def get_browser_state(self, *, record: str | None = None) -> ProjectedState:
+        """Return the current projected browser state."""
+        result = await self.send(GetBrowserStateArgs(record=record))
+        return ProjectedState.model_validate(result)
+
+    async def navigate(
+        self,
+        *,
+        locus: str | None = None,
+        zoom: Literal["in", "out"] | None = None,
+        factor: float | None = None,
+    ) -> bool:
+        """Navigate the viewport to a locus or zoom in/out."""
+        return await self.send(NavigateArgs(locus=locus, zoom=zoom, factor=factor))
+
+    async def modify_tracks(
+        self, actions: list[ModifyTrackAction]
+    ) -> ModifyTracksResult:
+        """Apply one or more track modification actions."""
+        result = await self.send(ModifyTracksArgs(actions=actions))
+        return ModifyTracksResult.model_validate(result)
+
+    async def query_features(
+        self, track_id: str, *, summarize: bool | None = None
+    ) -> QueryFeaturesResult:
+        """Query features for a specific track."""
+        result = await self.send(
+            QueryFeaturesArgs(trackId=track_id, summarize=summarize)
+        )
+        return QueryFeaturesResult.model_validate(result)
+
+    async def set_layout(
+        self,
+        tracks: list[TrackSessionConfig],
+        *,
+        locus: str | None = None,
+    ) -> SetLayoutResult:
+        """Replace the current track layout."""
+        result = await self.send(SetLayoutArgs(tracks=tracks, locus=locus))
+        return SetLayoutResult.model_validate(result)
+
+    async def export_view(
+        self,
+        format: Literal["svg", "png", "session"],
+        *,
+        width: int | None = None,
+    ) -> str | SessionConfig:
+        """Export the current view as SVG, PNG, or a session config."""
+        result = await self.send(ExportViewArgs(format=format, width=width))
+        if format == "session":
+            return SessionConfig.model_validate(result)
+        return result  # SVG/PNG as string
+
+    async def manage_rois(self, action: ROIAction) -> Any:
+        """Perform a ROI management action."""
+        result = await self.send(ManageROIsArgs(action=action))
+        return result
+
+    async def subscribe_events(self, events: list[str]) -> SubscribeEventsResult:
+        """Subscribe to browser events. Use ``["*"]`` for all, ``[]`` to unsubscribe."""
+        result = await self.send(SubscribeEventsArgs(events=events))
+        return SubscribeEventsResult.model_validate(result)
+
+    # ── Event subscription ────────────────────────────────────────────────────
+
+    def on(self, event: str, handler: Callable) -> None:
+        """Register an event handler. Use ``'*'`` for all events."""
+        self._event_handlers.setdefault(event, []).append(handler)
+
+    def off(self, event: str, handler: Callable) -> None:
+        """Unregister a previously registered event handler."""
+        handlers = self._event_handlers.get(event, [])
+        if handler in handlers:
+            handlers.remove(handler)

loom_client/exceptions.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+
+class CommandException(Exception):
+    """Raised when the server returns an error response."""
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code}] {message}")

loom_client/models.py

@@ -0,0 +1,526 @@
+from __future__ import annotations
+
+import uuid
+from enum import Enum
+from typing import Annotated, Any, Literal, Union
+
+from pydantic import BaseModel, Field
+
+
+# ── Wire messages ─────────────────────────────────────────────────────────────
+
+class RequestMessage(BaseModel):
+    """Client → Server request."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    command: str
+    args: dict[str, Any] | None = None
+
+
+class ResponseMessage(BaseModel):
+    """Server → Client success response."""
+
+    id: str
+    result: Any
+
+
+class ErrorDetail(BaseModel):
+    code: str
+    message: str
+
+
+class ErrorMessage(BaseModel):
+    """Server → Client error response."""
+
+    id: str
+    error: ErrorDetail
+
+
+class EventMessage(BaseModel):
+    """Server → Client unsolicited event."""
+
+    event: str
+    data: Any
+
+
+# Discriminated parsing of inbound server messages
+OutboundMessage = Annotated[
+    Union[ResponseMessage, ErrorMessage, EventMessage],
+    Field(discriminator=None),  # manually discriminate on field presence
+]
+
+
+# ── Core genomic types ────────────────────────────────────────────────────────
+
+class Locus(BaseModel):
+    chr: str
+    start: int
+    end: int
+
+
+class ROI(BaseModel):
+    """Region of Interest."""
+
+    id: str
+    chr: str
+    start: int  # 0-based
+    end: int
+    name: str | None = None
+    description: str | None = None
+    color: str | None = None  # CSS color with alpha
+
+
+class ROISetConfig(BaseModel):
+    name: str
+    color: str | None = None
+    is_user_defined: bool | None = Field(None, alias="isUserDefined")
+    features: list[ROI]
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Track session configs ─────────────────────────────────────────────────────
+
+class DataSourceConfig(BaseModel):
+    """Discriminated union — use the `type` field."""
+
+    type: str
+    url: str | None = None
+    genome: str | None = None
+    track: str | None = None
+    experiment_id: str | None = Field(None, alias="experimentId")
+    window_function: str | None = Field(None, alias="windowFunction")
+    format: str | None = None
+    index_url: str | None = Field(None, alias="indexURL")
+    indexed: bool | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class TrackSessionConfig(BaseModel):
+    """
+    Discriminated union on ``type``. Valid types:
+    ``'wig'``, ``'annotation'``, ``'ruler'``, ``'sequence'``, ``'interact'``
+    """
+
+    type: str
+    id: str | None = None
+    name: str | None = None
+    order: int | None = None
+    metadata: dict[str, str] | None = None
+    data_source: DataSourceConfig | None = Field(None, alias="dataSource")
+    config: dict[str, Any] | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class SessionConfig(BaseModel):
+    version: str
+    locus: Locus
+    viewport_width: int | None = Field(None, alias="viewportWidth")
+    theme: dict[str, Any] | None = None
+    genome: dict[str, Any] | None = None
+    tracks: list[TrackSessionConfig]
+    rois: list[ROISetConfig] | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+# ── State projection (get_browser_state response) ─────────────────────────────
+
+class ZoomLevel(str, Enum):
+    BASE = "base"
+    ELEMENT = "element"
+    GENE = "gene"
+    REGION = "region"
+    CHROMOSOME = "chromosome"
+    GENOME = "genome"
+
+
+class SignalRange(BaseModel):
+    min: float
+    max: float
+
+
+class WigFeatureSummary(BaseModel):
+    feature_count: int = Field(alias="featureCount")
+    signal_range: SignalRange = Field(alias="signalRange")
+
+    model_config = {"populate_by_name": True}
+
+
+class AnnotationFeatureSummary(BaseModel):
+    feature_count: int = Field(alias="featureCount")
+    feature_names: list[str] = Field(alias="featureNames")
+    packing_depth: int = Field(alias="packingDepth")
+
+    model_config = {"populate_by_name": True}
+
+
+class InteractionFeatureSummary(BaseModel):
+    feature_count: int = Field(alias="featureCount")
+    value_range: SignalRange = Field(alias="valueRange")
+
+    model_config = {"populate_by_name": True}
+
+
+TrackFeatureSummary = WigFeatureSummary | AnnotationFeatureSummary | InteractionFeatureSummary
+
+
+class TrackSummary(BaseModel):
+    id: str
+    type: str
+    name: str | None = None
+    metadata: dict[str, str] | None = None
+    loading: bool | None = None
+    feature_summary: dict[str, Any] | None = Field(None, alias="featureSummary")
+
+    model_config = {"populate_by_name": True}
+
+
+class ProjectedState(BaseModel):
+    locus: Locus
+    locus_string: str = Field(alias="locusString")
+    span: int
+    zoom_level: ZoomLevel = Field(alias="zoomLevel")
+    genome: str | None = None
+    tracks: list[TrackSummary]
+    rois: list[ROISetConfig]
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Track selector ────────────────────────────────────────────────────────────
+
+class WireTrackSelector(BaseModel):
+    """
+    JSON-safe track selector. Fields are AND-combined.
+
+    - id: exact match on track ID
+    - name: case-insensitive substring match
+    - name_regex: regex pattern (takes precedence over name), matched case-insensitive
+    - type: exact match on track type (``'wig'``, ``'annotation'``, etc.)
+    - where: AND semantics on metadata key-value pairs
+    """
+
+    id: str | None = None
+    name: str | None = None
+    name_regex: str | None = Field(None, alias="nameRegex")
+    type: str | None = None
+    where: dict[str, str] | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Command argument models ───────────────────────────────────────────────────
+
+class GetBrowserStateArgs(BaseModel):
+    command: Literal["get_browser_state"] = "get_browser_state"
+    record: str | None = None
+
+
+class NavigateArgs(BaseModel):
+    command: Literal["navigate"] = "navigate"
+    locus: str | None = None
+    zoom: Literal["in", "out"] | None = None
+    factor: float | None = None
+
+
+# ── modify_tracks ─────────────────────────────────────────────────────────────
+
+class AddTrackAction(BaseModel):
+    action: Literal["add"] = "add"
+    config: TrackSessionConfig
+
+
+class RemoveTrackAction(BaseModel):
+    action: Literal["remove"] = "remove"
+    selector: WireTrackSelector
+
+
+class FindTrackAction(BaseModel):
+    action: Literal["find"] = "find"
+    selector: WireTrackSelector
+
+
+class UpdateMetadataAction(BaseModel):
+    action: Literal["update_metadata"] = "update_metadata"
+    selector: WireTrackSelector
+    metadata: dict[str, str]
+
+
+ModifyTrackAction = AddTrackAction | RemoveTrackAction | FindTrackAction | UpdateMetadataAction
+
+
+class ModifyTracksArgs(BaseModel):
+    command: Literal["modify_tracks"] = "modify_tracks"
+    actions: list[ModifyTrackAction]
+
+
+# ── query_features ────────────────────────────────────────────────────────────
+
+class QueryFeaturesArgs(BaseModel):
+    command: Literal["query_features"] = "query_features"
+    track_id: str = Field(alias="trackId")
+    summarize: bool | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+# ── set_layout ────────────────────────────────────────────────────────────────
+
+class SetLayoutArgs(BaseModel):
+    command: Literal["set_layout"] = "set_layout"
+    tracks: list[TrackSessionConfig]
+    locus: str | None = None
+
+
+# ── export_view ───────────────────────────────────────────────────────────────
+
+class ExportViewArgs(BaseModel):
+    command: Literal["export_view"] = "export_view"
+    format: Literal["svg", "png", "session"]
+    width: int | None = None
+
+
+# ── manage_rois ───────────────────────────────────────────────────────────────
+
+class AddROIAction(BaseModel):
+    action: Literal["add"] = "add"
+    roi: ROI
+    set_name: str | None = Field(None, alias="setName")
+
+    model_config = {"populate_by_name": True}
+
+
+class RemoveROIAction(BaseModel):
+    action: Literal["remove"] = "remove"
+    roi_id: str = Field(alias="roiId")
+
+    model_config = {"populate_by_name": True}
+
+
+class UpdateROIAction(BaseModel):
+    action: Literal["update"] = "update"
+    roi_id: str = Field(alias="roiId")
+    changes: dict[str, Any]
+
+    model_config = {"populate_by_name": True}
+
+
+class ClearROIAction(BaseModel):
+    action: Literal["clear"] = "clear"
+
+
+class ListROIAction(BaseModel):
+    action: Literal["list"] = "list"
+
+
+class ListROISetsAction(BaseModel):
+    action: Literal["list_sets"] = "list_sets"
+
+
+class FindROIAtLocusAction(BaseModel):
+    action: Literal["find_at_locus"] = "find_at_locus"
+    chr: str
+    start: int
+    end: int
+
+
+class GetVisibleROIAction(BaseModel):
+    action: Literal["get_visible"] = "get_visible"
+
+
+ROIAction = (
+    AddROIAction
+    | RemoveROIAction
+    | UpdateROIAction
+    | ClearROIAction
+    | ListROIAction
+    | ListROISetsAction
+    | FindROIAtLocusAction
+    | GetVisibleROIAction
+)
+
+
+class ManageROIsArgs(BaseModel):
+    command: Literal["manage_rois"] = "manage_rois"
+    action: ROIAction
+
+
+# ── subscribe_events ──────────────────────────────────────────────────────────
+
+class SubscribeEventsArgs(BaseModel):
+    """Subscribe to browser events. Use ``["*"]`` for all events, ``[]`` to unsubscribe."""
+
+    command: Literal["subscribe_events"] = "subscribe_events"
+    events: list[str]
+
+
+# ── Union of all commands ─────────────────────────────────────────────────────
+
+CommandArgs = (
+    GetBrowserStateArgs
+    | NavigateArgs
+    | ModifyTracksArgs
+    | QueryFeaturesArgs
+    | SetLayoutArgs
+    | ExportViewArgs
+    | ManageROIsArgs
+    | SubscribeEventsArgs
+)
+
+
+# ── Command result models ─────────────────────────────────────────────────────
+
+class ModifyTrackActionResult(BaseModel):
+    action: str
+    success: bool
+    track_id: str | None = Field(None, alias="trackId")
+    tracks: list[TrackSummary] | None = None
+    count: int | None = None
+    error: str | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class ModifyTracksResult(BaseModel):
+    results: list[ModifyTrackActionResult]
+
+
+class QueryFeaturesResult(BaseModel):
+    track_id: str = Field(alias="trackId")
+    feature_count: int = Field(alias="featureCount")
+    features: list[Any] | None = None
+    summary: Any | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class SetLayoutResult(BaseModel):
+    added: list[str]
+    removed: list[str]
+    unchanged: list[str]
+
+
+# ManageROIs results — discriminated on ``action``
+
+class AddROIResult(BaseModel):
+    action: Literal["add"] = "add"
+    roi: ROI
+
+
+class RemoveROIResult(BaseModel):
+    action: Literal["remove"] = "remove"
+    success: bool
+
+
+class UpdateROIResult(BaseModel):
+    action: Literal["update"] = "update"
+    roi: ROI | None = None
+
+
+class ClearROIResult(BaseModel):
+    action: Literal["clear"] = "clear"
+
+
+class ListROIResult(BaseModel):
+    action: Literal["list"] = "list"
+    rois: list[ROI]
+
+
+class ListROISetsResult(BaseModel):
+    action: Literal["list_sets"] = "list_sets"
+    sets: list[ROISetConfig]
+
+
+class FindROIAtLocusResult(BaseModel):
+    action: Literal["find_at_locus"] = "find_at_locus"
+    rois: list[ROI]
+
+
+class GetVisibleROIResult(BaseModel):
+    action: Literal["get_visible"] = "get_visible"
+    rois: list[ROI]
+
+
+ManageROIsResult = (
+    AddROIResult
+    | RemoveROIResult
+    | UpdateROIResult
+    | ClearROIResult
+    | ListROIResult
+    | ListROISetsResult
+    | FindROIAtLocusResult
+    | GetVisibleROIResult
+)
+
+
+class SubscribeEventsResult(BaseModel):
+    subscribed: list[str]
+
+
+# ── Event data models ─────────────────────────────────────────────────────────
+
+class LocusChangeData(BaseModel):
+    locus: Locus
+
+
+class SingleTrackEventData(BaseModel):
+    """Used for: trackadded, trackremoved, dataloaded"""
+
+    track_id: str = Field(alias="trackId")
+    track_type: str = Field(alias="trackType")
+    track_name: str | None = Field(None, alias="trackName")
+
+    model_config = {"populate_by_name": True}
+
+
+class TrackOrderChangedData(BaseModel):
+    track_ids: list[str] = Field(alias="trackIds")
+
+    model_config = {"populate_by_name": True}
+
+
+class TrackErrorData(BaseModel):
+    """Used for: dataerror, rendererror"""
+
+    track_id: str = Field(alias="trackId")
+    track_type: str = Field(alias="trackType")
+    track_name: str | None = Field(None, alias="trackName")
+    error: str
+
+    model_config = {"populate_by_name": True}
+
+
+class TrackInteractionData(BaseModel):
+    """Used for: trackclick, trackhover, trackcontextmenu"""
+
+    track_id: str = Field(alias="trackId")
+    track_type: str = Field(alias="trackType")
+    track_name: str | None = Field(None, alias="trackName")
+    genomic_location: int = Field(alias="genomicLocation")
+    feature_count: int = Field(alias="featureCount")
+
+    model_config = {"populate_by_name": True}
+
+
+class ROIEventData(BaseModel):
+    """Used for: roiadded, roiremoved, roichanged"""
+
+    roi: ROI
+    set_name: str | None = Field(None, alias="setName")
+    changes: dict[str, Any] | None = None
+
+    model_config = {"populate_by_name": True}
+
+
+class ROIInteractionEventData(BaseModel):
+    """Used for: roiclick, roicontextmenu"""
+
+    roi: ROI
+    genomic_location: int = Field(alias="genomicLocation")
+    x: float
+    y: float
+
+    model_config = {"populate_by_name": True}

loom_client-0.0.1.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: loom-client
+Version: 0.0.1
+Summary: Python WebSocket client for the Loom Genome Browser
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# loom-client
+
+Python WebSocket client for the [Loom Genome Browser](https://github.com/nicholasrq/loom). Provides a fully async, typed interface for programmatically controlling a running Loom instance -- navigating loci, managing tracks and regions of interest, exporting views, and subscribing to browser events.
+
+## Installation
+
+```bash
+pip install loom-client
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/riyavsinha/loom-client.git
+cd loom-client
+pip install -e .
+```
+
+Requires Python >= 3.11.
+
+## Quick start
+
+```python
+import asyncio
+from loom_client import LoomClient
+
+async def main():
+    client = LoomClient("ws://localhost:8080")
+    await client.connect()
+
+    # Get current browser state
+    state = await client.get_browser_state()
+    print(state.locus_string)   # e.g. "chr1:1,000-2,000"
+    print(state.zoom_level)     # e.g. ZoomLevel.GENE
+
+    # Navigate to a locus
+    await client.navigate(locus="chr17:7565097-7590856")  # TP53
+
+    # Zoom out 2x
+    await client.navigate(zoom="out", factor=2.0)
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## API reference
+
+### Connection
+
+```python
+client = LoomClient(url)   # Create client
+await client.connect()     # Open WebSocket + start listener
+await client.close()       # Tear down
+```
+
+### Commands
+
+All command methods are async and return typed Pydantic models.
+
+#### `get_browser_state(record=None) -> ProjectedState`
+
+Returns the current viewport state including locus, zoom level, loaded tracks, and ROIs.
+
+```python
+state = await client.get_browser_state()
+for track in state.tracks:
+    print(f"{track.name} ({track.type})")
+```
+
+#### `navigate(locus=None, zoom=None, factor=None) -> bool`
+
+Move the viewport to a genomic locus or zoom in/out.
+
+```python
+await client.navigate(locus="chr1:1000-2000")
+await client.navigate(zoom="in", factor=3.0)
+```
+
+#### `modify_tracks(actions) -> ModifyTracksResult`
+
+Add, remove, find, or update tracks in a single batch.
+
+```python
+from loom_client import AddTrackAction, RemoveTrackAction, TrackSessionConfig, DataSourceConfig, WireTrackSelector
+
+# Add a BigWig track
+result = await client.modify_tracks([
+    AddTrackAction(config=TrackSessionConfig(
+        type="wig",
+        name="H3K27ac",
+        data_source=DataSourceConfig(
+            type="bigwig",
+            url="https://example.com/h3k27ac.bw",
+        ),
+    ))
+])
+
+# Remove by name pattern
+result = await client.modify_tracks([
+    RemoveTrackAction(selector=WireTrackSelector(name_regex="H3K.*"))
+])
+```
+
+#### `query_features(track_id, summarize=None) -> QueryFeaturesResult`
+
+Query features for a loaded track.
+
+```python
+result = await client.query_features("track-id-123", summarize=True)
+print(result.feature_count)
+```
+
+#### `set_layout(tracks, locus=None) -> SetLayoutResult`
+
+Replace the entire track layout at once.
+
+```python
+result = await client.set_layout(
+    tracks=[
+        TrackSessionConfig(type="ruler"),
+        TrackSessionConfig(type="sequence"),
+        TrackSessionConfig(
+            type="annotation",
+            name="GENCODE",
+            data_source=DataSourceConfig(type="gencode", genome="hg38"),
+        ),
+    ],
+    locus="chr1:1000-5000",
+)
+```
+
+#### `export_view(format, width=None) -> str | SessionConfig`
+
+Export the current view as SVG, PNG (returned as strings), or a session config object.
+
+```python
+svg = await client.export_view("svg", width=1200)
+session = await client.export_view("session")  # returns SessionConfig
+```
+
+#### `manage_rois(action) -> ROI result`
+
+Manage regions of interest. The action type determines the operation.
+
+```python
+from loom_client import AddROIAction, ROI, ListROIAction, FindROIAtLocusAction
+
+# Add a region of interest
+result = await client.manage_rois(AddROIAction(
+    roi=ROI(id="roi-1", chr="chr17", start=7565097, end=7590856,
+            name="TP53", color="rgba(255,0,0,0.3)"),
+    set_name="Genes of interest",
+))
+
+# List all ROIs
+result = await client.manage_rois(ListROIAction())
+
+# Find ROIs overlapping a locus
+result = await client.manage_rois(
+    FindROIAtLocusAction(chr="chr17", start=7500000, end=7600000)
+)
+```
+
+#### `subscribe_events(events) -> SubscribeEventsResult`
+
+Subscribe to server-pushed events. Use `["*"]` for all events or `[]` to unsubscribe.
+
+```python
+await client.subscribe_events(["locuschange", "trackadded", "dataloaded"])
+```
+
+### Event handling
+
+Register callbacks for browser events:
+
+```python
+def on_locus_change(data):
+    locus = data["locus"]
+    print(f"Moved to {locus['chr']}:{locus['start']}-{locus['end']}")
+
+client.on("locuschange", on_locus_change)
+
+# Wildcard handler receives (event_name, data)
+client.on("*", lambda name, data: print(f"Event: {name}"))
+
+# Unregister
+client.off("locuschange", on_locus_change)
+```
+
+**Available events:** `locuschange`, `trackadded`, `trackremoved`, `dataloaded`, `dataerror`, `rendererror`, `trackclick`, `trackhover`, `trackcontextmenu`, `trackorderchanged`, `roiadded`, `roiremoved`, `roichanged`, `roiclick`, `roicontextmenu`
+
+### Error handling
+
+Server errors raise `CommandException`:
+
+```python
+from loom_client import CommandException
+
+try:
+    await client.navigate(locus="invalid")
+except CommandException as e:
+    print(e.code, e.message)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

loom_client-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+loom_client/__init__.py,sha256=uJTC_QMv7UiznSFdS4k5KT0WloBYX-CxYetBiEQs8hY,3330
+loom_client/client.py,sha256=INP8FMcj7F9cTwXFRtRR-PF-nF95dR2n_jlURLMp8cg,6807
+loom_client/exceptions.py,sha256=ArcoUrn1dTG-iYFYa6gfhJk2ZZHdnufjuUZ99f0WSGk,294
+loom_client/models.py,sha256=5Kqt-97ClFOVgitdPG8l901Wn1lZaNUHn3wlEmVGumM,14774
+loom_client-0.0.1.dist-info/METADATA,sha256=h5hyR6J3NQOsqLfn_bYTDhWdnMEFv_Qtti8aRYN7SSE,5673
+loom_client-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+loom_client-0.0.1.dist-info/top_level.txt,sha256=CDXwXEAiCy3zLc_Rsk69qCErhtdh5_BmXRUOEVX2D-g,12
+loom_client-0.0.1.dist-info/RECORD,,

loom_client-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

loom_client-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+loom_client