paglets 1.0.0

A small Python Aglets-inspired mobile object runtime.

paglets

Introduction / overview paper:

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:

uv run pytest

Build the Python package locally:

uv build

After a tagged release is published, install the package with:

python -m pip install paglets

Start two local hosts:

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:

uv run paglets-sysinfo summary
uv run paglets-compute-slots status
uv run paglets-analysis-jobs --tasks 3 --target-runtime 3
uv run paglets-search grep TODO .
uv run paglets-pi-compute --digits 32

The built-in compute-slots service admits coarse jobs by explicit cpu_cores, expected RAM, and temp-storage estimates; on Linux and Windows it can best-effort pin granted jobs to allocated CPU IDs. New compute job paglets can derive from ComputeJobPaglet so scheduling, wakeup, redirects, affinity metadata, and lease release stay out of job-specific code.

Run a source-tree demo:

uv run python demos/disk_survey_demo.py --hosts alpha beta gamma

Minimal Paglet

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:

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
• Examples
• Operations
• Technical Reference
• Status And Limitations

Build docs locally:

uv run --extra docs mkdocs build --strict
uv run --extra docs mkdocs serve

Project Layout

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/system/          built-in resident service agents
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.