nest-plugins-reference 0.1.0__py3-none-any.whl

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/auth/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.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/comms/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.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/coordination/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.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/datafacts/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.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/identity/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.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/memory/__init__.py

@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.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/negotiation/__init__.py

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

nest_plugins_reference/negotiation/alternating_offers.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Alternating offers negotiation plugin — Rubinstein-style bargaining.
+
+Example::
+
+    neg = AlternatingOffers(AgentId("a1"), patience=0.9)
+    session = await neg.open(AgentId("a2"), Terms(price=Money(amount=100)))
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from nest_core.types import (
+    AgentId,
+    Agreement,
+    NegotiationResponse,
+    NegotiationSession,
+    NegotiationStatus,
+    Terms,
+)
+
+
+class AlternatingOffers:
+    """Rubinstein-style alternating-offers negotiation.
+
+    Example::
+
+        neg = AlternatingOffers(AgentId("a1"))
+        session = await neg.open(AgentId("a2"), terms)
+    """
+
+    def __init__(self, agent_id: AgentId, patience: float = 0.9) -> None:
+        self._agent_id = agent_id
+        self._patience = patience
+        self._sessions: dict[str, NegotiationSession] = {}
+
+    async def open(self, partner: AgentId, terms: Terms) -> NegotiationSession:
+        """Open a negotiation with initial terms.
+
+        Example::
+
+            session = await neg.open(AgentId("a2"), terms)
+        """
+        session = NegotiationSession(
+            id=str(uuid.uuid4()),
+            initiator=self._agent_id,
+            partner=partner,
+            status=NegotiationStatus.OPEN,
+            current_terms=terms,
+            history=[terms],
+        )
+        self._sessions[session.id] = session
+        return session
+
+    async def offer(self, session: NegotiationSession, terms: Terms) -> None:
+        """Make a counter-offer.
+
+        Example::
+
+            await neg.offer(session, Terms(price=Money(amount=80)))
+        """
+        session.current_terms = terms
+        session.history.append(terms)
+
+    async def respond(self, session: NegotiationSession) -> NegotiationResponse:
+        """Respond to the current offer using the patience discount.
+
+        Example::
+
+            resp = await neg.respond(session)
+        """
+        if session.current_terms is None or session.current_terms.price is None:
+            return NegotiationResponse(accepted=True)
+
+        rounds = len(session.history)
+        threshold = session.current_terms.price.amount * (self._patience**rounds)
+        if session.current_terms.price.amount <= threshold or rounds >= 10:
+            return NegotiationResponse(accepted=True)
+
+        return NegotiationResponse(accepted=False, counter_terms=session.current_terms)
+
+    async def close(self, session: NegotiationSession) -> Agreement | None:
+        """Close a session, returning an agreement if both parties accepted.
+
+        Example::
+
+            agreement = await neg.close(session)
+        """
+        if session.status == NegotiationStatus.AGREED or session.current_terms is not None:
+            session.status = NegotiationStatus.AGREED
+            return Agreement(
+                session_id=session.id,
+                terms=session.current_terms or Terms(),
+                parties=[session.initiator, session.partner],
+            )
+        session.status = NegotiationStatus.REJECTED
+        return None

nest_plugins_reference/payments/__init__.py

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

