expt-logger 0.1.0.dev0__py3-none-any.whl

expt_logger/__init__.py

@@ -0,0 +1,205 @@
+"""
+expt_logger - Simple experiment tracking library.
+
+Usage:
+    import expt_logger
+
+    run = expt_logger.init(name="experiment-1")
+
+    for step in range(100):
+        expt_logger.log({"train/loss": 0.5, "train/accuracy": 0.9})
+
+    expt_logger.end()
+
+Or with context manager:
+    with expt_logger.init(name="my-experiment") as run:
+        expt_logger.log({"loss": 0.5})
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .client import APIError, Client
+from .config import DEFAULT_BASE_URL
+from .run import Run
+from .types import Config, Message, Reward, Rollout, Scalar
+from .utils import parse_conversation
+
+__version__ = "0.1.0"
+__all__ = [
+    # Main API
+    "init",
+    "log",
+    "log_rollout",
+    "flush",
+    "end",
+    # Global state
+    "run",
+    "config",
+    # Classes
+    "Run",
+    "Config",
+    "Client",
+    "APIError",
+    # Types
+    "Scalar",
+    "Rollout",
+    "Message",
+    "Reward",
+    # Utils
+    "parse_conversation",
+]
+
+# Global run instance
+_current_run: Run | None = None
+
+
+def init(
+    name: str | None = None,
+    config: dict[str, Any] | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Run:
+    """
+    Initialize a new experiment run.
+
+    Args:
+        name: Experiment name. Auto-generated if not provided.
+        config: Initial configuration dictionary.
+        api_key: API key. Falls back to EXPT_LOGGER_API_KEY environment variable.
+        base_url: API server URL.
+                  Falls back to EXPT_LOGGER_BASE_URL env var or configured default.
+
+    Returns:
+        Run instance (also accessible via expt_logger.run).
+
+    Example:
+        run = expt_logger.init(
+            name="my-experiment",
+            config={"lr": 0.001, "batch_size": 32}
+        )
+    """
+    global _current_run
+
+    # Finish any existing run
+    if _current_run is not None:
+        _current_run.end()
+
+    # Resolve API key
+    resolved_api_key = api_key or os.environ.get("EXPT_LOGGER_API_KEY")
+    if not resolved_api_key:
+        raise ValueError("API key required. Pass api_key or set EXPT_LOGGER_API_KEY env variable.")
+
+    # Resolve base URL
+    resolved_base_url = base_url or os.environ.get("EXPT_LOGGER_BASE_URL", DEFAULT_BASE_URL)
+
+    _current_run = Run(
+        name=name,
+        config=config,
+        api_key=resolved_api_key,
+        base_url=resolved_base_url,
+    )
+
+    return _current_run
+
+
+def _get_run() -> Run:
+    """Get the current run, raising if not initialized."""
+    if _current_run is None:
+        raise RuntimeError("No active run. Call expt_logger.init() first.")
+    return _current_run
+
+
+def run() -> Run | None:
+    """Get the current active run."""
+    return _current_run
+
+
+def config() -> Config:
+    """Get the current run's config."""
+    return _get_run().config
+
+
+def log(
+    metrics: dict[str, float],
+    step: int | None = None,
+    mode: str | None = None,
+    commit: bool = True,
+) -> None:
+    """
+    Log scalar metrics to the current run.
+
+    Args:
+        metrics: Dictionary of metric names to values.
+                 Use slash prefix for mode: "train/loss", "eval/accuracy"
+        step: Step number. Auto-increments if not provided.
+        mode: Default mode for metrics without slash prefix.
+        commit: If False, buffer metrics until next commit=True call.
+
+    Example:
+        expt_logger.log({"loss": 0.5, "accuracy": 0.9})
+        expt_logger.log({"train/loss": 0.5, "eval/loss": 0.6}, step=10)
+
+        # Multiple metrics at same step
+        expt_logger.log({"train/loss": 0.5}, commit=False)
+        expt_logger.log({"train/acc": 0.9})  # commits both
+    """
+    _get_run().log(metrics, step=step, mode=mode, commit=commit)
+
+
+def log_rollout(
+    prompt: str,
+    messages: list[dict[str, str]] | str,
+    rewards: dict[str, float] | list[dict[str, float | str]],
+    step: int | None = None,
+    mode: str = "train",
+) -> None:
+    """
+    Log a conversation rollout to the current run.
+
+    Args:
+        prompt: The prompt text.
+        messages: Either a list of message dicts [{"role": "...", "content": "..."}]
+                  or a string that will be parsed into messages.
+        rewards: Either a dict {"reward_name": value} or list [{"name": ..., "value": ...}]
+        step: Step number. Uses current step if not provided.
+        mode: "train" or "eval".
+
+    Example:
+        expt_logger.log_rollout(
+            prompt="What is 2+2?",
+            messages=[
+                {"role": "assistant", "content": "2+2 equals 4."},
+                {"role": "user", "content": "Thanks!"},
+            ],
+            rewards={"correctness": 1.0, "clarity": 0.9},
+        )
+
+        # Or with string parsing:
+        expt_logger.log_rollout(
+            prompt="Explain gravity",
+            messages="Assistant: Gravity is a force...\\nUser: Can you elaborate?",
+            rewards={"quality": 0.8},
+        )
+    """
+    _get_run().log_rollout(prompt, messages, rewards, step=step, mode=mode)
+
+
+def flush() -> None:
+    """Manually flush buffered data to the server."""
+    _get_run().flush()
+
+
+def end() -> None:
+    """
+    Finish the current run.
+
+    This is called automatically on program exit, but can be called
+    explicitly to end a run early.
+    """
+    global _current_run
+    if _current_run is not None:
+        _current_run.end()
+        _current_run = None

