Initial implementation of the Fray/RPC controller.

.gitignore

@@ -223,3 +223,4 @@ gha-creds-*.json
 *.jsonl
 **/*.jsonl
 scr/*
+.weaver/

AGENTS.md

@@ -23,7 +23,7 @@
 - Assume Python >=3.11.
 - Always use `uv run` for Python entry points. If that fails, try `.venv/bin/python` directly.
 - Run `uv run python infra/pre-commit.py --all-files` before sending changes; formatting and linting are enforced with `ruff`.
-- Keep type hints passing under `uv run mypy`; configuration lives in `pyproject.toml`.
+- Keep type hints passing under `uv run pyrefly`; configuration lives in `pyproject.toml`.
 
 ### Communication & Commits
 
@@ -88,6 +88,15 @@ You don't generate comments that merely restate the code, e.g.
 - Run the appropriate tests for your changes (for example, `uv run pytest` under the relevant directory); consult subproject guides for preferred markers.
 - Use pytest features like fixtures and parameterization to avoid duplication and write clean code.
 
+PREFER:
+
+- Integration style tests which exercise behavior and test the output
+
+DO NOT:
+
+- Create tests which validate obvious features: if a type exists, a constant has a value, etc.
+
+
 ## Environment
 
 - Prefer to use `uv` when possible. If you can't (for instance, due to sandbox restrictions) you can use `.venv/bin/python`

infra/pre-commit.py

@@ -46,6 +46,9 @@
     ".git/**",
     ".github/**",
     "tests/snapshots/**",
+    # grpc generated files
+    "**/*_connect.py",
+    "**/*_pb2.py",
     "**/*.gz",
     "**/*.pb",
     "**/*.index",

lib/fluster/AGENTS.md

@@ -0,0 +1,46 @@
+# Agent Tips
+
+* Use the connect/RPC abstractions to implement and perform RPC calls. DO NOT use httpx or raw HTTP.
+* Use scripts/generate-protos.py to regenerate files after changing the `.proto` files.
+* Prefer shallow, functional interfaces which return control to the user, vs callbacks or inheritance.
+
+e.g.
+
+class Scheduler:
+  def add_job()
+  def add_worker():
+  def compute_schedule() -> ScheduledJobs:
+
+is preferable to:
+
+class Scheduler:
+  def __init__(self, job_creator: JobCreator):
+    self.job_creator = job_creator
+  def run(self):
+    ... self.job_creator.create_job()
+
+It's acceptable to have a top-level class which implements the main loop of
+course, but prefer to keep other interfaces shallow and functional whenever
+possible.
+
+* Tests should evaluate _behavior_, not implementation. Don't test things that are trivially caught by the type checker. Explicitly that means:
+
+- No tests for "constant = constant"
+- No tests for "method exists"
+- No tests for "create an object(x, y, z) and attributes are x, y, z"
+
+These tests have negative value - they make our code more brittle. Test
+_behavior_ instead. You can use mocks as needed to isolate environments (e.g.
+mock around a remote API). Prefer "fakes" -- e.g. create a real database but
+with fake data -- when reasonable.
+
+## Protocols and Testing
+
+Non-trivial public classes should define a protocol which represents their
+_important_ interface characteristics. Use this protocol in type hints for
+when the class is used instead of the concrete class.
+
+Test to this protocol, not the concrete class: the protocol should describe the
+interesting behavior of the class, but not betray the implementation details.
+
+(You may of course _instantiate_ the concrete class for testing.)

lib/fluster/README.md

