monsta 0.1.0__tar.gz

monsta-0.1.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.3
+Name: monsta
+Version: 0.1.0
+Summary: Simple monitoring REST API for Python applications
+Author: Stefan Schönberger
+Author-email: Stefan Schönberger <stefan@sniner.dev>
+Requires-Dist: fastapi>=0.133.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: uvicorn>=0.41.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Monsta - Status Reporting REST API for Python Applications
+
+**Monsta** (short for "Monitoring State") is a lightweight library for Python applications that provides a REST API endpoint for exposing application state and metrics. It's designed for seamless integration with FastAPI.
+
+## Features
+
+- **Simple Integration**: Add monitoring to your application with just a few lines of code
+- **Async Support**: Native async/await support for FastAPI
+- **Thread-Safe**: Built-in thread safety for concurrent access
+- **Flexible State Management**: Support for both direct state values and callback functions
+- **Built-in Metrics**: Automatic uptime tracking (and possibly other internal metrics)
+- **Customizable**: Configure endpoint paths, ports, and update intervals
+
+## Installation
+
+```bash
+pip install monsta
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from monsta import StatusReporter
+
+# Create status reporter
+mon = StatusReporter()
+
+# Set application state
+mon.publish({"status": "running", "version": "1.0.0"})
+
+# Start status reporting server (blocking)
+mon.start(blocking=True)
+```
+
+### FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from monsta import StatusReporter
+
+app = FastAPI()
+
+# Create and integrate status reporter
+mon = StatusReporter(endpoint="/api/v1/monitoring")
+app.include_router(mon.router)
+
+# Update state during application lifecycle
+mon.publish({"status": "running", "requests": 0})
+
+# Start FastAPI app
+# Status reporting will be available at /api/v1/monitoring
+```
+
+### Async FastAPI Integration
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from monsta import AsyncStatusReporter
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Initialize status reporting
+    app.state.mon = AsyncStatusReporter(endpoint="/api/v1/state")
+    app.include_router(app.state.mon.router)
+    
+    # Start async status reporting
+    await app.state.mon.start(state={"status": "starting"})
+    
+    yield
+    
+    # Clean up
+    await app.state.mon.stop()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/")
+async def root():
+    # Update status asynchronously
+    await app.state.mon.publish({"status": "running", "requests": 1})
+    return {"message": "Hello World"}
+```
+
+## API Reference
+
+### StatusReporter
+
+The main synchronous status reporter class.
+
+#### `StatusReporter(endpoint: Optional[str] = None)`
+
+- `endpoint`: Custom endpoint path for the status API (default: `/mon/v1/state`)
+
+#### `publish(state: StateSource) -> Self`
+
+Set the application state.
+
+- `state`: Either a callable that returns state data, or a mapping/dictionary containing the state data directly
+
+Returns `self` for method chaining.
+
+**Examples:**
+```python
+# Direct state setting
+reporter.publish({"status": "running", "count": 42})
+
+# Using a callback function
+def get_current_state():
+    return {"status": "running", "count": get_count()}
+
+reporter.publish(get_current_state)
+```
+
+#### `start(*, state: Optional[StateSource] = None, host: Optional[str] = None, port: Optional[int] = None, log_level: Optional[Union[int, str]] = None, blocking: bool = False) -> None`
+
+Start the status reporter.
+
+- `state`: Initial state or callable to get initial state
+- `host`: Host address to bind to (default: `"0.0.0.0"`)
+- `port`: Port number to listen on (default: `4242`)
+- `log_level`: Logging level for uvicorn
+- `blocking`: If True, blocks until server stops (default: `False`)
+
+#### `stop() -> None`
+
+Stop the status reporter and clean up resources.
+
+#### `reset() -> None`
+
+Reset the status reporter to its initial state.
+
+### AsyncStatusReporter
+
+Async version of StatusReporter for use with FastAPI and other async frameworks.
+
+#### `AsyncStatusReporter(endpoint: Optional[str] = None)`
+
+- `endpoint`: Custom endpoint path for the status API
+
+#### `async publish(state: AsyncStateType) -> None`
+
+Set the application state asynchronously.
+
+- `state`: Either a callable that returns state data (can be async), or a mapping/dictionary containing the state data directly
+
+**Examples:**
+```python
+# Direct state setting
+await reporter.publish({"status": "running", "count": 42})
+
+# Using an async callback function
+async def get_current_state():
+    return {"status": "running", "count": await get_count()}
+await reporter.publish(get_current_state)
+
+# Using a sync callback function
+def get_current_state():
+    return {"status": "running", "count": get_count()}
+await reporter.publish(get_current_state)
+```
+
+#### `async start(*, state: Optional[AsyncStateType] = None, host: Optional[str] = None, port: Optional[int] = None, update_interval: int = 5) -> None`
+
+Start the async status reporter.
+
+- `state`: Initial state or callable to get initial state
+- `host`: Host address to bind to (default: `"0.0.0.0"`)
+- `port`: Port number to listen on (default: `4242`)
+- `update_interval`: Interval in seconds for automatic state updates (default: `5`)
+
+#### `async stop() -> None`
+
+Stop the async status reporter.
+
+#### `reset() -> None`
+
+Reset the status reporter to its initial state.
+
+## Singleton Functions
+
+For simple use cases, you can use the singleton functions:
+
+```python
+import monsta
+
+# Start monitoring with singleton
+monsta.start(state={"status": "running"}, blocking=False)
+
+# Update state
+monsta.publish({"status": "running", "requests": 42})
+
+# Stop monitoring
+monsta.stop()
+```
+
+## Configuration
+
+### Environment Variables
+
+Monsta respects standard uvicorn environment variables for configuration.
+
+### Customization
+
+You can customize the monitoring behavior:
+
+```python
+# Custom endpoint
+mon = MonitoringAgent(endpoint="/custom/monitoring/path")
+
+# Custom host and port
+mon.start(host="127.0.0.1", port=8080)
+
+# Custom update interval (async only)
+await async_mon.start(update_interval=10)  # Update every 10 seconds
+```
+
+## Monitoring Endpoint
+
+The monitoring endpoint returns a JSON response with the following structure:
+
+```json
+{
+  "internal": {
+    "uptime": 12345
+  },
+  "state": {
+    "status": "running",
+    "requests": 42,
+    "custom_metrics": {}
+  }
+}
+```
+
+- `internal.uptime`: Automatic uptime tracking in seconds
+- `state`: Your application-specific state data
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `embedded.py`: Basic FastAPI integration
+- `embedded_async.py`: Async FastAPI integration
+- `singleton.py`: Singleton usage example
+- `standalone.py`: Standalone monitoring server
+
+## Development
+
+```bash
+# Install development dependencies using uv
+uv sync --dev
+
+# Run tests
+uv run pytest
+```
+
+## Project Structure
+
+```
+src/monsta/
+├── __init__.py          # Main package exports
+├── mon.py              # Synchronous StatusReporter implementation
+├── aiomon.py           # Async StatusReporter implementation
+└── py.typed            # Type annotations
+
+examples/
+├── embedded.py         # Basic FastAPI integration example
+├── embedded_async.py   # Async FastAPI integration example  
+├── singleton.py        # Singleton usage example
+└── standalone.py       # Standalone server example
+
+tests/
+├── test_sync.py       # Synchronous StatusReporter tests
+└── test_async.py      # AsyncStatusReporter tests
+```
+
+## License
+
+[BSD 3-Clause License](./LICENSE)
+
+## Support
+
+For issues, questions, or contributions, please open an issue on the GitHub repository.