expt_logger/client.py

@@ -0,0 +1,207 @@
+"""HTTP client for the experiment tracking API."""
+
+import logging
+from typing import Any, cast
+
+import httpx
+
+from .types import Rollout, Scalar
+
+logger = logging.getLogger(__name__)
+
+
+class APIError(Exception):
+    """Raised when an API request fails."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class Client:
+    """HTTP client for the experiment tracking API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: int = 30,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+        headers = {"Content-Type": "application/json"}
+        if api_key:
+            headers["x-api-key"] = api_key
+
+        self._client = httpx.Client(headers=headers, timeout=timeout)
+
+    def create_experiment(
+        self, name: str | None = None, config: dict[str, Any] | None = None
+    ) -> str:
+        """
+        Create a new experiment.
+
+        Args:
+            name: Experiment name. If not provided, a random name is generated on the server.
+            config: Initial experiment configuration.
+
+        Returns the experiment ID.
+        """
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if config is not None:
+            payload["config"] = config
+
+        response = self._request("POST", "/api/experiments", json=payload)
+        return cast(str, response["experimentId"])
+
+    def log_scalars(self, experiment_id: str, scalars: list[Scalar]) -> dict[str, Any]:
+        """Log scalar metrics for an experiment (non-blocking)."""
+        payload = {
+            "scalars": [
+                {
+                    "step": s.step,
+                    "mode": s.mode,
+                    "type": s.type,
+                    "value": s.value,
+                }
+                for s in scalars
+            ]
+        }
+        return self._request(
+            "POST",
+            f"/api/experiments/{experiment_id}/scalars",
+            json=payload,
+            fire_and_forget=True,
+        )
+
+    def log_rollouts(self, experiment_id: str, rollouts: list[Rollout]) -> dict[str, Any]:
+        """Log rollouts for an experiment (non-blocking)."""
+        payload = {
+            "rollouts": [
+                {
+                    "step": r.step,
+                    "mode": r.mode,
+                    "promptText": r.prompt_text,
+                    "messages": [{"role": m.role, "content": m.content} for m in r.messages],
+                    "rewards": [{"name": rw.name, "value": rw.value} for rw in r.rewards],
+                }
+                for r in rollouts
+            ]
+        }
+        return self._request(
+            "POST",
+            f"/api/experiments/{experiment_id}/rollouts",
+            json=payload,
+            fire_and_forget=True,
+        )
+
+    def update_experiment(
+        self,
+        experiment_id: str,
+        name: str | None = None,
+        config: dict[str, Any] | None = None,
+        status: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Update an experiment's name, config, and/or status.
+
+        Args:
+            experiment_id: The experiment ID.
+            name: New experiment name (optional).
+            config: New experiment configuration (optional).
+            status: New experiment status (optional).
+
+        Returns:
+            Response with success status.
+        """
+        if name is None and config is None and status is None:
+            raise ValueError("At least one of name, config, or status must be provided")
+
+        payload: dict[str, Any] = {"id": experiment_id}
+        if name is not None:
+            payload["name"] = name
+        if config is not None:
+            payload["config"] = config
+        if status is not None:
+            payload["status"] = status
+
+        return self._request("PUT", "/api/experiments", json=payload)
+
+    def log_config(self, experiment_id: str, config: dict[str, Any]) -> dict[str, Any]:
+        """Log configuration for an experiment."""
+        return self.update_experiment(experiment_id, config=config)
+
+    def end_experiment(self, experiment_id: str) -> dict[str, Any]:
+        """Mark an experiment as finished."""
+        return self.update_experiment(experiment_id, status="complete")
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        fire_and_forget: bool = False,
+    ) -> dict[str, Any]:
+        """
+        Make an HTTP request to the API.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: API path
+            json: JSON payload
+            fire_and_forget: If True, send request without waiting for response.
+                           Used for logging operations to avoid blocking.
+        """
+        url = f"{self.base_url}{path}"
+
+        try:
+            if fire_and_forget:
+                # Fire and forget - don't wait for response
+                # This makes logging operations non-blocking
+                response = self._client.post(url, json=json)
+                # Log errors but don't raise them
+                if not response.is_success:
+                    try:
+                        error_data = response.json()
+                        error_msg = error_data.get("error", response.text)
+                    except ValueError:
+                        error_msg = response.text
+                    logger.warning(
+                        f"Fire-and-forget request failed: {method} {path} "
+                        f"returned {response.status_code}: {error_msg}"
+                    )
+                return {}
+
+            response = self._client.request(
+                method=method,
+                url=url,
+                json=json,
+            )
+        except httpx.RequestError as e:
+            if fire_and_forget:
+                # Silently fail for fire-and-forget requests
+                logger.warning(f"Fire-and-forget request exception: {method} {path} - {e}")
+                return {}
+            raise APIError(f"Request failed: {e}") from e
+
+        if not response.is_success:
+            try:
+                error_data = response.json()
+                message = error_data.get("error", response.text)
+            except ValueError:
+                message = response.text
+            raise APIError(message, status_code=response.status_code)
+
+        # Handle empty responses
+        if not response.text:
+            return {}
+
+        return cast(dict[str, Any], response.json())
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()

expt_logger/config.py

@@ -0,0 +1,5 @@
+"""Central configuration for expt_logger."""
+
+# Default API base URL
+# Change this value to switch to production endpoint
+DEFAULT_BASE_URL = "https://expt-platform.vercel.app/"

expt_logger/run.py

@@ -0,0 +1,317 @@
+"""Run class for experiment tracking."""
+
+from __future__ import annotations
+
+import atexit
+import signal
+import sys
+import threading
+from typing import Any
+
+from .client import Client
+from .config import DEFAULT_BASE_URL
+from .types import Config, Message, Reward, Rollout, Scalar
+from .utils import parse_conversation, parse_metric_key
+
+
+class Run:
+    """
+    A single experiment run.
+
+    Tracks metrics, rollouts, and configuration for an experiment.
+    Handles automatic cleanup on exit or interrupt.
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        config: dict[str, Any] | None = None,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ):
+        self.name = name  # May be None initially; set after server response
+        self.config = Config()
+
+        if config:
+            self.config.update(config)
+
+        # Internal state
+        self._client = Client(base_url=base_url, api_key=api_key)
+        self._base_url = base_url
+        self._experiment_id: str | None = None
+        self._current_step = 1
+        self._scalar_buffer: list[Scalar] = []
+        self._rollout_buffer: list[Rollout] = []
+        self._lock = threading.Lock()
+        self._finished = False
+
+        # Track pending metrics for commit=False behavior
+        self._pending_metrics: dict[str, float] = {}
+        self._pending_step: int | None = None
+        self._pending_mode: str | None = None
+
+        # Create experiment on server
+        self._init_experiment()
+
+        # Setup exit handlers
+        self._setup_exit_handlers()
+
+    def _init_experiment(self) -> None:
+        """Create the experiment on the server."""
+        # Pass both name and config to the server
+        # If name is None, server will generate a random one
+        config_dict = self.config.to_dict() if self.config.to_dict() else None
+        self._experiment_id = self._client.create_experiment(self.name, config_dict)
+
+    def _setup_exit_handlers(self) -> None:
+        """Register cleanup handlers for graceful shutdown."""
+        atexit.register(self._cleanup)
+
+        # Store original signal handlers
+        self._original_handlers: dict[signal.Signals, Any] = {}
+
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            self._original_handlers[sig] = signal.getsignal(sig)
+            signal.signal(sig, self._signal_handler)
+
+    def _signal_handler(self, signum: int, frame: Any) -> None:
+        """Handle interrupt signals."""
+        self._cleanup()
+
+        # Restore original handler and re-raise
+        sig = signal.Signals(signum)
+        original = self._original_handlers.get(sig)
+        signal.signal(sig, original or signal.SIG_DFL)
+
+        if signum == signal.SIGINT:
+            raise KeyboardInterrupt
+        else:
+            sys.exit(128 + signum)
+
+    def _cleanup(self) -> None:
+        """Flush buffers and mark experiment as finished."""
+        with self._lock:
+            if self._finished:
+                return
+            self._finished = True
+
+        # Commit any pending metrics
+        self._commit_pending()
+
+        # Flush remaining data
+        self.flush()
+
+        # Mark as finished on server
+        if self._experiment_id:
+            try:
+                self._client.end_experiment(self._experiment_id)
+            except Exception:
+                pass  # Best effort
+
+        # Cleanup
+        self._client.close()
+
+        # Unregister atexit
+        try:
+            atexit.unregister(self._cleanup)
+        except Exception:
+            pass
+
+    def log(
+        self,
+        metrics: dict[str, float],
+        step: int | None = None,
+        mode: str | None = None,
+        commit: bool = True,
+    ) -> None:
+        """
+        Log scalar metrics.
+
+        Args:
+            metrics: Dictionary of metric names to values.
+                     Use slash prefix for mode: "train/loss", "eval/accuracy"
+            step: Step number. Auto-increments if not provided.
+            mode: Default mode for metrics without slash prefix.
+                  If not specified, defaults to "train".
+            commit: If False, buffer metrics until next commit=True call.
+                    Useful for logging multiple metrics at the same step.
+
+        Note:
+            If mode is specified, all metrics should either have slash prefixes
+            or none should have slash prefixes. Mixing both styles is not recommended
+            as it may lead to unexpected behavior.
+        """
+        if self._finished:
+            return
+
+        # Check for conflicting usage: mode param with slash-prefixed keys
+        has_slash_keys = any("/" in key for key in metrics.keys())
+        if mode is not None and has_slash_keys:
+            raise ValueError(
+                "Cannot specify 'mode' parameter when metric keys contain slashes. "
+                "Either use slash-prefixed keys like 'train/loss' OR use the mode "
+                "parameter, not both."
+            )
+
+        # Determine step
+        if step is None:
+            if self._pending_step is not None:
+                step = self._pending_step
+            else:
+                step = self._current_step
+
+        default_mode = mode or self._pending_mode or "train"
+
+        # Accumulate metrics
+        for key, value in metrics.items():
+            parsed_mode, metric_name = parse_metric_key(key)
+            # Use parsed mode from key, or fall back to default
+            final_mode = parsed_mode if "/" in key else default_mode
+            self._pending_metrics[f"{final_mode}/{metric_name}"] = value
+
+        self._pending_step = step
+        self._pending_mode = default_mode
+
+        if commit:
+            self._commit_pending()
+
+    def _commit_pending(self) -> None:
+        """Commit all pending metrics to the buffer."""
+        if not self._pending_metrics or self._pending_step is None:
+            return
+
+        with self._lock:
+            for key, value in self._pending_metrics.items():
+                mode, metric_name = parse_metric_key(key)
+                self._scalar_buffer.append(
+                    Scalar(
+                        step=self._pending_step,
+                        mode=mode,
+                        type=metric_name,
+                        value=value,
+                    )
+                )
+
+            # Auto-increment step for next log call
+            self._current_step = self._pending_step + 1
+
+        # Clear pending state
+        self._pending_metrics = {}
+        self._pending_step = None
+        self._pending_mode = None
+
+    def log_rollout(
+        self,
+        prompt: str,
+        messages: list[dict[str, str]] | str,
+        rewards: dict[str, float] | list[dict[str, float | str]],
+        step: int | None = None,
+        mode: str = "train",
+    ) -> None:
+        """
+        Log a conversation rollout.
+
+        Args:
+            prompt: The prompt text.
+            messages: Either a list of message dicts [{"role": "...", "content": "..."}]
+                      or a string that will be parsed into messages.
+            rewards: Either a dict {"reward_name": value} or list [{"name": ..., "value": ...}]
+            step: Step number. Uses current step if not provided.
+            mode: "train" or "eval".
+        """
+        if self._finished:
+            return
+
+        if step is None:
+            step = self._current_step
+
+        # Parse messages if string
+        if isinstance(messages, str):
+            parsed = parse_conversation(messages)
+        else:
+            parsed = messages
+
+        # Convert to Message objects
+        message_objs = [Message(role=m["role"], content=m["content"]) for m in parsed]
+
+        # Parse rewards
+        if isinstance(rewards, dict):
+            reward_objs = [Reward(name=k, value=v) for k, v in rewards.items()]
+        else:
+            reward_objs = [Reward(name=str(r["name"]), value=float(r["value"])) for r in rewards]
+
+        with self._lock:
+            self._rollout_buffer.append(
+                Rollout(
+                    step=step,
+                    mode=mode,
+                    prompt_text=prompt,
+                    messages=message_objs,
+                    rewards=reward_objs,
+                )
+            )
+
+    def flush(self) -> None:
+        """Send all buffered data to the server."""
+        if self._experiment_id is None:
+            return
+
+        # Commit any pending metrics first
+        self._commit_pending()
+
+        with self._lock:
+            scalars = self._scalar_buffer.copy()
+            rollouts = self._rollout_buffer.copy()
+            self._scalar_buffer.clear()
+            self._rollout_buffer.clear()
+
+        # Send to server
+        if scalars:
+            try:
+                self._client.log_scalars(self._experiment_id, scalars)
+            except Exception as e:
+                print(f"Warning: Failed to log scalars: {e}")
+
+        if rollouts:
+            try:
+                self._client.log_rollouts(self._experiment_id, rollouts)
+            except Exception as e:
+                print(f"Warning: Failed to log rollouts: {e}")
+
+    def end(self) -> None:
+        """Explicitly finish the run."""
+        self._cleanup()
+
+    @property
+    def id(self) -> str | None:
+        """Return the experiment ID."""
+        return self._experiment_id
+
+    @property
+    def step(self) -> int:
+        """Return the current step."""
+        return self._current_step
+
+    @property
+    def base_url(self) -> str:
+        """Return the base URL of the experiment tracking server."""
+        return self._base_url
+
+    @property
+    def experiment_url(self) -> str | None:
+        """Return the full URL to view this experiment in the web interface."""
+        if self._experiment_id is None:
+            return None
+        # Remove /api prefix if present and construct experiment URL
+        base = self._base_url.rstrip("/")
+        return f"{base}/experiments/{self._experiment_id}"
+
+    def __enter__(self) -> Run:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.end()
+        # Don't suppress exceptions
+
+    def __repr__(self) -> str:
+        return f"Run(name={self.name!r}, id={self._experiment_id!r}, step={self._current_step})"

