Feature/refactor api

README.md

@@ -10,9 +10,13 @@
 **Lightweight distributed framework designed for high-performance AI applications.**
 
 🚀 **Zero Dependencies** — Pure Rust + Tokio, no NATS/etcd/Redis
+
 🌐 **Auto Discovery** — Built-in Gossip protocol for cluster management
+
 🔀 **Location Transparent** — Same API for local and remote Actors
+
 ⚡ **Streaming Ready** — Native support for LLM streaming responses
+
 🤖 **Agent Friendly** — Integrates with AutoGen, LangGraph out of the box
 
 ## 🚀 Get Started in 5 Minutes
@@ -27,10 +31,10 @@ pip install pulsing
 
 ```python
 import asyncio
-from pulsing.actor import remote, resolve
+import pulsing as pul
 from pulsing.agent import runtime
 
-@remote
+@pul.remote
 class Greeter:
     def __init__(self, display_name: str):
         self.display_name = display_name
@@ -39,7 +43,8 @@ class Greeter:
         return f"[{self.display_name}] Received: {message}"
 
     async def chat_with(self, peer_name: str, message: str) -> str:
-        peer = await resolve(peer_name)
+        # Use Greeter.resolve() to get a typed proxy
+        peer = await Greeter.resolve(peer_name)
         return await peer.greet(f"From {self.display_name}: {message}")
 
 async def main():
@@ -55,7 +60,7 @@ async def main():
 asyncio.run(main())
 ```
 
-**That's it!** `@remote` turns a regular class into a distributed Actor, and `resolve()` enables agents to discover and communicate with each other.
+**That's it!** `@pul.remote` turns a regular class into a distributed Actor, and `Greeter.resolve()` enables agents to discover and communicate with each other.
 
 ## 💡 I want to...
 
@@ -129,10 +134,10 @@ Out-of-the-box GPU cluster inference:
 
 ```bash
 # Start Router (OpenAI-compatible API)
-pulsing actor router --addr 0.0.0.0:8000 --http_port 8080 --model_name my-llm
+pulsing actor pulsing.actors.Router --addr 0.0.0.0:8000 --http_port 8080 --model_name my-llm
 
 # Start vLLM Worker (can have multiple)
-pulsing actor vllm --model Qwen/Qwen2.5-0.5B --addr 0.0.0.0:8002 --seeds 127.0.0.1:8000
+pulsing actor pulsing.actors.VllmWorker --model Qwen/Qwen2.5-0.5B --addr 0.0.0.0:8002 --seeds 127.0.0.1:8000
 
 # Test
 curl http://localhost:8080/v1/chat/completions \

README.zh.md

@@ -10,9 +10,13 @@
 **轻量级分布式框架，专为高性能 AI 应用设计。**
 
 🚀 **零外部依赖** — 纯 Rust + Tokio，无需 NATS/etcd/Redis
+
 🌐 **自动发现** — 内置 Gossip 协议管理集群
+
 🔀 **位置透明** — 本地和远程 Actor 使用相同 API
+
 ⚡ **流式支持** — 原生支持 LLM 流式响应
+
 🤖 **Agent 友好** — 开箱即用集成 AutoGen、LangGraph
 
 ## 🚀 5分钟快速体验
@@ -27,10 +31,10 @@ pip install pulsing
 
 ```python
 import asyncio
-from pulsing.actor import remote, resolve
+import pulsing as pul
 from pulsing.agent import runtime
 
-@remote
+@pul.remote
 class Greeter:
     def __init__(self, display_name: str):
         self.display_name = display_name
@@ -39,7 +43,8 @@ class Greeter:
         return f"[{self.display_name}] 收到: {message}"
 
     async def chat_with(self, peer_name: str, message: str) -> str:
-        peer = await resolve(peer_name)
+        # 使用 Greeter.resolve() 获取有类型的代理
+        peer = await Greeter.resolve(peer_name)
         return await peer.greet(f"来自 {self.display_name}: {message}")
 
 async def main():
@@ -55,7 +60,7 @@ async def main():
 asyncio.run(main())
 ```
 
-**就这么简单！** `@remote` 让普通类变成可分布式部署的 Actor，`resolve()` 让 Agent 互相发现和通信。
+**就这么简单！** `@pul.remote` 让普通类变成可分布式部署的 Actor，`Greeter.resolve()` 让 Agent 互相发现和通信。
 
 ## 💡 我想做...
 
@@ -129,10 +134,10 @@ async with runtime(addr="0.0.0.0:8002", seeds=["node1:8001"]):
 
 ```bash
 # 启动 Router（OpenAI 兼容 API）
