flux-vm 0.1.0__py3-none-any.whl

flux/__init__.py

@@ -0,0 +1,8 @@
+"""FLUX — Fluid Language Universal eXecution.
+
+A Self-Assembling, Self-Improving Runtime for Agent-First Code.
+"""
+
+__version__ = "0.1.0"
+__author__ = "SuperInstance"
+__license__ = "MIT"

flux/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running FLUX as ``python -m flux``."""
+
+from flux.cli import main
+
+if __name__ == "__main__":
+    main()

flux/a2a/__init__.py

@@ -0,0 +1,44 @@
+"""FLUX A2A Protocol Layer — Agent-to-Agent communication primitives.
+
+This package provides:
+- ``messages``  — Binary A2A message types (A2AMessage with 52-byte header)
+- ``transport``  — Local in-process message delivery (LocalTransport)
+- ``trust``      — INCREMENTS+2 trust engine (TrustEngine, InteractionRecord, AgentProfile)
+- ``coordinator`` — Multi-agent orchestration (AgentCoordinator)
+- ``primitives`` — Rich protocol primitives (Branch, Fork, CoIterate, Discuss, Synthesize, Reflect)
+"""
+
+from flux.a2a.messages import A2AMessage
+from flux.a2a.transport import LocalTransport
+from flux.a2a.trust import InteractionRecord, AgentProfile, TrustEngine
+from flux.a2a.coordinator import AgentCoordinator
+from flux.a2a.primitives import (
+    BranchPrimitive, BranchBody,
+    ForkPrimitive, ForkInherit, ForkMutation,
+    CoIteratePrimitive,
+    DiscussPrimitive, Participant,
+    SynthesizePrimitive, SynthesisSource,
+    ReflectPrimitive,
+    parse_primitive,
+)
+
+__all__ = [
+    # Messages
+    "A2AMessage",
+    # Transport
+    "LocalTransport",
+    # Trust
+    "InteractionRecord",
+    "AgentProfile",
+    "TrustEngine",
+    # Coordinator
+    "AgentCoordinator",
+    # Protocol Primitives (Phase 1: adopted from flux-a2a-prototype)
+    "BranchPrimitive", "BranchBody",
+    "ForkPrimitive", "ForkInherit", "ForkMutation",
+    "CoIteratePrimitive",
+    "DiscussPrimitive", "Participant",
+    "SynthesizePrimitive", "SynthesisSource",
+    "ReflectPrimitive",
+    "parse_primitive",
+]

flux/a2a/coordinator.py

@@ -0,0 +1,165 @@
+"""Agent Coordinator — Orchestrates multiple agents within a single VM.
+
+Ties together :class:`LocalTransport` for message delivery and
+:class:`TrustEngine` for trust-gated communication.  Agents are
+identified by string names; internally each is assigned a ``uuid.UUID``
+for the A2A protocol layer.
+
+Message flow:
+
+    agent_a.send_message("bob", TELL, payload=b"hi")
+        → trust check (compute_trust >= threshold)
+        → build A2AMessage
+        → transport.send(message)
+        → message lands in bob's mailbox
+        → agent_b.get_messages("bob") drains the mailbox
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import uuid
+
+from flux.a2a.messages import A2AMessage
+from flux.a2a.transport import LocalTransport
+from flux.a2a.trust import TrustEngine
+
+
+class AgentCoordinator:
+    """Coordinates multiple agents running in the same VM.
+
+    Parameters
+    ----------
+    trust_threshold : float
+        Minimum trust score required for message delivery (default 0.3).
+    """
+
+    def __init__(self, trust_threshold: float = 0.3) -> None:
+        self._agents: Dict[str, Dict[str, Any]] = {}
+        self.trust: TrustEngine = TrustEngine()
+        self.transport: LocalTransport = LocalTransport()
+        self.trust_threshold: float = trust_threshold
+
+    # ── Agent Registration ────────────────────────────────────────────────
+
+    def register_agent(
+        self, agent_id: str, interpreter: Any = None
+    ) -> uuid.UUID:
+        """Register an agent with an optional VM interpreter.
+
+        Parameters
+        ----------
+        agent_id : str
+            Logical name for the agent.
+        interpreter : Any, optional
+            A :class:`flux.vm.interpreter.Interpreter` instance, or None.
+
+        Returns
+        -------
+        uuid.UUID
+            The generated UUID for this agent (used in A2A headers).
+        """
+        aid = uuid.uuid4()
+        self.transport.register(aid)
+        self._agents[agent_id] = {
+            "uuid": aid,
+            "interpreter": interpreter,
+        }
+        return aid
+
+    def unregister_agent(self, agent_id: str) -> None:
+        """Remove an agent from the coordinator."""
+        info = self._agents.pop(agent_id, None)
+        if info is not None:
+            self.transport.unregister(info["uuid"])
+
+    # ── Messaging ─────────────────────────────────────────────────────────
+
+    def send_message(
+        self,
+        sender: str,
+        receiver: str,
+        msg_type: int,
+        payload: bytes = b"",
+        priority: int = 5,
+        in_reply_to: Optional[uuid.UUID] = None,
+    ) -> bool:
+        """Send an A2A message between registered agents.
+
+        The message is only delivered if the trust score from *sender*
+        to *receiver* meets the configured threshold.
+
+        Parameters
+        ----------
+        sender : str
+            Name of the sending agent.
+        receiver : str
+            Name of the receiving agent.
+        msg_type : int
+            A2A message type (0x60–0x7B).
+        payload : bytes
+            Application-level payload.
+        priority : int
+            Delivery priority 0–15.
+        in_reply_to : uuid.UUID, optional
+            UUID this message is replying to.
+
+        Returns
+        -------
+        bool
+            ``True`` if the message was delivered, ``False`` if blocked
+            by the trust gate or if either agent is unknown.
+        """
+        # Trust gate
+        trust = self.trust.compute_trust(sender, receiver)
+        if trust < self.trust_threshold:
+            return False
+
+        sender_info = self._agents.get(sender)
+        receiver_info = self._agents.get(receiver)
+        if sender_info is None or receiver_info is None:
+            return False
+
+        msg = A2AMessage(
+            sender=sender_info["uuid"],
+            receiver=receiver_info["uuid"],
+            conversation_id=uuid.uuid4(),
+            in_reply_to=in_reply_to,
+            message_type=msg_type,
+            priority=priority,
+            trust_token=int(trust * 1e9),
+            capability_token=0,
+            payload=payload,
+        )
+
+        delivered = self.transport.send(msg)
+        if delivered:
+            # Record positive interaction on success
+            self.trust.record_interaction(sender, receiver, True, 0.1)
+        return delivered
+
+    def get_messages(self, agent_id: str) -> List[A2AMessage]:
+        """Drain the mailbox for *agent_id* and return all pending messages."""
+        info = self._agents.get(agent_id)
+        if info is None:
+            return []
+        return self.transport.receive(info["uuid"])
+
+    def pending_count(self, agent_id: str) -> int:
+        """Return the number of pending messages for *agent_id*."""
+        info = self._agents.get(agent_id)
+        if info is None:
+            return 0
+        return self.transport.pending_count(info["uuid"])
+
+    # ── Queries ───────────────────────────────────────────────────────────
+
+    def get_agent_uuid(self, agent_name: str) -> Optional[uuid.UUID]:
+        """Return the UUID for a named agent, or ``None``."""
+        info = self._agents.get(agent_name)
+        return info["uuid"] if info else None
+
+    def registered_agents(self) -> List[str]:
+        """Return a list of all registered agent names."""
+        return list(self._agents.keys())