nest_plugins_reference/payments/prepaid_credits.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Prepaid credits payment plugin — simple debit/credit ledger.
+
+Example::
+
+    payments = PrepaidCredits(AgentId("a1"), initial_balance=1000)
+    receipt = await payments.pay(AgentId("a2"), Money(amount=50), PaymentRef("p1"))
+"""
+
+from __future__ import annotations
+
+from nest_core.types import (
+    AgentId,
+    Money,
+    PaymentRef,
+    PaymentStatus,
+    Quote,
+    Receipt,
+    ServiceRef,
+)
+
+
+class PrepaidCredits:
+    """Simple debit/credit ledger for payments.
+
+    Example::
+
+        pay = PrepaidCredits(AgentId("a1"), initial_balance=1000)
+        receipt = await pay.pay(AgentId("a2"), Money(amount=50), PaymentRef("p1"))
+    """
+
+    def __init__(self, agent_id: AgentId, initial_balance: int = 1000) -> None:
+        self._agent_id = agent_id
+        self._balances: dict[AgentId, int] = {agent_id: initial_balance}
+        self._payments: dict[PaymentRef, Receipt] = {}
+
+    def balance(self, agent: AgentId) -> int:
+        """Check an agent's balance.
+
+        Example::
+
+            bal = pay.balance(AgentId("a1"))
+        """
+        return self._balances.get(agent, 0)
+
+    async def quote(self, service: ServiceRef) -> Quote:
+        """Return a fixed quote for any service.
+
+        Example::
+
+            q = await pay.quote(ServiceRef("svc"))
+        """
+        return Quote(service=service, price=Money(amount=10))
+
+    async def pay(self, to: AgentId, amount: Money, ref: PaymentRef) -> Receipt:
+        """Execute a payment from this agent to another.
+
+        Example::
+
+            receipt = await pay.pay(AgentId("a2"), Money(amount=50), PaymentRef("p1"))
+        """
+        payer_balance = self._balances.get(self._agent_id, 0)
+        if payer_balance < amount.amount:
+            msg = f"Insufficient balance: {payer_balance} < {amount.amount}"
+            raise ValueError(msg)
+
+        self._balances[self._agent_id] = payer_balance - amount.amount
+        self._balances[to] = self._balances.get(to, 0) + amount.amount
+
+        receipt = Receipt(ref=ref, payer=self._agent_id, payee=to, amount=amount)
+        self._payments[ref] = receipt
+        return receipt
+
+    async def verify_payment(self, ref: PaymentRef) -> PaymentStatus:
+        """Verify a payment status by reference.
+
+        Example::
+
+            status = await pay.verify_payment(PaymentRef("p1"))
+        """
+        if ref in self._payments:
+            return PaymentStatus.CONFIRMED
+        return PaymentStatus.FAILED
+
+    async def refund(self, ref: PaymentRef) -> None:
+        """Refund a payment.
+
+        Example::
+
+            await pay.refund(PaymentRef("p1"))
+        """
+        receipt = self._payments.get(ref)
+        if receipt is None:
+            msg = f"Payment not found: {ref}"
+            raise ValueError(msg)
+
+        self._balances[receipt.payee] = self._balances.get(receipt.payee, 0) - receipt.amount.amount
+        self._balances[receipt.payer] = self._balances.get(receipt.payer, 0) + receipt.amount.amount
+        del self._payments[ref]

nest_plugins_reference/privacy/__init__.py

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

nest_plugins_reference/privacy/noop.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Noop privacy plugin — transparent passthrough, no actual encryption.
+
+Example::
+
+    priv = NoopPrivacy()
+    ct = await priv.encrypt(b"data", [AgentId("a1")])
+    assert ct == b"data"
+"""
+
+from __future__ import annotations
+
+from nest_core.types import AgentId, Proof, Statement, Witness
+
+
+class NoopPrivacy:
+    """Transparent passthrough — no encryption, mock proofs always valid.
+
+    Example::
+
+        priv = NoopPrivacy()
+        ct = await priv.encrypt(b"data", [AgentId("a1")])
+    """
+
+    async def encrypt(self, data: bytes, audience: list[AgentId]) -> bytes:
+        """Return data unchanged (no encryption).
+
+        Example::
+
+            ct = await priv.encrypt(b"secret", [AgentId("a1")])
+        """
+        return data
+
+    async def decrypt(self, data: bytes) -> bytes:
+        """Return data unchanged (no decryption).
+
+        Example::
+
+            pt = await priv.decrypt(ct)
+        """
+        return data
+
+    async def prove(self, statement: Statement, witness: Witness) -> Proof:
+        """Generate a mock proof (always valid).
+
+        Example::
+
+            proof = await priv.prove(stmt, witness)
+        """
+        return Proof(statement=statement, data=b"mock-proof", scheme="noop")
+
+    async def verify_proof(self, statement: Statement, proof: Proof) -> bool:
+        """Verify a mock proof (always True).
+
+        Example::
+
+            ok = await priv.verify_proof(stmt, proof)
+        """
+        return True

