plexi-sdk 0.3.0__tar.gz → 0.3.2__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 (33) hide show
  1. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/PKG-INFO +1 -1
  2. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/templates/AGENTS.md +7 -0
  3. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/templates/app_init.py +16 -16
  4. plexi_sdk-0.3.2/plexi_sdk/templates/app_init_tools.py +35 -0
  5. plexi_sdk-0.3.2/plexi_sdk/templates/app_init_ui.py +25 -0
  6. plexi_sdk-0.3.2/plexi_sdk/templates/test_app_init.py +87 -0
  7. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/pyproject.toml +1 -1
  8. plexi_sdk-0.3.0/plexi_sdk/templates/test_app_init.py +0 -46
  9. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/.gitignore +0 -0
  10. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/README.md +0 -0
  11. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/__init__.py +0 -0
  12. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_adapter.py +0 -0
  13. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_keys.py +0 -0
  14. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_protocol.py +0 -0
  15. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_theme.py +0 -0
  16. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_types.py +0 -0
  17. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_v3_delta.py +0 -0
  18. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_v3_process.py +0 -0
  19. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_v3_runtime.py +0 -0
  20. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_v3_state.py +0 -0
  21. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/_version.py +0 -0
  22. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/effects.py +0 -0
  23. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/events.py +0 -0
  24. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/midi.py +0 -0
  25. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/py.typed +0 -0
  26. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/state_format.py +0 -0
  27. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/templates/__init__.py +0 -0
  28. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/templates/agent_init.py +0 -0
  29. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/templates/gitignore +0 -0
  30. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/templates/manifest.toml +0 -0
  31. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/testing.py +0 -0
  32. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/tools.py +0 -0
  33. {plexi_sdk-0.3.0 → plexi_sdk-0.3.2}/plexi_sdk/ui.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: plexi-sdk
3
- Version: 0.3.0
3
+ Version: 0.3.2
4
4
  Summary: Python SDK v3 for Plexi apps running through the CPython-in-WASM runtime
5
5
  Project-URL: Homepage, https://github.com/ianjamesburke/PLEXI
6
6
  Project-URL: Repository, https://github.com/ianjamesburke/PLEXI
@@ -17,6 +17,13 @@ the Plexi website docs). This file holds only this app's build loop and metadata
17
17
 
18
18
  Machine-readable drift data lives in `plexi.scaffold.toml`. Run `plexi app check .` before handing off; it warns when this scaffold was generated by a different CLI, SDK, schema, runtime, template, or channel/profile.
19
19
 
20
+ ## Module Layout
21
+
22
+ - `main.py` — thin wiring only: `init` returns `tools.expose()`, `update` calls `tools.dispatch(event)` first and then handles keys/UI actions, `view` delegates to `app.ui.build_view(...)`. Do not grow logic here.
23
+ - `app/tools.py` — assistant-callable tools as plain Python functions registered with `@tools.tool(...)` (`from plexi_sdk import tools`). No UI code.
24
+ - `app/ui.py` — pure view builders (`Column`, `AppBar`, `Text`, `FooterKeys`, ...). No effects.
25
+ - `app/__init__.py` — marks the app package. The package avoids a bare root-level `tools.py`, which would shadow `plexi_sdk.tools`. Add further modules there and import them from `main.py`.
26
+
20
27
  ## Build Loop
21
28
 
22
29
  - Use TDD. Add or update tests for every behavior change before changing app code.
@@ -1,28 +1,37 @@
1
1
  """__DISPLAY_NAME__ - SDK v3 app generated by `plexi app init`.
2
2
 
3
3
  Plexi calls init(size, args), update(event), and view().
4
+ This file is deliberately thin. It only wires the lifecycle:
5
+
6
+ app/tools.py assistant-callable tools (plain functions + @tools.tool)
7
+ app/ui.py view builders (the component tree)
8
+ main.py init / update / view, delegating to the two modules above
9
+
4
10
  Do not mutate Plexi state in-place: return effects.
5
11
  Components describe UI. Effects describe host work.
6
- Useful primitives include ActionBar(), Card(), Section(), Badge(),
7
- Divider(), TextEdit(), SelectList(), and Scrollable().
8
- Editable controls deliver UiValueChange. Use FooterKeys(), SPACE_MD, and
9
- padding=SPACE_MD. Logging levels: log.debug, log.info, log.warn, log.error.
10
12
  """
11
13
 
12
- from plexi_sdk import state
14
+ from plexi_sdk import log, state, tools
13
15
  from plexi_sdk.effects import SetState, SetTitle
14
16
  from plexi_sdk.events import KeyEvent
15
- from plexi_sdk.ui import AppBar, Column, FooterKeys, Text
17
+
18
+ from app import tools as app_tools # noqa: F401 (importing registers @tools.tool functions)
19
+ from app import ui as app_ui
16
20
 
17
21
 
18
22
  def init(size, args):
23
+ log.info("__DISPLAY_NAME__: init")
19
24
  return [
20
25
  SetTitle("__DISPLAY_NAME__"),
21
26
  SetState({"count": 0}),
27
+ tools.expose(),
22
28
  ]