flux/a2a/messages.py

@@ -0,0 +1,171 @@
+"""A2A Message Types — Fixed-format binary messages for agent-to-agent communication.
+
+Message layout (binary, 52-byte header):
+
+    Offset  Size   Field
+    ─────── ────── ──────────────────────────────────────
+    0       16     sender_uuid        (128-bit UUID)
+    16      16     receiver_uuid      (128-bit UUID)
+    32       8     conversation_id    (compact 64-bit)
+    40       1     message_type       (uint8, 0x60–0x7B)
+    41       1     priority           (uint8, 0–15)
+    42       4     trust_token        (uint32 LE)
+    46       4     capability_token   (uint32 LE)
+    50       2     in_reply_to        (uint16 LE, 0 = None)
+    52      var    payload            (arbitrary bytes)
+"""
+
+from __future__ import annotations
+
+import struct
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional
+
+# Header format: <16s16s8sBBIIH  = 16+16+8+1+1+4+4+2 = 52
+_HEADER_STRUCT = struct.Struct("<16s16s8sBBIIH")
+
+
+# ── A2A Message ───────────────────────────────────────────────────────────
+
+
+@dataclass
+class A2AMessage:
+    """Fixed-format binary A2A message with a 52-byte header.
+
+    Attributes
+    ----------
+    sender : uuid.UUID
+        128-bit UUID of the originating agent.
+    receiver : uuid.UUID
+        128-bit UUID of the target agent.
+    conversation_id : uuid.UUID
+        128-bit UUID grouping related messages.  Serialized as the first
+        8 bytes (time_low + time_mid) for compactness; zero-padded on
+        deserialization.
+    in_reply_to : Optional[uuid.UUID]
+        When set, marks this message as a reply.  Serialized as a uint16
+        extracted from the UUID bytes; deserialized as None when zero.
+    message_type : int
+        Protocol verb in range 0x60–0x7B (A2A opcode space).
+    priority : int
+        Delivery priority 0–15.
+    trust_token : int
+        32-bit unsigned trust evidence token.
+    capability_token : int
+        32-bit unsigned capability evidence token.
+    payload : bytes
+        Arbitrary application-level payload.
+    """
+
+    sender: uuid.UUID
+    receiver: uuid.UUID
+    conversation_id: uuid.UUID
+    in_reply_to: Optional[uuid.UUID]
+    message_type: int
+    priority: int
+    trust_token: int
+    capability_token: int
+    payload: bytes = b""
+
+    HEADER_SIZE: int = 52  # fixed header length in bytes
+
+    # ── Validation helpers ────────────────────────────────────────────────
+
+    def __post_init__(self) -> None:
+        if not (0x60 <= self.message_type <= 0x7B):
+            raise ValueError(
+                f"message_type must be in 0x60–0x7B, got 0x{self.message_type:02X}"
+            )
+        if not (0 <= self.priority <= 15):
+            raise ValueError(
+                f"priority must be 0–15, got {self.priority}"
+            )
+        if not (0 <= self.trust_token <= 0xFFFFFFFF):
+            raise ValueError(
+                f"trust_token must fit in uint32, got {self.trust_token}"
+            )
+        if not (0 <= self.capability_token <= 0xFFFFFFFF):
+            raise ValueError(
+                f"capability_token must fit in uint32, got {self.capability_token}"
+            )
+
+    # ── Serialization ─────────────────────────────────────────────────────
+
+    def to_bytes(self) -> bytes:
+        """Serialize to binary (52-byte header + payload).
+
+        The compact header drops the low 8 bytes of *conversation_id* and
+        reduces *in_reply_to* to a uint16 tag (0 when None).
+        """
+        # conversation_id → first 8 bytes of UUID (time_low + time_mid + time_hi)
+        conv_bytes = self.conversation_id.bytes[:8]
+
+        # in_reply_to → uint16 from first 2 bytes, 0 if None
+        reply_u16 = 0
+        if self.in_reply_to is not None:
+            reply_u16 = int.from_bytes(
+                self.in_reply_to.bytes[:2], byteorder="little"
+            )
+
+        header = _HEADER_STRUCT.pack(
+            self.sender.bytes,
+            self.receiver.bytes,
+            conv_bytes,
+            self.message_type,
+            self.priority,
+            self.trust_token,
+            self.capability_token,
+            reply_u16,
+        )
+        return header + self.payload
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> A2AMessage:
+        """Deserialize from binary.
+
+        Raises ``ValueError`` if the buffer is shorter than 52 bytes.
+        """
+        if len(data) < cls.HEADER_SIZE:
+            raise ValueError(
+                f"A2AMessage requires at least {cls.HEADER_SIZE} bytes, "
+                f"got {len(data)}"
+            )
+
+        (sender_b, receiver_b, conv_b, msg_type, prio,
+         trust_tok, cap_tok, reply_u16) = _HEADER_STRUCT.unpack_from(data, 0)
+
+        # Reconstruct full UUIDs from compact fields
+        sender = uuid.UUID(bytes=sender_b)
+        receiver = uuid.UUID(bytes=receiver_b)
+        conversation_id = uuid.UUID(bytes=conv_b + b"\x00" * 8)
+
+        # Reconstruct in_reply_to
+        in_reply_to = None
+        if reply_u16 != 0:
+            in_reply_to = uuid.UUID(
+                bytes=reply_u16.to_bytes(2, byteorder="little") + b"\x00" * 14
+            )
+
+        payload = data[cls.HEADER_SIZE:]
+
+        return cls(
+            sender=sender,
+            receiver=receiver,
+            conversation_id=conversation_id,
+            in_reply_to=in_reply_to,
+            message_type=msg_type,
+            priority=prio,
+            trust_token=trust_tok,
+            capability_token=cap_tok,
+            payload=payload,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"A2AMessage(type=0x{self.message_type:02X}, "
+            f"sender={self.sender}, receiver={self.receiver}, "
+            f"conv={self.conversation_id}, "
+            f"priority={self.priority}, "
+            f"payload_len={len(self.payload)})"
+        )