python-beam 0.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. python_beam-0.1.0a1/.gitignore +248 -0
  2. python_beam-0.1.0a1/PKG-INFO +45 -0
  3. python_beam-0.1.0a1/README.md +20 -0
  4. python_beam-0.1.0a1/benchmarks/pyproject.toml +40 -0
  5. python_beam-0.1.0a1/benchmarks/web/pyproject.toml +2 -0
  6. python_beam-0.1.0a1/docs/research/probes/README.md +58 -0
  7. python_beam-0.1.0a1/examples/chat_load/README.md +154 -0
  8. python_beam-0.1.0a1/examples/chat_load/conventional/pyproject.toml +19 -0
  9. python_beam-0.1.0a1/examples/discord_demo/README.md +23 -0
  10. python_beam-0.1.0a1/examples/distributed/README.md +61 -0
  11. python_beam-0.1.0a1/examples/fastapi/README.md +16 -0
  12. python_beam-0.1.0a1/examples/otp_host/README.md +40 -0
  13. python_beam-0.1.0a1/pyproject.toml +112 -0
  14. python_beam-0.1.0a1/site/README.md +30 -0
  15. python_beam-0.1.0a1/src/pybeam/__init__.py +10 -0
  16. python_beam-0.1.0a1/src/pybeam/_shared/__init__.py +0 -0
  17. python_beam-0.1.0a1/src/pybeam/_shared/lifecycle.py +13 -0
  18. python_beam-0.1.0a1/src/pybeam/actors/__init__.py +15 -0
  19. python_beam-0.1.0a1/src/pybeam/actors/classes.py +421 -0
  20. python_beam-0.1.0a1/src/pybeam/actors/codec.py +185 -0
  21. python_beam-0.1.0a1/src/pybeam/actors/groups.py +378 -0
  22. python_beam-0.1.0a1/src/pybeam/actors/native.py +50 -0
  23. python_beam-0.1.0a1/src/pybeam/actors/protocol.py +60 -0
  24. python_beam-0.1.0a1/src/pybeam/actors/state.py +194 -0
  25. python_beam-0.1.0a1/src/pybeam/codec.py +608 -0
  26. python_beam-0.1.0a1/src/pybeam/distribution.py +158 -0
  27. python_beam-0.1.0a1/src/pybeam/integrations/__init__.py +0 -0
  28. python_beam-0.1.0a1/src/pybeam/integrations/fastapi/__init__.py +0 -0
  29. python_beam-0.1.0a1/src/pybeam/integrations/fastapi/dependencies.py +30 -0
  30. python_beam-0.1.0a1/src/pybeam/integrations/genstage/__init__.py +0 -0
  31. python_beam-0.1.0a1/src/pybeam/integrations/genstage/graph.ex +213 -0
  32. python_beam-0.1.0a1/src/pybeam/integrations/genstage/pipeline.py +84 -0
  33. python_beam-0.1.0a1/src/pybeam/integrations/genstage/pybeam_genstage.app +10 -0
  34. python_beam-0.1.0a1/src/pybeam/integrations/genstage/pybeam_genstage.erl +14 -0
  35. python_beam-0.1.0a1/src/pybeam/integrations/hornbeam/__init__.py +5 -0
  36. python_beam-0.1.0a1/src/pybeam/integrations/hornbeam/client.py +90 -0
  37. python_beam-0.1.0a1/src/pybeam/integrations/hornbeam/contracts.py +37 -0
  38. python_beam-0.1.0a1/src/pybeam/integrations/hornbeam/dependencies.py +32 -0
  39. python_beam-0.1.0a1/src/pybeam/integrations/hornbeam/errors.py +6 -0
  40. python_beam-0.1.0a1/src/pybeam/integrations/hornbeam/runtime.py +23 -0
  41. python_beam-0.1.0a1/src/pybeam/integrations/litestar/__init__.py +0 -0
  42. python_beam-0.1.0a1/src/pybeam/integrations/litestar/channels.py +262 -0
  43. python_beam-0.1.0a1/src/pybeam/integrations/litestar/store.py +57 -0
  44. python_beam-0.1.0a1/src/pybeam/integrations/litestar/tasks.py +24 -0
  45. python_beam-0.1.0a1/src/pybeam/integrations/pyview/__init__.py +0 -0
  46. python_beam-0.1.0a1/src/pybeam/integrations/pyview/dependencies.py +31 -0
  47. python_beam-0.1.0a1/src/pybeam/integrations/pyview/subscriptions.py +103 -0
  48. python_beam-0.1.0a1/src/pybeam/mailbox.py +46 -0
  49. python_beam-0.1.0a1/src/pybeam/py.typed +0 -0
  50. python_beam-0.1.0a1/src/pybeam/queues.py +294 -0
  51. python_beam-0.1.0a1/src/pybeam/runtime/__init__.py +0 -0
  52. python_beam-0.1.0a1/src/pybeam/runtime/assets.py +242 -0
  53. python_beam-0.1.0a1/src/pybeam/runtime/attach.py +216 -0
  54. python_beam-0.1.0a1/src/pybeam/runtime/cli.py +112 -0
  55. python_beam-0.1.0a1/src/pybeam/runtime/cluster.py +462 -0
  56. python_beam-0.1.0a1/src/pybeam/runtime/config.py +164 -0
  57. python_beam-0.1.0a1/src/pybeam/runtime/console.py +24 -0
  58. python_beam-0.1.0a1/src/pybeam/runtime/debug.py +45 -0
  59. python_beam-0.1.0a1/src/pybeam/runtime/entrypoint.py +35 -0
  60. python_beam-0.1.0a1/src/pybeam/runtime/guardian.py +531 -0
  61. python_beam-0.1.0a1/src/pybeam/runtime/inspector.py +102 -0
  62. python_beam-0.1.0a1/src/pybeam/runtime/loader.py +224 -0
  63. python_beam-0.1.0a1/src/pybeam/runtime/optional.py +48 -0
  64. python_beam-0.1.0a1/src/pybeam/runtime/optional_manifest.py +163 -0
  65. python_beam-0.1.0a1/src/pybeam/runtime/optional_specs/genstage.json +2978 -0
  66. python_beam-0.1.0a1/src/pybeam/runtime/ownership.py +237 -0
  67. python_beam-0.1.0a1/src/pybeam/runtime/process.py +262 -0
  68. python_beam-0.1.0a1/src/pybeam/runtime/startup.py +138 -0
  69. python_beam-0.1.0a1/src/pybeam/runtime/tui.py +247 -0
  70. python_beam-0.1.0a1/src/pybeam/services/__init__.py +0 -0
  71. python_beam-0.1.0a1/src/pybeam/services/background.py +7 -0
  72. python_beam-0.1.0a1/src/pybeam/submissions.py +10 -0
  73. python_beam-0.1.0a1/src/pybeam/supervision/__init__.py +0 -0
  74. python_beam-0.1.0a1/src/pybeam/supervision/config.py +75 -0
  75. python_beam-0.1.0a1/src/pybeam/supervision/errors.py +2 -0
  76. python_beam-0.1.0a1/src/pybeam/supervision/ref.py +118 -0
  77. python_beam-0.1.0a1/src/pybeam/tasks.py +505 -0
  78. python_beam-0.1.0a1/tools/build_genstage.py +220 -0
  79. python_beam-0.1.0a1/tools/build_native.py +93 -0
  80. python_beam-0.1.0a1/tools/build_runtime.py +468 -0
  81. python_beam-0.1.0a1/tools/genstage_assets.py +151 -0
  82. python_beam-0.1.0a1/tools/genstage_fixtures.py +89 -0
  83. python_beam-0.1.0a1/tools/hatch_build.py +29 -0
  84. python_beam-0.1.0a1/tools/runtime_wheel.py +121 -0
