flakepl 0.3.1__tar.gz

flakepl-0.3.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: flakepl
+Version: 0.3.1
+Summary: FlakePL – a Python framework for executable multi-agent process and epistemic models
+Author: Elisson
+Keywords: multi-agent systems,epistemic logic,process calculus,process algebra,formal verification,AI agents,temporal logic,dynamic epistemic logic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# FlakePL
+
+FlakePL is a small Python library for modeling and exploring finite multi-agent systems with process semantics, epistemic logic, temporal properties, dynamic epistemic updates, and executable protocol transitions.
+
+The current goal is deliberately modest: provide a clean, testable MVP library. A dedicated FlakePL programming language is a later stage and is not part of the current release.
+
+## MVP capabilities
+
+- process algebra: `Nil`, `Prefix`, `Choice`, `Parallel`
+- actions: `Tau`, `Send`, `Receive`
+- executable system configurations and immutable agent state
+- finite state-space exploration
+- observations and epistemic relations
+- `K`, `E`, `D`, `C` knowledge operators
+- boolean formulas
+- temporal operators `X`, `F`, `G`, `U`
+- public announcements and action-model product updates
+- process-aware epistemic execution
+- counterexample traces for temporal verification
+
+## Installation
+
+```bash
+python -m pip install flakepl
+```
+
+The public API is:
+
+```python
+from flakepl import ...
+```
+
+The old `flake` namespace remains available temporarily for compatibility with the prototype.
+
+## Quick example
+
+```python
+from flakepl import Agent, Configuration, GlobalState, explore, recv, send, stop
+
+alice = Agent.create(
+    "alice",
+    send("channel", "secret") >> stop(),
+)
+
+bob = Agent.create(
+    "bob",
+    recv("channel", "value") >> stop(),
+)
+
+initial = Configuration(
+    state=GlobalState(),
+    agents=(alice, bob),
+)
+
+space = explore(initial)
+
+print("states:", len(space.states))
+print("transitions:", len(space.transitions))
+```
+
+## Epistemic model
+
+```python
+from flakepl import Atom, EpistemicModel, K, observe_local_state
+
+model = EpistemicModel.from_state_space(
+    space,
+    observations={
+        "alice": observe_local_state(),
+        "bob": observe_local_state(),
+    },
+)
+
+# Evaluate a registered proposition with model.check(...).
+```
+
+See `examples/` for complete runnable programs, including a two-phase-commit verification example.
+
+## Development
+
+Run the full test suite:
+
+```bash
+python -m pytest -q
+```
+
+Compile all sources:
+
+```bash
+python -m compileall -q src tests
+```
+
+## Project layout
+
+```text
+src/flake/       implementation and legacy compatibility API
+src/flakepl/     public FlakePL API
+examples/        runnable MVP examples
+tests/           unit, semantic, integration, and example tests
+```
+
+## Status
+
+FlakePL is alpha software. The MVP API is intentionally small and may evolve before 1.0.
+
+## License
+
+The repository license will be added before the first public release.

flakepl-0.3.1/README.md