23
29
 
24
30
 
25
31
  def update(event):
32
+ tool_effects = tools.dispatch(event)
33
+ if tool_effects is not None:
34
+ return tool_effects
26
35
  if isinstance(event, KeyEvent) and event.pressed:
27
36
  if event.key in ("equals", "plus"):
28
37
  return [SetState({"count": state.get("count", 0) + 1})]
@@ -34,13 +43,4 @@ def update(event):
34
43
 
35
44
 
36
45
  def view():
37
- count = state.get("count", 0)
38
- return Column([
39
- AppBar("__DISPLAY_NAME__"),
40
- Text(str(count), bold=True),
41
- FooterKeys([
42
- ("+", "increment"),
43
- ("-", "decrement"),
44
- ("r", "reset"),
45
- ]),
46
- ], grow=True)
46
+ return app_ui.build_view(state.get("count", 0))
@@ -0,0 +1,35 @@
1
+ """Assistant-callable tools for __DISPLAY_NAME__.
2
+
3
+ Each tool is a plain Python function registered with ``@tools.tool``. Keep
4
+ this module free of UI code: it answers the Assistant, ``app/ui.py`` draws.
5
+ ``main.py`` returns ``tools.expose()`` from ``init`` and calls
6
+ ``tools.dispatch(event)`` first in ``update``.
7
+
8
+ It lives in the ``app`` package so a top-level ``tools.py`` never shadows
9
+ ``plexi_sdk.tools``.
10
+ Read-only tools pass ``read_only=True`` and skip the write-grant prompt; a
11
+ mutating tool returns ``tools.Reply(output, effects)`` with its effects.
12
+ """
13
+
14
+ from plexi_sdk import state, tools
15
+
16
+
17
+ @tools.tool(
18
+ "demo.greet",
19
+ "Greet someone by name.",
20
+ {"name": str},
21
+ {"greeting": str},
22
+ read_only=True,
23
+ )
24
+ def greet(name: str) -> dict:
25
+ return {"greeting": f"Hello, {name}!"}
26
+
27
+
28
+ @tools.tool(
29
+ "demo.count",
30
+ "Read the current counter value.",
31
+ returns={"count": int},
32
+ read_only=True,
33
+ )
34
+ def count() -> dict:
35
+ return {"count": state.get("count", 0)}
@@ -0,0 +1,25 @@
1
+ """View builders for __DISPLAY_NAME__.
2
+
3
+ Pure functions from app data to a component tree — no effects, no state
4
+ reads beyond what ``main.py`` passes in. Components describe UI; effects
5
+ (returned from ``main.py``) describe host work.
6
+
7
+ Useful primitives include ActionBar(), Card(), Section(), Badge(),
8
+ Divider(), TextEdit(), SelectList(), and Scrollable(). Editable controls
9
+ deliver UiValueChange. Use FooterKeys(), SPACE_MD, and padding=SPACE_MD.
10
+ Logging levels: log.debug, log.info, log.warn, log.error.
11
+ """
12
+
13
+ from plexi_sdk.ui import SPACE_MD, AppBar, Column, FooterKeys, Text
14
+
15
+
16
+ def build_view(count: int) -> Column:
17
+ return Column([
18
+ AppBar("__DISPLAY_NAME__"),
19
+ Text(str(count), bold=True),
20
+ FooterKeys([
21
+ ("+", "increment"),
22
+ ("-", "decrement"),
23
+ ("r", "reset"),
24
+ ]),
25
+ ], grow=True, padding=SPACE_MD)
@@ -0,0 +1,87 @@
1
+ """Tests for __DISPLAY_NAME__ — generated by `plexi app init`.
2
+
3
+ Run with: plexi app test (from the app directory)
4
+ or: uv run --no-project --with pytest pytest tests/
5
+
6
+ AppHarness spawns this app as a real subprocess and speaks the PGAP protocol
7
+ over stdin/stdout — no running Plexi host or display required. See
8
+ `plexi_sdk/testing.py` for the full API (key injection, pixel asserts, …).
9
+ """
10
+ import json
11
+ import shutil
12
+ from pathlib import Path
13
+
14
+ import pytest
15
+
16
+ from plexi_sdk.effects import ExposeTools, ToolResult
17
+ from plexi_sdk.events import ToolCall
18
+ from plexi_sdk.testing import AppHarness
19
+
20
+ APP_DIR = Path(__file__).resolve().parent.parent
21
+ APP = APP_DIR / "main.py"
22
+ if not APP.exists():
23
+ # This template is collected as part of the SDK suite before `app init`
24
+ # copies it into a generated app. Materialize the package layout under
25
+ # their generated names and exercise them in a scratch directory.
26
+ _TEMPLATES = Path(__file__).resolve().parent
27
+ _SCRATCH = Path(__file__).resolve().parent / "__pycache__" / "scaffold_app"
28
+ _SCRATCH.mkdir(parents=True, exist_ok=True)
29
+ (_SCRATCH / "app").mkdir(exist_ok=True)
30
+ (_SCRATCH / "app" / "__init__.py").touch()
31
+ for _src, _dst in (
32
+ ("app_init.py", "main.py"),
33
+ ("app_init_tools.py", "app/tools.py"),
34
+ ("app_init_ui.py", "app/ui.py"),
35
+ ):
36
+ shutil.copyfile(_TEMPLATES / _src, _SCRATCH / _dst)
37
+ APP_DIR = _SCRATCH
38
+ APP = _SCRATCH / "main.py"
39
+
40
+
41
+ @pytest.mark.parametrize("size", [(300, 200), (800, 600)])
42
+ def test_renders_without_overlap(size):
43
+ """The view renders one frame with no overlapping rects, small and normal."""
44
+ width, height = size
45
+ # This exercises the same init -> update(RenderFrame) -> view lifecycle that
46
+ # Plexi uses for a real app pane, then checks host-side layout geometry.
47
+ with AppHarness(str(APP), width=width, height=height) as h:
48
+ h.run(1)
49
+ h.assert_no_overlap()
50
+
51
+
52
+ def test_snapshot(tmp_path):
53
+ """Render a PNG snapshot of the first frame.
54
+
55
+ Skips when the plexi binary is unavailable — snapshotting needs the host
56
+ renderer, which is not present in a bare `uv run pytest` environment.
57
+ """
58
+ with AppHarness(str(APP), width=800, height=600) as h:
59
+ h.run(1)
60
+ try:
61
+ h.save_snapshot(tmp_path / "snapshot.png")
62
+ except RuntimeError as exc:
63
+ pytest.skip(f"plexi binary not available for rendering: {exc}")
64
+
65
+
66
+ def test_tools_are_declared_and_dispatch():
67
+ """init exposes the app.tools declarations; a ToolCall gets a ToolResult."""
68
+ import sys
69
+
70
+ sys.path.insert(0, str(APP_DIR))
71
+ try:
72
+ from app import tools as app_tools # noqa: F401 (registers the tools)
73
+ from plexi_sdk import tools
74
+
75
+ names = {decl.name for decl in tools.declarations()}
76
+ assert "demo.greet" in names
77
+ assert isinstance(tools.expose(), ExposeTools)
78
+
79
+ effects = tools.dispatch(ToolCall(
80
+ call_id="c1", name="demo.greet", input_json=json.dumps({"name": "Ada"}), caller_id="test",
81
+ ))
82
+ assert effects is not None
83
+ assert isinstance(effects[0], ToolResult)
84
+ assert effects[0].output_json is not None
85
+ assert json.loads(effects[0].output_json) == {"greeting": "Hello, Ada!"}
86
+ finally:
87
+ sys.path.remove(str(APP_DIR))
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "plexi-sdk"
3
- version = "0.3.0"
3
+ version = "0.3.2"
4
4
  description = "Python SDK v3 for Plexi apps running through the CPython-in-WASM runtime"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -1,46 +0,0 @@
