nest-plugins-reference 0.1.0__tar.gz

nest_plugins_reference-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+uv.lock

nest_plugins_reference-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: nest-plugins-reference
+Version: 0.1.0
+Summary: NEST reference plugins: default implementations for all 12 layers
+Project-URL: Homepage, https://github.com/mariagorskikh/nest
+Project-URL: Repository, https://github.com/mariagorskikh/nest
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: nest-core
+Requires-Dist: nest-sdk
+Description-Content-Type: text/markdown
+
+# nest-plugins-reference
+
+NEST reference plugins: default implementations for all 12 layers
+
+Part of [NEST](https://github.com/mariagorskikh/nest) (Network Environment for Swarm Testing), built at MIT Media Lab.
+
+## Installation
+
+```bash
+pip install nest-plugins-reference
+```
+
+See the [main repository](https://github.com/mariagorskikh/nest) for full documentation.

nest_plugins_reference-0.1.0/README.md

@@ -0,0 +1,13 @@
+# nest-plugins-reference
+
+NEST reference plugins: default implementations for all 12 layers
+
+Part of [NEST](https://github.com/mariagorskikh/nest) (Network Environment for Swarm Testing), built at MIT Media Lab.
+
+## Installation
+
+```bash
+pip install nest-plugins-reference
+```
+
+See the [main repository](https://github.com/mariagorskikh/nest) for full documentation.

nest_plugins_reference-0.1.0/nest_plugins_reference/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+"""NEST reference plugins: default implementations for all 12 layers."""
+
+__version__ = "0.1.0"

nest_plugins_reference-0.1.0/nest_plugins_reference/auth/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

nest_plugins_reference-0.1.0/nest_plugins_reference/auth/jwt_auth.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: Apache-2.0
+"""JWT auth plugin — sign tokens with HMAC-SHA256 for simulation.
+
+Example::
+
+    auth = JwtAuth(secret=b"my-secret")
+    token = await auth.issue(AgentId("a1"), ["read", "write"])
+    ctx = await auth.verify(token)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+
+from nest_core.types import AgentId, AuthContext, Token
+
+
+class JwtAuth:
+    """Simplified JWT-style auth using HMAC-SHA256.
+
+    Example::
+
+        auth = JwtAuth(secret=b"secret")
+        token = await auth.issue(AgentId("a1"), ["read"])
+    """
+
+    def __init__(self, secret: bytes = b"nest-default-secret", clock: float | None = None) -> None:
+        self._secret = secret
+        self._clock = clock
+        self._revoked: set[str] = set()
+
+    def _now(self) -> float:
+        if self._clock is not None:
+            return self._clock
+        return time.time()
+
+    def _sign(self, payload: str) -> str:
+        return hmac.new(self._secret, payload.encode(), hashlib.sha256).hexdigest()
+
+    async def issue(self, subject: AgentId, scopes: list[str]) -> Token:
+        """Issue a token for a subject with given scopes.
+
+        Example::
+
+            token = await auth.issue(AgentId("a1"), ["read", "write"])
+        """
+        now = self._now()
+        payload = json.dumps(
+            {
+                "sub": str(subject),
+                "scopes": scopes,
+                "iat": now,
+                "exp": now + 3600,
+            },
+            sort_keys=True,
+        )
+        sig = self._sign(payload)
+        return Token(f"{payload}|{sig}")
+
+    async def verify(self, token: Token) -> AuthContext:
+        """Verify a token and return its context.
+
+        Example::
+
+            ctx = await auth.verify(token)
+            assert ctx.subject == AgentId("a1")
+        """
+        raw = str(token)
+        if raw in self._revoked:
+            msg = "Token has been revoked"
+            raise ValueError(msg)
+
+        parts = raw.rsplit("|", 1)
+        if len(parts) != 2:
+            msg = "Invalid token format"
+            raise ValueError(msg)
+
+        payload_str, sig = parts
+        expected = self._sign(payload_str)
+        if not hmac.compare_digest(sig, expected):
+            msg = "Invalid token signature"
+            raise ValueError(msg)
+
+        data = json.loads(payload_str)
+        return AuthContext(
+            subject=AgentId(data["sub"]),
+            scopes=data["scopes"],
+            issued_at=data["iat"],
+            expires_at=data["exp"],
+        )
+
+    async def revoke(self, token: Token) -> None:
+        """Revoke a token.
+
+        Example::
+
+            await auth.revoke(token)
+        """
+        self._revoked.add(str(token))

nest_plugins_reference-0.1.0/nest_plugins_reference/comms/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

nest_plugins_reference-0.1.0/nest_plugins_reference/comms/nest_native.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Nest-native communication plugin — minimal JSON envelope.
+
+Example::
+
+    comms = NestNativeComms(AgentId("a1"), transport, registry)
+    raw = comms.serialize(msg)
+    msg2 = comms.deserialize(raw)
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+from nest_core.types import (
+    AgentCard,
+    AgentId,
+    Message,
+    MessageId,
+    Query,
+    Response,
+)
+
+
+class NestNativeComms:
+    """Minimal JSON-based communication protocol.
+
+    Example::
+
+        comms = NestNativeComms(AgentId("a1"), transport=t, registry=r)
+        resp = await comms.send(AgentId("a2"), msg)
+    """
+
+    def __init__(
+        self,
+        agent_id: AgentId,
+        transport: Any = None,
+        registry: Any = None,
+    ) -> None:
+        self._agent_id = agent_id
+        self._transport = transport
+        self._registry = registry
+
+    def serialize(self, msg: Message) -> bytes:
+        """Serialize a Message to JSON bytes.
+
+        Example::
+
+            raw = comms.serialize(msg)
+        """
+        data = {
+            "id": str(msg.id),
+            "sender": str(msg.sender),
+            "receiver": str(msg.receiver),
+            "payload": base64.b64encode(msg.payload).decode("ascii"),
+            "correlation_id": str(msg.correlation_id) if msg.correlation_id else None,
+            "timestamp": msg.timestamp,
+            "metadata": msg.metadata,
+        }
+        return json.dumps(data, sort_keys=True).encode("utf-8")
+
+    def deserialize(self, raw: bytes) -> Message:
+        """Deserialize JSON bytes back to a Message.
+
+        Example::
+
+            msg = comms.deserialize(raw)
+        """
+        data = json.loads(raw)
+        return Message(
+            id=MessageId(data["id"]),
+            sender=AgentId(data["sender"]),
+            receiver=AgentId(data["receiver"]),
+            payload=base64.b64decode(data["payload"]),
+            correlation_id=data.get("correlation_id"),
+            timestamp=data.get("timestamp"),
+            metadata=data.get("metadata", {}),
+        )
+
+    async def send(self, to: AgentId, msg: Message) -> Response:
+        """Send a message via the transport layer.
+
+        Example::
+
+            resp = await comms.send(AgentId("a2"), msg)
+        """
+        raw = self.serialize(msg)
+        if self._transport is not None:
+            await self._transport.send(to, raw)
+        return Response(success=True)
+
+    async def advertise(self, card: AgentCard) -> None:
+        """Advertise an agent card to the registry.
+
+        Example::
+
+            await comms.advertise(my_card)
+        """
+        if self._registry is not None:
+            await self._registry.register(card)
+
+    async def discover(self, query: Query) -> list[AgentCard]:
+        """Discover agents via the registry.
+
+        Example::
+
+            cards = await comms.discover(Query(capabilities=["sell"]))
+        """
+        if self._registry is not None:
+            result: list[AgentCard] = await self._registry.lookup(query)
+            return result
+        return []

nest_plugins_reference-0.1.0/nest_plugins_reference/coordination/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

nest_plugins_reference-0.1.0/nest_plugins_reference/coordination/contract_net.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Contract Net coordination plugin — classic FIPA Contract Net Protocol.
+
+The Round object is shared between manager and workers. Bids are stored
+in the round's metadata so any party can resolve them.
+
+Example::
+
+    coord = ContractNet(AgentId("manager"))
+    rnd = await coord.propose(task)
+    bid = await coord.participate(rnd)
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from nest_core.types import (
+    AgentId,
+    Bid,
+    Money,
+    Outcome,
+    Round,
+    Task,
+    Vote,
+)
+
+
+class ContractNet:
+    """FIPA Contract Net Protocol implementation.
+
+    Example::
+
+        coord = ContractNet(AgentId("a1"))
+        rnd = await coord.propose(Task(id="t1", description="work"))
+    """
+
+    def __init__(self, agent_id: AgentId) -> None:
+        self._agent_id = agent_id
+
+    async def propose(self, task: Task) -> Round:
+        """Propose a task for bidding.
+
+        Example::
+
+            rnd = await coord.propose(task)
+        """
+        round_id = str(uuid.uuid4())
+        rnd = Round(
+            id=round_id,
+            task=task,
+            participants=[],
+            metadata={"bids": []},
+        )
+        return rnd
+
+    async def participate(self, round: Round) -> Vote | Bid:
+        """Submit a bid for a round.
+
+        Example::
+
+            bid = await coord.participate(rnd)
+        """
+        bid = Bid(
+            bidder=self._agent_id,
+            round_id=round.id,
+            amount=Money(amount=1),
+        )
+        bids: list[dict[str, object]] = round.metadata.setdefault("bids", [])
+        bids.append({"bidder": str(bid.bidder), "amount": bid.amount.amount})
+        if self._agent_id not in round.participants:
+            round.participants.append(self._agent_id)
+        return bid
+
+    async def resolve(self, round: Round) -> Outcome:
+        """Resolve a round by selecting the lowest bidder.
+
+        Example::
+
+            outcome = await coord.resolve(rnd)
+        """
+        bids: list[dict[str, object]] = round.metadata.get("bids", [])
+        winner: AgentId | None = None
+        if bids:
+            best = min(bids, key=lambda b: int(str(b["amount"])))
+            winner = AgentId(str(best["bidder"]))
+        return Outcome(round_id=round.id, winner=winner, task=round.task)
+
+    async def commit(self, outcome: Outcome) -> None:
+        """Commit to an outcome.
+
+        Example::
+
+            await coord.commit(outcome)
+        """

nest_plugins_reference-0.1.0/nest_plugins_reference/datafacts/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

nest_plugins_reference-0.1.0/nest_plugins_reference/datafacts/datafacts_v1.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""DataFacts v1 plugin — dataset metadata registry.
+
+Example::
+
+    df = DataFactsV1()
+    url = await df.publish(DatasetMetadata(name="weather", owner=AgentId("a1")))
+    meta = await df.fetch(url)
+"""
+
+from __future__ import annotations
+
+import time
+
+from nest_core.types import AccessGrant, AgentId, DataFactsUrl, DatasetMetadata
+
+
+class DataFactsV1:
+    """In-memory DataFacts metadata registry.
+
+    Example::
+
+        df = DataFactsV1()
+        url = await df.publish(meta)
+    """
+
+    def __init__(self) -> None:
+        self._datasets: dict[DataFactsUrl, DatasetMetadata] = {}
+        self._grants: dict[DataFactsUrl, list[AccessGrant]] = {}
+        self._timestamps: dict[DataFactsUrl, float] = {}
+
+    async def publish(self, dataset: DatasetMetadata) -> DataFactsUrl:
+        """Publish dataset metadata and return its URL.
+
+        Example::
+
+            url = await df.publish(DatasetMetadata(name="weather", owner=AgentId("a1")))
+        """
+        url = DataFactsUrl(f"df://{dataset.name}")
+        self._datasets[url] = dataset
+        self._timestamps[url] = time.time()
+        return url
+
+    async def fetch(self, url: DataFactsUrl) -> DatasetMetadata:
+        """Fetch metadata for a dataset URL.
+
+        Example::
+
+            meta = await df.fetch(DataFactsUrl("df://weather"))
+        """
+        meta = self._datasets.get(url)
+        if meta is None:
+            msg = f"Dataset not found: {url}"
+            raise KeyError(msg)
+        return meta
+
+    async def request_access(self, url: DataFactsUrl, requester: AgentId) -> AccessGrant:
+        """Request access to a dataset (always grants in v1).
+
+        Example::
+
+            grant = await df.request_access(url, AgentId("a2"))
+        """
+        grant = AccessGrant(url=url, grantee=requester, tier="read")
+        self._grants.setdefault(url, []).append(grant)
+        return grant
+
+    async def verify_freshness(self, url: DataFactsUrl) -> bool:
+        """Check if a dataset was published within the last hour.
+
+        Example::
+
+            fresh = await df.verify_freshness(url)
+        """
+        ts = self._timestamps.get(url)
+        if ts is None:
+            return False
+        return (time.time() - ts) < 3600

nest_plugins_reference-0.1.0/nest_plugins_reference/identity/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

nest_plugins_reference-0.1.0/nest_plugins_reference/identity/did_key.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: Apache-2.0
+"""DID:key identity plugin — Ed25519 key-based identity.
+
+Uses hashlib for deterministic key derivation in simulation (no real crypto
+needed for testing). For real deployments, swap to a proper Ed25519 library.
+
+Example::
+
+    identity = DidKeyIdentity(AgentId("a1"), seed=b"secret")
+    sig = identity.sign(b"payload")
+    ok = identity.verify(b"payload", sig, AgentId("a1"))
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from nest_core.types import AgentId, AgentIdentity, Signature
+
+
+class DidKeyIdentity:
+    """Ed25519-style identity using HMAC-SHA256 for simulation.
+
+    Example::
+
+        ident = DidKeyIdentity(AgentId("a1"), seed=b"seed")
+        sig = ident.sign(b"hello")
+    """
+
+    def __init__(self, agent_id: AgentId, seed: bytes = b"") -> None:
+        self._agent_id = agent_id
+        self._seed = seed
+        key_material = hashlib.sha256(seed + agent_id.encode()).digest()
+        self._private_key = key_material
+        self._public_key = hashlib.sha256(key_material).digest()
+        self._known_keys: dict[AgentId, bytes] = {agent_id: self._public_key}
+        self._private_keys: dict[AgentId, bytes] = {agent_id: self._private_key}
+
+    def register_peer(
+        self,
+        agent_id: AgentId,
+        public_key: bytes,
+        private_key: bytes | None = None,
+    ) -> None:
+        """Register a peer's public key (and optionally private key) for verification.
+
+        Example::
+
+            ident.register_peer(AgentId("a2"), peer_pk)
+        """
+        self._known_keys[agent_id] = public_key
+        if private_key is not None:
+            self._private_keys[agent_id] = private_key
+
+    @property
+    def public_key(self) -> bytes:
+        """This agent's public key.
+
+        Example::
+
+            pk = ident.public_key
+        """
+        return self._public_key
+
+    def sign(self, payload: bytes) -> Signature:
+        """Sign a payload with this agent's private key.
+
+        Example::
+
+            sig = ident.sign(b"data")
+        """
+        sig_bytes = hmac.new(self._private_key, payload, hashlib.sha256).digest()
+        return Signature(signer=self._agent_id, value=sig_bytes, algorithm="hmac-sha256")
+
+    def verify(self, payload: bytes, sig: Signature, agent: AgentId) -> bool:
+        """Verify a signature from a given agent.
+
+        Example::
+
+            ok = ident.verify(b"data", sig, AgentId("a1"))
+        """
+        private_key = self._private_keys.get(agent)
+        if private_key is None:
+            return False
+        expected = hmac.new(private_key, payload, hashlib.sha256).digest()
+        return hmac.compare_digest(sig.value, expected)
+
+    async def resolve(self, agent: AgentId) -> AgentIdentity:
+        """Resolve an agent ID to its identity record.
+
+        Example::
+
+            info = await ident.resolve(AgentId("a1"))
+        """
+        pk = self._known_keys.get(agent, b"")
+        return AgentIdentity(
+            agent_id=agent,
+            public_key=pk,
+            method="did:key",
+        )

nest_plugins_reference-0.1.0/nest_plugins_reference/memory/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0

nest_plugins_reference-0.1.0/nest_plugins_reference/memory/blackboard.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Blackboard memory plugin — shared key-value store.
+
+Example::
+
+    mem = Blackboard()
+    await mem.write("key", b"value")
+    val = await mem.read("key")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+
+class Blackboard:
+    """Shared key-value blackboard for agent state.
+
+    Example::
+
+        bb = Blackboard()
+        await bb.write("counter", b"42")
+        val = await bb.read("counter")
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, bytes] = {}
+        self._subscribers: dict[str, list[asyncio.Queue[bytes]]] = {}
+
+    async def read(self, key: str) -> bytes | None:
+        """Read a value by key.
+
+        Example::
+
+            val = await bb.read("counter")
+        """
+        return self._store.get(key)
+
+    async def write(self, key: str, value: bytes) -> None:
+        """Write a value for a key, notifying subscribers.
+
+        Example::
+
+            await bb.write("counter", b"42")
+        """
+        self._store[key] = value
+        for q in self._subscribers.get(key, []):
+            await q.put(value)
+
+    async def subscribe(self, key: str) -> AsyncIterator[bytes]:
+        """Subscribe to changes for a key.
+
+        Example::
+
+            async for val in bb.subscribe("counter"):
+                print(val)
+        """
+        q: asyncio.Queue[bytes] = asyncio.Queue()
+        self._subscribers.setdefault(key, []).append(q)
+        try:
+            while True:
+                yield await q.get()
+        finally:
+            self._subscribers[key].remove(q)
+
+    async def cas(self, key: str, expected: bytes, new: bytes) -> bool:
+        """Compare-and-swap: update only if current value matches expected.
+
+        Example::
+
+            ok = await bb.cas("counter", b"42", b"43")
+        """
+        current = self._store.get(key)
+        if current == expected:
+            self._store[key] = new
+            for q in self._subscribers.get(key, []):
+                await q.put(new)
+            return True
+        return False

nest_plugins_reference-0.1.0/nest_plugins_reference/negotiation/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0