@@ -0,0 +1,130 @@
+# Fluster
+
+Fluster is a distributed job orchestration and RPC framework designed to replace Ray with simpler, more focused primitives. It provides job lifecycle management, actor-based RPC communication, and task dispatch capabilities for distributed Python workloads.
+
+## Architecture Overview
+
+Fluster consists of four main components:
+
+| Component | Description |
+|-----------|-------------|
+| **Controller** | Central coordinator managing job scheduling, worker registration, and service discovery |
+| **Worker** | Execution agent that runs jobs in isolated containers with resource management |
+| **Actor System** | RPC framework enabling Python object method invocation across processes |
+| **WorkerPool** | High-level task dispatch abstraction for stateless parallel workloads |
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Controller                               │
+│                                                                  │
+│     Job Scheduling    │    Worker Registry    │  Endpoint Registry│
+└─────────────────────────────────────────────────────────────────┘
+        │                       │                       ▲
+        │ dispatch              │ health                │ register
+        ▼                       ▼                       │
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│     Worker      │     │     Worker      │     │   ActorServer   │
+│                 │     │                 │     │   (in job)      │
+│  runs jobs in   │     │  runs jobs in   │     │                 │
+│  containers     │     │  containers     │     │                 │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+```
+
+## Directory Structure
+
+```
+src/fluster/
+├── actor/                    # Actor RPC system
+│   ├── client.py            # Actor method invocation
+│   ├── pool.py              # Multi-endpoint management
+│   ├── resolver.py          # Endpoint discovery
+│   ├── server.py            # Actor hosting
+│   └── types.py             # Core types
+├── cluster/                  # Cluster orchestration
+│   ├── controller/          # Controller service
+│   ├── worker/              # Worker service
+│   ├── client.py            # Client interface
+│   └── types.py             # Shared types
+├── proto/                    # Protocol definitions
+├── worker_pool.py           # Task dispatch
+└── *_pb2.py, *_connect.py   # Generated RPC code
+```
+
+## Component Documentation
+
+- [Controller Overview](docs/controller.md) - Job scheduling and coordination
+- [Worker Overview](docs/worker.md) - Job execution and container management
+- [Actor System Overview](docs/actor.md) - RPC and service discovery
+
+## Quick Start
+
+### Submitting a Job
+
+```python
+from fluster.cluster import RpcClusterClient, Entrypoint, create_environment
+from fluster.cluster_pb2 import ResourceSpec
+
+def my_task():
+    print("Hello from fluster!")
+
+client = RpcClusterClient("http://controller:8080")
+job_id = client.submit(
+    name="my-job",
+    entrypoint=Entrypoint(callable=my_task),
+    resources=ResourceSpec(cpu=1, memory="2GB"),
+    environment=create_environment(),
+)
+client.wait(job_id)
+```
+
+### Running an Actor Server
+
+```python
+from fluster.actor import ActorServer, ActorContext
+
+class InferenceActor:
+    def predict(self, ctx: ActorContext, data: list) -> list:
+        return [x * 2 for x in data]
+
+server = ActorServer(controller_address="http://controller:8080")
+server.register("inference", InferenceActor())
+server.serve()
+```
+
+### Calling Actors
+
+```python
+from fluster.actor import ActorPool, ClusterResolver
+
+resolver = ClusterResolver("http://controller:8080")
+pool: ActorPool = resolver.lookup("inference")
+pool.wait_for_size(1)
+
+result = pool.call().predict([1, 2, 3])
+```
+
+### Using WorkerPool for Task Dispatch
+
+```python
+from fluster.worker_pool import WorkerPool, WorkerPoolConfig
+from fluster.cluster import RpcClusterClient
+
+client = RpcClusterClient("http://controller:8080")
+config = WorkerPoolConfig(num_workers=10, resources=ResourceSpec(cpu=2))
+pool = WorkerPool(client, config)
+
+futures = [pool.submit(process_shard, shard) for shard in shards]
+results = [f.result() for f in futures]
+pool.shutdown()
+```
+
+## Design Principles
+
+1. **Shallow interfaces**: Components expose minimal APIs with clear responsibilities
+2. **Explicit over implicit**: No magic discovery or hidden state synchronization
+3. **Stateless workers**: Task retry and load balancing work because workers maintain no shared state
+4. **Arbitrary callables**: Jobs and actor methods accept any picklable Python callable
+
+## Related Documentation
+
+- [Fray-Zero Design](docs/fray-zero.md) - Original design document and rationale

lib/fluster/buf.gen.yaml

@@ -0,0 +1,10 @@
+version: v2
+managed:
+  enabled: true
+plugins:
+  - remote: buf.build/protocolbuffers/python
+    out: src/fluster
+  - remote: buf.build/protocolbuffers/pyi
+    out: src/fluster
+  - remote: buf.build/connectrpc/python
+    out: src/fluster

lib/fluster/buf.yaml

@@ -0,0 +1,10 @@
+version: v2
+modules:
+  - path: src/fluster/proto
+  - path: src/fluster/actor/proto
+lint:
+  use:
+    - STANDARD
+breaking:
+  use:
+    - FILE