hse-sampletracker-client 0.1.1__py3-none-any.whl

hse_sampletracker_client-0.1.1.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: hse-sampletracker-client
+Version: 0.1.1
+Summary: A Pythonic client library for the SampleTracker SaaS API
+Project-URL: Documentation, https://github.com/Alexander Schramm/sampletracker#readme
+Project-URL: Issues, https://github.com/Alexander Schramm/sampletracker/issues
+Project-URL: Source, https://github.com/Alexander Schramm/sampletracker
+Author-email: Alexander Schramm <info@expectiq.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: api,client,hse,laboratory,samples,sampletracker
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Description-Content-Type: text/markdown
+
+# HSE SampleTracker Client
+
+[![PyPI - Version](https://img.shields.io/pypi/v/hse-sampletracker-client.svg)](https://pypi.org/project/hse-sampletracker-client)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hse-sampletracker-client.svg)](https://pypi.org/project/hse-sampletracker-client)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+A Pythonic client library for the HSE SampleTracker API - manage laboratory samples, processing steps, and observations with ease.
+
+## Features
+
+- **Synchronous API Client** - Simple, blocking HTTP client using `httpx`
+- **Type Hints Throughout** - Fully typed for better IDE support and code safety
+- **Command-Line Interface** - Interactive CLI for quick sample management
+- **Pydantic-like Models** - Dataclass-based models with `from_dict` constructors
+- **Comprehensive Exceptions** - Clear error hierarchy for different failure modes
+- **Environment Configuration** - Support for `.env` files and environment variables
+- **Pagination Support** - Built-in cursor-based pagination for listing samples
+
+## Installation
+
+```console
+pip install hse-sampletracker-client
+```
+
+## Quick Start
+
+### Using the Python API
+
+```python
+from sampletracker import SampleTrackerClient
+
+# Create a client
+client = SampleTrackerClient(
+    api_key="your-api-key",
+    base_url="https://your-instance.com/api/v1"
+)
+
+# List samples
+samples = client.list_samples(limit=10)
+for sample in samples:
+    print(f"{sample.sample_id}: {sample.name}")
+
+# Get detailed sample information
+sample = client.load_sample("SAMPLE-123")
+print(f"Description: {sample.description}")
+print(f"Steps: {sample.stats.step_count}")
+print(f"Observations: {sample.stats.observation_count}")
+
+# View history
+for event in sample.history:
+    if hasattr(event, 'name'):  # StepEvent
+        print(f"Step: {event.name}")
+    else:  # ObservationEvent
+        print(f"Observation: {event.content}")
+```
+
+### Using the CLI
+
+Set up your environment:
+
+```bash
+# Option 1: Environment variables
+export SAMPLETRACKER_API_KEY="your-api-key"
+export SAMPLETRACKER_BASE_URL="https://your-instance.com/api/v1"
+
+# Option 2: Create a .env file
+echo "SAMPLETRACKER_API_KEY=your-api-key" > .env
+echo "SAMPLETRACKER_BASE_URL=https://your-instance.com/api/v1" >> .env
+```
+
+List samples:
+
+```console
+$ sampletracker list --limit 5
+    ID |       Sample ID |                           Name | Steps | Observations
+--------------------------------------------------------------------------------
+     1 |      sample-001 |                     test batch |     3 |            2
+     2 |        M315SO23 |              test batch (Copy) |     3 |            2
+```
+
+View sample details:
+
+```console
+$ sampletracker view sample-001
+Sample Details:
+  ID:          1
+  Sample ID:   sample-001
+  Name:        test batch
+  Description: mein erster test
+  Owner ID:    2
+  Owner Email: admin@example.com
+  Created:     2026-04-25 13:14:13.126000+00:00
+  Updated:     2026-04-25 13:14:13.126000+00:00
+  Steps:       2
+  Observations: 2
+
+  History:
+    [Step] Backen
+      Performed: 2026-04-25 13:20:00+00:00
+      Parameters:
+        - Temperatur: 210 °C
+    [Observation] Das Ding ist heiß
+      Created: 2026-04-25 13:21:06.172000+00:00
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `SAMPLETRACKER_API_KEY` | Your API key | Yes |
+| `SAMPLETRACKER_BASE_URL` | API base URL | No (defaults to official SaaS) |
+
+### .env File
+
+Create a `.env` file in your project root:
+
+```
+SAMPLETRACKER_API_KEY=your-api-key
+SAMPLETRACKER_BASE_URL=https://your-instance.com/api/v1
+```
+
+The CLI automatically loads variables from `.env` files in the current or parent directories.
+
+## API Reference
+
+### SampleTrackerClient
+
+The main client class for interacting with the API.
+
+```python
+client = SampleTrackerClient(
+    api_key: str,           # Your API key
+    base_url: str | None,   # Optional base URL
+    timeout: float | None   # Optional timeout (default: 30s)
+)
+```
+
+### Methods
+
+#### `list_samples(limit: int = 10, after_id: int | None = None) -> list[SampleListItem]`
+
+List samples with pagination support.
+
+- `limit`: Number of samples to return (max: 100)
+- `after_id`: Cursor for pagination (returns samples with ID > after_id)
+
+#### `load_sample(sample_id: str) -> Sample | None`
+
+Get detailed information about a specific sample, including history.
+
+Returns `None` if the sample doesn't exist.
+
+### Models
+
+#### SampleListItem
+
+Lightweight model for list responses:
+
+- `id`: Internal database ID
+- `sample_id`: User-facing sample identifier
+- `name`: Sample name
+- `description`: Optional description
+- `owner_id`: Owner's user ID
+- `created_at`: Creation timestamp
+- `updated_at`: Last update timestamp
+- `step_count`: Number of processing steps
+- `observation_count`: Number of observations
+
+#### Sample
+
+Detailed model with full history:
+
+- All fields from `SampleListItem`, plus:
+- `owner_email`: Email of the owner
+- `history`: List of `StepEvent` and `ObservationEvent`
+- `stats`: `SampleStats` with aggregated counts
+
+### Exceptions
+
+All exceptions inherit from `SampleTrackerError`:
+
+- `SampleTrackerAuthError` - Authentication failed (401)
+- `SampleTrackerNotFoundError` - Resource not found (404)
+- `SampleTrackerValidationError` - Request validation failed (422)
+- `SampleTrackerRateLimitError` - Rate limit exceeded (429)
+- `SampleTrackerAPIError` - Other API errors
+
+## Supported Python Versions
+
+- Python 3.10+
+- Python 3.11+
+- Python 3.12+
+- Python 3.13+
+- Python 3.14+
+- PyPy 3.10+
+
+## License
+
+`hse-sampletracker-client` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
+
+## Links
+
+- **Documentation**: https://github.com/Alexander Schramm/sampletracker#readme
+- **Issues**: https://github.com/Alexander Schramm/sampletracker/issues
+- **Source**: https://github.com/Alexander Schramm/sampletracker
+- **PyPI**: https://pypi.org/project/hse-sampletracker-client

hse_sampletracker_client-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+sampletracker/__about__.py,sha256=K6bS7LuwO0rIivSI3klu2Pwkt5GN_rpKMF_KetE0bqY,112
+sampletracker/__init__.py,sha256=Tv4QpZAggX0L3sx4zR4t2v4QPhAEh-1gTAtkLuGcgB8,728
+sampletracker/__main__.py,sha256=alTBn5AbxyvHtmiyjWmVWcDA69gmJXVuVph5BfOzWvU,186
+sampletracker/client.py,sha256=kQ0BiL_Tx-NGuZ3vTmq0wxLiIjhknbWHt0MgPOvZ52Q,5433
+sampletracker/exceptions.py,sha256=YFkDqBWV7G_wqYYDU4SqvhCNUsregnHtk7YT2DBcIYU,1211
+sampletracker/models.py,sha256=EjVg3oSasdLlaPT30KDjN-yecTPEUqLG_skWaE9BSD8,7810
+sampletracker/run.py,sha256=D3ksHYJIUEmNeMZjVhbmmJmsFlQe-_onjQEuJF9TlYA,7956
+hse_sampletracker_client-0.1.1.dist-info/METADATA,sha256=4inQ_jPuhuZkSaBIzviI-RZQchXxnKPm-FzQ7h66dB0,7420
+hse_sampletracker_client-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hse_sampletracker_client-0.1.1.dist-info/entry_points.txt,sha256=BjKNRQ8TBIBmPLcxy5taBB8pb1p2gZa4C1OH-Qep8lw,57
+hse_sampletracker_client-0.1.1.dist-info/licenses/LICENSE.txt,sha256=S9jT5nNiRR4e9s4E7hgy2CTR46T7lRpz6y1RpFZ5V0s,1114
+hse_sampletracker_client-0.1.1.dist-info/RECORD,,

hse_sampletracker_client-0.1.1.dist-info/WHEEL

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

hse_sampletracker_client-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sampletracker = sampletracker.run:main

hse_sampletracker_client-0.1.1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present Alexander Schramm <alexander.schramm96@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

sampletracker/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present Alexander Schramm
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.1.1"

sampletracker/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2026-present Alexander Schramm
+#
+# SPDX-License-Identifier: MIT
+
+"""SampleTracker API client library."""
+
+from sampletracker.client import SampleTrackerClient
+from sampletracker.exceptions import (
+    SampleTrackerAPIError,
+    SampleTrackerAuthError,
+    SampleTrackerError,
+    SampleTrackerNotFoundError,
+    SampleTrackerRateLimitError,
+    SampleTrackerValidationError,
+)
+from sampletracker.models import Sample, SampleListItem
+
+__all__ = [
+    "SampleTrackerClient",
+    "Sample",
+    "SampleListItem",
+    "SampleTrackerError",
+    "SampleTrackerAPIError",
+    "SampleTrackerAuthError",
+    "SampleTrackerNotFoundError",
+    "SampleTrackerValidationError",
+    "SampleTrackerRateLimitError",
+]

sampletracker/__main__.py

@@ -0,0 +1,9 @@
+"""Entry point for running sampletracker as a module.
+
+Allows running the CLI via: python -m sampletracker
+"""
+
+from sampletracker.run import main
+
+if __name__ == "__main__":
+    main()

sampletracker/client.py

@@ -0,0 +1,164 @@
+"""Main client for interacting with the SampleTracker API."""
+
+from typing import Any
+
+import httpx
+
+from sampletracker.exceptions import (
+    SampleTrackerAPIError,
+    SampleTrackerAuthError,
+    SampleTrackerNotFoundError,
+    SampleTrackerRateLimitError,
+    SampleTrackerValidationError,
+)
+from sampletracker.models import Sample, SampleListItem
+
+
+class SampleTrackerClient:
+    """A synchronous client for the SampleTracker API.
+
+    This client provides methods to interact with the SampleTracker SaaS API
+    in a Pythonic way.
+
+    Args:
+        api_key: Your SampleTracker API key.
+        base_url: The base URL of the SampleTracker API.
+            Defaults to https://sampletracker.com/api/v1/.
+        timeout: Request timeout in seconds. Defaults to 30.
+
+    Example:
+        >>> from sampletracker import SampleTrackerClient
+        >>> client = SampleTrackerClient(api_key="your-api-key")
+        >>> samples = client.list_samples()
+    """
+
+    DEFAULT_BASE_URL = "https://sampletracker.com/api/v1/"
+    DEFAULT_TIMEOUT = 30.0
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout or self.DEFAULT_TIMEOUT
+        self._client: httpx.Client | None = None
+
+    def _get_client(self) -> httpx.Client:
+        """Get or create the HTTP client."""
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                },
+                timeout=self.timeout,
+            )
+        return self._client
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Handle API error responses."""
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            status_code = e.response.status_code
+            try:
+                body = e.response.json()
+            except Exception:
+                body = {"message": e.response.text}
+
+            message = body.get("message", str(e))
+
+            if status_code == 401:
+                raise SampleTrackerAuthError(message, status_code, body) from e
+            elif status_code == 404:
+                raise SampleTrackerNotFoundError(message, status_code, body) from e
+            elif status_code == 422:
+                raise SampleTrackerValidationError(message, status_code, body) from e
+            elif status_code == 429:
+                retry_after = e.response.headers.get("Retry-After")
+                raise SampleTrackerRateLimitError(
+                    message, retry_after=int(retry_after) if retry_after else None
+                ) from e
+            else:
+                raise SampleTrackerAPIError(message, status_code, body) from e
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Make an HTTP request to the API."""
+        client = self._get_client()
+        response = client.request(method, path, **kwargs)
+        self._handle_error(response)
+        return response.json()
+
+    def _get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Make a GET request."""
+        return self._request("GET", path, **kwargs)
+
+    def _post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Make a POST request."""
+        return self._request("POST", path, **kwargs)
+
+    def _put(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Make a PUT request."""
+        return self._request("PUT", path, **kwargs)
+
+    def _patch(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Make a PATCH request."""
+        return self._request("PATCH", path, **kwargs)
+
+    def _delete(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Make a DELETE request."""
+        return self._request("DELETE", path, **kwargs)
+
+
+
+
+    def load_sample(self, sample_id: str) -> Sample | None:
+        """Loads a sample by its ID.
+
+        Returns:
+            The loaded sample
+        """
+        if sample_id is None or sample_id.strip() == "":
+            return None
+        response = self._get(f"/samples/{sample_id}")
+        response_data = response.get("data")
+
+        if response_data is None:
+            return None
+
+        sample = Sample.from_dict(response_data)
+        return sample
+    
+
+    def list_samples(self, limit: int = 10, after_id: int | None = None) -> list[SampleListItem]:
+        """List all samples
+        
+        Args:
+            limit: Number of results to return (max: 100). Defaults to 10.
+            after_id: Pagination cursor - return samples with ID > after_id (maps to minId).
+        
+        Returns:
+            List of sample list items
+        """
+        params: dict[str, Any] = {"l": limit}
+        if after_id is not None:
+            params["minId"] = after_id
+        
+        response = self._get("/samples", params=params)
+        response_data = response.get("data", [])
+        
+        if not response_data:
+            return []
+        
+        samples = [SampleListItem.from_dict(item) for item in response_data]
+        return samples

sampletracker/exceptions.py

@@ -0,0 +1,42 @@
+"""Custom exceptions for the SampleTracker API client."""
+
+
+class SampleTrackerError(Exception):
+    """Base exception for all SampleTracker errors."""
+
+    pass
+
+
+class SampleTrackerAPIError(SampleTrackerError):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, message: str, status_code: int | None = None, response_body: dict | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body or {}
+
+
+class SampleTrackerAuthError(SampleTrackerAPIError):
+    """Raised when authentication fails (401 Unauthorized)."""
+
+    pass
+
+
+class SampleTrackerNotFoundError(SampleTrackerAPIError):
+    """Raised when a resource is not found (404 Not Found)."""
+
+    pass
+
+
+class SampleTrackerValidationError(SampleTrackerAPIError):
+    """Raised when request validation fails (422 Unprocessable Entity)."""
+
+    pass
+
+
+class SampleTrackerRateLimitError(SampleTrackerAPIError):
+    """Raised when rate limit is exceeded (429 Too Many Requests)."""
+
+    def __init__(self, message: str, retry_after: int | None = None) -> None:
+        super().__init__(message, status_code=429)
+        self.retry_after = retry_after

sampletracker/models.py

@@ -0,0 +1,248 @@
+"""Data models for the SampleTracker API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class SampleListItem:
+    """Represents a sample item in the list response.
+    
+    This is the lightweight model used in the list samples endpoint.
+    
+    Attributes:
+        id: The internal database ID of the sample.
+        sample_id: The user-facing sample identifier (e.g., "ABC123").
+        name: The name of the sample.
+        description: Optional description of the sample.
+        owner_id: The ID of the sample owner.
+        created_at: When the sample was created.
+        updated_at: When the sample was last updated.
+        step_count: Number of processing steps.
+        observation_count: Number of observations.
+    """
+    
+    id: int
+    sample_id: str
+    name: str | None
+    description: str | None
+    owner_id: int
+    created_at: datetime
+    updated_at: datetime
+    step_count: int = 0
+    observation_count: int = 0
+    
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SampleListItem:
+        """Create a SampleListItem instance from a dictionary.
+        
+        Args:
+            data: Dictionary containing sample data from the list API.
+            
+        Returns:
+            A new SampleListItem instance.
+        """
+        return cls(
+            id=data["id"],
+            sample_id=data["sampleId"],
+            name=data.get("name"),
+            description=data.get("description"),
+            owner_id=data["ownerId"],
+            created_at=datetime.fromisoformat(data["createdAt"].replace("Z", "+00:00")),
+            updated_at=datetime.fromisoformat(data["updatedAt"].replace("Z", "+00:00")),
+            step_count=data.get("stepCount", 0),
+            observation_count=data.get("observationCount", 0),
+        )
+    
+    def __repr__(self) -> str:
+        """Return a string representation of the sample."""
+        return f"SampleListItem(id={self.id}, sample_id='{self.sample_id}', name='{self.name}')"
+
+
+@dataclass
+class Parameter:
+    """Represents a parameter in a step.
+    
+    Attributes:
+        id: The parameter ID.
+        key: The parameter name/key.
+        value: The parameter value.
+        unit: The unit of measurement (optional).
+    """
+    
+    id: int
+    key: str
+    value: Any
+    unit: str | None
+    
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Parameter:
+        """Create a Parameter instance from a dictionary."""
+        return cls(
+            id=data["id"],
+            key=data["key"],
+            value=data["value"],
+            unit=data.get("unit"),
+        )
+
+
+@dataclass
+class StepEvent:
+    """Represents a processing step in the sample history.
+    
+    Attributes:
+        id: The step ID.
+        name: The step name.
+        description: Optional description.
+        performed_by: User ID who performed the step.
+        recorded_by: User ID who recorded the step.
+        performed_at: When the step was performed.
+        created_at: When the step was recorded.
+        parameters: List of parameters for this step.
+    """
+    
+    id: int
+    name: str
+    description: str | None
+    performed_by: int
+    recorded_by: int
+    performed_at: datetime
+    created_at: datetime
+    parameters: list[Parameter]
+    
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> StepEvent:
+        """Create a StepEvent instance from a dictionary."""
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            description=data.get("description"),
+            performed_by=data["performedBy"],
+            recorded_by=data["recordedBy"],
+            performed_at=datetime.fromisoformat(data["performedAt"].replace("Z", "+00:00")),
+            created_at=datetime.fromisoformat(data["createdAt"].replace("Z", "+00:00")),
+            parameters=[Parameter.from_dict(p) for p in data.get("parameters", [])],
+        )
+
+
+@dataclass
+class ObservationEvent:
+    """Represents an observation in the sample history.
+    
+    Attributes:
+        id: The observation ID.
+        content: The observation text.
+        user_id: User ID who made the observation.
+        created_at: When the observation was created.
+        updated_at: When the observation was last updated.
+    """
+    
+    id: int
+    content: str
+    user_id: int
+    created_at: datetime
+    updated_at: datetime
+    
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ObservationEvent:
+        """Create an ObservationEvent instance from a dictionary."""
+        return cls(
+            id=data["id"],
+            content=data["content"],
+            user_id=data["userId"],
+            created_at=datetime.fromisoformat(data["createdAt"].replace("Z", "+00:00")),
+            updated_at=datetime.fromisoformat(data["updatedAt"].replace("Z", "+00:00")),
+        )
+
+
+@dataclass 
+class SampleStats:
+    """Statistics about a sample.
+    
+    Attributes:
+        step_count: Number of processing steps.
+        observation_count: Number of observations.
+    """
+    
+    step_count: int
+    observation_count: int
+    
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SampleStats:
+        """Create a SampleStats instance from a dictionary."""
+        return cls(
+            step_count=data.get("stepCount", 0),
+            observation_count=data.get("observationCount", 0),
+        )
+
+
+HistoryEvent = StepEvent | ObservationEvent
+
+
+@dataclass
+class Sample:
+    """Represents a detailed sample with full history.
+    
+    This is the full model used in the get sample details endpoint.
+    
+    Attributes:
+        id: The internal database ID of the sample.
+        sample_id: The user-facing sample identifier (e.g., "ABC123").
+        name: The name of the sample.
+        description: Optional description of the sample.
+        owner_id: The ID of the sample owner.
+        owner_email: Email of the sample owner.
+        created_at: When the sample was created.
+        updated_at: When the sample was last updated.
+        history: List of history events (steps and observations).
+        stats: Statistics about the sample.
+    """
+    
+    id: int
+    sample_id: str
+    name: str | None
+    description: str | None
+    owner_id: int
+    owner_email: str
+    created_at: datetime
+    updated_at: datetime
+    history: list[HistoryEvent]
+    stats: SampleStats
+    
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Sample:
+        """Create a Sample instance from a dictionary.
+        
+        Args:
+            data: Dictionary containing sample data from the detail API.
+            
+        Returns:
+            A new Sample instance.
+        """
+        history: list[HistoryEvent] = []
+        for event_data in data.get("history", []):
+            event_type = event_data.get("type")
+            if event_type == "step":
+                history.append(StepEvent.from_dict(event_data))
+            elif event_type == "observation":
+                history.append(ObservationEvent.from_dict(event_data))
+        
+        return cls(
+            id=data["id"],
+            sample_id=data["sampleId"],
+            name=data.get("name"),
+            description=data.get("description"),
+            owner_id=data["ownerId"],
+            owner_email=data["ownerEmail"],
+            created_at=datetime.fromisoformat(data["createdAt"].replace("Z", "+00:00")),
+            updated_at=datetime.fromisoformat(data["updatedAt"].replace("Z", "+00:00")),
+            history=history,
+            stats=SampleStats.from_dict(data.get("stats", {})),
+        )
+    
+    def __repr__(self) -> str:
+        """Return a string representation of the sample."""
+        return f"Sample(id={self.id}, sample_id='{self.sample_id}', name='{self.name}')"

sampletracker/run.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""CLI for interacting with the SampleTracker API.
+
+This module provides a command-line interface for listing samples
+and viewing sample details.
+
+Examples:
+    # List all samples (default limit: 10)
+    python -m sampletracker.run list
+    
+    # List samples with a specific limit
+    python -m sampletracker.run list --limit 20
+    
+    # View a specific sample's details
+    python -m sampletracker.run view SAMPLE-123
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from sampletracker.client import SampleTrackerClient
+from sampletracker.exceptions import SampleTrackerError
+from sampletracker.models import ObservationEvent, SampleListItem, StepEvent
+
+
+def _load_env_file() -> None:
+    """Load environment variables from .env file if it exists."""
+    # Look for .env file in the current directory and parent directories
+    current_dir = Path.cwd()
+    for parent in [current_dir] + list(current_dir.parents):
+        env_file = parent / ".env"
+        if env_file.exists():
+            with open(env_file) as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith("#") and "=" in line:
+                        key, value = line.split("=", 1)
+                        # Only set if not already set in environment
+                        if key not in os.environ:
+                            os.environ[key] = value
+            break
+
+
+# Load .env file on module import
+_load_env_file()
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create and configure the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="sampletracker",
+        description="CLI for interacting with the SampleTracker API",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Configuration (in order of precedence):
+    1. Command-line options (--api-key, --base-url)
+    2. Environment variables (SAMPLETRACKER_API_KEY, SAMPLETRACKER_BASE_URL)
+    3. .env file in current or parent directory (gitignored)
+
+Examples:
+    %(prog)s list                    # List first 10 samples
+    %(prog)s list --limit 20         # List first 20 samples
+    %(prog)s view SAMPLE-123         # View sample details
+        """,
+    )
+    
+    parser.add_argument(
+        "--api-key",
+        type=str,
+        default=os.environ.get("SAMPLETRACKER_API_KEY"),
+        help="Your SampleTracker API key (can also be set via SAMPLETRACKER_API_KEY env var)",
+    )
+    
+    parser.add_argument(
+        "--base-url",
+        type=str,
+        default=os.environ.get("SAMPLETRACKER_BASE_URL"),
+        help="The base URL of the SampleTracker API",
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # List command
+    list_parser = subparsers.add_parser(
+        "list",
+        help="List all samples",
+        description="List samples from the SampleTracker API",
+    )
+    list_parser.add_argument(
+        "--limit",
+        "-l",
+        type=int,
+        default=10,
+        help="Number of samples to return (max: 100, default: 10)",
+    )
+    list_parser.add_argument(
+        "--after-id",
+        "-a",
+        type=int,
+        default=None,
+        help="Pagination cursor - return samples with ID > after_id",
+    )
+    
+    # View command
+    view_parser = subparsers.add_parser(
+        "view",
+        help="View a specific sample's details",
+        description="View detailed information about a sample",
+    )
+    view_parser.add_argument(
+        "sample_id",
+        type=str,
+        help="The sample ID to look up (e.g., 'ABC123')",
+    )
+    
+    return parser
+
+
+def get_client(args: argparse.Namespace) -> SampleTrackerClient:
+    """Create a client instance from parsed arguments."""
+    if not args.api_key:
+        print(
+            "Error: API key is required. Set it via --api-key option or SAMPLETRACKER_API_KEY environment variable.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    
+    return SampleTrackerClient(
+        api_key=args.api_key,
+        base_url=args.base_url if args.base_url else None,
+    )
+
+
+def cmd_list(client: SampleTrackerClient, args: argparse.Namespace) -> int:
+    """Execute the list command.
+    
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    try:
+        samples = client.list_samples(limit=args.limit, after_id=args.after_id)
+        
+        if not samples:
+            print("No samples found.")
+            return 0
+        
+        print(f"{'ID':>6} | {'Sample ID':>15} | {'Name':>30} | {'Steps':>5} | {'Observations':>12}")
+        print("-" * 80)
+        
+        for sample in samples:
+            name = sample.name or "(unnamed)"
+            name = name[:28] + ".." if len(name) > 30 else name
+            print(
+                f"{sample.id:>6} | {sample.sample_id:>15} | {name:>30} | "
+                f"{sample.step_count:>5} | {sample.observation_count:>12}"
+            )
+        
+        return 0
+        
+    except SampleTrackerError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_view(client: SampleTrackerClient, args: argparse.Namespace) -> int:
+    """Execute the view command.
+    
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    try:
+        sample = client.load_sample(args.sample_id)
+        
+        if sample is None:
+            print(f"Sample '{args.sample_id}' not found.", file=sys.stderr)
+            return 1
+        
+        print(f"Sample Details:")
+        print(f"  ID:          {sample.id}")
+        print(f"  Sample ID:   {sample.sample_id}")
+        print(f"  Name:        {sample.name or '(unnamed)'}")
+        print(f"  Description: {sample.description or '(none)'}")
+        print(f"  Owner ID:    {sample.owner_id}")
+        print(f"  Owner Email: {sample.owner_email}")
+        print(f"  Created:     {sample.created_at}")
+        print(f"  Updated:     {sample.updated_at}")
+        print(f"  Steps:       {sample.stats.step_count}")
+        print(f"  Observations: {sample.stats.observation_count}")
+        
+        if sample.history:
+            print(f"\n  History:")
+            for event in sample.history:
+                if isinstance(event, StepEvent):
+                    print(f"    [Step] {event.name}")
+                    if event.description:
+                        print(f"      Description: {event.description}")
+                    print(f"      Performed: {event.performed_at}")
+                    if event.parameters:
+                        print(f"      Parameters:")
+                        for param in event.parameters:
+                            unit = f" {param.unit}" if param.unit else ""
+                            print(f"        - {param.key}: {param.value}{unit}")
+                elif isinstance(event, ObservationEvent):
+                    print(f"    [Observation] {event.content[:50]}{'...' if len(event.content) > 50 else ''}")
+                    print(f"      Created: {event.created_at}")
+        
+        return 0
+        
+    except SampleTrackerError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def main(args: Sequence[str] | None = None) -> int:
+    """Main entry point for the CLI.
+    
+    Args:
+        args: Command-line arguments (defaults to sys.argv[1:])
+        
+    Returns:
+        Exit code (0 for success, non-zero for failure)
+    """
+    parser = create_parser()
+    parsed_args = parser.parse_args(args)
+    
+    if not parsed_args.command:
+        parser.print_help()
+        return 1
+    
+    client = get_client(parsed_args)
+    
+    if parsed_args.command == "list":
+        return cmd_list(client, parsed_args)
+    elif parsed_args.command == "view":
+        return cmd_view(client, parsed_args)
+    else:
+        parser.print_help()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())