Refactor service spawning: add ForgeActor.options().as_service() API

[DNXie]

This PR refactors how services are spawned for ForgeActor instances, providing a more actor-centric and user-friendly API. It is based on the discussion in #133

Before:

policy = await spawn_service(
    ServiceConfig(num_replicas=1, procs_per_replica=2),
    Policy,
    **cfg.policy,
)
shutdown_service(policy)

After:

Option 1: pass service configs

policy = await Policy.options(num_replicas=1, procs_per_replica=2).as_service(**cfg.policy)

Option 2: pass ServiceConfig object directly

cfg = ServiceConfig(num_replicas=1, procs_per_replica=2)
policy = await Policy.options(service_config=cfg).as_service(**cfg.policy)

Option 3: use the default configuration

# by default uses num_replicas=1, procs_per_replica = 1
policy = await Policy.as_service(**cfg.policy)

To shutdown:

policy.shutdown()

Changes introduced:

• Added ForgeActor.options() class method, which returns a pre-configured ForgeActor subclass.
• Updated ForgeActor.as_service() to spawn the service asynchronously and return a ServiceInterface.
• Added ServiceInterface.shutdown() to allow shutting down the underlying service directly.
• Updated test files tests/unit_tests/test_service.py and tests/integration_tests/test_policy_update.py.
• Added two new unit tests in tests/unit_tests/test_service.py to verify all three construction options (explicit ServiceConfig, implicit kwargs, and defaults) work correctly.
• Updated all service usages in code to align with the new API.
• Removed spawn_service() and shutdown_service().

Test:

pytest tests/unit_tests/test_service.py
pytest tests/integration_tests/test_policy_update.py
python -m apps.grpo.main --config apps/grpo/qwen3_1_7b.yaml
python -m apps.rl.main --config apps/rl/llama3_8b.yaml
python -m apps.vllm.main --config apps/vllm/llama3_8b.yaml

[DNXie]

@allenwang28 I removed spawn_service and shutdown_service as we don't need them anymore. How about spawn_service_v2, shutdown_service_v2? Actually the question is: do we need ServiceActor (as well as ServiceInterfaceV2)? It is never used.

And the way how ServiceActor initiates Service, looks buggy to me.

[allenwang28]

Can we remove the ConfiguredService piece altogether? options() should return a type["ForgeActor"]

[DNXie]

The main reason we have the ConfiguredService wrapper is to allow direct access to actor endpoints via instance attributes (e.g., service.value.choose()) while still carrying the ServiceConfig on the class.

If we remove the wrapper and make options() return a subclass of ForgeActor directly, the endpoints (like counter.value) are only accessible through the underlying ServiceInterface. So we need to change the statement

await service.value.choose()

to

await service._service_interface.value.choose()

I attempted to delegate EndpointProperty access via __getattr__ like this

def __getattr__(self, item):
    if self._service_interface is None:
        raise AttributeError(f"Service not started yet; cannot access '{item}'")
    
    attr = getattr(self._service_interface, item)
    from monarch._src.actor.endpoint import EndpointProperty
    if isinstance(attr, EndpointProperty):
        # Call the descriptor's __get__ to bind it
        return attr.__get__(self._service_interface, type(self._service_interface))

    return attr

However, it didn’t fully work: Python descriptors like EndpointProperty only bind correctly when accessed through the class or a properly initialized ServiceInterface instance. The __get__ call in __getattr__ does not fully replicate the descriptor binding behavior.

I’m still getting familiar with the internals of Monarch and some of the Python descriptor mechanics, so I'd love to hear any suggestions if there’s a cleaner way to handle this.

[allenwang28]

hmm, EndpointProperty binding is only needed after we do as_service() right?

this is how I imagine the options piece:

class ForgeActor(Actor):
    _service_config: ServiceConfig | None = None

    @classmethod
    def options(
        cls,
        *,
        service_config: ServiceConfig | None = None,
        num_replicas: int | None = None,
        procs_per_replica: int | None = None,
        **service_kwargs,
    ) -> Type["ForgeActor"]:
        if service_config:
            config = service_config
        else:
            config = ServiceConfig(num_replicas=num_replicas, procs_per_replica=procs_per_replica)  
        return type(
            f"{cls.__name__}",
            (cls,),
            {"_service_config": config}
        )```

[DNXie]

EndpointProperty binding is only needed after we do as_service() right?

Yes. It is needed whenever we call an endpoint function.

Your proposed implementation seems reasonable. However, it does not handle endpoint binding. After as_service(), you still need to go through service._service_interface to access endpoints.

[DNXie]

As we discussed offline, if as_service returns a ServiceInterface directly, we cannot terminate the service with

service.shutdown()

because the returned object (service) is just a ServiceInterface. In that case, we’d have to fall back to

shutdown_service(service)

Personally, I prefer the service.shutdown() style since it feels more natural and object-oriented, but I’m okay with either one.

[allenwang28]

We can add def shutdown(self) directly to ServiceInterface

[DNXie]

Done!

[allenwang28]

Actually the question is: do we need ServiceActor (as well as ServiceInterfaceV2)? It is never used.

yeah please leave it for now, I'm gonna clean this all up once HostMesh lands 😅

[allenwang28]

this is fine, just curious if this is a circular dependency issue?

[DNXie]

Yes. There would be a circular dependency issue

[allenwang28]

beautiful, thank you! Can you message the Forge devs group about the updates? There are a few PRs in flight that will have to rebase, please let them know what changed and how to rebase