expt_logger/types.py

@@ -0,0 +1,90 @@
+"""Type definitions for the expt_logger library."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Message:
+    """A single message in a conversation."""
+
+    role: str  # "user", "assistant", "system"
+    content: str
+
+
+@dataclass
+class Reward:
+    """A named reward value."""
+
+    name: str
+    value: float
+
+
+@dataclass
+class Scalar:
+    """A scalar metric logged at a specific step."""
+
+    step: int
+    mode: str
+    type: str  # metric name
+    value: float
+
+
+@dataclass
+class Rollout:
+    """A conversation rollout with rewards."""
+
+    step: int
+    mode: str
+    prompt_text: str
+    messages: list[Message]
+    rewards: list[Reward]
+
+
+@dataclass
+class Config:
+    """
+    Experiment configuration that supports both dict-style and attribute-style access.
+
+    Usage:
+        config = Config()
+        config.learning_rate = 0.001
+        config["batch_size"] = 32
+        config.update({"epochs": 10})
+    """
+
+    _data: dict[str, Any] = field(default_factory=dict)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name == "_data":
+            object.__setattr__(self, name, value)
+        else:
+            self._data[name] = value
+
+    def __getattr__(self, name: str) -> Any:
+        if name == "_data":
+            return object.__getattribute__(self, name)
+        try:
+            return self._data[name]
+        except KeyError:
+            raise AttributeError(f"Config has no attribute '{name}'")
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._data[key] = value
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def update(self, data: dict[str, Any]) -> None:
+        """Update config with a dictionary of values."""
+        self._data.update(data)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return config as a plain dictionary."""
+        return self._data.copy()
+
+    def __repr__(self) -> str:
+        return f"Config({self._data})"