-pulsing actor router --addr 0.0.0.0:8000 --http_port 8080 --model_name my-llm
+pulsing actor pulsing.actors.Router --addr 0.0.0.0:8000 --http_port 8080 --model_name my-llm
 
 # 启动 vLLM Worker（可多个）
-pulsing actor vllm --model Qwen/Qwen2.5-0.5B --addr 0.0.0.0:8002 --seeds 127.0.0.1:8000
+pulsing actor pulsing.actors.VllmWorker --model Qwen/Qwen2.5-0.5B --addr 0.0.0.0:8002 --seeds 127.0.0.1:8000
 
 # 测试
 curl http://localhost:8080/v1/chat/completions \

benchmarks/large_scale_stress_test.py

@@ -17,7 +17,8 @@
 from collections import defaultdict
 from dataclasses import dataclass, field
 
-from pulsing.actor import Actor, StreamMessage, SystemConfig, create_actor_system
+import pulsing as pul
+from pulsing.actor import Actor, StreamMessage, SystemConfig
 
 
 # ============================================================================
@@ -268,14 +269,15 @@
 
     # Configure system
     port = (8000 if args.port == 0 else args.port) + rank
-    config = SystemConfig.with_addr(f"0.0.0.0:{port}")
+    addr = f"0.0.0.0:{port}"
 
+    seeds = None
     if args.seed_nodes:
-        config = config.with_seeds(args.seed_nodes)
+        seeds = args.seed_nodes
     elif rank > 0:
-        config = config.with_seeds([f"127.0.0.1:{8000 + rank - 1}"])
+        seeds = [f"127.0.0.1:{8000 + rank - 1}"]
 
-    system = await create_actor_system(config)
+    system = await pul.actor_system(addr=addr, seeds=seeds)
     print(f"System started at {system.addr}")
 
     # Wait for cluster to stabilize
@@ -288,7 +290,7 @@
     # Create local workers
     worker_refs = {}
     for name, cls in WORKERS.items():
-        ref = await system.spawn(f"{name}_{rank}", cls(), public=True)
+        ref = await system.spawn(cls(), name=f"{name}_{rank}", public=True)
         worker_refs[name] = ref
         print(f"  Spawned {name}_{rank}")
 

benchmarks/large_scale_stress_test_pulsing_single.py

@@ -16,7 +16,8 @@
 from collections import defaultdict
 from dataclasses import dataclass, field
 
-from pulsing.actor import Actor, StreamMessage, SystemConfig, create_actor_system
+import pulsing as pul
+from pulsing.actor import Actor, StreamMessage, SystemConfig
 
 
 # ============================================================================
@@ -235,15 +236,15 @@
     )
     print(f"{'=' * 50}\n")
 
-    system = await create_actor_system(SystemConfig.with_addr(f"0.0.0.0:{args.port}"))
+    system = await pul.actor_system(addr=f"0.0.0.0:{args.port}")
     print(f"System started at {system.addr}")
 
     # Create workers
     workers = {}
     for name, cls in WORKERS.items():
         workers[name] = []
         for i in range(args.num_workers):
-            ref = await system.spawn(f"{name}_{i}", cls())
+            ref = await system.spawn(cls(), name=f"{name}_{i}")
             workers[name].append(ref)
         print(f"Created {args.num_workers} {name} workers")
 

benchmarks/queue_benchmark.py

@@ -29,7 +29,8 @@
 from collections import defaultdict
 from dataclasses import dataclass, field
 
-from pulsing.actor import SystemConfig, create_actor_system
+import pulsing as pul
+from pulsing.actor import SystemConfig
 from pulsing.queue import read_queue, write_queue
 
 
@@ -353,17 +354,18 @@
     else:
         port = args.port + rank
 
-    config = SystemConfig.with_addr(f"0.0.0.0:{port}")
+    addr = f"0.0.0.0:{port}"
 
     # Add seed nodes
+    seeds = None
     if args.seed_nodes:
-        config = config.with_seeds(args.seed_nodes)
+        seeds = args.seed_nodes
     elif rank > 0:
         prev_port = 9000 + (rank - 1)
-        config = config.with_seeds([f"127.0.0.1:{prev_port}"])
+        seeds = [f"127.0.0.1:{prev_port}"]
 
     # Create system
-    system = await create_actor_system(config)
+    system = await pul.actor_system(addr=addr, seeds=seeds)
     print(f"[Process {rank}] ActorSystem started at {system.addr}")
 
     # Wait for cluster to stabilize

comparison_examples/pulsing_pingpong.py

@@ -0,0 +1,27 @@
+"""
+Pulsing Ping-Pong Example using @remote decorator
+Same functionality as AutoGen version
+"""
+
+from pulsing.actor import remote, runtime
+
+
+# Define Agent
+@remote
+class PingPongAgent:
+    async def ping(self, message: str) -> str:
+        return f"pong: {message}"
+
+
+# Run
+async def main():
+    async with runtime():
+        agent = await PingPongAgent.spawn(name="pingpong")
+        response = await agent.ping("hello")
+        print(f"Received: {response}")
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(main())

comparison_examples/pulsing_research.py

@@ -0,0 +1,59 @@
+"""
+Pulsing Multi-Agent Research Workflow using @agent decorator
+Same functionality as AutoGen version
+"""
+
+from pulsing.actor import resolve
+from pulsing.agent import agent, runtime
+
+
+# Researcher Agent
+@agent(role="Researcher", goal="Research topics")
+class ResearcherAgent:
+    async def research(self, topic: str) -> list[str]:
+        return [
+            f"Research point 1 about {topic}",
+            f"Research point 2 about {topic}",
+        ]
+
+
+# Analyst Agent
+@agent(role="Analyst", goal="Analyze research results")
+class AnalystAgent:
+    async def analyze(self, points: list[str]) -> str:
+        combined = " ".join(points)
+        return f"Analysis: {combined[:50]}..."
+
+
+# Reporter Agent
+@agent(role="Reporter", goal="Write final report")
+class ReporterAgent:
+    async def write(self, summary: str) -> str:
+        return f"Final Report:\n{summary}"
+
+
+# Workflow
+async def run_workflow():
+    async with runtime():
+        # Spawn agents with names
+        researcher = await ResearcherAgent.spawn(name="researcher")
+        analyst = await AnalystAgent.spawn(name="analyst")
+        reporter = await ReporterAgent.spawn(name="reporter")
+
+        # Resolve by name (automatic load balancing)
+        researcher = await resolve("researcher")
+        analyst = await resolve("analyst")
+        reporter = await resolve("reporter")
+
+        # Execute workflow
+        research = await researcher.research("Quantum Computing")
+        analysis = await analyst.analyze(research)
+        report = await reporter.write(analysis)
+
+        print(report)
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(run_workflow())

crates/pulsing-actor/README.md

@@ -87,8 +87,8 @@ let system2 = ActorSystem::builder()
     .build()
     .await?;
 
-// 通过路径解析远程 Actor
-let remote = system2.resolve_named("services/echo", None).await?;
+// 通过名称解析远程 Actor
+let remote = system2.resolve("services/echo").await?;
 let resp: String = remote.ask("hello".to_string()).await?;
 ```
 
@@ -97,18 +97,20 @@ let resp: String = remote.ask("hello".to_string()).await?;
 除了传统 Actor trait，还提供函数式 Behavior API：
 
 ```rust
-use pulsing_actor::behavior::{stateful, BehaviorAction, BehaviorSpawner};
+use pulsing_actor::behavior::{stateful, Behavior, BehaviorAction};
+use pulsing_actor::prelude::*;
 
 fn counter(initial: i32) -> Behavior<i32> {
-    stateful(initial, |count, n| {
+    stateful(initial, |count, n, _ctx| {
         *count += n;
         println!("count = {}", *count);
         BehaviorAction::Same
     })
 }
 
 let system = ActorSystem::builder().build().await?;
-let counter_ref = system.spawn_behavior("counter", counter(0)).await?;
+// Behavior 实现 IntoActor，可以直接传给 spawn_named
+let counter_ref = system.spawn_named("actors/counter", counter(0)).await?;
 
 counter_ref.tell(5).await?;  // count = 5
 counter_ref.tell(3).await?;  // count = 8