nest_plugins_reference/registry/__init__.py

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

nest_plugins_reference/registry/in_memory.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+"""In-memory registry plugin — local dictionary-based agent discovery.
+
+Example::
+
+    registry = InMemoryRegistry()
+    await registry.register(card)
+    results = await registry.lookup(Query(capabilities=["sell"]))
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+from nest_core.types import AgentCard, AgentId, Query
+
+
+class InMemoryRegistry:
+    """Dictionary-backed agent registry.
+
+    Example::
+
+        reg = InMemoryRegistry()
+        await reg.register(AgentCard(agent_id=AgentId("a1"), name="Agent1"))
+    """
+
+    def __init__(self) -> None:
+        self._cards: dict[AgentId, AgentCard] = {}
+        self._subscribers: list[asyncio.Queue[AgentCard]] = []
+
+    async def register(self, card: AgentCard) -> None:
+        """Register an agent card.
+
+        Example::
+
+            await reg.register(card)
+        """
+        self._cards[card.agent_id] = card
+        for q in self._subscribers:
+            await q.put(card)
+
+    async def lookup(self, query: Query) -> list[AgentCard]:
+        """Look up agents matching a query.
+
+        Example::
+
+            results = await reg.lookup(Query(capabilities=["sell"]))
+        """
+        results: list[AgentCard] = []
+        for card in self._cards.values():
+            if self._matches(card, query):
+                results.append(card)
+        return results
+
+    async def subscribe(self, query: Query) -> AsyncIterator[AgentCard]:
+        """Subscribe to new agent registrations matching a query.
+
+        Example::
+
+            async for card in reg.subscribe(query):
+                print(card.name)
+        """
+        q: asyncio.Queue[AgentCard] = asyncio.Queue()
+        self._subscribers.append(q)
+        try:
+            while True:
+                card = await q.get()
+                if self._matches(card, query):
+                    yield card
+        finally:
+            self._subscribers.remove(q)
+
+    async def deregister(self, agent: AgentId) -> None:
+        """Remove an agent from the registry.
+
+        Example::
+
+            await reg.deregister(AgentId("a1"))
+        """
+        self._cards.pop(agent, None)
+
+    @staticmethod
+    def _matches(card: AgentCard, query: Query) -> bool:
+        if query.capabilities and not all(cap in card.capabilities for cap in query.capabilities):
+            return False
+        return not (query.name_pattern and query.name_pattern not in card.name)

nest_plugins_reference/transport/__init__.py

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

nest_plugins_reference/transport/in_memory.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: Apache-2.0
+"""In-memory transport plugin — standalone version for non-simulator use.
+
+Example::
+
+    transport = StandaloneInMemoryTransport(AgentId("a1"), network)
+    await transport.send(AgentId("a2"), b"hello")
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from nest_core.types import AgentId, TransportCapabilities
+
+
+class InMemoryNetwork:
+    """Shared network that routes messages between in-memory transports.
+
+    Example::
+
+        network = InMemoryNetwork()
+        t1 = StandaloneInMemoryTransport(AgentId("a1"), network)
+    """
+
+    def __init__(self) -> None:
+        self._queues: dict[AgentId, asyncio.Queue[tuple[AgentId, bytes]]] = {}
+        self._agents: list[AgentId] = []
+
+    def register(self, agent_id: AgentId) -> asyncio.Queue[tuple[AgentId, bytes]]:
+        """Register an agent and return its message queue.
+
+        Example::
+
+            queue = network.register(AgentId("a1"))
+        """
+        q: asyncio.Queue[tuple[AgentId, bytes]] = asyncio.Queue()
+        self._queues[agent_id] = q
+        self._agents.append(agent_id)
+        return q
+
+    def get_agents(self) -> list[AgentId]:
+        """Return all registered agent IDs.
+
+        Example::
+
+            agents = network.get_agents()
+        """
+        return list(self._agents)
+
+    async def deliver(self, sender: AgentId, to: AgentId, payload: bytes) -> None:
+        """Deliver a message to the target agent's queue.
+
+        Example::
+
+            await network.deliver(AgentId("a1"), AgentId("a2"), b"hi")
+        """
+        q = self._queues.get(to)
+        if q is not None:
+            await q.put((sender, payload))
+
+
+class StandaloneInMemoryTransport:
+    """In-memory transport for use outside the simulator (e.g., Tier 2).
+
+    Example::
+
+        network = InMemoryNetwork()
+        transport = StandaloneInMemoryTransport(AgentId("a1"), network)
+        await transport.send(AgentId("a2"), b"hello")
+    """
+
+    capabilities = TransportCapabilities(
+        supports_streaming=False,
+        ordered=True,
+        reliable=True,
+    )
+
+    def __init__(self, agent_id: AgentId, network: InMemoryNetwork) -> None:
+        self._agent_id = agent_id
+        self._network = network
+        self._queue = network.register(agent_id)
+
+    async def send(self, to: AgentId, payload: bytes) -> None:
+        """Send a payload to a specific agent.
+
+        Example::
+
+            await transport.send(AgentId("a2"), b"hello")
+        """
+        await self._network.deliver(self._agent_id, to, payload)
+
+    async def receive(self) -> tuple[AgentId, bytes]:
+        """Wait for the next message and return (sender, payload).
+
+        Example::
+
+            sender, data = await transport.receive()
+        """
+        return await self._queue.get()
+
+    async def broadcast(self, payload: bytes) -> None:
+        """Broadcast to all agents on the network.
+
+        Example::
+
+            await transport.broadcast(b"announcement")
+        """
+        for aid in self._network.get_agents():
+            if aid != self._agent_id:
+                await self.send(aid, payload)