monsta-0.1.0/README.md

@@ -0,0 +1,284 @@
+# Monsta - Status Reporting REST API for Python Applications
+
+**Monsta** (short for "Monitoring State") is a lightweight library for Python applications that provides a REST API endpoint for exposing application state and metrics. It's designed for seamless integration with FastAPI.
+
+## Features
+
+- **Simple Integration**: Add monitoring to your application with just a few lines of code
+- **Async Support**: Native async/await support for FastAPI
+- **Thread-Safe**: Built-in thread safety for concurrent access
+- **Flexible State Management**: Support for both direct state values and callback functions
+- **Built-in Metrics**: Automatic uptime tracking (and possibly other internal metrics)
+- **Customizable**: Configure endpoint paths, ports, and update intervals
+
+## Installation
+
+```bash
+pip install monsta
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from monsta import StatusReporter
+
+# Create status reporter
+mon = StatusReporter()
+
+# Set application state
+mon.publish({"status": "running", "version": "1.0.0"})
+
+# Start status reporting server (blocking)
+mon.start(blocking=True)
+```
+
+### FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from monsta import StatusReporter
+
+app = FastAPI()
+
+# Create and integrate status reporter
+mon = StatusReporter(endpoint="/api/v1/monitoring")
+app.include_router(mon.router)
+
+# Update state during application lifecycle
+mon.publish({"status": "running", "requests": 0})
+
+# Start FastAPI app
+# Status reporting will be available at /api/v1/monitoring
+```
+
+### Async FastAPI Integration
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from monsta import AsyncStatusReporter
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Initialize status reporting
+    app.state.mon = AsyncStatusReporter(endpoint="/api/v1/state")
+    app.include_router(app.state.mon.router)
+    
+    # Start async status reporting
+    await app.state.mon.start(state={"status": "starting"})
+    
+    yield
+    
+    # Clean up
+    await app.state.mon.stop()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/")
+async def root():
+    # Update status asynchronously
+    await app.state.mon.publish({"status": "running", "requests": 1})
+    return {"message": "Hello World"}
+```
+
+## API Reference
+
+### StatusReporter
+
+The main synchronous status reporter class.
+
+#### `StatusReporter(endpoint: Optional[str] = None)`
+
+- `endpoint`: Custom endpoint path for the status API (default: `/mon/v1/state`)
+
+#### `publish(state: StateSource) -> Self`
+
+Set the application state.
+
+- `state`: Either a callable that returns state data, or a mapping/dictionary containing the state data directly
+
+Returns `self` for method chaining.
+
+**Examples:**
+```python
+# Direct state setting
+reporter.publish({"status": "running", "count": 42})
+
+# Using a callback function
+def get_current_state():
+    return {"status": "running", "count": get_count()}
+
+reporter.publish(get_current_state)
+```
+
+#### `start(*, state: Optional[StateSource] = None, host: Optional[str] = None, port: Optional[int] = None, log_level: Optional[Union[int, str]] = None, blocking: bool = False) -> None`
+
+Start the status reporter.
+
+- `state`: Initial state or callable to get initial state
+- `host`: Host address to bind to (default: `"0.0.0.0"`)
+- `port`: Port number to listen on (default: `4242`)
+- `log_level`: Logging level for uvicorn
+- `blocking`: If True, blocks until server stops (default: `False`)
+
+#### `stop() -> None`
+
+Stop the status reporter and clean up resources.
+
+#### `reset() -> None`
+
+Reset the status reporter to its initial state.
+
+### AsyncStatusReporter
+
+Async version of StatusReporter for use with FastAPI and other async frameworks.
+
+#### `AsyncStatusReporter(endpoint: Optional[str] = None)`
+
+- `endpoint`: Custom endpoint path for the status API
+
+#### `async publish(state: AsyncStateType) -> None`
+
+Set the application state asynchronously.
+
+- `state`: Either a callable that returns state data (can be async), or a mapping/dictionary containing the state data directly
+
+**Examples:**
+```python
+# Direct state setting
+await reporter.publish({"status": "running", "count": 42})
+
+# Using an async callback function
+async def get_current_state():
+    return {"status": "running", "count": await get_count()}
+await reporter.publish(get_current_state)
+
+# Using a sync callback function
+def get_current_state():
+    return {"status": "running", "count": get_count()}
+await reporter.publish(get_current_state)
+```
+
+#### `async start(*, state: Optional[AsyncStateType] = None, host: Optional[str] = None, port: Optional[int] = None, update_interval: int = 5) -> None`
+
+Start the async status reporter.
+
+- `state`: Initial state or callable to get initial state
+- `host`: Host address to bind to (default: `"0.0.0.0"`)
+- `port`: Port number to listen on (default: `4242`)
+- `update_interval`: Interval in seconds for automatic state updates (default: `5`)
+
+#### `async stop() -> None`
+
+Stop the async status reporter.
+
+#### `reset() -> None`
+
+Reset the status reporter to its initial state.
+
+## Singleton Functions
+
+For simple use cases, you can use the singleton functions:
+
+```python
+import monsta
+
+# Start monitoring with singleton
+monsta.start(state={"status": "running"}, blocking=False)
+
+# Update state
+monsta.publish({"status": "running", "requests": 42})
+
+# Stop monitoring
+monsta.stop()
+```
+
+## Configuration
+
+### Environment Variables
+
+Monsta respects standard uvicorn environment variables for configuration.
+
+### Customization
+
+You can customize the monitoring behavior:
+
+```python
+# Custom endpoint
+mon = MonitoringAgent(endpoint="/custom/monitoring/path")
+
+# Custom host and port
+mon.start(host="127.0.0.1", port=8080)
+
+# Custom update interval (async only)
+await async_mon.start(update_interval=10)  # Update every 10 seconds
+```
+
+## Monitoring Endpoint
+
+The monitoring endpoint returns a JSON response with the following structure:
+
+```json
+{
+  "internal": {
+    "uptime": 12345
+  },
+  "state": {
+    "status": "running",
+    "requests": 42,
+    "custom_metrics": {}
+  }
+}
+```
+
+- `internal.uptime`: Automatic uptime tracking in seconds
+- `state`: Your application-specific state data
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `embedded.py`: Basic FastAPI integration
+- `embedded_async.py`: Async FastAPI integration
+- `singleton.py`: Singleton usage example
+- `standalone.py`: Standalone monitoring server
+
+## Development
+
+```bash
+# Install development dependencies using uv
+uv sync --dev
+
+# Run tests
+uv run pytest
+```
+
+## Project Structure
+
+```
+src/monsta/
+├── __init__.py          # Main package exports
+├── mon.py              # Synchronous StatusReporter implementation
+├── aiomon.py           # Async StatusReporter implementation
+└── py.typed            # Type annotations
+
+examples/
+├── embedded.py         # Basic FastAPI integration example
+├── embedded_async.py   # Async FastAPI integration example  
+├── singleton.py        # Singleton usage example
+└── standalone.py       # Standalone server example
+
+tests/
+├── test_sync.py       # Synchronous StatusReporter tests
+└── test_async.py      # AsyncStatusReporter tests
+```
+
+## License
+
+[BSD 3-Clause License](./LICENSE)
+
+## Support
+
+For issues, questions, or contributions, please open an issue on the GitHub repository.

monsta-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "monsta"
+version = "0.1.0"
+description = "Simple monitoring REST API for Python applications"
+readme = "README.md"
+authors = [
+    { name = "Stefan Schönberger", email = "stefan@sniner.dev" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "fastapi>=0.133.1",
+    "pydantic>=2.12.5",
+    "uvicorn>=0.41.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.6,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.38.2",
+    "pytest>=9.0.2",
+    "ruff>=0.15.3",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+testpaths = [
+    "tests",
+]
+
+[tool.pyright]
+typeCheckingMode = "standard"
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"
+
+[tool.ruff]
+line-length = 96
+ignore = ["E402"]
+
+[tool.ruff.lint]
+per-file-ignores = { "__init__.py" = ["F401"] }

monsta-0.1.0/src/monsta/__init__.py

@@ -0,0 +1,10 @@
+from .aiomon import (
+    AsyncStatusReporter,
+)
+from .mon import (
+    StatusReporter,
+    publish,
+    reset,
+    start,
+    stop,
+)

monsta-0.1.0/src/monsta/aiomon.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from typing import Any, Callable, Mapping, Optional, Union
+
+from .mon import (
+    DEFAULT_HOST,
+    DEFAULT_PORT,
+    UPDATE_HOLDOFF,
+    StateCallback,
+    StatusReporter,
+    _now,
+)
+
+_logger = logging.getLogger(__name__)
+
+AsyncStateCallback = Callable[[], Any]
+AsyncStateType = Union[AsyncStateCallback, StateCallback, Mapping]
+
+
+class AsyncStatusReporter:
+    """Async version of StatusReporter for use with FastAPI and other async frameworks.
+
+    This class provides the same status reporting functionality as StatusReporter but with
+    native async/await support, making it ideal for FastAPI applications.
+    """
+
+    def __init__(self, *, endpoint: Optional[str] = None):
+        """Initialize an async status reporter.
+
+        Args:
+            endpoint: Custom endpoint path for the status API
+        """
+        # Create a synchronous StatusReporter for state management
+        self._sync_agent = StatusReporter(endpoint=endpoint)
+
+        # Async-specific components
+        self._async_state_callback: Optional[AsyncStateCallback] = None
+        self._async_update_task: Optional[asyncio.Task] = None
+
+        # Use the sync agent's router
+        self.router = self._sync_agent.router
+
+    def reset(self) -> None:
+        """Reset the monitoring agent to its initial state."""
+        self._sync_agent.reset()
+
+    async def publish(self, state: AsyncStateType) -> None:
+        """Set the application state asynchronously.
+
+        Args:
+            state: Either a callable that returns state data (can be async),
+                   or a mapping/dictionary containing the state data directly
+
+        Examples:
+            # Direct state setting
+            await agent.publish({"status": "running", "count": 42})
+
+            # Using an async callback function
+            async def get_current_state():
+                return {"status": "running", "count": await get_count()}
+            await agent.publish(get_current_state)
+
+            # Using a sync callback function
+            def get_current_state():
+                return {"status": "running", "count": get_count()}
+            await agent.publish(get_current_state)
+        """
+        if inspect.iscoroutinefunction(state):
+            self._async_state_callback = state
+            self._sync_agent._state_callback = None
+            _state = await state()
+            _logger.debug("Async state callback registered and executed")
+            self._sync_agent._set_state(_state)
+        else:
+            self._async_state_callback = None
+            self._sync_agent.publish(state)
+
+    async def _update_state_async(self) -> None:
+        """Update the monitoring state if sufficient time has passed.
+
+        This method implements rate-limiting to prevent excessive state updates.
+        Only updates the state if UPDATE_HOLDOFF seconds have passed since
+        the last update.
+        """
+
+        if self._async_state_callback:
+            now = _now()
+            if self._sync_agent._update_deferred(now):
+                return
+            try:
+                self._sync_agent._update_internal_state(now)
+                _state = await self._async_state_callback()
+                self._sync_agent._set_state(_state)
+            except ValueError as ve:
+                _logger.error("Invalid state value during async update: %s", ve)
+            except RuntimeError as re:
+                _logger.error("Runtime error during async state update: %s", re)
+            except Exception as exc:
+                _logger.error("Unexpected error during async state update: %s", exc)
+        else:
+            self._sync_agent._update_state()
+
+    async def start(
+        self,
+        *,
+        state: Optional[AsyncStateType] = None,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        update_interval: int = UPDATE_HOLDOFF,
+    ) -> None:
+        """Start the async monitoring agent.
+
+        Args:
+            app_state: Initial state or callable to get initial state
+            host: Host address to bind to
+            port: Port number to listen on
+            update_interval: Interval in seconds for automatic state updates
+        """
+        try:
+            if self._sync_agent._worker_alive():
+                raise RuntimeError("Monitoring agent already running")
+
+            self.reset()
+            await self.publish(state or {})
+
+            actual_host = host or DEFAULT_HOST
+            actual_port = port or DEFAULT_PORT
+
+            # Start the async update task
+            self._async_update_task = asyncio.create_task(
+                self._periodic_update_async(update_interval)
+            )
+            _logger.info(
+                "Async monitoring agent started successfully on %s:%d", actual_host, actual_port
+            )
+
+        except Exception as exc:
+            _logger.error("Failed to start async monitoring agent: %s", exc)
+            raise
+
+    async def _periodic_update_async(self, interval: int) -> None:
+        """Background task for periodic state updates in async mode."""
+        try:
+            while True:
+                await asyncio.sleep(interval)
+                await self._update_state_async()
+        except asyncio.CancelledError:
+            _logger.info("Async update task cancelled")
+        except Exception as exc:
+            _logger.error("Async update task failed: %s", exc)
+
+    async def stop(self) -> None:
+        """Stop the async monitoring agent."""
+        try:
+            # Cancel async update task if running
+            if self._async_update_task:
+                self._async_update_task.cancel()
+                try:
+                    await self._async_update_task
+                except asyncio.CancelledError:
+                    pass
+                self._async_update_task = None
+                _logger.info("Async update task cancelled successfully")
+
+            # Stop the sync components
+            if self._sync_agent._uvicorn_server:
+                self._sync_agent._uvicorn_server.should_exit = True
+                _logger.info("Signaled uvicorn server to exit")
+
+            if self._sync_agent._worker_thread:
+                self._sync_agent._worker_thread.join(timeout=5)
+                if self._sync_agent._worker_thread.is_alive():
+                    _logger.warning("Monitoring thread did not terminate within timeout")
+                self._sync_agent._worker_thread = None
+                _logger.info("Monitoring thread joined successfully")
+
+            self._sync_agent._uvicorn_server = None
+            _logger.info("Async monitoring agent stopped successfully")
+        except RuntimeError as re:
+            _logger.error("Runtime error during async agent shutdown: %s", re)
+        except Exception as exc:
+            _logger.error("Unexpected error during async agent shutdown: %s", exc)

monsta-0.1.0/src/monsta/mon.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Callable, Mapping, Optional, Self, Union
+
+import uvicorn
+from fastapi import APIRouter, FastAPI
+from pydantic import BaseModel, Field
+
+_logger = logging.getLogger(__name__)
+
+UPDATE_HOLDOFF = 5  # seconds: rate limit for state updates
+DEFAULT_PORT = 4242
+DEFAULT_HOST = "0.0.0.0"
+
+DEFAULT_ENDPOINT = "/mon/v1/state"
+
+StateValue = Mapping[str, Any]
+StateCallback = Callable[[], StateValue]
+StateSource = Union[StateCallback, StateValue]
+
+
+class InternalState(BaseModel):
+    uptime: int = 0
+
+
+class MonitoringState(BaseModel):
+    # "internal" holds library-generated stats (like uptime)
+    internal: InternalState = Field(default_factory=InternalState)
+    # "state" holds the application state
+    state: StateValue = {}
+
+
+def _now() -> float:
+    return time.monotonic()
+
+
+class StatusReporter:
+    def __init__(self, *, endpoint: Optional[str] = None):
+        self._state: MonitoringState = MonitoringState()
+        self._state_lock: threading.RLock = threading.RLock()
+        self._state_callback: Optional[StateCallback] = None
+        self._update_time: float = 0.0
+        self._startup_time: float = _now()
+
+        self._worker_thread: Optional[threading.Thread] = None
+        self._uvicorn_server: Optional[uvicorn.Server] = None
+
+        self.router = APIRouter()
+        self.router.add_api_route(
+            path=endpoint or DEFAULT_ENDPOINT,
+            endpoint=self._api_endpoint,
+            methods=["GET"],
+            response_model=MonitoringState,
+        )
+
+    def reset(self) -> None:
+        """Reset the monitoring agent to its initial state.
+
+        Clears all state variables and resets timers, but does not stop
+        any running threads. Use stop() method to stop the monitoring agent.
+
+        Note: This method does NOT kill the monitoring thread.
+        Use stop() or restart() for thread management.
+        """
+        with self._state_lock:
+            self._state = MonitoringState()
+            self._update_time = 0.0
+            self._startup_time = _now()
+        _logger.debug("State reset")
+
+    def _set_state(self, state: StateValue) -> None:
+        """Internal method to update the state with thread safety.
+
+        Args:
+            state: The state data to set, as a mapping/dictionary
+        """
+        with self._state_lock:
+            self._state.state = state
+        _logger.debug("State updated: %r", state)
+
+    def publish(self, state: StateSource) -> Self:
+        """Set the application state.
+
+        Args:
+            state: Either a callable that returns state data, or a mapping/dictionary
+                   containing the state data directly
+
+        Returns:
+            Self: Returns self for method chaining
+
+        Examples:
+            # Direct state setting
+            agent.publish({"status": "running", "count": 42})
+
+            # Using a callback function
+            def get_current_state():
+                return {"status": "running", "count": get_count()}
+            agent.publish(get_current_state)
+        """
+        _state: Mapping[str, Any] = {}
+        if callable(state):
+            self._state_callback = state
+            _state = state()
+            _logger.debug("State callback registered and executed")
+        else:
+            self._state_callback = None
+            if isinstance(state, Mapping):
+                _state = dict(state)
+            else:
+                _logger.warning("Unsupported state value: %r", state)
+        self._set_state(_state)
+        return self
+
+    def _uptime(self, now: Optional[float] = None) -> int:
+        return int((now or _now()) - self._startup_time)
+
+    def _update_internal_state(self, now: Optional[float] = None) -> None:
+        """Update the internal state with global monitoring information.
+
+        Updates system-level monitoring data like uptime.
+        """
+        try:
+            self._state.internal.uptime = self._uptime(now)
+        except Exception as exc:
+            _logger.error("Failed to update internal state: %s", exc)
+            raise
+
+    def _update_deferred(self, now: float) -> bool:
+        if now - self._update_time < UPDATE_HOLDOFF:
+            return True
+        self._update_time = now
+        return False
+
+    def _update_state(self) -> None:
+        """Update the monitoring state if sufficient time has passed.
+
+        This method implements rate-limiting to prevent excessive state updates.
+        Only updates the state if UPDATE_HOLDOFF seconds have passed since
+        the last update.
+        """
+        now = _now()
+        if self._update_deferred(now):
+            return
+        try:
+            self._update_internal_state(now)
+            if self._state_callback:
+                self._set_state(self._state_callback())
+        except ValueError as ve:
+            _logger.error("Invalid state value during update: %s", ve)
+        except RuntimeError as re:
+            _logger.error("Runtime error during state update: %s", re)
+        except Exception as exc:
+            _logger.error("Unexpected error during state update: %s", exc)
+
+    def _api_endpoint(self) -> MonitoringState:
+        """Get the current monitoring status.
+
+        Returns the complete monitoring state including both internal
+        monitoring data and application state.
+
+        Returns:
+            Dict[str, Any]: Dictionary containing 'internal' and 'state' keys
+
+        Note:
+            This method is called by the FastAPI endpoint and implements
+            error handling to ensure a response is always returned.
+        """
+        try:
+            with self._state_lock:
+                self._update_state()
+                return self._state
+        except Exception as exc:
+            _logger.error("Failed to provide monitoring status: %s", exc)
+            # Return minimal state even on error
+            return MonitoringState(internal=InternalState(uptime=self._uptime()))
+
+    def _worker(
+        self,
+        host: str,
+        port: int,
+        log_level: Optional[Union[int, str]] = None,
+    ) -> None:
+        """Main monitoring worker thread function.
+
+        Starts the FastAPI application with uvicorn server and handles
+        the monitoring endpoint.
+
+        Args:
+            host: Host address to bind to
+            port: Port number to listen on
+            log_level: Logging level for uvicorn
+        """
+        try:
+            app = FastAPI()
+            app.include_router(self.router)
+
+            config = uvicorn.Config(
+                app=app,
+                host=host,
+                port=port,
+                log_level=log_level,
+            )
+            self._uvicorn_server = uvicorn.Server(config)
+
+            _logger.info("Starting monitoring worker on %s:%d", host, port)
+
+            # Update state once on startup
+            self._update_state()
+
+            self._uvicorn_server.run()
+        except Exception as exc:
+            _logger.error("Monitoring worker failed to start: %s", exc)
+            raise
+
+    def _worker_alive(self) -> bool:
+        return bool(self._worker_thread and self._worker_thread.is_alive())
+
+    def start(
+        self,
+        *,
+        state: Optional[StateSource] = None,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        log_level: Optional[Union[int, str]] = None,
+        blocking: bool = False,
+    ) -> None:
+        try:
+            if self._worker_alive():
+                raise RuntimeError("Monitoring worker already running")
+
+            self.reset()
+            self.publish(state or {})
+
+            actual_host = host or DEFAULT_HOST
+            actual_port = port or DEFAULT_PORT
+
+            self._worker_thread = threading.Thread(
+                target=self._worker,
+                args=(actual_host, actual_port, log_level),
+                daemon=True,
+            )
+            self._worker_thread.start()
+            _logger.debug("Monitoring worker started successfully")
+
+            if blocking:
+                try:
+                    self._worker_thread.join()
+                except KeyboardInterrupt:
+                    _logger.debug("Received keyboard interrupt, stopping monitoring worker")
+                    self.stop()
+                    raise
+        except Exception as exc:
+            _logger.error("Failed to start monitoring worker: %s", exc)
+            raise
+
+    def stop(self) -> None:
+        try:
+            if self._uvicorn_server:
+                self._uvicorn_server.should_exit = True
+                _logger.debug("Signaled uvicorn server to exit")
+
+            if self._worker_thread:
+                self._worker_thread.join(timeout=5)
+                if self._worker_thread.is_alive():
+                    _logger.warning("Monitoring worker did not terminate within timeout")
+                self._worker_thread = None
+                _logger.debug("Monitoring worker joined successfully")
+
+            self._uvicorn_server = None
+            _logger.debug("Monitoring worker stopped successfully")
+        except RuntimeError as re:
+            _logger.error("Runtime error during worker shutdown: %s", re)
+        except Exception as exc:
+            _logger.error("Unexpected error during worker shutdown: %s", exc)
+
+
+# Singleton instance
+_instance: Optional[StatusReporter] = None
+
+
+def _get_instance() -> StatusReporter:
+    global _instance
+    if _instance is None:
+        _instance = StatusReporter()
+    return _instance
+
+
+def publish(state: StateSource) -> None:
+    _get_instance().publish(state)
+
+
+def start(
+    *,
+    state: Optional[StateSource] = None,
+    host: Optional[str] = None,
+    port: Optional[int] = None,
+    log_level: Optional[Union[int, str]] = None,
+    blocking: bool = False,
+) -> None:
+    _get_instance().start(
+        state=state,
+        port=port,
+        blocking=blocking,
+        host=host,
+        log_level=log_level,
+    )
+
+
+def stop() -> None:
+    _get_instance().stop()
+
+
+def reset() -> None:
+    """Reset the global agent state. For testing purposes only."""
+    _get_instance().reset()