1
- """Tests for __DISPLAY_NAME__ — generated by `plexi app init`.
2
-
3
- Run with: plexi app test (from the app directory)
4
- or: uv run pytest tests/
5
-
6
- AppHarness spawns this app as a real subprocess and speaks the PGAP protocol
7
- over stdin/stdout — no running Plexi host or display required. See
8
- `plexi_sdk/testing.py` for the full API (key injection, pixel asserts, …).
9
- """
10
- from pathlib import Path
11
-
12
- import pytest
13
-
14
- from plexi_sdk.testing import AppHarness
15
-
16
- APP_DIR = Path(__file__).resolve().parent.parent
17
- APP = APP_DIR / "main.py"
18
- if not APP.exists():
19
- # This template is collected as part of the SDK suite before `app init`
20
- # copies it into a generated app. Exercise the template app in place.
21
- APP = Path(__file__).resolve().parent / "app_init.py"
22
-
23
-
24
- @pytest.mark.parametrize("size", [(300, 200), (800, 600)])
25
- def test_renders_without_overlap(size):
26
- """The view renders one frame with no overlapping rects, small and normal."""
27
- width, height = size
28
- # This exercises the same init -> update(RenderFrame) -> view lifecycle that
29
- # Plexi uses for a real app pane, then checks host-side layout geometry.
30
- with AppHarness(str(APP), width=width, height=height) as h:
31
- h.run(1)
32
- h.assert_no_overlap()
33
-
34
-
35
- def test_snapshot(tmp_path):
36
- """Render a PNG snapshot of the first frame.
37
-
38
- Skips when the plexi binary is unavailable — snapshotting needs the host
39
- renderer, which is not present in a bare `uv run pytest` environment.
40
- """
41
- with AppHarness(str(APP), width=800, height=600) as h:
42
- h.run(1)
43
- try:
44
- h.save_snapshot(tmp_path / "snapshot.png")
45
- except RuntimeError as exc:
46
- pytest.skip(f"plexi binary not available for rendering: {exc}")
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes