https://github.com/zen-xu/sunray
More robust and elegant ray
https://github.com/zen-xu/sunray
pythonic ray typing
Last synced: 4 months ago
JSON representation
More robust and elegant ray
- Host: GitHub
- URL: https://github.com/zen-xu/sunray
- Owner: zen-xu
- License: mit
- Created: 2024-02-06T12:56:48.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-09-29T19:27:27.000Z (5 months ago)
- Last Synced: 2025-10-02T16:44:05.580Z (4 months ago)
- Topics: pythonic, ray, typing
- Language: Python
- Homepage:
- Size: 484 KB
- Stars: 17
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Sunray
[](https://github.com/astral-sh/uv)
[](https://github.com/astral-sh/ruff)
[](https://github.com/zen-xu/sunray/actions/workflows/test.yaml)
[](https://github.com/zen-xu/sunray/actions/workflows/test-mypy.yaml)
[](https://codecov.io/gh/zen-xu/sunray)
[Ray](https://github.com/ray-project/ray) is a unified framework for scaling AI and Python applications. However, it falls short in offering friendly type hints, particularly when it comes to working with the `Actor`.
To address this shortfall, sunray provides enhanced and more robust type hints.
## install
```shell
pip install sunray
```
## Let's vs.
### Round 1: Build an actor
| sunray | ray |
| :-------------------------------------------------------------------------: | :----------------------------------------------------------------------: |
|  |  |
- sunray returns `Actor[Demo]`, but ray returns `ObjectRef[Demo]`
- ray mypy raise error `Type[Demo] has no attribute "remote"`
### Round 2: Get actor remote methods
| sunray | ray |
| :---------------------------------------------------------------------------------: | :------------------------------------------------------------------------------: |
|  |  |
- sunray list all remote methods
- ray list nothing
### Round 3: Actor remote method call
| sunray | ray |
| :--------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------: |
|  |  |
- sunray correctly provided parameter hints.
- ray ...
### Round 4: Annotate with Actor
| sunray | ray |
| :------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: |
|  |  |
- with sunray, just annotate it with `Actor[Demo]`.
- with ray, I don't known.
### Round 5: Stream
| sunray | ray |
| :--------------------------------------------------------------------------: | :-----------------------------------------------------------------------: |
|  |  |
- sunray correctly identified that `stream` returns a generator.
- ray still returns ObjectRef.
### Round 6: Unpack result
| sunray | ray |
| :--------------------------------------------------------------------------: | :-----------------------------------------------------------------------: |
|  |  |
- sunray will auto unpack tuple result if options specify `unpack=True`.
- ray need to specify how many return numbers, so you need to count it.
- ray mypy raise error 'RemoteFunctionNoArgs has no attribute "options"'.
### Round 7: Get actor
| sunray | ray |
| :-----------------------------------------------------------------------------: | :--------------------------------------------------------------------------: |
|  |  |
- sunray get_actor will return `ActorHandle`, and return `Actor[Demo]` if you specify with generic type.
- ray just return `Any`.
### Round 8: Call self remote method
| sunray | ray |
| :-------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------: |
|  |  |
- sunray maintains a consistent calling convention, whether it's from internal or external functions.
- ray, you need to first obtain the current actor from the running context, and then call through the actor.
### Round 9: Lazy Computation
| sunray | ray |
| :------------------------------------------------------------------------: | :---------------------------------------------------------------------: |
|  |  |
- sunray can successfully track the input parameter types and output types.
- ray does not have this capability.
## API
`sunray` re-export all apis from `ray.core` with friendly type hints. In addition, `sunray` provides `ActorMixin` which is used to help creating more robust actors.
### ActorMixin
`ActorMixin` is a mixin, and provides a classmethod `new_actor`
```python
import sunray
class Demo(
# Here to specify default actor options
sunray.ActorMixin, name="DemoActor", num_cpus=1, concurrency_groups={"g1": 1}
):
def __init__(self, init_v: int):
self.init_v = init_v
# annotate `add` is a remote_method
@sunray.remote_method
def add(self, v: int) -> int:
return self.init_v + v
# support directly call remote_method
@sunray.remote_method
def calculate(self, v: int) -> int:
return self.add(v)
# support specify remote method options
@sunray.remote_method(concurrency_group="g1")
async def sleep(self): ...
# construct the actor
actor = Demo.new_actor().remote(1)
# call remote method
ref = actor.methods.add.remote(1)
print(sunray.get(ref))
```