rats-apps 0.10.3.dev20250520163928__py3-none-any.whl → 0.11.0.dev20250521180658__py3-none-any.whl

rats/app_context/__init__.py

@@ -1,4 +1,55 @@
-"""Application context package to help share [apps.Container][] state across machines."""
+"""
+Allows marshaling of simple value objects across processes and machines.
+
+The [rats.app_context.Collection][] and [rats.app_context.Context][] classes are the building
+blocks for creating a collection of services that can be serialized to json and shared across
+applications. In order to be easily serializable, all service values managed by this module must
+be instances of [dataclasses.dataclass][], must be immutable, and must be made up of simple value
+types.
+
+!!! example
+    If we have an example data structure, `MySimpleData`, we can store instances of it into a
+    [rats.app_context.Context][] object by assigning them a service id. Every service id in a
+    context maps to zero or more instances of our data structure. Zero or more context objects can
+    be used to create [rats.app_context.Collection][] instances, which can be serialized with the
+    [rats.app_context.dumps][] and [rats.app_context.loads][] functions.
+
+    ```python
+    from dataclasses import dataclass
+    from rats import apps, app_context
+
+
+    @dataclass(frozen=True)
+    class MySimpleData:
+        blob_path: tuple[str, str, str]
+        offset: int
+
+
+    data1 = MySimpleData(
+        blob_path=("accountname", "containername", "/some/blob/path"),
+        offset=3,
+    )
+
+    data2 = MySimpleData(
+        blob_path=("accountname", "containername", "/another/blob/path"),
+        offset=3,
+    )
+
+    service_id = apps.ServiceId[MySimpleData]("example-service")
+
+    ctx = app_context.Context[MySimpleData].make(service_id, data1, data2)
+    collection = app_context.Collection.make(ctx)
+
+    # the encoded json string can be moved between machines through files, env variables, etc.
+    json_encoded = app_context.dumps(collection)
+    # on the remote process, we can rebuild the original collection object
+    original_collection = app_context.loads(json_encoded)
+    # we can retrieve the json-encoded contexts
+    values = original_collection.values(service_id)
+    # and we can decode the values back into the `MySimpleData` instances
+    simple_data_instances = original_collection.decoded_values(MySimpleData, service_id)
+    ```
+"""
 
 from ._collection import (
     EMPTY_COLLECTION,
@@ -7,12 +58,13 @@ from ._collection import (
     loads,
 )
 from ._container import GroupContainer, ServiceContainer
-from ._context import Context, T_ContextType
+from ._context import Context, ContextValue, T_ContextType
 
 __all__ = [
     "EMPTY_COLLECTION",
     "Collection",
     "Context",
+    "ContextValue",
     "GroupContainer",
     "ServiceContainer",
     "T_ContextType",

rats/app_context/_collection.py

@@ -25,24 +25,37 @@ class Collection(Generic[T_ContextType]):
     """
 
     items: tuple[Context[T_ContextType], ...]
+    """Access to the raw [rats.app_context.Context][] instances in the collection."""
 
     @staticmethod
     def merge(*collections: Collection[T_ContextType]) -> Collection[T_ContextType]:
+        """
+        Merge multiple collections into a new, combined instance.
+
+        Args:
+            *collections: zero or more collections to merge into one.
+        """
         return Collection[T_ContextType].make(
             *[ctx for collection in collections for ctx in collection.items]
         )
 
     @staticmethod
     def empty() -> Collection[T_ContextType]:
-        """Useful when wanting to define a simple default value for a context collection."""
+        """A shortcut to retrieving an empty collection."""
         return Collection(items=())
 
     @staticmethod
     def make(*items: Context[T_ContextType]) -> Collection[T_ContextType]:
-        # just a handy shortcut to remove a nested tuple from the end-user code.
+        """
+        Convenience function to create a collection from a list of contexts.
+
+        Args:
+            *items: zero or more context objects to turn into a collection.
+        """
         return Collection(items=items)
 
     def service_ids(self) -> set[apps.ServiceId[T_ContextType]]:
+        """Get the list of service items found in the collection, across all context instances."""
         return {item.service_id for item in self.items}
 
     def decoded_values(
@@ -50,9 +63,31 @@ class Collection(Generic[T_ContextType]):
         cls: type[T_ContextType],
         service_id: apps.ServiceId[T_ContextType],
     ) -> tuple[T_ContextType, ...]:
+        """
+        Given a reference to a dataclass type, retrieves and builds instances matching a service id.
+
+        !!! info
+            The dataclass used in the two communicating processes does not need to be the same, but
+            we expect the constructor arguments to be compatible.
+
+        Args:
+            cls: the type all selected context objects will be cast into before returning.
+            service_id: the selector for the expected context objects.
+        """
         return tuple(dataclass_wizard.fromlist(cls, list(self.values(service_id))))
 
     def values(self, service_id: apps.ServiceId[T_ContextType]) -> tuple[ContextValue, ...]:
+        """
+        Retrieves the raw data structures matching a service id.
+
+        The values returned here have been encoded into simple dictionaries and are ready to be
+        serialized and transferred across machines. See the
+        [rats.app_context.Collection.decoded_values][] method to retrieve context values that have
+        been turned back into the desired dataclass objects.
+
+        Args:
+            service_id: the selector for the expected context objects.
+        """
         results: list[ContextValue] = []
         for item in self.with_id(service_id).items:
             for value in item.values:
@@ -61,19 +96,32 @@ class Collection(Generic[T_ContextType]):
         return tuple(results)
 
     def add(self, *items: Context[T_ContextType]) -> Collection[T_ContextType]:
-        """Creates a new Collection with the provided items added to the current ones."""
+        """
+        Creates a new Collection with the provided items added to the current ones.
+
+        Args:
+            *items: the context items to be added in the new collection.
+        """
         return Collection[T_ContextType].make(
             *self.items,
             *items,
         )
 
     def with_id(self, *service_ids: apps.ServiceId[T_ContextType]) -> Collection[T_ContextType]:
-        """Filter out context items not matching the provided service ids and return a new Collection."""
+        """
+        Filter out context items not matching the provided service ids and return a new Collection.
+
+        Args:
+            *service_ids: the selector for the returned context collection.
+        """
         return Collection[T_ContextType](
             items=tuple(item for item in self.items if item.service_id in service_ids),
         )
 
 
+# disable key transformation for our collection class
+dataclass_wizard.DumpMeta(key_transform="NONE").bind_to(Collection)  # type: ignore[reportUnknownMemberType]
+dataclass_wizard.LoadMeta(key_transform="NONE").bind_to(Collection)  # type: ignore[reportUnknownMemberType]
 EMPTY_COLLECTION = Collection[Any].empty()
 """Empty collection constant usable as default method values."""
 
@@ -92,10 +140,10 @@ def loads(context: str) -> Collection[Any]:
         items=tuple(
             [
                 Context(
-                    service_id=apps.ServiceId(*x["serviceId"]),
+                    service_id=apps.ServiceId(*x["service_id"]),
                     values=tuple(x["values"]),
                 )
-                for x in data["items"]
+                for x in data.get("items", [])
             ]
         ),
     )
@@ -107,8 +155,5 @@ def dumps(collection: Collection[Any]) -> str:
 
     Args:
         collection: collection of serializable services wanting to be shared between machines.
-
-    Returns: a string that can easily be shared between machines.
-
     """
-    return json.dumps(dataclass_wizard.asdict(collection))  # type: ignore
+    return json.dumps(dataclass_wizard.asdict(collection), indent=4)  # type: ignore

rats/app_context/_context.py

@@ -10,7 +10,17 @@ from rats import apps
 
 logger = logging.getLogger(__name__)
 T_ContextType = TypeVar("T_ContextType")  # TODO: figure out how to bind this to dataclasses :(
+"""
+Generic type for context value objects.
+
+!!! warning
+    Python lacks the ability to bind generic values to require them to be a
+    [dataclasses.dataclass][] instance, but all [rats.app_context.T_ContextType][] instances must
+    be dataclasses in order for them to serialize and deserialize. This is mostly a leaky private
+    detail, and we hope to remove this requirement in the future.
+"""
 ContextValue = dict[str, Any]
+"""Values found in [rats.app_context.Context][] in their simple value type representations."""
 
 
 @final
@@ -25,7 +35,11 @@ class Context(dataclass_wizard.JSONSerializable, Generic[T_ContextType]):
     """
 
     service_id: apps.ServiceId[T_ContextType]
+    """
+    The [rats.apps.ServiceId][] the remote app will be able to use to retrieve the stored values.
+    """
     values: tuple[ContextValue, ...]
+    """The encoded value object, ready to be turned into json for marshaling."""
 
     @staticmethod
     def make(
@@ -39,18 +53,28 @@ class Context(dataclass_wizard.JSONSerializable, Generic[T_ContextType]):
         from dataclass import dataclass
 
 
+        @dataclass(frozen=True)
         class MySimpleData:
             blob_path: Tuple[str, str, str]
             offset: int
 
 
+        service_id = apps.ServiceId[MySimpleData]("example-service")
         ctx = app_context.Context[MySimpleData].make(
+            service_id,
             MySimpleData(
                 blob_path=("accountname", "containername", "/some/blob/path"),
-            )
+            ),
         )
         ```
+
+        Args:
+            service_id: The service id the context values will be retrievable as.
+            *contexts: Zero or more [rats.app_context.T_ContextType][] instances.
         """
+        if len(contexts) > 0:
+            cls = contexts[0].__class__
+            dataclass_wizard.DumpMeta(key_transform="NONE").bind_to(cls)  # type: ignore[reportUnknownMemberType]
         return Context(
             service_id,
             tuple([dataclass_wizard.asdict(ctx) for ctx in contexts]),  # type: ignore

rats/cli/_click_app.py

@@ -40,7 +40,7 @@ class ClickApp(apps.Executable):
         Attach any commands provided by the [rats.cli.Container][] and then execute the group.
 
         !!! note
-            Currently, this method runs [click.BaseCommand.main][] without arguments, causing Click
+            Currently, this method runs [click.Command.main][] without arguments, causing Click
             to pull the command arguments from [sys.argv][]. If you are needing to change this,
             skip using this class and implement the custom logic yourself.
         """

rats/logs/__init__.py

@@ -1,7 +1,22 @@
-"""Small package to help configure logging for rats applications."""
+"""
+Small module to help configure logging for rats applications.
 
-from ._app import ConfigureApplication
+We provide a rats application that can be executed at the beginning of your process, that will
+handle configuring the python logging libraries, with a few configuration options being exposed.
+
+!!! warning
+    We expose the logging functionality through a [rats.apps.AppContainer][] in order to leverage
+    the built in plugin system to give users the ability to adjust the default settings, but this
+    entire application should be lightweight and should not contain very complex logic, avoiding
+    logic that is very time consuming or has a chance of failing with confusing errors.
+
+    If the logging options made available through this module are far from what is desired, instead
+    of adding flags and options to this module, we recommend configuring logging in your own code.
+"""
+
+from ._app import AppConfigs, ConfigureApplication
 
 __all__ = [
+    "AppConfigs",
     "ConfigureApplication",
 ]

rats/logs/_app.py

@@ -1,12 +1,58 @@
 import logging.config
+import warnings
+from collections.abc import Iterator
+from typing import Any
 
 from rats import apps
 
 logger = logging.getLogger(__name__)
+LoggerConfigEntry = tuple[str, dict[str, Any]]
+
+
+@apps.autoscope
+class AppConfigs:
+    LOGGERS = apps.ServiceId[LoggerConfigEntry]("loggers.config-group")
+    """
+    Register additional loggers to this service group.
+
+    ```python
+    from rats import apps
+
+
+    class PluginContainer(apps.Container, apps.PluginMixin):
+        @apps.group(AppConfigs.LOGGERS)
+        def _custom_loggers(self) -> Iterator[LoggerConfigEntry]:
+            yield "", {"level": "INFO", "handlers": ["console"]}
+            yield "azure", {"level": "WARNING", "handlers": ["console"]}
+
+
+    # provide the new configuration when executing `logs.ConfigureAppilcation`
+    apps.run(apps.AppBundle(
+        app_plugin=logs.ConfigureApplication,
+        container_plugin=PluginContainer,
+    ))
+    ```
+    """
 
 
 class ConfigureApplication(apps.AppContainer, apps.PluginMixin):
+    """
+    Configure logging for the current process.
+
+    We try to provide some simple default loggers, but you can replace the loggers by providing the
+    [rats.logs.AppConfigs.LOGGERS][] service group.
+
+    ```python
+    from rats import apps, logs
+
+    apps.run(apps.AppBundle(app_plugin=logs.ConfigureApplication))
+    ```
+    """
+
     def execute(self) -> None:
+        """Applies the logging configuration."""
+        logger_configs = self._app.get_group(AppConfigs.LOGGERS)
+        loggers_dict = {key: value for key, value in logger_configs}
         logging.config.dictConfig(
             {
                 "version": 1,
@@ -36,10 +82,15 @@ class ConfigureApplication(apps.AppContainer, apps.PluginMixin):
                         "stream": "ext://sys.stderr",
                     }
                 },
-                "loggers": {
-                    "": {"level": "INFO", "handlers": ["console"]},
-                    "azure": {"level": "WARNING", "handlers": ["console"]},
-                },
+                "loggers": loggers_dict,
             }
         )
+        # enable deprecation warnings by default
+        logging.captureWarnings(True)
+        warnings.simplefilter("default", DeprecationWarning)
         logger.debug("done configuring logging")
+
+    @apps.fallback_group(AppConfigs.LOGGERS)
+    def _default_loggers(self) -> Iterator[LoggerConfigEntry]:
+        yield "", {"level": "INFO", "handlers": ["console"]}
+        yield "azure", {"level": "WARNING", "handlers": ["console"]}

rats/runtime/__init__.py

@@ -0,0 +1,64 @@
+"""
+Run rats applications, providing external context.
+
+The provided `rats-runtime` cli allows the registration and execution of [rats.apps.AppContainer][]
+applications. Register to the python plugin group called `rats.runtime.apps`, and list available
+plugins with `rats-runtime list`.
+
+```toml title="pyproject.toml"
+[project.entry-points."rats.runtime.apps"]
+"rats_e2e.runtime" = "rats_e2e.runtime:Application"
+```
+
+We register an example application you can run with `rats-runtime run rats_e2e.runtime`. The name
+of the registered entry point in your `pyproject.toml` will map to the name provided to
+`rats-runtime run`.
+
+```bash
+$ rats-runtime run rats_e2e.runtime
+hello, world!
+looking for any registered context: rats_e2e.runtime._app:AppServices[example-data]
+```
+
+Our example application looks for any context services, which can be provided to the `run` command.
+
+=== "/code"
+    ```bash
+    $ rats-runtime run \
+        rats_e2e.runtime \
+        --context-file src/rats_resources/runtime/example-context.yaml
+    hello, world!
+    looking for any registered context: rats_e2e.runtime._app:AppServices[example-data]
+    found example data element: ExampleData(id='111', thing_a='111', thing_b='111')
+    found example data element: ExampleData(id='222', thing_a='222', thing_b='222')
+    ```
+=== "src/rats_resources/runtime/example-context.yaml"
+    ```yaml
+    --8<-- "rats_resources/runtime/example-context.yaml"
+    ```
+=== "src/rats_e2e/runtime/_app.py"
+    ```python
+    --8<-- "rats_e2e/runtime/_app.py"
+    ```
+=== "src/rats_e2e/runtime/_data.py"
+    ```python
+    --8<-- "rats_e2e/runtime/_data.py"
+    ```
+
+!!! info
+    Most users won't typically use `rats-runtime` directly, but this interface is used by other
+    abstractions to execute applications remotely, like the [rats.aml][] module, adding the ability
+    to execute applications within an azure ml job.
+"""
+
+from ._app import Application, AppServices, main
+from ._request import DuplicateRequestError, Request, RequestNotFoundError
+
+__all__ = [
+    "AppServices",
+    "Application",
+    "DuplicateRequestError",
+    "Request",
+    "RequestNotFoundError",
+    "main",
+]

rats/runtime/__main__.py

@@ -0,0 +1,5 @@
+"""Run the rats-runtime commands."""
+
+from rats import runtime
+
+runtime.main()

rats/runtime/_app.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from collections.abc import Iterator
+from functools import cache
+from importlib import metadata
+from importlib.metadata import EntryPoint
+from pathlib import Path
+from typing import Any, final
+
+import click
+import yaml
+
+from rats import app_context, apps, cli, logs
+
+from ._request import DuplicateRequestError, Request, RequestNotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+@apps.autoscope
+class AppServices:
+    """Services used by the `rats.runtime.Application` cli command."""
+
+    CONTEXT = apps.ServiceId[app_context.Collection[Any]]("app-ctx-collection.config")
+    """
+    [rats.app_context.Collection][] available in the application run using `rats-runtime run`.
+
+    ```python
+    from rats import apps, runtime
+
+
+    class Application(apps.AppContainer, apps.PluginMixin):
+        def execute(self) -> None:
+            context = self._app.get(runtime.AppConfigs.CONTEXT)
+            print("loaded context:")
+            for item in context_collection.items:
+                print(f"{item.service_id} -> {item.values}")
+    ```
+    """
+    REQUEST = apps.ServiceId[Request]("runtime-details-client")
+    """
+    The request information, available after the call to [rats.runtime.Application.execute][].
+    """
+
+
+@final
+class Application(apps.AppContainer, cli.Container, apps.PluginMixin):
+    """
+    The `rats-runtime` cli application.
+
+    ```bash
+    $ rats-runtime --help
+    Usage: rats-runtime [OPTIONS] COMMAND [ARGS]...
+
+    Options:
+      --help  Show this message and exit.
+
+    Commands:
+      list  List all the exes and groups that are configured to run with `rats-
+            runtime run`.
+      run   Run one or more apps, adding an optional additional context.
+    ```
+    """
+
+    _request: Request | None = None
+
+    def execute(self) -> None:
+        """Runs the `rats-runtime` cli."""
+        argv = self._app.get(cli.PluginConfigs.ARGV)
+        cli.create_group(click.Group("rats-runtime"), self).main(
+            args=argv[1:],
+            prog_name=Path(argv[0]).name,
+            auto_envvar_prefix="RATS_RUNTIME",
+            # don't end the process
+            standalone_mode=False,
+        )
+
+    @cli.command()
+    def _list(self) -> None:
+        """List all the exes and groups that are configured to run with `rats-runtime run`."""
+        for entry in self._get_app_entrypoints():
+            click.echo(entry.name)
+
+    @cli.command()
+    @click.argument("app-ids", nargs=-1)
+    @click.option("--context", default="{}")
+    @click.option("--context-file")
+    def _run(self, app_ids: tuple[str, ...], context: str, context_file: str | None) -> None:
+        """Run one or more apps, adding an optional additional context."""
+        if self._request is not None:
+            print(self._request)
+            raise DuplicateRequestError()
+
+        ctx_collection = app_context.loads(context)
+        if context_file:
+            p = Path(context_file)
+            if not p.is_file():
+                raise RuntimeError(f"context file not found: {context_file}")
+
+            data = yaml.safe_load(p.read_text())
+            ctx_collection = ctx_collection.merge(app_context.loads(json.dumps(data)))
+
+        self._request = Request(
+            app_ids=app_ids,
+            context=ctx_collection,
+        )
+
+        def _load_app(name: str, ctx: app_context.Collection[Any]) -> apps.AppContainer:
+            return apps.AppBundle(
+                app_plugin=self._find_app(name),
+                context=apps.StaticContainer(
+                    apps.StaticProvider(
+                        namespace=apps.ProviderNamespaces.SERVICES,
+                        service_id=AppServices.CONTEXT,
+                        call=lambda: ctx,
+                    ),
+                ),
+            )
+
+        if len(app_ids) == 0:
+            logger.warning("No applications were passed to the command")
+
+        for app_id in app_ids:
+            app = _load_app(app_id, ctx_collection)
+            app.execute()
+
+    def _find_app(self, name: str) -> type[apps.AppContainer]:
+        for e in self._get_app_entrypoints():
+            if e.name == name:
+                return e.load()
+
+        raise RuntimeError(f"rats app-id not found: {name}")
+
+    @cache  # noqa: B019
+    def _get_app_entrypoints(self) -> Iterator[EntryPoint]:
+        yield from metadata.entry_points(group="rats.runtime.apps")
+
+    @apps.service(AppServices.REQUEST)
+    def _request_provider(self) -> Request:
+        if self._request is None:
+            raise RequestNotFoundError()
+
+        return self._request
+
+    @apps.container()
+    def _plugins(self) -> apps.Container:
+        return cli.PluginContainer(self._app)
+
+
+def main() -> None:
+    """Main entry-point to the `rats-runtime` cli command."""
+    try:
+        apps.run_plugin(logs.ConfigureApplication)
+        apps.run_plugin(Application)
+    except click.exceptions.ClickException as e:
+        e.show()
+        sys.exit(e.exit_code)

rats/runtime/_request.py

@@ -0,0 +1,23 @@
+from typing import Any, NamedTuple
+
+from rats import app_context
+
+
+class Request(NamedTuple):
+    app_ids: tuple[str, ...]
+    """The app ids being run by [rats.runtime.Application][]."""
+
+    context: app_context.Collection[Any]
+    """The [rats.app_context.Collection][] that was submitted and made available to executed apps."""
+
+
+class RequestNotFoundError(RuntimeError):
+    """Thrown if [rats.runtime.AppServices.REQUEST][] is accessed without the application being run."""
+
+    def __init__(self) -> None:
+        super().__init__("no running runtime request found.")
+
+
+class DuplicateRequestError(RuntimeError):
+    def __init__(self) -> None:
+        super().__init__("request already executed.")

{rats_apps-0.10.3.dev20250520163928.dist-info → rats_apps-0.11.0.dev20250521180658.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: rats-apps
-Version: 0.10.3.dev20250520163928
+Version: 0.11.0.dev20250521180658
 Summary: research analysis tools for building applications
 License: MIT
 Keywords: pipelines,machine learning,research
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: click
 Requires-Dist: colorlog
 Requires-Dist: dataclass-wizard
+Requires-Dist: pyyaml
 Requires-Dist: typing-extensions
 Project-URL: Documentation, https://microsoft.github.io/rats
 Project-URL: Repository, https://github.com/microsoft/rats

{rats_apps-0.10.3.dev20250520163928.dist-info → rats_apps-0.11.0.dev20250521180658.dist-info}/RECORD

@@ -2,10 +2,10 @@ rats/annotations/__init__.py,sha256=YmydaopUSlpoX6MvQ-3p18sgEC_DB_y683wVICD-jnU,
 rats/annotations/__main__.py,sha256=vlzQOM9y82P0OL5tYcmSM_4jTg0s8jayAcvEoi9cBvI,1065
 rats/annotations/_functions.py,sha256=UkHh3zdBivluE7dBeGQ17zoIfGdyIokMAkFmpWaIlDc,4284
 rats/annotations/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rats/app_context/__init__.py,sha256=WHFPJXl7WHHIgfQxzmDbGHIW8YTbDsCrusLlFctGW_o,447
-rats/app_context/_collection.py,sha256=5-Nog2Du2v0tAZbhsbpg3vMjMcZ--hSZ4acWM2HTlMY,3717
+rats/app_context/__init__.py,sha256=8d8LCe2fOi4_W1bPnJlk5t_HETHW8sV4c35z5iwAuxo,2529
+rats/app_context/_collection.py,sha256=f9sqdAokVsyt7zFz0Va7_48wK18wT44H7berPrx2RpM,5571
 rats/app_context/_container.py,sha256=YkNG25jngfN_064jv8fZmKW1FSuL6RRJAp9F_hm2NZg,2954
-rats/app_context/_context.py,sha256=VUm-cg2WKtFU2VvIJI8OmTdRRoDLXeWPBYu_ynpUjlY,1599
+rats/app_context/_context.py,sha256=S7D8NLefZJI4MDEpYKdenfNsemus4bUlQCG-gd3U3g8,2777
 rats/app_context/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats/apps/__init__.py,sha256=6B5qQvzx1xlRrNRY4QJi6GEywuQ1MoW454kC4nO2Yqg,2084
 rats/apps/_annotations.py,sha256=6M_M7K8haNVda0Tx02EpFf3s9EjnWYacNMjTIkNEdRU,4617
@@ -24,15 +24,20 @@ rats/apps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats/cli/__init__.py,sha256=zMywV-4vqbtlobIoMItwbxxdvYGC20wiGU2TKm3II2A,714
 rats/cli/__main__.py,sha256=WeldAKjA3Kmz9ZRnZVd3G8Ud66Y_gSRDLIPNE1JyhV0,1418
 rats/cli/_annotations.py,sha256=-B2Y1bYjPbeTNTBMZzMdAU92qu9AyutKHN_NdFy-xhA,2964
-rats/cli/_click_app.py,sha256=4z2jiRHafCAN7S-cbMhfQJhLGwl6ljFS3r6P1COgR00,1454
+rats/cli/_click_app.py,sha256=Jvs6OqNC4Yoe6kbc2tCzjzUieNFa1n_zwXPsdo971Wc,1450
 rats/cli/_command.py,sha256=kyU3UqqF9aiTTaFvlQFBKDLXvArQS1QgjoQqlMbKzok,597
 rats/cli/_container.py,sha256=FIQBqi9PTNpE2P52qkfGET51BczdD-JvcWXLTjCNPDI,3512
 rats/cli/_functions.py,sha256=BNmgWVquQUEqJAYsed_l8vLnlLP7u3XC1TDyEFI1AiU,1552
 rats/cli/_plugin.py,sha256=o-pmEqU6mVH3QoRfRBrbG-XRTWCzt6pLKtSV3-5VSx0,1144
 rats/cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rats/logs/__init__.py,sha256=sizLa6JbqekhJGKDyRZUUQvTuqiJx6yxwA5jT-tDQck,152
-rats/logs/_app.py,sha256=TF6rfQXQfaHd3AFW2anAoAGaxzU31kqJMoKkjuBtbF0,1617
+rats/logs/__init__.py,sha256=dSO-V2eu2W7w4w7oRau-UOfXXIkyZ2bHB6-kaasbeFM,970
+rats/logs/_app.py,sha256=SoTxk6g84tygOP_346NwXPcG1o6KZLd7lIgayq5vMdc,3239
 rats/logs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats/runtime/__init__.py,sha256=f9aEnynHuePP9OP5XCtB-6nCBvNWWlQQLTzuxFEueoQ,2150
+rats/runtime/__main__.py,sha256=y01yOymsL075poX95pc02sJR1HD0pDNFRZdpOdi0R6Y,79
+rats/runtime/_app.py,sha256=zR4o5kd3Xg6oJB-S92iG5ffoUafG1xDYQfcTBnshUuA,5001
+rats/runtime/_request.py,sha256=E2Oos_mkruPh4h-chys64AMFR_YMdrAx95avXsPeaog,706
+rats/runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 rats_e2e/apps/__init__.py,sha256=c2QG818ACyS9MBXs_Evg5yYT6k-KPMQfIqF7Z77Cau0,142
 rats_e2e/apps/__main__.py,sha256=ETECGDD8glcbmx0P-WWmjQQX6gtF-5L7_DxZjNmx3X4,350
 rats_e2e/apps/_example_cli.py,sha256=XzWOdnQrSp-F_FZEdm2CCm8dUJZWOSm2KFPIK0jzoi8,2840
@@ -42,6 +47,14 @@ rats_e2e/apps/inputs/_app.py,sha256=FiaLgOZc-d1ryKSwKnL5XBNGcOP1bHbxxeMJqoU_RJg,
 rats_e2e/apps/minimal/__init__.py,sha256=bUR6Oexx6Jsouxor0cL9emXoVha4cm3WqyhU1pgchsI,521
 rats_e2e/apps/minimal/__main__.py,sha256=Mf-a2iQKTTgh9hMd6AeuzmU9araMIyf1AtdWkh_L07E,117
 rats_e2e/apps/minimal/_app.py,sha256=CQ09LVTNRarz7Pb1wiSuNHrZ_2KGcgH8nUqy4BjxMUY,849
-rats_apps-0.10.3.dev20250520163928.dist-info/METADATA,sha256=8S_U7EpOEgolriB2hEv7VauOv1PKzo-R63MmSwFMXfE,867
-rats_apps-0.10.3.dev20250520163928.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-rats_apps-0.10.3.dev20250520163928.dist-info/RECORD,,
+rats_e2e/apps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats_e2e/runtime/__init__.py,sha256=0oWKhywQaXzjs2bHI3WHYBF8vIbK-NAWBJsxTal7sC0,163
+rats_e2e/runtime/_app.py,sha256=hz0BB15CIkjLsz8YPfZiIm9jKiOq8JFaHR7_cJGBkMA,790
+rats_e2e/runtime/_data.py,sha256=3d1F_JO2gEOPUjBp_KYMP3TefyneiG_ktlJjdIIYUy8,125
+rats_e2e/runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats_resources/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rats_resources/runtime/example-context.yaml,sha256=eiLsNFquFfkIpUhxUCQLzLigH21QF2F00fzA_e_aOKk,215
+rats_apps-0.11.0.dev20250521180658.dist-info/METADATA,sha256=dcJpnIbCfQHHsWtD0bjxHQ26671OecfVVNeISRUoJYg,889
+rats_apps-0.11.0.dev20250521180658.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+rats_apps-0.11.0.dev20250521180658.dist-info/entry_points.txt,sha256=Gf6bPwxIVjWd3Xx71upZo7eDJA5cujniLew6fxJMgA4,117
+rats_apps-0.11.0.dev20250521180658.dist-info/RECORD,,

rats_apps-0.11.0.dev20250521180658.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+rats-runtime=rats.runtime:main
+
+[rats.runtime.apps]
+rats_e2e.runtime=rats_e2e.runtime:Application
+

rats_e2e/runtime/__init__.py

@@ -0,0 +1,7 @@
+"""A small example application, registered to be run with `rats-runtime run rats_e2e.runtime`."""
+
+from ._app import Application
+
+__all__ = [
+    "Application",
+]

rats_e2e/runtime/_app.py

@@ -0,0 +1,23 @@
+from collections.abc import Iterator
+
+from rats import apps, runtime
+
+from ._data import ExampleData
+
+
+@apps.autoscope
+class AppServices:
+    EXAMPLE_DATA = apps.ServiceId[ExampleData]("example-data")
+
+
+class Application(apps.AppContainer, apps.PluginMixin):
+    def execute(self) -> None:
+        print("hello, world!")
+        print(f"looking for any registered context: {AppServices.EXAMPLE_DATA.name}")
+        for data in self._app.get_group(AppServices.EXAMPLE_DATA):
+            print(f"found example data element: {data}")
+
+    @apps.fallback_group(AppServices.EXAMPLE_DATA)
+    def _data_from_context(self) -> Iterator[ExampleData]:
+        collection = self._app.get(runtime.AppServices.CONTEXT)
+        yield from collection.decoded_values(ExampleData, AppServices.EXAMPLE_DATA)

rats_e2e/runtime/_data.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ExampleData:
+    id: str
+    thing_a: str
+    thing_b: str

rats_resources/runtime/example-context.yaml

@@ -0,0 +1,9 @@
+items:
+  - service_id: ["rats_e2e.runtime._app:AppServices[example-data]"]
+    values:
+      - id: "111"
+        thing_a: "111"
+        thing_b: "111"
+      - id: "222"
+        thing_a: "222"
+        thing_b: "222"