paglets 0.1.0__tar.gz

paglets-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+# Copyright (c) 2026 by C. Klukas.
+# Licensed under the MIT License. See LICENSE for details.
+
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install project
+        run: uv sync --dev --extra docs
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest --cov=paglets --cov-report=term-missing --cov-report=xml
+
+      - name: Build documentation
+        run: uv run --extra docs mkdocs build --strict
+
+      - name: Build package
+        run: uv build
+
+      - name: Smoke-test wheel installation
+        run: |
+          python -m venv /tmp/paglets-wheel-smoke
+          /tmp/paglets-wheel-smoke/bin/python -m pip install dist/*.whl
+          /tmp/paglets-wheel-smoke/bin/paglets-host --help
+          /tmp/paglets-wheel-smoke/bin/paglets-mesh-benchmark --help
+          /tmp/paglets-wheel-smoke/bin/paglets-mesh-info --help
+          /tmp/paglets-wheel-smoke/bin/paglets-perf-test --help
+          /tmp/paglets-wheel-smoke/bin/paglets-pi-compute --help
+          /tmp/paglets-wheel-smoke/bin/paglets-search --help
+          /tmp/paglets-wheel-smoke/bin/paglets-sysinfo --help
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+
+      - name: Smoke-test command line entry points
+        run: |
+          uv run paglets-host --help
+          uv run paglets-mesh-benchmark --help
+          uv run paglets-mesh-info --help
+          uv run paglets-perf-test --help
+          uv run paglets-pi-compute --help
+          uv run paglets-search --help
+          uv run paglets-sysinfo --help

paglets-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+# Copyright (c) 2026 by C. Klukas.
+# Licensed under the MIT License. See LICENSE for details.
+
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "src/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install documentation dependencies
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run --extra docs mkdocs build --strict
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+
+      - name: Upload documentation artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

paglets-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,113 @@
+# Copyright (c) 2026 by C. Klukas.
+# Licensed under the MIT License. See LICENSE for details.
+
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install project
+        run: uv sync --dev --extra docs
+
+      - name: Verify release tag matches package version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]["version"]
+          tag = os.environ["GITHUB_REF_NAME"]
+          tag_version = tag[1:] if tag.startswith("v") else tag
+          if tag_version != version:
+              raise SystemExit(f"tag {tag!r} does not match pyproject version {version!r}")
+          PY
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build documentation
+        run: uv run --extra docs mkdocs build --strict
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package metadata
+        run: uvx twine check --strict dist/*
+
+      - name: Smoke-test wheel installation
+        run: |
+          python -m venv /tmp/paglets-wheel-smoke
+          /tmp/paglets-wheel-smoke/bin/python -m pip install dist/*.whl
+          /tmp/paglets-wheel-smoke/bin/python - <<'PY'
+          import importlib.metadata
+          import paglets
+
+          assert importlib.metadata.version("paglets")
+          assert paglets.__doc__
+          PY
+          /tmp/paglets-wheel-smoke/bin/paglets-host --help
+          /tmp/paglets-wheel-smoke/bin/paglets-mesh-benchmark --help
+          /tmp/paglets-wheel-smoke/bin/paglets-mesh-info --help
+          /tmp/paglets-wheel-smoke/bin/paglets-perf-test --help
+          /tmp/paglets-wheel-smoke/bin/paglets-pi-compute --help
+          /tmp/paglets-wheel-smoke/bin/paglets-search --help
+          /tmp/paglets-wheel-smoke/bin/paglets-sysinfo --help
+
+      - name: Upload distribution artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: paglets-dist
+          path: dist/*
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/paglets/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifact
+        uses: actions/download-artifact@v6
+        with:
+          name: paglets-dist
+          path: dist
+
+      - name: Publish distribution
+        uses: pypa/gh-action-pypi-publish@release/v1

paglets-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+aglets-git/
+
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+.env.*
+
+# Build artifacts
+build/
+dist/
+site/
+*.egg-info/
+*.egg
+
+# Local/editor/system files
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local paglets runtime/config artifacts
+.paglets/
+ROADMAP.md
+aglets_manual_ocr_clean.md

paglets-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+# Copyright (c) 2026 by C. Klukas.
+# Licensed under the MIT License. See LICENSE for details.
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.18
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format

paglets-0.1.0/AGENTS.md

@@ -0,0 +1,39 @@
+# Agent Instructions
+
+## License Headers
+
+New code files must include the project copyright and license notice.
+
+For Python files, use this exact header at the top of the file:
+
+```python
+# Copyright (c) 2026 by C. Klukas.
+# Licensed under the MIT License. See LICENSE for details.
+```
+
+For other source-code file types, use the equivalent comment syntax for that
+language while preserving the same text.
+
+Do not add project license headers to generated files, vendored dependencies,
+virtual environments, caches, build outputs, or other ignored artifacts.
+
+## Documentation
+
+When adding or changing user-visible features, update the MkDocs documentation
+under `docs/`.
+
+Also update root-level `README.md` when the change affects installation,
+quick-start usage, command-line entry points, major examples, public APIs, or
+project-level behavior.
+
+Keep documentation examples current with the code and prefer commands that can
+be run from the repository root.
+
+## Units
+
+Use classic binary-scaled byte units for storage, payload sizes, and byte
+throughput: label them as `KB`, `MB`, `GB`, etc., and scale by 1024. Do not use
+IEC labels such as `KiB`, `MiB`, or `GiB`.
+
+For network-style bit throughput, use decimal-scaled units such as `kbit/s`,
+`Mbit/s`, and `Gbit/s`, scaled by 1000.

paglets-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 by C. Klukas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paglets-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: paglets
+Version: 0.1.0
+Summary: A small Python Aglets-inspired mobile object runtime.
+Project-URL: Homepage, https://github.com/cklukas/paglets
+Project-URL: Documentation, https://cklukas.github.io/paglets/
+Project-URL: Repository, https://github.com/cklukas/paglets
+Project-URL: Issues, https://github.com/cklukas/paglets/issues
+Author: C. Klukas
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,distributed-systems,mesh,mobile-agents,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: pathspec>=0.12
+Requires-Dist: psutil>=5.9
+Requires-Dist: setproctitle>=1.3
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]<1,>=0.28; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# paglets
+
+[![CI](https://github.com/cklukas/paglets/actions/workflows/ci.yml/badge.svg)](https://github.com/cklukas/paglets/actions/workflows/ci.yml)
+[![Publish Package](https://github.com/cklukas/paglets/actions/workflows/publish.yml/badge.svg)](https://github.com/cklukas/paglets/actions/workflows/publish.yml)
+[![Docs](https://github.com/cklukas/paglets/actions/workflows/docs.yml/badge.svg)](https://cklukas.github.io/paglets/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+`paglets` is a compact Python re-imagining of the Java Aglets mobile-agent idea: stateful objects with identity, lifecycle hooks, message passing, proxies, movement between hosts, durable deactivation, resident services, and explicit dataclass state serialization.
+
+Hosts are expected to already have the same paglet code importable. Movement transfers the paglet class name, state class name, and serialized dataclass state; it does not upload code or move Python stacks, threads, sockets, or arbitrary live resources.
+
+## Quick Start
+
+Install and run tests from a checkout:
+
+```bash
+uv run pytest
+```
+
+Build the Python package locally:
+
+```bash
+uv build
+```
+
+After a tagged release is published, install the package with:
+
+```bash
+python -m pip install paglets
+```
+
+Start two local hosts:
+
+```bash
+uv run paglets-host --name alpha --port 8765 --mesh-version dev
+uv run paglets-host --name beta --port 8766 --peer http://127.0.0.1:8765 --mesh-version dev
+```
+
+Run a packaged example CLI:
+
+```bash
+uv run paglets-sysinfo summary
+uv run paglets-search grep TODO .
+uv run paglets-pi-compute --digits 32
+```
+
+Run a source-tree demo:
+
+```bash
+uv run python demos/disk_survey_demo.py --hosts alpha beta gamma
+```
+
+## Minimal Paglet
+
+```python
+from dataclasses import dataclass, field
+
+from paglets.core.agent import Paglet, PagletState
+from paglets.core.messages import Message
+
+
+@dataclass
+class CounterState(PagletState):
+    count: int = 0
+    events: list[str] = field(default_factory=list)
+
+
+class CounterPaglet(Paglet[CounterState]):
+    State = CounterState
+
+    def handle_message(self, message: Message):
+        if message.kind == "increment":
+            self.state.count += int(message.args.get("by", 1))
+            return {"count": self.state.count}
+        return self.not_handled()
+```
+
+Public imports are intentionally explicit:
+
+```python
+from paglets.runtime.host import Host
+from paglets.core.agent import Paglet, PagletState
+from paglets.core.messages import Message
+from paglets.remote.proxy import PagletProxy
+```
+
+Flat imports such as `from paglets import Host` are unsupported.
+
+## Documentation
+
+The full documentation is published at <https://cklukas.github.io/paglets/>.
+
+Useful entry points:
+
+- [Implementing Paglets](https://cklukas.github.io/paglets/implementing-paglets/)
+- [Examples](https://cklukas.github.io/paglets/examples/)
+- [Operations](https://cklukas.github.io/paglets/operations/)
+- [Technical Reference](https://cklukas.github.io/paglets/technical/overview/)
+- [Status And Limitations](https://cklukas.github.io/paglets/project/status/)
+
+Build docs locally:
+
+```bash
+uv run --extra docs mkdocs build --strict
+uv run --extra docs mkdocs serve
+```
+
+## Project Layout
+
+```text
+src/paglets/core/            paglet model, messages, lifecycle events
+src/paglets/runtime/         host facade, child processes, HTTP, relay, storage runtime
+src/paglets/remote/          clients, proxies, transfer tickets, mesh, admin API
+src/paglets/persistence/     inactive records and managed storage
+src/paglets/services/        service contracts and resident services
+src/paglets/serialization/   dataclass wire conversion and import resolution
+src/paglets/config/          launch config and bundled defaults
+src/paglets/tooling/         CLI, discovery, git auto-update
+src/paglets/examples/        packaged example agents and CLIs
+demos/                       runnable source-tree demo scripts
+tests/                       behavior-oriented test suites by topic
+```
+
+## Status
+
+`paglets` is early-stage software for experiments and trusted local/LAN meshes. Use API-key authentication for shared networks and relay deployments.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

paglets-0.1.0/README.md

@@ -0,0 +1,131 @@
+# paglets
+
+[![CI](https://github.com/cklukas/paglets/actions/workflows/ci.yml/badge.svg)](https://github.com/cklukas/paglets/actions/workflows/ci.yml)
+[![Publish Package](https://github.com/cklukas/paglets/actions/workflows/publish.yml/badge.svg)](https://github.com/cklukas/paglets/actions/workflows/publish.yml)
+[![Docs](https://github.com/cklukas/paglets/actions/workflows/docs.yml/badge.svg)](https://cklukas.github.io/paglets/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+`paglets` is a compact Python re-imagining of the Java Aglets mobile-agent idea: stateful objects with identity, lifecycle hooks, message passing, proxies, movement between hosts, durable deactivation, resident services, and explicit dataclass state serialization.
+
+Hosts are expected to already have the same paglet code importable. Movement transfers the paglet class name, state class name, and serialized dataclass state; it does not upload code or move Python stacks, threads, sockets, or arbitrary live resources.
+
+## Quick Start
+
+Install and run tests from a checkout:
+
+```bash
+uv run pytest
+```
+
+Build the Python package locally:
+
+```bash
+uv build
+```
+
+After a tagged release is published, install the package with:
+
+```bash
+python -m pip install paglets
+```
+
+Start two local hosts:
+
+```bash
+uv run paglets-host --name alpha --port 8765 --mesh-version dev
+uv run paglets-host --name beta --port 8766 --peer http://127.0.0.1:8765 --mesh-version dev
+```
+
+Run a packaged example CLI:
+
+```bash
+uv run paglets-sysinfo summary
+uv run paglets-search grep TODO .
+uv run paglets-pi-compute --digits 32
+```
+
+Run a source-tree demo:
+
+```bash
+uv run python demos/disk_survey_demo.py --hosts alpha beta gamma
+```
+
+## Minimal Paglet
+
+```python
+from dataclasses import dataclass, field
+
+from paglets.core.agent import Paglet, PagletState
+from paglets.core.messages import Message
+
+
+@dataclass
+class CounterState(PagletState):
+    count: int = 0
+    events: list[str] = field(default_factory=list)
+
+
+class CounterPaglet(Paglet[CounterState]):
+    State = CounterState
+
+    def handle_message(self, message: Message):
+        if message.kind == "increment":
+            self.state.count += int(message.args.get("by", 1))
+            return {"count": self.state.count}
+        return self.not_handled()
+```
+
+Public imports are intentionally explicit:
+
+```python
+from paglets.runtime.host import Host
+from paglets.core.agent import Paglet, PagletState
+from paglets.core.messages import Message
+from paglets.remote.proxy import PagletProxy
+```
+
+Flat imports such as `from paglets import Host` are unsupported.
+
+## Documentation
+
+The full documentation is published at <https://cklukas.github.io/paglets/>.
+
+Useful entry points:
+
+- [Implementing Paglets](https://cklukas.github.io/paglets/implementing-paglets/)
+- [Examples](https://cklukas.github.io/paglets/examples/)
+- [Operations](https://cklukas.github.io/paglets/operations/)
+- [Technical Reference](https://cklukas.github.io/paglets/technical/overview/)
+- [Status And Limitations](https://cklukas.github.io/paglets/project/status/)
+
+Build docs locally:
+
+```bash
+uv run --extra docs mkdocs build --strict
+uv run --extra docs mkdocs serve
+```
+
+## Project Layout
+
+```text
+src/paglets/core/            paglet model, messages, lifecycle events
+src/paglets/runtime/         host facade, child processes, HTTP, relay, storage runtime
+src/paglets/remote/          clients, proxies, transfer tickets, mesh, admin API
+src/paglets/persistence/     inactive records and managed storage
+src/paglets/services/        service contracts and resident services
+src/paglets/serialization/   dataclass wire conversion and import resolution
+src/paglets/config/          launch config and bundled defaults
+src/paglets/tooling/         CLI, discovery, git auto-update
+src/paglets/examples/        packaged example agents and CLIs
+demos/                       runnable source-tree demo scripts
+tests/                       behavior-oriented test suites by topic
+```
+
+## Status
+
+`paglets` is early-stage software for experiments and trusted local/LAN meshes. Use API-key authentication for shared networks and relay deployments.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

paglets-0.1.0/demos/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2026 by C. Klukas.
+# Licensed under the MIT License. See LICENSE for details.
+"""Importable paglets example modules."""