expt_logger/utils.py

@@ -0,0 +1,49 @@
+"""Utility functions for the expt_logger library."""
+
+import os
+from typing import TypeVar
+
+
+def get_env_var(name: str, default: str | None = None) -> str | None:
+    """Get environment variable with optional default."""
+    return os.environ.get(name, default)
+
+
+def parse_metric_key(key: str) -> tuple[str, str]:
+    """
+    Parse a metric key into (mode, metric_name).
+
+    Examples:
+        "train/loss" -> ("train", "loss")
+        "eval/accuracy" -> ("eval", "accuracy")
+        "loss" -> ("train", "loss")  # default mode
+    """
+    if "/" in key:
+        parts = key.split("/", 1)
+        return parts[0], parts[1]
+    return "train", key
+
+
+def parse_conversation(text: str) -> list[dict[str, str]]:
+    """
+    Parse a conversation string into a list of messages.
+
+    TODO: Implement parsing logic for different conversation formats:
+        - "User: hello\nAssistant: hi there"
+        - "Human: hello\nAssistant: hi there"
+        - "<user>hello</user><assistant>hi</assistant>"
+
+    Returns list of {"role": "user"|"assistant", "content": "..."}
+    """
+    raise NotImplementedError(
+        "Conversation parsing from raw text is not yet implemented. "
+        "Please pass messages as a list of dicts with 'role' and 'content' keys."
+    )
+
+
+T = TypeVar("T")
+
+
+def chunk_list(lst: list[T], chunk_size: int) -> list[list[T]]:
+    """Split a list into chunks of specified size."""
+    return [lst[i : i + chunk_size] for i in range(0, len(lst), chunk_size)]

