vention-communication 0.1.0__tar.gz → 0.2.0__tar.gz

{vention_communication-0.1.0 → vention_communication-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vention-communication
-Version: 0.1.0
+Version: 0.2.0
 Summary: A framework for storing and managing component and application data for machine apps.
 License: Proprietary
 Author: VentionCo
@@ -28,26 +28,31 @@ A thin, FastAPI-powered RPC layer for machine-apps that exposes Connect-compatib
 
 ## ✨ Features
 
-- **Decorator-based RPCs**: `@action()` for request-response calls, `@stream()` for server streams. Types inferred from Python type hints or Pydantic models.
-- **Connect-compatible endpoints**: Works seamlessly with Connect clients — compatible with `@connectrpc/connect-web` and `connectrpc-python`.
-- **FastAPI-based**: Leverages FastAPI for routing and async concurrency.
+- **Zero boilerplate RPCs**: Expose any async Python function as a network API with a single decorator.
+- **Strong typing**: Request and response models derived directly from Python annotations.
+- **Built-in schema emission**: Generates a .proto file at runtime, ready for SDK code generation.
 - **Single service surface**: All methods exposed under `/rpc/<package.Service>/<Method>`.
-- **Automatic .proto emission**: Generates a single .proto file describing all registered RPCs and models at runtime, ready for use in Buf-based SDK generation.
+- **Connect-compatible transport**: Works seamlessly with `@connectrpc/connect-web` and `connectrpc-python`.
 
 ## 🧠 Concepts & Overview
 
-### What is an RPC?
+### The Problem
 
-**RPC (Remote Procedure Call)** is a way to call a function on a remote server as if it were a local function. Instead of manually crafting HTTP requests and parsing responses, you define your functions with decorators, and the library handles the network communication for you. Your client code can call `client.ping({ message: "Hello" })` and get back a response, just like calling a local function.
+Machine-app developers write Python daily but shouldn’t need to know REST, gRPC, or frontend networking.
+They just need a way to say “this function should be callable from anywhere.”
 
-### What is Connect?
+### The Solution
 
-**Connect** is a protocol for building APIs that combines the simplicity of REST with the type safety of gRPC. It uses Protocol Buffers (protobuf) for defining your API contract, but sends data as JSON over HTTP, making it easy to use from browsers and simple HTTP clients. Connect provides:
+vention-communication bridges that gap by turning annotated Python functions into typed RPC endpoints automatically.
 
-- **Type safety**: Your API contract is defined in a `.proto` file, ensuring clients and servers agree on the data structure
-- **Error handling**: Standardized error responses that work across languages
-- **Streaming**: Built-in support for server-side streaming (continuously sending updates to clients)
-- **Developer experience**: Works with standard HTTP tools and browsers
+`@action()` → defines a one-request / one-response method.
+
+`@stream()` → defines a live telemetry or event stream that other services can subscribe to.
+
+`VentionApp.finalize()` → scans for decorators, builds a Connect router, and emits a .proto schema.
+
+Once the .proto exists, SDKs for TypeScript, Python, or Go can be generated using Buf.
+The result: your frontend gets auto-completed methods for every RPC, no HTTP or JSON code required.
 
 ### Core Concepts
 
@@ -56,52 +61,6 @@ A thin, FastAPI-powered RPC layer for machine-apps that exposes Connect-compatib
 - **Service Surface** — all actions and streams belong to one service, e.g. `vention.app.v1.<YourAppName>Service`, with routes mounted under `/rpc`.
 - **Proto Generation** — `VentionApp.finalize()` writes a .proto to disk, capturing all decorated RPCs, inferred models, and scalar wrappers. SDK generation (via Buf) is handled externally.
 
-### Stream Configuration Options
-
-When creating a stream with `@stream()`, you can configure how updates are delivered to subscribers:
-
-#### `replay` (default: `True`)
-
-Controls whether new subscribers receive the last published value immediately when they subscribe.
-
-- **`replay=True`**: New subscribers instantly receive the most recent value (if one exists). Useful for state streams where clients need the current state immediately upon connection.
-- **`replay=False`**: New subscribers only receive values published after they subscribe. Useful for event streams where you only want to see new events.
-
-
-#### `queue_maxsize` (default: `1`)
-
-The maximum number of items that can be queued for each subscriber before the delivery policy kicks in.
-
-- **`queue_maxsize=1`**: Only the latest value is kept. Perfect for state streams where you only care about the current state.
-- **`queue_maxsize=N`** (N > 1): Allows buffering up to N items. Useful when subscribers might process items slower than they're published, but you still want to limit memory usage.
-
-```python
-# Only keep latest temperature reading
-@stream(name="Temperature", payload=Temperature, queue_maxsize=1)
-
-# Buffer up to 10 sensor readings
-@stream(name="SensorData", payload=SensorReading, queue_maxsize=10)
-```
-
-#### `policy` (default: `"latest"`)
-
-Controls what happens when a subscriber's queue is full and a new value is published.
-
-- **`policy="latest"`**: Drops the oldest item and adds the new one. Ensures subscribers always have the most recent data. Best for state streams where you only care about the current value.
-- **`policy="fifo"`**: Waits for the subscriber to process items and make space in the queue before adding new items. Ensures no data is lost but may cause backpressure if subscribers are slow. Best for event streams where you need to process every event.
-
-```python
-# Latest-wins: always show current state
-@stream(name="Status", payload=Status, policy="latest", queue_maxsize=1)
-
-# FIFO: process every event, even if slow
-@stream(name="Events", payload=Event, policy="fifo", queue_maxsize=100)
-```
-
-**Common Combinations:**
-
-- **State monitoring** (default): `replay=True`, `queue_maxsize=1`, `policy="latest"` — subscribers get current state immediately and always see the latest value.
-- **Event streaming**: `replay=False`, `queue_maxsize=100`, `policy="fifo"` — subscribers only see new events and process them in order.
 
 ## ⚙️ Installation & Setup
 
@@ -123,46 +82,38 @@ pip install vention-communication
 - Python: `connectrpc` with `httpx.AsyncClient`
 
 ## 🚀 Quickstart Tutorial
+A complete "hello world" in three steps.
 
 ### 1. Define your RPCs
 
 ```python
-# demo/main.py
 from pydantic import BaseModel
-
-from vention_communication.app import VentionApp
-from vention_communication.decorators import action, stream
-
+from vention_communication import VentionApp, action, stream
+import time, random
 
 class PingRequest(BaseModel):
     message: str
 
-
 class PingResponse(BaseModel):
     message: str
 
-
 class Heartbeat(BaseModel):
     value: str
     timestamp: int
 
-
-app = VentionApp(name="DemoApp", emit_proto=True, proto_path="proto/app.proto")
-
+app = VentionApp(name="DemoApp", emit_proto=True)
 
 @action()
 async def ping(req: PingRequest) -> PingResponse:
     return PingResponse(message=f"Pong: {req.message}")
 
-
-@stream(name="Heartbeat", payload=Heartbeat)
-async def heartbeat_publisher() -> Heartbeat:
-    from time import time
-    import random
-    return Heartbeat(value=f"{random.random():.2f}", timestamp=int(time()))
-
+@stream(name="heartbeat", payload=Heartbeat, replay=True)
+async def heartbeat():
+    """Broadcast a live heartbeat value to all subscribers."""
+    return Heartbeat(value=f"{random.uniform(0,100):.2f}", timestamp=int(time.time()))
 
 app.finalize()
+
 ```
 
 **Run:**
@@ -171,10 +122,7 @@ app.finalize()
 uvicorn demo.main:app --reload
 ```
 
-Routes are exposed under:
-
-- `/rpc/vention.app.v1.DemoAppService/Ping`
-- `/rpc/vention.app.v1.DemoAppService/Heartbeat`
+Endpoints are automatically registered under `/rpc/vention.app.v1.DemoAppService.`
 
 ### 2. Generated .proto
 
@@ -252,7 +200,7 @@ VentionApp(
 
 **Methods:**
 
-- `.extend_bundle(bundle: RpcBundle)` — merges external action/stream definitions (e.g., from state-machine or storage).
+- `.register_rpc_plugin(bundle: RpcBundle)` — merges external action/stream definitions (e.g., from state-machine or storage).
 - `.finalize()` — registers routes, emits .proto, and makes publishers available.
 
 **Attributes:**
@@ -284,7 +232,90 @@ VentionApp(
 - `queue_maxsize`: Maximum items per subscriber queue (default: `1`)
 - `policy`: Delivery policy when queue is full - `"latest"` drops old items, `"fifo"` waits for space (default: `"latest"`)
 
-Type inference ensures annotations are valid. Pydantic models are expanded into message definitions in the emitted .proto.
+### Stream Configuration Options
+
+When creating a stream with `@stream()`, you can configure how updates are delivered to subscribers:
+
+#### `replay` (default: `True`)
+
+Controls whether new subscribers receive the last published value immediately when they subscribe.
+
+- **`replay=True`**: New subscribers instantly receive the most recent value (if one exists). Useful for state streams where clients need the current state immediately upon connection.
+- **`replay=False`**: New subscribers only receive values published after they subscribe. Useful for event streams where you only want to see new events.
+
+
+#### `queue_maxsize` (default: `1`)
+
+The maximum number of items that can be queued for each subscriber before the delivery policy kicks in.
+
+- **`queue_maxsize=1`**: Only the latest value is kept. Perfect for state streams where you only care about the current state.
+- **`queue_maxsize=N`** (N > 1): Allows buffering up to N items. Useful when subscribers might process items slower than they're published, but you still want to limit memory usage.
+
+```python
+# Only keep latest temperature reading
+@stream(name="Temperature", payload=Temperature, queue_maxsize=1)
+
+# Buffer up to 10 sensor readings
+@stream(name="SensorData", payload=SensorReading, queue_maxsize=10)
+```
+
+#### `policy` (default: `"latest"`)
+
+Defines what happens when a subscriber’s queue is full and a new value is published.
+
+Each subscriber maintains its own in-memory queue of pending messages.
+When you publish faster than a client can consume, the queue eventually fills — the policy determines what happens next.
+
+`policy="latest"` — “drop oldest, never block”
+
+- The publisher never waits.
+- If a subscriber’s queue is full, the oldest item is dropped and the new one is inserted immediately.
+- Fast subscribers receive every message; slow subscribers skip intermediate values but always see the most recent state.
+
+✅ Pros
+- Zero backpressure — publisher performance unaffected by slow clients.
+- Keeps UI dashboards and telemetry feeds current (“latest value always wins”).
+- Ideal for high-frequency data (positions, sensor readings, machine state).
+
+⚠️ Cons
+- Drops messages for slow clients (they may miss intermediate updates).
+- Subscribers can diverge — one may receive more updates than another.
+
+Example:
+```python
+@stream(name="Temperature", payload=TempReading,
+        policy="latest", queue_maxsize=1)
+# → publisher never blocks; subscribers always see the most recent temperature
+```
+`policy="fifo"` — “deliver all, may block”
+
+- The publisher awaits until there’s space in every subscriber’s queue.
+- Guarantees that all messages are delivered in order to every subscriber.
+- A slow subscriber can stall the entire stream, because the distributor
+waits for that subscriber’s queue to make room before continuing.
+
+✅ Pros
+- Preserves every event and strict ordering.
+- Reliable for command sequences, audit logs, and event-driven logic.
+
+⚠️ Cons
+- One slow or paused subscriber can block all others.
+- Publishing rate is limited by the slowest client.
+- In extreme cases, a throttled browser or dropped connection can cause the
+distributor to stall until the queue frees or the subscriber is removed.
+
+Example:
+```python
+@stream(name="Events", payload=MachineEvent,
+        policy="fifo", queue_maxsize=100)
+# → guarantees ordered delivery but can back-pressure the publisher
+```
+
+**Common Combinations:**
+
+- **State monitoring** (default): `replay=True`, `queue_maxsize=1`, `policy="latest"` — subscribers get current state immediately and always see the latest value.
+- **Event streaming**: `replay=False`, `queue_maxsize=100`, `policy="fifo"` — subscribers only see new events and process them in order.
+
 
 ## 🔍 Troubleshooting & FAQ
 
@@ -298,5 +329,5 @@ Ensure `app.finalize()` has been called before publishing or subscribing.
 
 **Q: How do I integrate this with other libraries (state machine, storage, etc.)?**
 
-Use `app.extend_bundle()` to merge additional RPC definitions before calling `.finalize()`.
+Use `app.register_rpc_plugin()` to merge additional RPC definitions before calling `.finalize()`.
 

{vention_communication-0.1.0 → vention_communication-0.2.0}/README.md

@@ -14,26 +14,31 @@ A thin, FastAPI-powered RPC layer for machine-apps that exposes Connect-compatib
 
 ## ✨ Features
 
-- **Decorator-based RPCs**: `@action()` for request-response calls, `@stream()` for server streams. Types inferred from Python type hints or Pydantic models.
-- **Connect-compatible endpoints**: Works seamlessly with Connect clients — compatible with `@connectrpc/connect-web` and `connectrpc-python`.
-- **FastAPI-based**: Leverages FastAPI for routing and async concurrency.
+- **Zero boilerplate RPCs**: Expose any async Python function as a network API with a single decorator.
+- **Strong typing**: Request and response models derived directly from Python annotations.
+- **Built-in schema emission**: Generates a .proto file at runtime, ready for SDK code generation.
 - **Single service surface**: All methods exposed under `/rpc/<package.Service>/<Method>`.
-- **Automatic .proto emission**: Generates a single .proto file describing all registered RPCs and models at runtime, ready for use in Buf-based SDK generation.
+- **Connect-compatible transport**: Works seamlessly with `@connectrpc/connect-web` and `connectrpc-python`.
 
 ## 🧠 Concepts & Overview
 
-### What is an RPC?
+### The Problem
 
-**RPC (Remote Procedure Call)** is a way to call a function on a remote server as if it were a local function. Instead of manually crafting HTTP requests and parsing responses, you define your functions with decorators, and the library handles the network communication for you. Your client code can call `client.ping({ message: "Hello" })` and get back a response, just like calling a local function.
+Machine-app developers write Python daily but shouldn’t need to know REST, gRPC, or frontend networking.
+They just need a way to say “this function should be callable from anywhere.”
 
-### What is Connect?
+### The Solution
 
-**Connect** is a protocol for building APIs that combines the simplicity of REST with the type safety of gRPC. It uses Protocol Buffers (protobuf) for defining your API contract, but sends data as JSON over HTTP, making it easy to use from browsers and simple HTTP clients. Connect provides:
+vention-communication bridges that gap by turning annotated Python functions into typed RPC endpoints automatically.
 
-- **Type safety**: Your API contract is defined in a `.proto` file, ensuring clients and servers agree on the data structure
-- **Error handling**: Standardized error responses that work across languages
-- **Streaming**: Built-in support for server-side streaming (continuously sending updates to clients)
-- **Developer experience**: Works with standard HTTP tools and browsers
+`@action()` → defines a one-request / one-response method.
+
+`@stream()` → defines a live telemetry or event stream that other services can subscribe to.
+
+`VentionApp.finalize()` → scans for decorators, builds a Connect router, and emits a .proto schema.
+
+Once the .proto exists, SDKs for TypeScript, Python, or Go can be generated using Buf.
+The result: your frontend gets auto-completed methods for every RPC, no HTTP or JSON code required.
 
 ### Core Concepts
 
@@ -42,52 +47,6 @@ A thin, FastAPI-powered RPC layer for machine-apps that exposes Connect-compatib
 - **Service Surface** — all actions and streams belong to one service, e.g. `vention.app.v1.<YourAppName>Service`, with routes mounted under `/rpc`.
 - **Proto Generation** — `VentionApp.finalize()` writes a .proto to disk, capturing all decorated RPCs, inferred models, and scalar wrappers. SDK generation (via Buf) is handled externally.
 
-### Stream Configuration Options
-
-When creating a stream with `@stream()`, you can configure how updates are delivered to subscribers:
-
-#### `replay` (default: `True`)
-
-Controls whether new subscribers receive the last published value immediately when they subscribe.
-
-- **`replay=True`**: New subscribers instantly receive the most recent value (if one exists). Useful for state streams where clients need the current state immediately upon connection.
-- **`replay=False`**: New subscribers only receive values published after they subscribe. Useful for event streams where you only want to see new events.
-
-
-#### `queue_maxsize` (default: `1`)
-
-The maximum number of items that can be queued for each subscriber before the delivery policy kicks in.
-
-- **`queue_maxsize=1`**: Only the latest value is kept. Perfect for state streams where you only care about the current state.
-- **`queue_maxsize=N`** (N > 1): Allows buffering up to N items. Useful when subscribers might process items slower than they're published, but you still want to limit memory usage.
-
-```python
-# Only keep latest temperature reading
-@stream(name="Temperature", payload=Temperature, queue_maxsize=1)
-
-# Buffer up to 10 sensor readings
-@stream(name="SensorData", payload=SensorReading, queue_maxsize=10)
-```
-
-#### `policy` (default: `"latest"`)
-
-Controls what happens when a subscriber's queue is full and a new value is published.
-
-- **`policy="latest"`**: Drops the oldest item and adds the new one. Ensures subscribers always have the most recent data. Best for state streams where you only care about the current value.
-- **`policy="fifo"`**: Waits for the subscriber to process items and make space in the queue before adding new items. Ensures no data is lost but may cause backpressure if subscribers are slow. Best for event streams where you need to process every event.
-
-```python
-# Latest-wins: always show current state
-@stream(name="Status", payload=Status, policy="latest", queue_maxsize=1)
-
-# FIFO: process every event, even if slow
-@stream(name="Events", payload=Event, policy="fifo", queue_maxsize=100)
-```
-
-**Common Combinations:**
-
-- **State monitoring** (default): `replay=True`, `queue_maxsize=1`, `policy="latest"` — subscribers get current state immediately and always see the latest value.
-- **Event streaming**: `replay=False`, `queue_maxsize=100`, `policy="fifo"` — subscribers only see new events and process them in order.
 
 ## ⚙️ Installation & Setup
 
@@ -109,46 +68,38 @@ pip install vention-communication
 - Python: `connectrpc` with `httpx.AsyncClient`
 
 ## 🚀 Quickstart Tutorial
+A complete "hello world" in three steps.
 
 ### 1. Define your RPCs
 
 ```python
-# demo/main.py
 from pydantic import BaseModel
-
-from vention_communication.app import VentionApp
-from vention_communication.decorators import action, stream
-
+from vention_communication import VentionApp, action, stream
+import time, random
 
 class PingRequest(BaseModel):
     message: str
 
-
 class PingResponse(BaseModel):
     message: str
 
-
 class Heartbeat(BaseModel):
     value: str
     timestamp: int
 
-
-app = VentionApp(name="DemoApp", emit_proto=True, proto_path="proto/app.proto")
-
+app = VentionApp(name="DemoApp", emit_proto=True)
 
 @action()
 async def ping(req: PingRequest) -> PingResponse:
     return PingResponse(message=f"Pong: {req.message}")
 
-
-@stream(name="Heartbeat", payload=Heartbeat)
-async def heartbeat_publisher() -> Heartbeat:
-    from time import time
-    import random
-    return Heartbeat(value=f"{random.random():.2f}", timestamp=int(time()))
-
+@stream(name="heartbeat", payload=Heartbeat, replay=True)
+async def heartbeat():
+    """Broadcast a live heartbeat value to all subscribers."""
+    return Heartbeat(value=f"{random.uniform(0,100):.2f}", timestamp=int(time.time()))
 
 app.finalize()
+
 ```
 
 **Run:**
@@ -157,10 +108,7 @@ app.finalize()
 uvicorn demo.main:app --reload
 ```
 
-Routes are exposed under:
-
-- `/rpc/vention.app.v1.DemoAppService/Ping`
-- `/rpc/vention.app.v1.DemoAppService/Heartbeat`
+Endpoints are automatically registered under `/rpc/vention.app.v1.DemoAppService.`
 
 ### 2. Generated .proto
 
@@ -238,7 +186,7 @@ VentionApp(
 
 **Methods:**
 
-- `.extend_bundle(bundle: RpcBundle)` — merges external action/stream definitions (e.g., from state-machine or storage).
+- `.register_rpc_plugin(bundle: RpcBundle)` — merges external action/stream definitions (e.g., from state-machine or storage).
 - `.finalize()` — registers routes, emits .proto, and makes publishers available.
 
 **Attributes:**
@@ -270,7 +218,90 @@ VentionApp(
 - `queue_maxsize`: Maximum items per subscriber queue (default: `1`)
 - `policy`: Delivery policy when queue is full - `"latest"` drops old items, `"fifo"` waits for space (default: `"latest"`)
 
-Type inference ensures annotations are valid. Pydantic models are expanded into message definitions in the emitted .proto.
+### Stream Configuration Options
+
+When creating a stream with `@stream()`, you can configure how updates are delivered to subscribers:
+
+#### `replay` (default: `True`)
+
+Controls whether new subscribers receive the last published value immediately when they subscribe.
+
+- **`replay=True`**: New subscribers instantly receive the most recent value (if one exists). Useful for state streams where clients need the current state immediately upon connection.
+- **`replay=False`**: New subscribers only receive values published after they subscribe. Useful for event streams where you only want to see new events.
+
+
+#### `queue_maxsize` (default: `1`)
+
+The maximum number of items that can be queued for each subscriber before the delivery policy kicks in.
+
+- **`queue_maxsize=1`**: Only the latest value is kept. Perfect for state streams where you only care about the current state.
+- **`queue_maxsize=N`** (N > 1): Allows buffering up to N items. Useful when subscribers might process items slower than they're published, but you still want to limit memory usage.
+
+```python
+# Only keep latest temperature reading
+@stream(name="Temperature", payload=Temperature, queue_maxsize=1)
+
+# Buffer up to 10 sensor readings
+@stream(name="SensorData", payload=SensorReading, queue_maxsize=10)
+```
+
+#### `policy` (default: `"latest"`)
+
+Defines what happens when a subscriber’s queue is full and a new value is published.
+
+Each subscriber maintains its own in-memory queue of pending messages.
+When you publish faster than a client can consume, the queue eventually fills — the policy determines what happens next.
+
+`policy="latest"` — “drop oldest, never block”
+
+- The publisher never waits.
+- If a subscriber’s queue is full, the oldest item is dropped and the new one is inserted immediately.
+- Fast subscribers receive every message; slow subscribers skip intermediate values but always see the most recent state.
+
+✅ Pros
+- Zero backpressure — publisher performance unaffected by slow clients.
+- Keeps UI dashboards and telemetry feeds current (“latest value always wins”).
+- Ideal for high-frequency data (positions, sensor readings, machine state).
+
+⚠️ Cons
+- Drops messages for slow clients (they may miss intermediate updates).
+- Subscribers can diverge — one may receive more updates than another.
+
+Example:
+```python
+@stream(name="Temperature", payload=TempReading,
+        policy="latest", queue_maxsize=1)
+# → publisher never blocks; subscribers always see the most recent temperature
+```
+`policy="fifo"` — “deliver all, may block”
+
+- The publisher awaits until there’s space in every subscriber’s queue.
+- Guarantees that all messages are delivered in order to every subscriber.
+- A slow subscriber can stall the entire stream, because the distributor
+waits for that subscriber’s queue to make room before continuing.
+
+✅ Pros
+- Preserves every event and strict ordering.
+- Reliable for command sequences, audit logs, and event-driven logic.
+
+⚠️ Cons
+- One slow or paused subscriber can block all others.
+- Publishing rate is limited by the slowest client.
+- In extreme cases, a throttled browser or dropped connection can cause the
+distributor to stall until the queue frees or the subscriber is removed.
+
+Example:
+```python
+@stream(name="Events", payload=MachineEvent,
+        policy="fifo", queue_maxsize=100)
+# → guarantees ordered delivery but can back-pressure the publisher
+```
+
+**Common Combinations:**
+
+- **State monitoring** (default): `replay=True`, `queue_maxsize=1`, `policy="latest"` — subscribers get current state immediately and always see the latest value.
+- **Event streaming**: `replay=False`, `queue_maxsize=100`, `policy="fifo"` — subscribers only see new events and process them in order.
+
 
 ## 🔍 Troubleshooting & FAQ
 
@@ -284,4 +315,4 @@ Ensure `app.finalize()` has been called before publishing or subscribing.
 
 **Q: How do I integrate this with other libraries (state machine, storage, etc.)?**
 
-Use `app.extend_bundle()` to merge additional RPC definitions before calling `.finalize()`.
+Use `app.register_rpc_plugin()` to merge additional RPC definitions before calling `.finalize()`.

{vention_communication-0.1.0 → vention_communication-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "vention-communication"
-version = "0.1.0"
+version = "0.2.0"
 description = "A framework for storing and managing component and application data for machine apps."
 authors = [ "VentionCo" ]
 readme = "README.md"

{vention_communication-0.1.0 → vention_communication-0.2.0}/src/communication/app.py

@@ -38,7 +38,7 @@ class VentionApp(FastAPI):
         self.connect_router = ConnectRouter()
         self._extra_bundles: List[RpcBundle] = []
 
-    def extend_bundle(self, bundle: RpcBundle) -> None:
+    def register_rpc_plugin(self, bundle: RpcBundle) -> None:
         """Add RPCs/streams provided by external libraries.
 
         Must be called before finalize().

{vention_communication-0.1.0 → vention_communication-0.2.0}/src/communication/codegen.py

@@ -21,19 +21,9 @@ import "google/protobuf/empty.proto";
 
 
 def _unwrap_optional(type_annotation: Any) -> tuple[Any, bool]:
-    """Unwrap Optional[T] or Union[T, None] to T.
-
-    Args:
-        type_annotation: Type annotation that may be Optional
-
-    Returns:
-        Tuple of (inner_type, is_optional)
-    """
     origin = get_origin(type_annotation)
-    # Check if it's a Union type (Optional is Union[T, None])
     if origin is Union:
         args = get_args(type_annotation)
-        # Filter out NoneType
         non_none_args = [arg for arg in args if arg is not type(None)]
         if len(non_none_args) == 1:
             return (non_none_args[0], True)
@@ -41,14 +31,6 @@ def _unwrap_optional(type_annotation: Any) -> tuple[Any, bool]:
 
 
 def _unwrap_list(type_annotation: Any) -> tuple[Any, bool]:
-    """Unwrap List[T] or list[T] to T.
-
-    Args:
-        type_annotation: Type annotation that may be a list
-
-    Returns:
-        Tuple of (inner_type, is_list)
-    """
     origin = get_origin(type_annotation)
     if origin in (list, List):
         args = get_args(type_annotation)
@@ -58,14 +40,6 @@ def _unwrap_list(type_annotation: Any) -> tuple[Any, bool]:
 
 
 def _msg_name_for_scalar_stream(stream_name: str) -> str:
-    """Generate a message name for a scalar stream payload.
-
-    Args:
-        stream_name: Name of the stream
-
-    Returns:
-        Message name for the scalar wrapper
-    """
     return f"{stream_name}Message"
 
 
@@ -74,19 +48,6 @@ def _determine_proto_type_for_field(
     seen_models: set[str],
     lines: list[str],
 ) -> str:
-    """Determine the proto type name for a field's inner type.
-
-    Handles scalars, nested Pydantic models, and fallback to string.
-    Recursively generates nested model definitions if needed.
-
-    Args:
-        inner_type: The unwrapped inner type (after Optional/List)
-        seen_models: Set of already-seen model names to avoid duplicates
-        lines: List to append nested message definitions to
-
-    Returns:
-        Proto type name string
-    """
     if inner_type in _SCALAR_MAP:
         return _SCALAR_MAP[inner_type]
 
@@ -109,28 +70,11 @@ def _process_pydantic_field(
     seen_models: set[str],
     lines: list[str],
 ) -> str:
-    """Process a single Pydantic field and generate its proto definition.
-
-    Args:
-        field_name: Name of the field
-        field_type: Type annotation of the field
-        field_index: Proto field number (1-indexed)
-        seen_models: Set of already-seen model names to avoid duplicates
-        lines: List to append nested message definitions to
-
-    Returns:
-        Proto field definition line (e.g., "  string name = 1;")
-    """
-    # Unwrap Optional first
     inner_type, _ = _unwrap_optional(field_type)
-
-    # Unwrap List
     list_inner_type, is_list = _unwrap_list(inner_type)
 
-    # Determine proto type (handles nested models recursively)
     proto_type = _determine_proto_type_for_field(list_inner_type, seen_models, lines)
 
-    # Add "repeated" prefix for lists
     if is_list:
         proto_type = f"repeated {proto_type}"
 
@@ -142,16 +86,6 @@ def _generate_pydantic_message(
     seen_models: set[str],
     lines: list[str],
 ) -> list[str]:
-    """Generate proto message definition for a Pydantic model.
-
-    Args:
-        type_annotation: Pydantic model type
-        seen_models: Set of already-seen model names to avoid duplicates
-        lines: List to append nested message definitions to
-
-    Returns:
-        List of lines for the message definition
-    """
     model_name = type_annotation.__name__
     fields = []
     field_index = 1
@@ -176,15 +110,6 @@ def _generate_pydantic_message(
 def _generate_scalar_wrapper_message(
     stream_name: str, payload_type: Type[Any]
 ) -> list[str]:
-    """Generate proto message definition for a scalar stream payload.
-
-    Args:
-        stream_name: Name of the stream
-        payload_type: Scalar type (int, float, str, bool)
-
-    Returns:
-        List of lines for the wrapper message definition
-    """
     wrapper_name = _msg_name_for_scalar_stream(stream_name)
     lines = [
         f"message {wrapper_name} {{",
@@ -199,30 +124,16 @@ def _proto_type_name(
     scalar_wrappers: Dict[str, str],
     stream_name: Optional[str] = None,
 ) -> str:
-    """Map a Python type to its proto type name.
-
-    Args:
-        type_annotation: Type to map
-        scalar_wrappers: Dictionary mapping stream names to wrapper message names
-        stream_name: Optional stream name for scalar wrapper lookup
-
-    Returns:
-        Proto type name string
-    """
     if type_annotation is None:
         return "google.protobuf.Empty"
 
-    # Unwrap Optional
     inner_type, _ = _unwrap_optional(type_annotation)
 
-    # Unwrap List (for streams, lists become scalar wrappers)
     list_inner_type, is_list = _unwrap_list(inner_type)
 
     if list_inner_type in _SCALAR_MAP:
         if stream_name and stream_name in scalar_wrappers:
             return scalar_wrappers[stream_name]
-        # For streams, if it's a list, we don't use "repeated" in the return type
-        # The stream itself provides the repetition
         return str(_SCALAR_MAP[list_inner_type])
 
     if is_pydantic_model(list_inner_type):
@@ -236,30 +147,17 @@ def _register_pydantic_model(
     seen_models: set[str],
     lines: list[str],
 ) -> None:
-    """Register a Pydantic model and recursively register nested models.
-
-    Unwraps Optional and List types to find the underlying Pydantic model,
-    then generates its proto definition if not already seen.
-
-    Args:
-        type_annotation: Type annotation that may contain a Pydantic model
-        seen_models: Set of already-seen model names to avoid duplicates
-        lines: List to append message definitions to
-    """
     if type_annotation is None:
         return
 
-    # Unwrap Optional
     inner_type, _ = _unwrap_optional(type_annotation)
 
-    # Unwrap List to get inner type
     list_inner_type, _ = _unwrap_list(inner_type)
 
     if is_pydantic_model(list_inner_type):
         model_name = list_inner_type.__name__
         if model_name not in seen_models:
             seen_models.add(model_name)
-            # This will recursively register nested models via _generate_pydantic_message
             lines.extend(
                 _generate_pydantic_message(list_inner_type, seen_models, lines)
             )
@@ -271,15 +169,6 @@ def _process_stream_payload(
     lines: list[str],
     scalar_wrappers: Dict[str, str],
 ) -> None:
-    """Process a stream's payload type and generate necessary message definitions.
-
-    Args:
-        stream_entry: Stream entry containing payload type information
-        seen_models: Set of already-seen model names to avoid duplicates
-        lines: List to append message definitions to
-        scalar_wrappers: Dictionary to populate with scalar wrapper mappings
-    """
-    # Unwrap Optional and List for stream payloads
     inner_type, _ = _unwrap_optional(stream_entry.payload_type)
     list_inner_type, _ = _unwrap_list(inner_type)
 
@@ -299,20 +188,10 @@ def _collect_message_types(
     seen_models: set[str],
     scalar_wrappers: Dict[str, str],
 ) -> None:
-    """Collect and generate all message types needed for the proto.
-
-    Args:
-        bundle: RPC bundle containing actions and streams
-        lines: List to append message definitions to
-        seen_models: Set of already-seen model names to avoid duplicates
-        scalar_wrappers: Dictionary to populate with scalar wrapper mappings
-    """
-    # Process action input/output types
     for action_entry in bundle.actions:
         _register_pydantic_model(action_entry.input_type, seen_models, lines)
         _register_pydantic_model(action_entry.output_type, seen_models, lines)
 
-    # Process stream payload types
     for stream_entry in bundle.streams:
         _process_stream_payload(stream_entry, seen_models, lines, scalar_wrappers)
 
@@ -320,13 +199,6 @@ def _collect_message_types(
 def _generate_service_rpcs(
     bundle: RpcBundle, lines: list[str], scalar_wrappers: Dict[str, str]
 ) -> None:
-    """Generate RPC method definitions for actions and streams.
-
-    Args:
-        bundle: RPC bundle containing actions and streams
-        lines: List to append RPC definitions to
-        scalar_wrappers: Dictionary mapping stream names to wrapper message names
-    """
     rpc_prefix = "  rpc"
 
     for action_entry in bundle.actions:
@@ -346,15 +218,6 @@ def _generate_service_rpcs(
 
 
 def generate_proto(app_name: str, *, bundle: Optional[RpcBundle] = None) -> str:
-    """Generate a Protocol Buffer definition from RPC actions and streams.
-
-    Args:
-        app_name: Name of the application (used for service name)
-        bundle: Optional RPC bundle. If not provided, collects from decorators.
-
-    Returns:
-        Complete proto3 file content as a string
-    """
     if bundle is None:
         bundle = collect_bundle()
 
@@ -373,17 +236,6 @@ def generate_proto(app_name: str, *, bundle: Optional[RpcBundle] = None) -> str:
 
 
 def sanitize_service_name(name: str) -> str:
-    """Sanitize an application name for use as a service name.
-
-    Extracts alphanumeric parts, capitalizes each part, and joins them.
-    Invalid characters are dropped.
-
-    Args:
-        name: Application name to sanitize
-
-    Returns:
-        Sanitized service name, or "VentionApp" if no valid parts found
-    """
     import re
 
     parts = re.findall(r"[A-Za-z0-9]+", name)

{vention_communication-0.1.0 → vention_communication-0.2.0}/src/communication/connect_router.py

@@ -18,14 +18,6 @@ CONTENT_TYPE = "application/connect+json"
 
 
 def _frame(payload: Dict[str, Any], *, trailer: bool = False) -> bytes:
-    """Create a Connect protocol frame for streaming responses.
-
-    Connect uses a binary framing format for streaming JSON over HTTP. Each frame
-    consists of:
-    - 1 byte: Flags (0x00 for data, 0x80 for trailer/end-of-stream)
-    - 4 bytes: Body length in big-endian format
-    - N bytes: JSON-encoded payload
-    """
     body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode(
         "utf-8"
     )
@@ -52,7 +44,6 @@ class StreamManager:
     """
 
     def __init__(self) -> None:
-        """Initialize the StreamManager with an empty topic registry."""
         self._topics: Dict[str, Dict[str, Any]] = {}
 
     def ensure_topic(self, entry: StreamEntry) -> None:
@@ -157,14 +148,6 @@ class StreamManager:
             topic["subscribers"].discard(subscriber)
 
     async def _distributor(self, stream_name: str) -> None:
-        """Distribute published items to all subscribers of a stream.
-
-        For FIFO policy, waits for queue space. For latest-wins policy,
-        drops oldest items when queues are full.
-
-        Args:
-            stream_name: Name of the stream topic to distribute
-        """
         topic = self._topics[stream_name]
         publish_queue: asyncio.Queue[Any] = topic["publish_queue"]
         subscribers: set[_Subscriber] = topic["subscribers"]
@@ -312,14 +295,6 @@ def _serialize_stream_item(item: Any) -> Dict[str, Any]:
 
 
 async def _maybe_await(value: Any) -> Any:
-    """Await a value if it's a coroutine or Future, otherwise return it.
-
-    Args:
-        value: Value that may or may not be awaitable
-
-    Returns:
-        The result of awaiting or the value itself
-    """
     if asyncio.iscoroutine(value) or isinstance(value, asyncio.Future):
         return await value
     return value