@@ -0,0 +1,248 @@
1
+ ### https://github.com/github/gitignore/blob/main/Python.gitignore
2
+
3
+ # Byte-compiled / optimized / DLL files
4
+ __pycache__/
5
+ *.py[codz]
6
+ *$py.class
7
+
8
+ # C extensions
9
+ *.so
10
+
11
+ # Distribution / packaging
12
+ .Python
13
+ build/
14
+ develop-eggs/
15
+ dist/
16
+ downloads/
17
+ eggs/
18
+ .eggs/
19
+ lib/
20
+ lib64/
21
+ parts/
22
+ sdist/
23
+ var/
24
+ wheels/
25
+ share/python-wheels/
26
+ *.egg-info/
27
+ .installed.cfg
28
+ *.egg
29
+ MANIFEST
30
+
31
+ # PyInstaller
32
+ # Usually these files are written by a python script from a template
33
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
34
+ *.manifest
35
+ *.spec
36
+
37
+ # Installer logs
38
+ pip-log.txt
39
+ pip-delete-this-directory.txt
40
+
41
+ # Unit test / coverage reports
42
+ htmlcov/
43
+ .tox/
44
+ .nox/
45
+ .coverage
46
+ .coverage.*
47
+ .cache
48
+ nosetests.xml
49
+ coverage.xml
50
+ *.cover
51
+ *.py.cover
52
+ *.lcov
53
+ .hypothesis/
54
+ .pytest_cache/
55
+ cover/
56
+
57
+ # Translations
58
+ *.mo
59
+ *.pot
60
+
61
+ # Django stuff:
62
+ *.log
63
+ local_settings.py
64
+ db.sqlite3
65
+ db.sqlite3-journal
66
+
67
+ # Flask stuff:
68
+ instance/
69
+ .webassets-cache
70
+
71
+ # Scrapy stuff:
72
+ .scrapy
73
+
74
+ # Sphinx documentation
75
+ docs/_build/
76
+
77
+ # PyBuilder
78
+ .pybuilder/
79
+ target/
80
+
81
+ # Jupyter Notebook
82
+ .ipynb_checkpoints
83
+
84
+ # IPython
85
+ profile_default/
86
+ ipython_config.py
87
+
88
+ # pyenv
89
+ # For a library or package, you might want to ignore these files since the code is
90
+ # intended to run in multiple environments; otherwise, check them in:
91
+ # .python-version
92
+
93
+ # pipenv
94
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
95
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
96
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
97
+ # install all needed dependencies.
98
+ # Pipfile.lock
99
+
100
+ # uv
101
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
102
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
103
+ # commonly ignored for libraries.
104
+ # uv.lock
105
+
106
+ # poetry
107
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
108
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
109
+ # commonly ignored for libraries.
110
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
111
+ # poetry.lock
112
+ # poetry.toml
113
+
114
+ # pdm
115
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
116
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
117
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
118
+ # pdm.lock
119
+ # pdm.toml
120
+ .pdm-python
121
+ .pdm-build/
122
+
123
+ # pixi
124
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
125
+ # pixi.lock
126
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
127
+ # in the .venv directory. It is recommended not to include this directory in version control.
128
+ .pixi/*
129
+ !.pixi/config.toml
130
+
131
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
132
+ __pypackages__/
133
+
134
+ # Celery stuff
135
+ celerybeat-schedule*
136
+ celerybeat.pid
137
+
138
+ # Redis
139
+ *.rdb
140
+ *.aof
141
+ *.pid
142
+
143
+ # RabbitMQ
144
+ mnesia/
145
+ rabbitmq/
146
+ rabbitmq-data/
147
+
148
+ # ActiveMQ
149
+ activemq-data/
150
+
151
+ # SageMath parsed files
152
+ *.sage.py
153
+
154
+ # Environments
155
+ .env
156
+ .envrc
157
+ .venv
158
+ env/
159
+ venv/
160
+ ENV/
161
+ env.bak/
162
+ venv.bak/
163
+
164
+ # Conda environments
165
+ conda-meta/
166
+
167
+ # Spyder project settings
168
+ .spyderproject
169
+ .spyproject
170
+
171
+ # Rope project settings
172
+ .ropeproject
173
+
174
+ # Documentation build output
175
+ site/node_modules/
176
+ site/dist/
177
+ site/.astro/
178
+
179
+ # mypy
180
+ .mypy_cache/
181
+ .dmypy.json
182
+ dmypy.json
183
+
184
+ # Pyre type checker
185
+ .pyre/
186
+
187
+ # pytype static type analyzer
188
+ .pytype/
189
+
190
+ # Cython debug symbols
191
+ cython_debug/
192
+
193
+ # PyCharm
194
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
195
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
196
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
197
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
198
+ # .idea/
199
+
200
+ # Abstra
201
+ # Abstra is an AI-powered process automation framework.
202
+ # Ignore directories containing user credentials, local state, and settings.
203
+ # Learn more at https://abstra.io/docs
204
+ .abstra/
205
+
206
+ # Visual Studio Code
207
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
208
+ # can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
209
+ # and can be added to the global gitignore or merged into this file. However, if you prefer, you
210
+ # could uncomment the following to ignore the entire vscode folder
211
+ # .vscode/
212
+ # Temporary file for partial code execution
213
+ tempCodeRunnerFile.py
214
+
215
+ # Ruff stuff:
216
+ .ruff_cache/
217
+
218
+ # PyPI configuration file
219
+ .pypirc
220
+
221
+ # Marimo
222
+ marimo/_static/
223
+ marimo/_lsp/
224
+ __marimo__/
225
+
226
+ # Streamlit
227
+ .streamlit/secrets.toml
228
+
229
+ ### https://github.com/github/gitignore/blob/main/Erlang.gitignore
230
+
231
+ .eunit
232
+ *.o
233
+ *.beam
234
+ *.plt
235
+ erl_crash.dump
236
+ .concrete/DEV_MODE
237
+
238
+ # rebar 2.x
239
+ .rebar
240
+ rel/example_project
241
+ ebin/*.beam
242
+ deps
243
+
244
+ # rebar 3
245
+ .rebar3
246
+ _build/
247
+ _checkouts/
248
+ src/pybeam/runtime/_assets/
@@ -0,0 +1,45 @@
1
+ Metadata-Version: 2.5
2
+ Name: python-beam
3
+ Version: 0.1.0a1
4
+ Summary: Python-first tools for BEAM services
5
+ Requires-Python: >=3.14
6
+ Provides-Extra: fastapi
7
+ Requires-Dist: fastapi==0.163.0; extra == 'fastapi'
8
+ Requires-Dist: jinja2<4,>=3.1.6; extra == 'fastapi'
9
+ Requires-Dist: python-multipart<1,>=0.0.20; extra == 'fastapi'
10
+ Requires-Dist: uvicorn==0.54.0; extra == 'fastapi'
11
+ Provides-Extra: genstage
12
+ Provides-Extra: hornbeam
13
+ Requires-Dist: hornbeam; extra == 'hornbeam'
14
+ Provides-Extra: litestar
15
+ Requires-Dist: litestar[jinja]==2.25.0; extra == 'litestar'
16
+ Requires-Dist: pydantic==2.14.3; extra == 'litestar'
17
+ Provides-Extra: pyview
18
+ Requires-Dist: python-multipart<1,>=0.0.20; extra == 'pyview'
19
+ Requires-Dist: pyview-web<1,>=0.9.0; extra == 'pyview'
20
+ Provides-Extra: showcase
21
+ Requires-Dist: fastapi==0.163.0; extra == 'showcase'
22
+ Requires-Dist: jinja2<4,>=3.1.6; extra == 'showcase'
23
+ Requires-Dist: uvicorn<1,>=0.41; extra == 'showcase'
24
+ Description-Content-Type: text/markdown
25
+
26
+ # PyBEAM
27
+
28
+ Actors, shared state and messaging for async Python, without a separate broker.
29
+
30
+ ```sh
31
+ uv add python-beam
32
+ ```
33
+
34
+ - [Actors](docs/guide/actors.md) keep state and handle one call at a time, without locks around actor state.
35
+ - [Supervision](docs/guide/supervision.md) restarts an actor that fails.
36
+ - [Shared state](docs/guide/state.md) stores values and counts atomically across requests.
37
+ - [Messaging](docs/guide/messaging.md) notifies subscribers without a broker.
38
+ - [Background services](docs/guide/background.md) run long-lived loops that stop cleanly.
39
+ - Integrations work with [FastAPI](docs/guide/integrations/fastapi.md), [Litestar](docs/guide/integrations/litestar.md) and [PyView](docs/guide/integrations/pyview.md).
40
+
41
+ Start with [Get started](docs/guide/index.md), or read [Why PyBEAM](docs/guide/why.md).
42
+
43
+ Try the [Discord demo](examples/discord_demo/README.md) and the [showcase](examples/showcase).
44
+
45
+ To work on PyBEAM itself, see [Development](docs/development.md).
@@ -0,0 +1,20 @@
1
+ # PyBEAM
2
+
3
+ Actors, shared state and messaging for async Python, without a separate broker.
4
+
5
+ ```sh
6
+ uv add python-beam
7
+ ```
8
+
9
+ - [Actors](docs/guide/actors.md) keep state and handle one call at a time, without locks around actor state.
10
+ - [Supervision](docs/guide/supervision.md) restarts an actor that fails.
11
+ - [Shared state](docs/guide/state.md) stores values and counts atomically across requests.
12
+ - [Messaging](docs/guide/messaging.md) notifies subscribers without a broker.
13
+ - [Background services](docs/guide/background.md) run long-lived loops that stop cleanly.
14
+ - Integrations work with [FastAPI](docs/guide/integrations/fastapi.md), [Litestar](docs/guide/integrations/litestar.md) and [PyView](docs/guide/integrations/pyview.md).
15
+
16
+ Start with [Get started](docs/guide/index.md), or read [Why PyBEAM](docs/guide/why.md).
17
+
18
+ Try the [Discord demo](examples/discord_demo/README.md) and the [showcase](examples/showcase).
19
+
20
+ To work on PyBEAM itself, see [Development](docs/development.md).
@@ -0,0 +1,40 @@
1
+ [project]
2
+ name = "pybeam-benchmark-contract"
3
+ version = "0.1.0"
4
+ requires-python = ">=3.14,<3.15"
5
+ dependencies = [
6
+ "fastapi==0.163.0",
7
+ "httpx>=0.28,<1",
8
+ "pydantic==2.14.3",
9
+ "psutil>=7,<8",
10
+ "python-beam",
11
+ "uvicorn==0.54.0",
12
+ "websockets>=15,<17",
13
+ ]
14
+
15
+ [dependency-groups]
16
+ dev = ["pytest>=9,<10", "pytest-asyncio>=1,<2", "ruff>=0.14,<1", "ty>=0.0.104", "types-psutil>=7,<8"]
17
+
18
+ [tool.uv]
19
+ package = false
20
+
21
+ [tool.uv.sources]
22
+ python-beam = { path = "..", editable = true }
23
+
24
+ [tool.ruff]
25
+ target-version = "py314"
26
+ line-length = 100
27
+
28
+ [tool.ruff.lint]
29
+ select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "ANN", "ASYNC", "S"]
30
+ ignore = ["UP031", "UP032"]
31
+
32
+ [tool.ruff.lint.per-file-ignores]
33
+ "tests/**" = ["S101", "S603", "S607"]
34
+
35
+ [tool.ty.rules]
36
+ all = "error"
37
+
38
+ [tool.pytest.ini_options]
39
+ testpaths = ["tests"]
40
+ pythonpath = ["..", "../src"]
@@ -0,0 +1,2 @@
1
+ [tool.pybeam]
2
+ development_runtime = "../../_build/hornbeam"
@@ -0,0 +1,58 @@
1
+ # Isolated static API probes
2
+
3
+ These are proposals, not implemented actors. `candidates.py` contains abstract class declarations and reference protocols. Nothing constructs an actor, sends a message, or dispatches application operations by string. No proxy is asserted to have an actor's type.
4
+
5
+ ## Reproduce
6
+
7
+ Run from the repository root. The commands use the existing environment without syncing or changing dependencies. Pyright is an isolated research tool, not a project dependency. Production checking remains ty with all configured rules treated as errors.
8
+
9
+ Observed versions were ty `0.0.104` (`b4bb5b2c8`, 2026-11-13), Ruff `0.17.5`, and Pyright `1.1.414`. Both checkers target Python 3.14. Version checks actually run were:
10
+
11
+ ```sh
12
+ uv run --no-sync ty --version
13
+ uv run --no-sync ruff --version
14
+ uvx --from pyright pyright --version
15
+ ```
16
+
17
+ Final lint, formatting, and positive commands actually run were:
18
+
19
+ ```sh
20
+ uv run --no-sync ruff format docs/research/probes
21
+ uv run --no-sync ruff check docs/research/probes
22
+ uv run --no-sync ty check --error-on-warning docs/research/probes/candidates.py docs/research/probes/positive.py
23
+ uvx --from pyright==1.1.414 pyright --warnings --pythonversion 3.14 docs/research/probes/candidates.py docs/research/probes/positive.py
24
+ ```
25
+
26
+ Lint and positive checks passed. Pyright reported zero errors and zero warnings. `assert_type` checks establish an awaited `int` result for each call shape. Additional positives show that an actor class can structurally satisfy `CounterRef` and that the generic callable contract accepts a free function with a compatible receiver. Neither observation establishes a remote reference or an allowed actor operation.
27
+
28
+ Negative commands actually run were:
29
+
30
+ ```sh
31
+ uv run --no-sync ty check --output-format concise --error-on-warning docs/research/probes/negative_generic.py docs/research/probes/negative_direct.py docs/research/probes/negative_explicit.py
32
+ uvx --from pyright==1.1.414 pyright --warnings --pythonversion 3.14 docs/research/probes/negative_generic.py docs/research/probes/negative_direct.py docs/research/probes/negative_explicit.py
33
+ ```
34
+
35
+ Both commands intentionally fail with verified exit status 1. Do not add these files to a passing production type gate. All negative functions must be rejected, not merely enough functions to produce a nonzero exit. ty reported 27 error diagnostics. Pyright reported 27 errors and zero warnings.
36
+
37
+ ## Expected negative diagnostics
38
+
39
+ Each negative module tests the following functions. Line numbers are shared across modules except the generic bound method case.
40
+
41
+ | Function | Line | ty | Pyright |
42
+ | --- | --- | --- | --- |
43
+ | `wrong_receiver` | 5 | `invalid-argument-type` for generic/direct; `invalid-explicit-return` for explicit | `reportArgumentType` for generic/direct; `reportReturnType` for explicit |
44
+ | `wrong_positional` | 9 | `invalid-argument-type` | `reportArgumentType` |
45
+ | `wrong_keyword_value` | 13 | `invalid-argument-type` | `reportArgumentType` |
46
+ | `wrong_keyword_name` | 17 | `missing-argument` and `unknown-argument` | Two `reportCallIssue` errors |
47
+ | `missing_keyword` | 21 | `missing-argument` | `reportCallIssue` |
48
+ | `positional_only` | 25 | `positional-only-parameter-as-kwarg` | `reportCallIssue` |
49
+ | `wrong_return` | 29 | `invalid-explicit-return` | `reportReturnType` |
50
+ | `bound_method`, generic only | 33 | `invalid-argument-type` | `reportArgumentType` and `reportCallIssue` |
51
+
52
+ For the generic wrong receiver and bound method, ty also reports `unsound-return` because failed inference leaves an unknown result. Pyright additionally reports `reportAbstractUsage` for the direct unbound invocation of the abstract method. These extra errors do not replace the receiver errors. Counts by file are ty 11 generic, 8 direct, 8 explicit; Pyright 10 generic, 9 direct, 8 explicit.
53
+
54
+ ## Limits
55
+
56
+ The probes establish the listed static facts for these checker versions and one method signature. They do not establish a transport implementation or prove actor membership. `CounterRef` is structural, not a remote identity marker. `Counter` is an abstract declaration, not a proxy returned from spawning. Abstract methods raise `NotImplementedError`; they are not local actor implementations.
57
+
58
+ No actor runtime, runtime test, framework integration test, dependency isolation test, or Python probe execution was run. Overloads, descriptors, inherited generic methods, and more complex ParamSpec inference were not tested. Pyright used its normal CLI checking mode with warnings enforced, not an added strict project configuration. No serialization, cancellation, mailbox scheduling, restart, cross-node compatibility, or isolation claim follows from passing these checks. In particular, `int` typing does not establish transport range limits or distinguish booleans from integers.
@@ -0,0 +1,154 @@
1
+ # Chat under load
2
+
3
+ This example runs the same chat server in two ways and drives both with one
4
+ traffic simulator:
5
+
6
+ - `app.py`: one PyBEAM process. Room counters, room pub/sub, and background
7
+ jobs use PyBEAM services and `TaskSupervisor`.
8
+ - `conventional/`: eight web workers, a KV cache for counters and pub/sub,
9
+ a message broker, and a task-queue worker.
10
+
11
+ Both servers share `protocol.py`, `rooms.py` and `jobs.py`. Each room keeps one
12
+ subscription per server process and fans pushes out to its local WebSockets.
13
+ A client that falls 256 pushes behind is closed with code 1013.
14
+
15
+ ## Simulate traffic
16
+
17
+ Pass the server URL. `--pid` samples a server process tree's CPU and memory
18
+ from `/proc` (Linux only); repeat it for each container.
19
+
20
+ ```console
21
+ $ mise run example:chat-load -- http://127.0.0.1:8800 --pid "$(pgrep -f examples.chat_load.app)"
22
+ $ mise run example:chat-load -- http://127.0.0.1:8801 \
23
+ $(docker compose -f examples/chat_load/conventional/compose.yaml ps -q | xargs docker inspect -f '--pid {{.State.Pid}}')
24
+ ```
25
+
26
+ Each client sends Poisson-timed messages without waiting for replies, and the
27
+ simulator posts background jobs at a fixed average rate. It reports measured
28
+ values only:
29
+
30
+ - acknowledgement, fan-out and job completion latency percentiles
31
+ - deliveries against the expected count (every client in a room sees each message)
32
+ - counter mismatches between the server's room counters and what clients saw
33
+ - rejected jobs, connection errors, and server CPU, memory and process count
34
+
35
+ Use `--json report.json` to keep the full report. Run `--help` for the load
36
+ options.
37
+
38
+ ## Crash test
39
+
40
+ With a compatible runtime installed, run the servers and dashboard in separate
41
+ terminals. Use a configured 3.14.10t runtime to reproduce the measurements below.
42
+
43
+ ```console
44
+ $ mise run example:chat
45
+ $ docker compose -f examples/chat_load/conventional/compose.yaml up -d --build
46
+ $ uv run --locked --extra fastapi python -m examples.chat_load.crash_test
47
+ ```
48
+
49
+ Open `http://127.0.0.1:8802`; servers use ports 8800/8801. The dashboard also
50
+ starts with `mise run example:crash-test`. Flags: `--usual-url`, `--pybeam-url`,
51
+ `--rooms`, `--clients`, `--rate` (messages/s/socket). Traffic runs once per
52
+ dashboard process, not per tab. Choose **Crash one request on both**. After a 4 s
53
+ countdown, the same native crash runs on both stacks concurrently. Watch another
54
+ user's connection: does it drop, or keep getting replies? Each test watches 10 s
55
+ of traffic, then allows 5 s for recovery.
56
+ The default rate is one message per second per user so the conversation is
57
+ readable. The button waits for live replies from every user on both stacks.
58
+
59
+ The view selects a user who actually disconnected or waited for a reply, then
60
+ shows the matching user on both sides. It retains the interruption and other-room
61
+ disconnect counts after connections recover. “Confirmed” means the server
62
+ acknowledged a send. An unconfirmed send might have reached the server; clients
63
+ do not replay it. A run with no disconnects does not establish zero latency impact.
64
+
65
+ Rooms group messages, not server processes. Users from different rooms can share
66
+ one web worker. A native crash kills that worker and closes its connections,
67
+ regardless of room. PyBEAM sends this crash-prone code to a separate child process,
68
+ away from chat connections. An ordinary Python exception does not kill the worker,
69
+ and a Python app could also isolate work in another process. This demo compares
70
+ the two configurations, not immunity from every kind of crash.
71
+
72
+ The dashboard has one test: the native crash. The runner also accepts
73
+ `POST /run/hog` and `POST /run/raise` for separate CPU-stall and exception tests.
74
+ Only the latest result is retained. A run already in progress rejects another
75
+ start. Keep this local.
76
+
77
+ The run targets `room-1` through `POST /rooms/{room}/faults/{kind}`:
78
+
79
+ | Fault | Usual stack | PyBEAM |
80
+ | --- | --- | --- |
81
+ | `raise` | Handler raises; HTTP 500 and failed notice | Dedicated-loop task raises; HTTP 200 and contained notice |
82
+ | `hog` | Tight loop blocks one web worker for 3 s | Dedicated-loop task runs the same loop; completed notice |
83
+ | `abort` | Worker dies; request loses its response; replacement worker starts | Isolated child dies; HTTP 200 and contained notice |
84
+
85
+ The fault target is separate from the other-room conversation. Its request
86
+ outcome is not a measurement of other users' experience. A lost fault request
87
+ alone does not prove a worker died. Results depend on worker assignment and
88
+ this machine. The usual stack runs faults in its web workers; PyBEAM runs native
89
+ crashes in isolated child processes. This compares those failure boundaries,
90
+ not maximum throughput. The measurements below used a separate load runner.
91
+
92
+ ### Measured limits
93
+
94
+ Linux x86-64, 8 CPUs shared with the loopback client; dashboard stopped,
95
+ stacks loaded sequentially. Three trials per point; medians [min–max].
96
+ PyBEAM: 3.14.10t, dedicated-loop tasks. Usual stack: 3.14.10, eight web workers
97
+ and a KV cache.
98
+
99
+ Fault trials: 8 rooms × 4 sockets × 4 messages/s, no jobs. Paired 3 s baseline
100
+ and fault windows; fault windows start at the client POST, including dispatch.
101
+ Only rooms 2–8 sends scheduled in the window count. Late replies retain full
102
+ latency; missing replies after an 8 s drain count as unbounded, including
103
+ sends missed during reconnection.
104
+
105
+ | Other-room ack p99, ms: baseline → fault | Usual stack | PyBEAM |
106
+ | --- | --- | --- |
107
+ | `hog` | 4.52 [4.19–4.59] → 2935.94 [2615.46–3003.46] | 3.63 [2.19–99.64] → 4.95 [3.27–5.93] |
108
+ | `abort` | 3.32 [3.27–4.51] → unbounded [3.74–unbounded] | 4.28 [3.61–4.46] → 4.52 [2.86–8.73] |
109
+ | `raise` | 2.72 [2.67–6.63] → 4.24 [2.58–12.32] | 5.11 [2.85–49.00] → 3.77 [3.46–5.98] |
110
+
111
+ Hog-window maximum pending age was 2962.41 [2905.37–2976.08] ms versus
112
+ 2.51 [1.29–4.16] ms. Abort disconnected 9 [3–9] of 28 other-room sockets
113
+ versus zero, with 12 [3–12] versus zero scheduled sends unacknowledged.
114
+ All post-fault health checks returned 200; other-room HTTP probes had zero
115
+ failures. PyBEAM's paired hog p99 changes (+2.30, +1.08, −94.68 ms) do **not**
116
+ establish zero latency impact.
117
+
118
+ Throughput: `traffic.py`, 8 rooms × 4 sockets, 64-byte messages, 15 s runs,
119
+ 10 s drain, 20 checksum jobs/s of size 200,000. Rates include completions
120
+ through the drain divided by active send time (jobs use the nominal 15 s).
121
+ Highest tested point with all
122
+ messages, fan-out and jobs delivered, no errors, and ack p99 ≤100 ms in all
123
+ three runs—not a server-only ceiling:
124
+
125
+ | Stack | Acknowledged messages/s | Ack p99, ms | Completed jobs/s |
126
+ | --- | --- | --- | --- |
127
+ | Usual stack | 3844 [3767–3884] | 21.05 [13.77–35.69] | 20.13 [19.80–20.27] |
128
+ | PyBEAM | 1989 [1969–1997] | 11.61 [8.84–14.36] | 21.20 [20.73–21.40] |
129
+
130
+ Nominal rates: 4096/s and 2048/s. Requiring ≥95% nominal delivery in every run
131
+ limits both to the 2048/s point. PyBEAM disconnected clients at 4096/s in two
132
+ of three runs, and at 8192/s in all three. The usual stack delivered all replies
133
+ at nominal 16384/s, but p99 reached 7892 [7005–8337] ms: draining a backlog is
134
+ not sustained throughput. Client CPU/pacing is shared; lower-load latency
135
+ outliers also occurred. These short-run points are not capacity guarantees.
136
+
137
+ ### Application and service changes
138
+
139
+ App code changes **205 lines: +130/−75**, not ten:
140
+ `git diff --no-index conventional/app.py app.py` gives +130/−52; deleting
141
+ the 23-line `conventional/worker.py` adds −23. Shared modules are excluded.
142
+ App code grows from 190 to 245 lines. Four compose services become one runtime:
143
+ the KV cache, message broker and task-queue worker are removed. Eight web
144
+ workers become one application process, plus a transient isolated abort child
145
+ and a separate development launcher.
146
+
147
+ ## Differences that affect the numbers
148
+
149
+ - PyBEAM admits at most 64 running jobs and rejects more with HTTP 503. The
150
+ task queue accepts every job and lets the broker queue grow.
151
+ - PyBEAM jobs use dedicated-loop worker tasks. Task-queue workers are
152
+ separate processes.
153
+ - Neither stack persists room counters or retries jobs. A job lost to a crash
154
+ stays lost in both. Counters in PyBEAM disappear when the process stops.
@@ -0,0 +1,19 @@
1
+ [project]
2
+ name = "chat-conventional"
3
+ version = "0.1.0"
4
+ requires-python = ">=3.14,<3.15"
5
+ dependencies = [
6
+ "celery>=5.5,<6",
7
+ "fastapi==0.163.0",
8
+ "redis>=6,<8",
9
+ "uvicorn[standard]==0.54.0",
10
+ ]
11
+
12
+ [dependency-groups]
13
+ dev = ["ty>=0.0.104"]
14
+
15
+ [tool.uv]
16
+ package = false
17
+
18
+ [tool.ty.rules]
19
+ all = "error"
@@ -0,0 +1,23 @@
1
+ # Native room miniapp
2
+
3
+ From the repository root:
4
+
5
+ ```sh
6
+ uv run --extra fastapi --extra hornbeam python -m examples.discord_demo.main
7
+ ```
8
+
9
+ Open `http://127.0.0.1:8766` in two separate browser sessions. Use `--port` to choose another loopback port. Join a room before sending. The first browser owns the crash button. Crashing replaces that room's BEAM child with empty state. Everyone must explicitly join the new generation.
10
+
11
+ This example needs locally staged Python 3.14 native assets with actor groups and opt-in Hornbeam services. The source installation alone does not provide those assets. The Hornbeam integration owns startup and shutdown of its existing supervised services and callback. It does not start Hornbeam's HTTP listener. Uvicorn serves FastAPI inside the managed native event loop. Missing runtime capabilities stop startup rather than substituting polling or Python room state.
12
+
13
+ Leave stops native delivery receipts for your membership. The live view remains open. Rejoin explicitly to receive deliveries again. Leave forms capture the native membership revision so an old form cannot remove a newer membership. Disconnect releases the subscription, not membership. Changing rooms navigates to a new page and closes the old stream.
14
+
15
+ Chrome acceptance is opt-in, separate from unit tests:
16
+
17
+ ```sh
18
+ uv run --extra fastapi --extra hornbeam pytest tests/test_discord_demo_browser.py --run-frameworks --run-runtime --run-browser
19
+ ```
20
+
21
+ An explicitly requested browser run fails if Chrome or the native runtime is unavailable. Without the flags, browser tests are deselected, not reported as passing.
22
+
23
+ Rooms are limited to eight distinct identities and 100 events per generation. Departed identities still occupy slots until restart; the same identity can rejoin. Only the latest 32 messages remain in history. Messages are limited to 256 characters and 1024 UTF-8 bytes. Native subscription queues are bounded. Slow output disconnects after five seconds. Failed or cancelled writes are never automatically retried and can have effects. There is no durability or Discord authentication.
@@ -0,0 +1,61 @@
1
+ # Local distribution
2
+
3
+ With a compatible runtime wheel installed, copy this directory to
4
+ `examples/distributed` in your project and run:
5
+
6
+ ```sh
7
+ python -m examples.distributed.demo
8
+ ```
9
+
10
+ You can also use `mise run example:distributed`. Neither command builds a runtime.
11
+ Both commands start two named OTP VMs and a foreground private EPMD. They print
12
+ one finite JSON result after stopping every owned process.
13
+
14
+ `config.py` declares two `PythonNode` entries, finite limits, and three private
15
+ ports. `LocalCluster` uses the existing managed launcher. Each VM waits for the
16
+ guardian to record its PID and creation time before executing the entry file.
17
+ The cookie is in a private file with mode 0600. No shared EPMD is used.
18
+ OTP also listens for private EPMD discovery on the IPv6 loopback address `::1`.
19
+ The VM distribution listeners use only `127.0.0.1`.
20
+
21
+ A sends data through OTP `erpc` to the fixed handler on B. B constructs its own
22
+ `TaskSupervisor` and `TaskFunction`, then registers the fixed `double` definition. Python callables and native handles never
23
+ cross nodes. The result includes the handler identities and a temporary task
24
+ PID checked inside B. B also calls A through OTP for the receipt acknowledgment.
25
+
26
+ Reservations cover recipient count and encoded request bytes before work enters
27
+ the application queue. Accepted jobs remain charged until body cleanup and an
28
+ explicit result acknowledgment. Polling has no persistent server waiters.
29
+ Abandoning an observer does not cancel work. Finished unobserved results consume
30
+ slots. At most 64 message IDs are accepted during one recipient incarnation.
31
+ The event history holds 32 entries and reports dropped entries. Control requests
32
+ and trusted OTP transport are outside the application byte budget.
33
+
34
+ The cluster lifetime is at most 120 seconds, with one permitted restart per node.
35
+ The example stops B gracefully while a task is running. A observes node down and
36
+ reports uncertainty. Restarting B creates empty state and a new incarnation.
37
+ A must explicitly join again and submit a new request. There is no replay or
38
+ durability. These limits do not bound network decoding or total process memory.
39
+
40
+ A host can pass a `GuardianEndpoint` through `LocalCluster(..., guardian=endpoint)`
41
+ when an existing outer guardian implements the registration acknowledgment
42
+ contract. The cluster borrows that guardian and does not stop it. The inner
43
+ guardian and every executable child must receive an outer acknowledgment after
44
+ their birth identity is recorded. Cancellation or a missing acknowledgment
45
+ blocks entry. The normal command does not require an outer guardian.
46
+
47
+ ## Source development
48
+
49
+ Use conventional CPython 3.14.10 and OTP 29.1.2. Build the paired native checkout
50
+ with a matching `PYTHON_CONFIG` and `CMAKE_BUILD_PARALLEL_LEVEL=1`.
51
+ Do not build optional dependencies through this example. Select prepared assets
52
+ with `[tool.pybeam].development_runtime` in your `pyproject.toml`. The normal
53
+ runtime manifest is used when this setting is absent. No manual EPMD or cookie
54
+ setup is needed. The three configured ports must be free. Port reservation and
55
+ listener startup are separate OS operations, so a collision fails startup rather
56
+ than retrying.
57
+
58
+ Run `mise run test:distributed` for the explicit finite tests. Ordinary core tests
59
+ do not start these VMs. The fixed `double` definition is an example operation,
60
+ not an arbitrary remote Python or Erlang execution API. Remote PIDs remain in
61
+ Erlang. Their text in the result is data, not a local `erlang.Pid` handle.