@@ -0,0 +1,108 @@
+# FlakePL
+
+FlakePL is a small Python library for modeling and exploring finite multi-agent systems with process semantics, epistemic logic, temporal properties, dynamic epistemic updates, and executable protocol transitions.
+
+The current goal is deliberately modest: provide a clean, testable MVP library. A dedicated FlakePL programming language is a later stage and is not part of the current release.
+
+## MVP capabilities
+
+- process algebra: `Nil`, `Prefix`, `Choice`, `Parallel`
+- actions: `Tau`, `Send`, `Receive`
+- executable system configurations and immutable agent state
+- finite state-space exploration
+- observations and epistemic relations
+- `K`, `E`, `D`, `C` knowledge operators
+- boolean formulas
+- temporal operators `X`, `F`, `G`, `U`
+- public announcements and action-model product updates
+- process-aware epistemic execution
+- counterexample traces for temporal verification
+
+## Installation
+
+```bash
+python -m pip install flakepl
+```
+
+The public API is:
+
+```python
+from flakepl import ...
+```
+
+The old `flake` namespace remains available temporarily for compatibility with the prototype.
+
+## Quick example
+
+```python
+from flakepl import Agent, Configuration, GlobalState, explore, recv, send, stop
+
+alice = Agent.create(
+    "alice",
+    send("channel", "secret") >> stop(),
+)
+
+bob = Agent.create(
+    "bob",
+    recv("channel", "value") >> stop(),
+)
+
+initial = Configuration(
+    state=GlobalState(),
+    agents=(alice, bob),
+)
+
+space = explore(initial)
+
+print("states:", len(space.states))
+print("transitions:", len(space.transitions))
+```
+
+## Epistemic model
+
+```python
+from flakepl import Atom, EpistemicModel, K, observe_local_state
+
+model = EpistemicModel.from_state_space(
+    space,
+    observations={
+        "alice": observe_local_state(),
+        "bob": observe_local_state(),
+    },
+)
+
+# Evaluate a registered proposition with model.check(...).
+```
+
+See `examples/` for complete runnable programs, including a two-phase-commit verification example.
+
+## Development
+
+Run the full test suite:
+
+```bash
+python -m pytest -q
+```
+
+Compile all sources:
+
+```bash
+python -m compileall -q src tests
+```
+
+## Project layout
+
+```text
+src/flake/       implementation and legacy compatibility API
+src/flakepl/     public FlakePL API
+examples/        runnable MVP examples
+tests/           unit, semantic, integration, and example tests
+```
+
+## Status
+
+FlakePL is alpha software. The MVP API is intentionally small and may evolve before 1.0.
+
+## License
+
+The repository license will be added before the first public release.