nest_plugins_reference/trust/__init__.py

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

nest_plugins_reference/trust/score_average.py

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Score-average trust plugin — running mean of feedback scores.
+
+Example::
+
+    trust = ScoreAverageTrust(identity)
+    await trust.report(AgentId("a1"), evidence)
+    score = await trust.score(AgentId("a1"))
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from nest_core.types import (
+    AgentId,
+    Attestation,
+    Claim,
+    Evidence,
+    ReputationScore,
+    Signature,
+)
+
+
+class ScoreAverageTrust:
+    """Running-mean reputation based on reported feedback.
+
+    Example::
+
+        trust = ScoreAverageTrust()
+        score = await trust.score(AgentId("a1"))
+    """
+
+    def __init__(self, identity: Any = None) -> None:
+        self._identity = identity
+        self._scores: dict[AgentId, list[float]] = {}
+        self._stakes: dict[AgentId, int] = {}
+
+    async def score(self, agent: AgentId) -> ReputationScore:
+        """Get the running-mean reputation score for an agent.
+
+        Example::
+
+            rep = await trust.score(AgentId("a1"))
+        """
+        entries = self._scores.get(agent, [])
+        if not entries:
+            return ReputationScore(agent_id=agent, score=0.5, confidence=0.0, sample_count=0)
+        avg = sum(entries) / len(entries)
+        confidence = min(1.0, len(entries) / 100.0)
+        return ReputationScore(
+            agent_id=agent,
+            score=avg,
+            confidence=confidence,
+            sample_count=len(entries),
+        )
+
+    async def attest(self, agent: AgentId, claim: Claim) -> Attestation:
+        """Create an attestation about an agent.
+
+        Example::
+
+            att = await trust.attest(AgentId("a1"), claim)
+        """
+        sig = Signature(signer=AgentId("system"), value=b"attestation", algorithm="none")
+        if self._identity is not None:
+            sig = self._identity.sign(claim.model_dump_json().encode())
+        return Attestation(issuer=AgentId("system"), claim=claim, signature=sig)
+
+    async def report(self, agent: AgentId, evidence: Evidence) -> None:
+        """Report evidence, updating the agent's score.
+
+        Evidence kind 'positive' adds 1.0, 'negative' adds 0.0, 'byzantine' adds 0.0.
+
+        Example::
+
+            await trust.report(AgentId("a1"), Evidence(reporter=..., subject=..., kind="negative"))
+        """
+        score_val = 0.5
+        if evidence.kind == "positive":
+            score_val = 1.0
+        elif evidence.kind in ("negative", "byzantine"):
+            score_val = 0.0
+        self._scores.setdefault(agent, []).append(score_val)
+
+    async def stake(self, agent: AgentId, amount: int) -> None:
+        """Stake reputation on an agent.
+
+        Example::
+
+            await trust.stake(AgentId("a1"), 100)
+        """
+        self._stakes[agent] = self._stakes.get(agent, 0) + amount