expt_logger-0.1.0.dev0.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: expt-logger
+Version: 0.1.0.dev0
+Summary: Simple experiment logging library
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# expt_logger
+
+Simple experiment tracking for RL training with a W&B-style API.
+
+## Quick Start
+
+**Install:**
+```bash
+uv add expt-logger
+# or
+pip install expt-logger
+```
+
+**Set your API key:**
+```bash
+export EXPT_LOGGER_API_KEY=your_api_key
+```
+
+**Start logging:**
+```python
+import expt_logger
+
+# Initialize run with config
+run = expt_logger.init(
+    name="grpo-math",
+    config={"lr": 3e-6, "batch_size": 8}
+)
+
+# Get experiment URLs
+print(f"View experiment: {run.experiment_url}")
+print(f"Base URL: {run.base_url}")
+
+# Log RL rollouts with rewards
+expt_logger.log_rollout(
+    prompt="What is 2+2?",
+    messages=[{"role": "assistant", "content": "The answer is 4."}],
+    rewards={"correctness": 1.0, "format": 0.9},
+    mode="train"
+)
+
+# Log scalar metrics
+expt_logger.log({
+    "train/loss": 0.45,
+    "train/kl": 0.02,
+    "train/reward": 0.85
+})
+
+expt_logger.end()
+```
+
+## Core Features
+
+### Scalar Metrics
+
+Log training metrics with automatic step tracking:
+
+```python
+# Auto-increment steps (defaults to "train" mode)
+expt_logger.log({"loss": 0.5})      # step 0, train/loss
+expt_logger.log({"loss": 0.4})      # step 1, train/loss
+
+# Use slash prefixes for train/eval modes
+expt_logger.log({
+    "train/loss": 0.5,
+    "eval/loss": 0.6
+}, step=10)
+
+# Or set mode explicitly
+expt_logger.log({"loss": 0.5}, mode="eval")
+```
+
+**Note:** Metrics default to `"train"` mode when no mode is specified and keys don't have slash prefixes.
+
+**Batching metrics** at the same step:
+```python
+expt_logger.log({"metric_a": 1.0}, commit=False)
+expt_logger.log({"metric_b": 2.0}, commit=False)
+expt_logger.log({"metric_c": 3.0})  # commits all three at step 0
+```
+
+### Rollouts (RL-specific)
+
+Log conversation rollouts with multiple reward functions:
+
+```python
+expt_logger.log_rollout(
+    prompt="Solve: x^2 - 5x + 6 = 0",
+    messages=[
+        {"role": "assistant", "content": "Let me factor this..."},
+        {"role": "user", "content": "Can you verify?"},
+        {"role": "assistant", "content": "Sure! (x-2)(x-3) = 0..."}
+    ],
+    rewards={
+        "correctness": 1.0,
+        "format": 0.9,
+        "helpfulness": 0.85
+    },
+    step=5,
+    mode="train"
+)
+```
+
+- **Messages format:** List of dicts with `"role"` and `"content"` keys
+- **Rewards format:** Dict of reward names to float values
+- **Mode:** `"train"` or `"eval"` (default: `"train"`)
+
+### Configuration
+
+Track hyperparameters and update them dynamically:
+
+```python
+run = expt_logger.init(config={"lr": 0.001, "batch_size": 32})
+
+# Update config during training
+run.config.lr = 0.0005              # attribute style
+run.config["epochs"] = 100          # dict style
+run.config.update({"model": "gpt2"}) # bulk update
+```
+
+### API Key & Server Configuration
+
+**API Key** (required):
+```bash
+export EXPT_LOGGER_API_KEY=your_api_key
+```
+Or pass directly:
+```python
+expt_logger.init(api_key="your_key")
+```
+
+**Custom server URL** (optional, for self-hosting):
+```bash
+export EXPT_LOGGER_BASE_URL=https://your-server.com
+```
+Or:
+```python
+expt_logger.init(base_url="https://your-server.com")
+```
+
+### Accessing Experiment URLs
+
+Get the experiment URL and base URL from the run object:
+
+```python
+run = expt_logger.init(name="my-experiment")
+
+# Get the full experiment URL to view in browser
+print(run.experiment_url)
+# https://expt-platform.vercel.app/experiments/ccf1f879-50a6-492b-9072-fed6effac731
+
+# Get the base URL of the tracking server
+print(run.base_url)
+# https://expt-platform.vercel.app
+```
+
+## API Reference
+
+### `expt_logger.init()`
+
+```python
+init(
+    name: str | None = None,
+    config: dict[str, Any] | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None
+) -> Run
+```
+
+- `name`: Experiment name (auto-generated if not provided)
+- `config`: Initial hyperparameters
+- `api_key`: API key (or set `EXPT_LOGGER_API_KEY`)
+- `base_url`: Custom server URL (or set `EXPT_LOGGER_BASE_URL`)
+
+### `expt_logger.log()`
+
+```python
+log(
+    metrics: dict[str, float],
+    step: int | None = None,
+    mode: str | None = None,
+    commit: bool = True
+)
+```
+
+- `metrics`: Dict of metric names to values
+- `step`: Step number (auto-increments if not provided)
+- `mode`: Default mode for keys without slashes (default: `"train"`)
+- `commit`: If `False`, buffer metrics until next `commit=True`
+
+### `expt_logger.log_rollout()`
+
+```python
+log_rollout(
+    prompt: str,
+    messages: list[dict[str, str]],
+    rewards: dict[str, float],
+    step: int | None = None,
+    mode: str = "train"
+)
+```
+
+- `prompt`: The prompt text
+- `messages`: List of `{"role": ..., "content": ...}` dicts
+- `rewards`: Dict of reward names to values
+- `step`: Step number (uses current step if not provided)
+- `mode`: `"train"` or `"eval"`
+
+### `expt_logger.flush()` / `expt_logger.end()`
+
+- `flush()`: Manually send buffered data to server
+- `end()`: Finish the run (called automatically on exit)
+
+## Advanced
+
+### Context Manager
+
+Ensures automatic cleanup:
+
+```python
+with expt_logger.init(name="my-run") as run:
+    expt_logger.log({"loss": 0.5})
+# end() called automatically
+```
+
+### Graceful Shutdown
+
+The library handles cleanup on:
+- Normal exit (`atexit`)
+- Ctrl+C (`SIGINT`)
+- `SIGTERM`
+
+All buffered data is flushed before exit.
+
+## Development
+
+For local development, see [DEVELOPMENT.md](DEVELOPMENT.md).
+
+Run the demo:
+
+```bash
+python demo.py          # GRPO-style training simulation
+python demo.py commit   # Batching demo
+python demo.py messages # Structured messages demo
+```