flakepl-0.3.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flakepl"
+version = "0.3.1"
+description = "FlakePL – a Python framework for executable multi-agent process and epistemic models"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+authors = [
+    { name = "Elisson" }
+]
+
+keywords = [
+    "multi-agent systems",
+    "epistemic logic",
+    "process calculus",
+    "process algebra",
+    "formal verification",
+    "AI agents",
+    "temporal logic",
+    "dynamic epistemic logic",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

flakepl-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flakepl-0.3.1/src/flake/__init__.py

@@ -0,0 +1,102 @@
+from .actions import Action, Receive, Send, Tau
+from .agent import Agent
+from .dynamic import (
+    ActionEvent,
+    ActionModel,
+    DynamicEvent,
+    PublicAnnouncement,
+    action_event,
+    announce,
+    event,
+    product_update,
+    public_announcement,
+)
+from .epistemic import (
+    CommonKnowledge,
+    DistributedKnowledge,
+    EpistemicModel,
+    EveryoneKnows,
+    Knowledge,
+    ProductWorld,
+    World,
+    C,
+    D,
+    E,
+    K,
+)
+from .explorer import StateSpace, explore, explore_many, explore_many_with, explore_with
+from .execution import (
+    ActionObservation,
+    BlindActionObservation,
+    ProcessExecutionEvent,
+    TransitionObservation,
+    blind_action,
+    execute,
+    execute_transition,
+    observe_action,
+    step,
+)
+from .formula import And, Atom, Formula, Not, Or, iff, implies
+from .observation import (
+    GlobalObservation,
+    LocalObservation,
+    ObservationBuilder,
+    global_,
+    local,
+    observe_global,
+    observe_local_process,
+    observe_local_state,
+    public,
+    same_observation,
+)
+from .process import Choice, Nil, Parallel, Prefix, Process, choice, parallel, recv, send, stop, tau
+from .propositions import Proposition
+from .runtime import Configuration, GlobalState, SystemTransition
+from .semantics import synchronous_system_transitions
+from .sos import Transition, transitions
+from .temporal import Always, Eventually, Next, Until, F, G, U, X
+from .verify import (
+    Trace,
+    VerificationResult,
+    find_always_counterexample,
+    find_eventually_counterexample,
+    find_next_counterexample,
+    find_path_to,
+    find_state_counterexample,
+    format_trace,
+    format_verification,
+    verify,
+    verify_always,
+    verify_eventually,
+)
+
+# Backward-compatible system-level name.
+system_transitions = synchronous_system_transitions
+
+__all__ = [
+    "Action", "Tau", "Send", "Receive",
+    "Agent",
+    "Process", "Nil", "Prefix", "Choice", "Parallel",
+    "stop", "send", "recv", "tau", "choice", "parallel",
+    "GlobalState", "Configuration", "SystemTransition",
+    "Proposition",
+    "Transition", "transitions",
+    "StateSpace", "explore", "explore_many", "explore_with", "explore_many_with",
+    "system_transitions", "synchronous_system_transitions",
+    "LocalObservation", "GlobalObservation", "ObservationBuilder",
+    "local", "global_", "public", "observe_global", "observe_local_state",
+    "observe_local_process", "same_observation",
+    "Formula", "Atom", "Not", "And", "Or", "implies", "iff",
+    "World", "ProductWorld", "EpistemicModel",
+    "Knowledge", "EveryoneKnows", "DistributedKnowledge", "CommonKnowledge",
+    "K", "E", "D", "C",
+    "Next", "Eventually", "Always", "Until", "X", "F", "G", "U",
+    "DynamicEvent", "PublicAnnouncement", "ActionEvent", "ActionModel",
+    "announce", "public_announcement", "event", "action_event", "product_update",
+    "TransitionObservation", "ActionObservation", "BlindActionObservation",
+    "ProcessExecutionEvent", "observe_action", "blind_action", "execute_transition",
+    "execute", "step",
+    "Trace", "VerificationResult", "find_path_to", "find_state_counterexample",
+    "find_next_counterexample", "find_always_counterexample", "find_eventually_counterexample",
+    "verify_always", "verify_eventually", "verify", "format_trace", "format_verification",
+]

flakepl-0.3.1/src/flake/actions.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Tau:
+    """
+    Internal action.
+
+    Represents:
+        τ
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class Send:
+    """
+    Output action:
+
+        channel!value
+    """
+
+    channel: str
+    value: Any
+
+
+@dataclass(frozen=True, slots=True)
+class Receive:
+    """
+    Input action:
+
+        channel?variable
+    """
+
+    channel: str
+    variable: str
+
+
+Action = Tau | Send | Receive

flakepl-0.3.1/src/flake/agent.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .process import Process
+
+
+@dataclass(frozen=True, slots=True)
+class Agent:
+    """
+    Runtime agent.
+
+    Agent identity is its logical name.
+
+    Runtime state consists of:
+
+        process
+        local state
+    """
+
+    name: str
+    process: Process
+    state: tuple[tuple[str, Any], ...] = ()
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        process: Process,
+        state: dict[str, Any] | None = None,
+    ) -> Agent:
+
+        if not name:
+            raise ValueError(
+                "Agent name cannot be empty"
+            )
+
+        if state is None:
+            state = {}
+
+        return cls(
+            name=name,
+            process=process,
+            state=tuple(
+                sorted(
+                    state.items(),
+                    key=lambda item: item[0],
+                )
+            ),
+        )
+
+    def get_state(
+        self,
+        key: str,
+        default: Any = None,
+    ) -> Any:
+        """
+        Read one local state variable.
+        """
+
+        return dict(
+            self.state
+        ).get(
+            key,
+            default,
+        )
+
+    def with_state(
+        self,
+        key: str,
+        value: Any,
+    ) -> Agent:
+        """
+        Return a new agent with updated local state.
+        """
+
+        state = dict(
+            self.state
+        )
+
+        state[key] = value
+
+        return Agent(
+            name=self.name,
+            process=self.process,
+            state=tuple(
+                sorted(
+                    state.items(),
+                    key=lambda item: item[0],
+                )
+            ),
+        )
+
+    def with_process(
+        self,
+        process: Process,
+    ) -> Agent:
+        """
+        Return a new agent with updated process.
+        """
+
+        return Agent(
+            name=self.name,
+            process=process,
+            state=self.state,
+        )