nest_plugins_reference-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,29 @@
+nest_plugins_reference/__init__.py,sha256=JqKQjeEjHA1_vRzgRj0ZHR4QeW1U1tnrbljaAP22uMI,134
+nest_plugins_reference/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nest_plugins_reference/auth/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/auth/jwt_auth.py,sha256=Zcy_XCwxzaHfTDaOwcB-U1LsVcDDmjoRgW3ZOwKnypo,2736
+nest_plugins_reference/comms/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/comms/nest_native.py,sha256=cQsavxpCus8tNu3VL2zWO-wSWVMUzzinIKr9LpJbXCU,3092
+nest_plugins_reference/coordination/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/coordination/contract_net.py,sha256=gc48YV7jB4FECRikOppHGJ63La-tSq42_iUvqe53tIA,2454
+nest_plugins_reference/datafacts/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/datafacts/datafacts_v1.py,sha256=igPD46EOJZFgHMS8cru38HpKDaNMzG0LFr2qpiEoIow,2255
+nest_plugins_reference/identity/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/identity/did_key.py,sha256=6q2ypKi47iXJ5ydF9gtk7fOD0ihlxSsBh57oJpEuaXY,3055
+nest_plugins_reference/memory/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/memory/blackboard.py,sha256=kbeYgoDelLfU5b_03PzAl7-jjDq5RkweoSFN2VGBVEQ,2085
+nest_plugins_reference/negotiation/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/negotiation/alternating_offers.py,sha256=mbLbQhTyI7PZg2R_PL0Bmc8R2JcgTToOGfAlXaqKBoQ,3055
+nest_plugins_reference/payments/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/payments/prepaid_credits.py,sha256=FmfY6T13U-7GoT4D_OEOOA7OGSl5dududnZHfvsH4xw,3020
+nest_plugins_reference/privacy/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/privacy/noop.py,sha256=xBXRFkQ3ZLR9lAkPScxBO3hbZFFfGLqDojF7h7_qtLA,1495
+nest_plugins_reference/registry/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/registry/in_memory.py,sha256=IRuHfgxS3TeiscI04nGWbWzrUqOYAEwVh-UfamF9ajs,2472
+nest_plugins_reference/transport/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/transport/in_memory.py,sha256=seH6etRlnduW3YVwUTWMA7ZJxnXMTcUEbchMIYMrCBA,3116
+nest_plugins_reference/trust/__init__.py,sha256=bG7Ffen4LvQtgnYPFEpFccsWs81t4zqqeqn9ZeirH6E,38
+nest_plugins_reference/trust/score_average.py,sha256=spzqxBsCW8lWKF5wnxymTdjz2Xf5-f5sxDdTkjqz9Kk,2792
+nest_plugins_reference-0.1.0.dist-info/METADATA,sha256=PPlhFGFSOxXs7WscPg1pZsSBiShFfchP8-u1APJ2hpc,1135
+nest_plugins_reference-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nest_plugins_reference-0.1.0.dist-info/RECORD,,

nest_plugins_reference-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any