jmux 0.0.5__tar.gz → 0.1.0__tar.gz

{jmux-0.0.5 → jmux-0.1.0}/.gitignore

@@ -79,5 +79,12 @@ Thumbs.db
 .env
 .env.*
 
+# Generated files
+src/jmux/generated/
+
 # Cursor
-.cursor/
+.cursor/
+
+# Claude Code
+.claude/
+CLAUDE.md

{jmux-0.0.5/src/jmux.egg-info → jmux-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jmux
-Version: 0.0.5
+Version: 0.1.0
 Summary: JMux: A Python package for demultiplexing a JSON string into multiple awaitable variables.
 Author-email: "Johannes A.I. Unruh" <johannes@unruh.ai>
 License: MIT License
@@ -40,10 +40,12 @@ Requires-Dist: pydantic>=2.0.0
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-anyio; extra == "test"
+Requires-Dist: trio; extra == "test"
 Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-anyio; extra == "dev"
+Requires-Dist: trio; extra == "dev"
 Requires-Dist: uv; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
@@ -61,8 +63,10 @@ This package is inspired by `Snapshot Streaming` mentioned in the [`WWDC25: Meet
 
 ## Features
 
-- **Asynchronous by Design**: Built on top of `asyncio`, JMux is perfect for modern, high-performance Python applications.
+- **Asynchronous by Design**: Built on top of `anyio`, JMux supports both `asyncio` and `trio` backends, making it perfect for modern, high-performance Python applications.
+- **Python 3.10+**: Supports Python 3.10 and newer versions.
 - **Pydantic Integration**: Validate your `JMux` classes against Pydantic models to ensure type safety and consistency.
+- **Code Generation**: Automatically generate JMux classes from `StreamableBaseModel` subclasses using the `jmux generate` CLI command.
 - **Awaitable and Streamable Sinks**: Use `AwaitableValue` for single values and `StreamableValues` for streams of values.
 - **Robust Error Handling**: JMux provides a comprehensive set of exceptions to handle parsing errors and other issues.
 - **Lightweight**: JMux has only a few external dependencies, making it easy to integrate into any project.
@@ -75,21 +79,155 @@ You can install JMux from PyPI using pip:
 pip install jmux
 ```
 
+## Code Generation
+
+JMux provides a CLI tool to automatically generate JMux classes from Pydantic models. Instead of manually writing both a Pydantic model and a corresponding JMux class, you can define your models using `StreamableBaseModel` and let JMux generate the demultiplexer classes for you.
+
+### Defining Models with StreamableBaseModel
+
+Use `StreamableBaseModel` as your base class instead of `pydantic.BaseModel`:
+
+```python
+from typing import Annotated
+from jmux import StreamableBaseModel, Streamed
+
+class LlmResponse(StreamableBaseModel):
+    thought: str
+    tool_code: Annotated[str, Streamed]
+    tags: list[str]
+```
+
+### Type Mappings
+
+The generator converts your model fields to JMux types as follows:
+
+| Model Field Type              | Generated JMux Type               |
+| ----------------------------- | --------------------------------- |
+| `str`, `int`, `float`, `bool` | `AwaitableValue[T]`               |
+| `Enum`                        | `AwaitableValue[EnumType]`        |
+| `T \| None`                   | `AwaitableValue[T \| None]`       |
+| `list[T]`                     | `StreamableValues[T]`             |
+| `Annotated[str, Streamed]`    | `StreamableValues[str]`           |
+| Nested `StreamableBaseModel`  | `AwaitableValue[NestedModelJMux]` |
+
+The `Streamed` marker is useful when you want to stream a string field character-by-character (e.g., for real-time display of LLM output) rather than awaiting the complete value.
+
+### Using the CLI
+
+Run the `jmux generate` command to scan your codebase and generate JMux classes:
+
+```bash
+jmux generate --root <directory>
+```
+
+This will:
+
+1. Recursively scan `<directory>` for Python files containing `StreamableBaseModel` subclasses
+2. Generate corresponding JMux classes with the suffix `JMux` (e.g., `LlmResponse` → `LlmResponseJMux`)
+3. Write the generated code to `src/jmux/generated/__init__.py`
+
+### Example
+
+Given this model:
+
+```python
+from typing import Annotated
+from jmux import StreamableBaseModel, Streamed
+
+class LlmResponse(StreamableBaseModel):
+    thought: str
+    tool_code: Annotated[str, Streamed]
+```
+
+Running `jmux generate` produces:
+
+```python
+from jmux.awaitable import AwaitableValue, StreamableValues
+from jmux.demux import JMux
+
+class LlmResponseJMux(JMux):
+    thought: AwaitableValue[str]
+    tool_code: StreamableValues[str]
+```
+
+You can then import and use the generated class:
+
+```python
+from jmux.generated import LlmResponseJMux
+
+jmux_instance = LlmResponseJMux()
+```
+
 ## Usage with LLMs (e.g., `litellm`)
 
 The primary use case for `jmux` is to process streaming JSON responses from LLMs. This allows you to react to parts of the data as it arrives, rather than waiting for the entire JSON object to be transmitted. While this should be obvious, I should mention, that **the order in which the pydantic model defines the properties, defines which stream is filled first**.
 
-Here’s a conceptual example of how you might integrate `jmux` with an LLM call, such as one made with `litellm`:
+### Using Code Generation (Recommended)
+
+The easiest way to use JMux with LLMs is to define your models using `StreamableBaseModel` and generate JMux classes automatically:
+
+```python
+from typing import Annotated
+from jmux import StreamableBaseModel, Streamed
+
+class LlmResponse(StreamableBaseModel): # Use `StreamableBaseModel` so that the CLI can find the `pydantic` models to parse
+    thought: str
+    tool_code: Annotated[str, Streamed]
+```
+
+Then run `jmux generate --root .` to generate the `LlmResponseJMux` class. You can then use it directly:
+
+```python
+import anyio
+from jmux.generated import LlmResponseJMux
+
+async def mock_llm_stream():
+    json_stream = '{"thought": "I need to write some code.", "tool_code": "print(\'Hello, World!\')"}'
+    for char in json_stream:
+        yield char
+        await anyio.sleep(0.01)
+
+async def process_llm_response():
+    jmux_instance = LlmResponseJMux()
+
+    async def feed_stream():
+        async for chunk in mock_llm_stream():
+            await jmux_instance.feed_chunks(chunk)
+
+    async def consume_thought():
+        thought = await jmux_instance.thought
+        print(f"LLM's thought received: '{thought}'")
+
+    async def consume_tool_code():
+        print("Receiving tool code...")
+        full_code = ""
+        async for code_fragment in jmux_instance.tool_code:
+            full_code += code_fragment
+            print(f"  -> Received fragment: {code_fragment}")
+        print(f"Full tool code received: {full_code}")
+
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(feed_stream)
+        tg.start_soon(consume_thought)
+        tg.start_soon(consume_tool_code)
+
+if __name__ == "__main__":
+    anyio.run(process_llm_response, backend="asyncio")
+```
+
+### Manual Approach
+
+If you prefer more control, you can manually define both the Pydantic model and the JMux class:
 
 ```python
-import asyncio
+import anyio
 from pydantic import BaseModel
 from jmux import JMux, AwaitableValue, StreamableValues
 # litellm is used conceptually here
 # from litellm import acompletion
 
 # 1. Define the Pydantic model for the expected JSON response
-class LlmResponse(BaseModel):
+class LlmResponse(BaseModel): # No need to use `StreamableBaseModel` here, since it is only used for detection purposes
     thought: str # **This property is filled first**
     tool_code: str
 
@@ -106,7 +244,7 @@ async def mock_llm_stream():
     json_stream = '{"thought": "I need to write some code.", "tool_code": "print(\'Hello, World!\')"}'
     for char in json_stream:
         yield char
-        await asyncio.sleep(0.01) # Simulate network latency
+        await anyio.sleep(0.01) # Simulate network latency
 
 # Main function to orchestrate the call and processing
 async def process_llm_response():
@@ -132,15 +270,16 @@ async def process_llm_response():
             print(f"  -> Received fragment: {code_fragment}")
         print(f"Full tool code received: {full_code}")
 
-    # Run all tasks concurrently
-    await asyncio.gather(
-        feed_stream(),
-        consume_thought(),
-        consume_tool_code()
-    )
+    # Run all tasks concurrently using anyio task group
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(feed_stream)
+        tg.start_soon(consume_thought)
+        tg.start_soon(consume_tool_code)
 
+# Run with asyncio backend
 if __name__ == "__main__":
-    asyncio.run(process_llm_response())
+    anyio.run(process_llm_response, backend="asyncio")
+    # Or use trio: anyio.run(process_llm_response, backend="trio")
 ```
 
 ## Example Implementation
@@ -212,7 +351,7 @@ You can either `await awaitable_llm_result` if you need the full result, or use
 Here is a simple example of how to use JMux to parse a JSON stream:
 
 ```python
-import asyncio
+import anyio
 from enum import Enum
 from types import NoneType
 from pydantic import BaseModel
@@ -297,10 +436,13 @@ async def main():
         nested_key_str = await key_nested.key_str
         print(f"nested_key_str: {nested_key_str}")
 
-    await asyncio.gather(produce(), consume())
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(produce)
+        tg.start_soon(consume)
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    anyio.run(main, backend="asyncio")
+    # Or use trio: anyio.run(main, backend="trio")
 ```
 
 ## API Reference
@@ -349,13 +491,35 @@ Additionally the following type is supported without being wrapped into `list`:
 
 This allows you to fully stream strings directly to a sink.
 
-## License
+### Class `jmux.StreamableBaseModel`
 
-This project is licensed under the terms of the MIT license. See the [LICENSE](LICENSE) file for details.
+A Pydantic `BaseModel` subclass used for defining models that can be automatically converted to JMux classes via the `jmux generate` CLI command.
+
+```python
+from jmux import StreamableBaseModel
 
-## Planned Improvements
+class MyModel(StreamableBaseModel):
+    name: str
+    age: int
+```
+
+### Class `jmux.Streamed`
+
+A marker class used with `typing.Annotated` to indicate that a string field should be streamed character-by-character rather than awaited as a complete value.
 
-- Add support for older Python versions
+```python
+from typing import Annotated
+from jmux import StreamableBaseModel, Streamed
+
+class MyModel(StreamableBaseModel):
+    content: Annotated[str, Streamed]
+```
+
+When generating JMux classes, fields annotated with `Streamed` will be converted to `StreamableValues[str]` instead of `AwaitableValue[str]`.
+
+## License
+
+This project is licensed under the terms of the MIT license. See the [LICENSE](LICENSE) file for details.
 
 ## Contributions
 

{jmux-0.0.5 → jmux-0.1.0}/README.md

@@ -8,8 +8,10 @@ This package is inspired by `Snapshot Streaming` mentioned in the [`WWDC25: Meet
 
 ## Features
 
-- **Asynchronous by Design**: Built on top of `asyncio`, JMux is perfect for modern, high-performance Python applications.
+- **Asynchronous by Design**: Built on top of `anyio`, JMux supports both `asyncio` and `trio` backends, making it perfect for modern, high-performance Python applications.
+- **Python 3.10+**: Supports Python 3.10 and newer versions.
 - **Pydantic Integration**: Validate your `JMux` classes against Pydantic models to ensure type safety and consistency.
+- **Code Generation**: Automatically generate JMux classes from `StreamableBaseModel` subclasses using the `jmux generate` CLI command.
 - **Awaitable and Streamable Sinks**: Use `AwaitableValue` for single values and `StreamableValues` for streams of values.
 - **Robust Error Handling**: JMux provides a comprehensive set of exceptions to handle parsing errors and other issues.
 - **Lightweight**: JMux has only a few external dependencies, making it easy to integrate into any project.
@@ -22,21 +24,155 @@ You can install JMux from PyPI using pip:
 pip install jmux
 ```
 
+## Code Generation
+
+JMux provides a CLI tool to automatically generate JMux classes from Pydantic models. Instead of manually writing both a Pydantic model and a corresponding JMux class, you can define your models using `StreamableBaseModel` and let JMux generate the demultiplexer classes for you.
+
+### Defining Models with StreamableBaseModel
+
+Use `StreamableBaseModel` as your base class instead of `pydantic.BaseModel`:
+
+```python
+from typing import Annotated
+from jmux import StreamableBaseModel, Streamed
+
+class LlmResponse(StreamableBaseModel):
+    thought: str
+    tool_code: Annotated[str, Streamed]
+    tags: list[str]
+```
+
+### Type Mappings
+
+The generator converts your model fields to JMux types as follows:
+
+| Model Field Type              | Generated JMux Type               |
+| ----------------------------- | --------------------------------- |
+| `str`, `int`, `float`, `bool` | `AwaitableValue[T]`               |
+| `Enum`                        | `AwaitableValue[EnumType]`        |
+| `T \| None`                   | `AwaitableValue[T \| None]`       |
+| `list[T]`                     | `StreamableValues[T]`             |
+| `Annotated[str, Streamed]`    | `StreamableValues[str]`           |
+| Nested `StreamableBaseModel`  | `AwaitableValue[NestedModelJMux]` |
+
+The `Streamed` marker is useful when you want to stream a string field character-by-character (e.g., for real-time display of LLM output) rather than awaiting the complete value.
+
+### Using the CLI
+
+Run the `jmux generate` command to scan your codebase and generate JMux classes:
+
+```bash
+jmux generate --root <directory>
+```
+
+This will:
+
+1. Recursively scan `<directory>` for Python files containing `StreamableBaseModel` subclasses
+2. Generate corresponding JMux classes with the suffix `JMux` (e.g., `LlmResponse` → `LlmResponseJMux`)
+3. Write the generated code to `src/jmux/generated/__init__.py`
+
+### Example
+
+Given this model:
+
+```python
+from typing import Annotated
+from jmux import StreamableBaseModel, Streamed
+
+class LlmResponse(StreamableBaseModel):
+    thought: str
+    tool_code: Annotated[str, Streamed]
+```
+
+Running `jmux generate` produces:
+
+```python
+from jmux.awaitable import AwaitableValue, StreamableValues
+from jmux.demux import JMux
+
+class LlmResponseJMux(JMux):
+    thought: AwaitableValue[str]
+    tool_code: StreamableValues[str]
+```
+
+You can then import and use the generated class:
+
+```python
+from jmux.generated import LlmResponseJMux
+
+jmux_instance = LlmResponseJMux()
+```
+
 ## Usage with LLMs (e.g., `litellm`)
 
 The primary use case for `jmux` is to process streaming JSON responses from LLMs. This allows you to react to parts of the data as it arrives, rather than waiting for the entire JSON object to be transmitted. While this should be obvious, I should mention, that **the order in which the pydantic model defines the properties, defines which stream is filled first**.
 
-Here’s a conceptual example of how you might integrate `jmux` with an LLM call, such as one made with `litellm`:
+### Using Code Generation (Recommended)
+
+The easiest way to use JMux with LLMs is to define your models using `StreamableBaseModel` and generate JMux classes automatically:
+
+```python
+from typing import Annotated
+from jmux import StreamableBaseModel, Streamed
+
+class LlmResponse(StreamableBaseModel): # Use `StreamableBaseModel` so that the CLI can find the `pydantic` models to parse
+    thought: str
+    tool_code: Annotated[str, Streamed]
+```
+
+Then run `jmux generate --root .` to generate the `LlmResponseJMux` class. You can then use it directly:
+
+```python
+import anyio
+from jmux.generated import LlmResponseJMux
+
+async def mock_llm_stream():
+    json_stream = '{"thought": "I need to write some code.", "tool_code": "print(\'Hello, World!\')"}'
+    for char in json_stream:
+        yield char
+        await anyio.sleep(0.01)
+
+async def process_llm_response():
+    jmux_instance = LlmResponseJMux()
+
+    async def feed_stream():
+        async for chunk in mock_llm_stream():
+            await jmux_instance.feed_chunks(chunk)
+
+    async def consume_thought():
+        thought = await jmux_instance.thought
+        print(f"LLM's thought received: '{thought}'")
+
+    async def consume_tool_code():
+        print("Receiving tool code...")
+        full_code = ""
+        async for code_fragment in jmux_instance.tool_code:
+            full_code += code_fragment
+            print(f"  -> Received fragment: {code_fragment}")
+        print(f"Full tool code received: {full_code}")
+
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(feed_stream)
+        tg.start_soon(consume_thought)
+        tg.start_soon(consume_tool_code)
+
+if __name__ == "__main__":
+    anyio.run(process_llm_response, backend="asyncio")
+```
+
+### Manual Approach
+
+If you prefer more control, you can manually define both the Pydantic model and the JMux class:
 
 ```python
-import asyncio
+import anyio
 from pydantic import BaseModel
 from jmux import JMux, AwaitableValue, StreamableValues
 # litellm is used conceptually here
 # from litellm import acompletion
 
 # 1. Define the Pydantic model for the expected JSON response
-class LlmResponse(BaseModel):
+class LlmResponse(BaseModel): # No need to use `StreamableBaseModel` here, since it is only used for detection purposes
     thought: str # **This property is filled first**
     tool_code: str
 
@@ -53,7 +189,7 @@ async def mock_llm_stream():
     json_stream = '{"thought": "I need to write some code.", "tool_code": "print(\'Hello, World!\')"}'
     for char in json_stream:
         yield char
-        await asyncio.sleep(0.01) # Simulate network latency
+        await anyio.sleep(0.01) # Simulate network latency
 
 # Main function to orchestrate the call and processing
 async def process_llm_response():
@@ -79,15 +215,16 @@ async def process_llm_response():
             print(f"  -> Received fragment: {code_fragment}")
         print(f"Full tool code received: {full_code}")
 
-    # Run all tasks concurrently
-    await asyncio.gather(
-        feed_stream(),
-        consume_thought(),
-        consume_tool_code()
-    )
+    # Run all tasks concurrently using anyio task group
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(feed_stream)
+        tg.start_soon(consume_thought)
+        tg.start_soon(consume_tool_code)
 
+# Run with asyncio backend
 if __name__ == "__main__":
-    asyncio.run(process_llm_response())
+    anyio.run(process_llm_response, backend="asyncio")
+    # Or use trio: anyio.run(process_llm_response, backend="trio")
 ```
 
 ## Example Implementation
@@ -159,7 +296,7 @@ You can either `await awaitable_llm_result` if you need the full result, or use
 Here is a simple example of how to use JMux to parse a JSON stream:
 
 ```python
-import asyncio
+import anyio
 from enum import Enum
 from types import NoneType
 from pydantic import BaseModel
@@ -244,10 +381,13 @@ async def main():
         nested_key_str = await key_nested.key_str
         print(f"nested_key_str: {nested_key_str}")
 
-    await asyncio.gather(produce(), consume())
+    async with anyio.create_task_group() as tg:
+        tg.start_soon(produce)
+        tg.start_soon(consume)
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    anyio.run(main, backend="asyncio")
+    # Or use trio: anyio.run(main, backend="trio")
 ```
 
 ## API Reference
@@ -296,13 +436,35 @@ Additionally the following type is supported without being wrapped into `list`:
 
 This allows you to fully stream strings directly to a sink.
 
-## License
+### Class `jmux.StreamableBaseModel`
 
-This project is licensed under the terms of the MIT license. See the [LICENSE](LICENSE) file for details.
+A Pydantic `BaseModel` subclass used for defining models that can be automatically converted to JMux classes via the `jmux generate` CLI command.
+
+```python
+from jmux import StreamableBaseModel
 
-## Planned Improvements
+class MyModel(StreamableBaseModel):
+    name: str
+    age: int
+```
+
+### Class `jmux.Streamed`
+
+A marker class used with `typing.Annotated` to indicate that a string field should be streamed character-by-character rather than awaited as a complete value.
 
-- Add support for older Python versions
+```python
+from typing import Annotated
+from jmux import StreamableBaseModel, Streamed
+
+class MyModel(StreamableBaseModel):
+    content: Annotated[str, Streamed]
+```
+
+When generating JMux classes, fields annotated with `Streamed` will be converted to `StreamableValues[str]` instead of `AwaitableValue[str]`.
+
+## License
+
+This project is licensed under the terms of the MIT license. See the [LICENSE](LICENSE) file for details.
 
 ## Contributions
 

{jmux-0.0.5 → jmux-0.1.0}/pyproject.toml

@@ -17,6 +17,9 @@ authors = [{ name = "Johannes A.I. Unruh", email = "johannes@unruh.ai" }]
 dependencies = ["anyio>=4.0.0", "pydantic>=2.0.0"]
 keywords = ["demultiplexer", "python", "package", "json"]
 
+[project.scripts]
+jmux = "jmux.cli:main"
+
 [tool.setuptools_scm]
 
 [project.urls]
@@ -24,11 +27,12 @@ Homepage = "https://github.com/jaunruh/jmux"
 Repository = "https://github.com/jaunruh/jmux"
 
 [project.optional-dependencies]
-test = ["pytest", "pytest-anyio"]
+test = ["pytest", "pytest-anyio", "trio"]
 dev = [
   "ruff",
   "pytest",
   "pytest-anyio",
+  "trio",
   "uv",
   "build",
   "twine",
@@ -39,8 +43,9 @@ dev = [
 [tool.ruff]
 # Ruff configuration example
 line-length = 88
-select = ["E", "F", "I"] # Errors, Fixes, Import sorting
+select = ["E", "F", "I"]          # Errors, Fixes, Import sorting
 ignore = []
+exclude = ["src/jmux/generated/"]
 
 # Or only in test files:
 [tool.ruff.per-file-ignores]

jmux-0.1.0/src/jmux/__init__.py

@@ -0,0 +1,11 @@
+from jmux.awaitable import AwaitableValue, StreamableValues
+from jmux.base import StreamableBaseModel, Streamed
+from jmux.demux import JMux
+
+__all__ = [
+    "AwaitableValue",
+    "JMux",
+    "Streamed",
+    "StreamableBaseModel",
+    "StreamableValues",
+]