expt_logger-0.1.0.dev0.dist-info/RECORD

@@ -0,0 +1,9 @@
+expt_logger/__init__.py,sha256=co2y2fVem9QlwcsE1IlrjbuykW0APpyxPllQpu1rSDk,5360
+expt_logger/client.py,sha256=SQIpVO0GWN3E51w5bHfvT7OhB5Vm1AdPB3sNZrNNt48,6771
+expt_logger/config.py,sha256=mImXM-cdiksBzCSVMortUXChYXn5Zx_kWLaL-CYQJbA,177
+expt_logger/run.py,sha256=OjtibIs9nCI-qtGfc3WYeRLwzf8zogDwNxqJhdGb8ls,10270
+expt_logger/types.py,sha256=RrVi935U7Q5kBBbY1XcrBBT_Kl03gDhbiegSUxU0y7U,2061
+expt_logger/utils.py,sha256=a9IsjzUSClNl2lxCp30xyi5eYC0K8LFcu3ohX7a7qyE,1473
+expt_logger-0.1.0.dev0.dist-info/METADATA,sha256=QojqT89iufcQwAE2DJML388bUiqKYplJC-VY-6-Vshg,5656
+expt_logger-0.1.0.dev0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+expt_logger-0.1.0.dev0.dist-info/RECORD,,

expt_logger-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any