nest-core 0.1.0__tar.gz

nest_core-0.1.0/.gitignore

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

nest_core-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: nest-core
+Version: 0.1.0
+Summary: NEST core engine: layer interfaces, runtime, event loop, and simulator
+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: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# nest-core
+
+NEST core engine: layer interfaces, runtime, event loop, and simulator
+
+Part of [NEST](https://github.com/mariagorskikh/nest) (Network Environment for Swarm Testing), built at MIT Media Lab.
+
+## Installation
+
+```bash
+pip install nest-core
+```
+
+See the [main repository](https://github.com/mariagorskikh/nest) for full documentation.

nest_core-0.1.0/README.md

@@ -0,0 +1,13 @@
+# nest-core
+
+NEST core engine: layer interfaces, runtime, event loop, and simulator
+
+Part of [NEST](https://github.com/mariagorskikh/nest) (Network Environment for Swarm Testing), built at MIT Media Lab.
+
+## Installation
+
+```bash
+pip install nest-core
+```
+
+See the [main repository](https://github.com/mariagorskikh/nest) for full documentation.

nest_core-0.1.0/nest_core/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+"""NEST core engine: layer interfaces, runtime, event loop, and simulator."""
+
+__version__ = "0.1.0"

nest_core-0.1.0/nest_core/inspect.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Trace file inspection and analysis.
+
+Example::
+
+    summary = analyze_trace("traces/marketplace.jsonl")
+    print(summary.total_events)
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class AgentStats:
+    """Per-agent statistics extracted from a trace."""
+
+    sends: int = 0
+    receives: int = 0
+    started: bool = False
+    stopped: bool = False
+
+
+@dataclass
+class TraceSummary:
+    """Summary statistics for a JSONL trace file."""
+
+    total_events: int = 0
+    duration: float = 0.0
+    event_kinds: dict[str, int] = field(default_factory=lambda: dict[str, int]())
+    agent_count: int = 0
+    message_count: int = 0
+    unique_correlations: int = 0
+    agents: dict[str, AgentStats] = field(default_factory=lambda: dict[str, AgentStats]())
+
+
+def analyze_trace(path: str | Path) -> TraceSummary:
+    """Analyze a JSONL trace file and return summary statistics.
+
+    Example::
+
+        summary = analyze_trace("trace.jsonl")
+    """
+    path = Path(path)
+    summary = TraceSummary()
+    kind_counter: Counter[str] = Counter()
+    agents_seen: set[str] = set()
+    corr_ids: set[str] = set()
+    min_ts = float("inf")
+    max_ts = float("-inf")
+
+    with path.open() as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+
+            event = json.loads(line)
+            summary.total_events += 1
+
+            ts = event.get("ts", 0.0)
+            if ts < min_ts:
+                min_ts = ts
+            if ts > max_ts:
+                max_ts = ts
+
+            kind = event.get("kind", "unknown")
+            kind_counter[kind] += 1
+
+            agent = event.get("agent", "")
+            if agent:
+                agents_seen.add(agent)
+                if agent not in summary.agents:
+                    summary.agents[agent] = AgentStats()
+
+                stats = summary.agents[agent]
+                if kind == "send":
+                    stats.sends += 1
+                elif kind == "receive":
+                    stats.receives += 1
+                elif kind == "start":
+                    stats.started = True
+                elif kind == "stop":
+                    stats.stopped = True
+
+            corr = event.get("corr")
+            if corr is not None:
+                corr_ids.add(str(corr))
+
+            if kind in ("send", "receive"):
+                summary.message_count += 1
+
+    summary.event_kinds = dict(kind_counter)
+    summary.agent_count = len(agents_seen)
+    summary.unique_correlations = len(corr_ids)
+    if max_ts > min_ts:
+        summary.duration = max_ts - min_ts
+
+    return summary
+
+
+def format_summary(summary: TraceSummary) -> str:
+    """Format a TraceSummary as a human-readable report.
+
+    Example::
+
+        print(format_summary(summary))
+    """
+    lines: list[str] = []
+    lines.append("NEST Trace Summary")
+    lines.append("=" * 40)
+    lines.append(f"  Total events:       {summary.total_events}")
+    lines.append(f"  Agents:             {summary.agent_count}")
+    lines.append(f"  Messages:           {summary.message_count}")
+    lines.append(f"  Correlation IDs:    {summary.unique_correlations}")
+    lines.append(f"  Duration:           {summary.duration:.1f} ticks")
+    lines.append("")
+    lines.append("Event breakdown:")
+    for kind, count in sorted(summary.event_kinds.items()):
+        lines.append(f"  {kind:20s} {count:>6d}")
+
+    lines.append("")
+    lines.append("Top agents by sends:")
+    top_senders = sorted(
+        summary.agents.items(),
+        key=lambda kv: kv[1].sends,
+        reverse=True,
+    )[:10]
+    for agent_name, stats in top_senders:
+        lines.append(f"  {agent_name:20s} sent={stats.sends:>4d}  recv={stats.receives:>4d}")
+
+    return "\n".join(lines)

nest_core-0.1.0/nest_core/layers/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Layer interface definitions for all 12 pluggable layers.
+
+Example::
+
+    from nest_core.layers import Transport, Payments, Registry
+"""
+
+from nest_core.layers.auth import Auth
+from nest_core.layers.comms import CommsProtocol
+from nest_core.layers.coordination import Coordination
+from nest_core.layers.datafacts import DataFacts
+from nest_core.layers.identity import Identity
+from nest_core.layers.memory import Memory
+from nest_core.layers.negotiation import Negotiation
+from nest_core.layers.payments import Payments
+from nest_core.layers.privacy import Privacy
+from nest_core.layers.registry import Registry
+from nest_core.layers.transport import Transport
+from nest_core.layers.trust import Trust
+
+__all__ = [
+    "Auth",
+    "CommsProtocol",
+    "Coordination",
+    "DataFacts",
+    "Identity",
+    "Memory",
+    "Negotiation",
+    "Payments",
+    "Privacy",
+    "Registry",
+    "Transport",
+    "Trust",
+]

nest_core-0.1.0/nest_core/layers/auth.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Auth layer interface: authentication and authorization.
+
+Example::
+
+    class MyAuth(Auth):
+        async def issue(self, subject, scopes):
+            return Token(jwt.encode({"sub": subject, "scopes": scopes}, key))
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from nest_core.types import AgentId, AuthContext, Token
+
+
+@runtime_checkable
+class Auth(Protocol):
+    """Authentication and authorization for agents.
+
+    Example::
+
+        auth: Auth = JwtAuth(identity)
+        token = await auth.issue(AgentId("a1"), ["read", "write"])
+    """
+
+    async def issue(self, subject: AgentId, scopes: list[str]) -> Token:
+        """Issue an auth token for a subject with given scopes.
+
+        Example::
+
+            token = await auth.issue(AgentId("a1"), ["read"])
+        """
+        ...
+
+    async def verify(self, token: Token) -> AuthContext:
+        """Verify a token and return its auth context.
+
+        Example::
+
+            ctx = await auth.verify(token)
+        """
+        ...
+
+    async def revoke(self, token: Token) -> None:
+        """Revoke a previously issued token.
+
+        Example::
+
+            await auth.revoke(token)
+        """
+        ...

nest_core-0.1.0/nest_core/layers/comms.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Communication layer interface: message format, request/response, discovery.
+
+Example::
+
+    class MyComms(CommsProtocol):
+        def serialize(self, msg):
+            return json.dumps(msg.model_dump()).encode()
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from nest_core.types import AgentCard, AgentId, Message, Query, Response
+
+
+@runtime_checkable
+class CommsProtocol(Protocol):
+    """Wire protocol for agent communication.
+
+    Example::
+
+        comms: CommsProtocol = NestNativeComms()
+        raw = comms.serialize(msg)
+    """
+
+    def serialize(self, msg: Message) -> bytes:
+        """Serialize a Message into bytes for transport.
+
+        Example::
+
+            raw = comms.serialize(msg)
+        """
+        ...
+
+    def deserialize(self, raw: bytes) -> Message:
+        """Deserialize bytes back into a Message.
+
+        Example::
+
+            msg = comms.deserialize(raw)
+        """
+        ...
+
+    async def send(self, to: AgentId, msg: Message) -> Response:
+        """Send a message and wait for a response.
+
+        Example::
+
+            resp = await comms.send(AgentId("a2"), msg)
+        """
+        ...
+
+    async def advertise(self, card: AgentCard) -> None:
+        """Advertise this agent's capabilities.
+
+        Example::
+
+            await comms.advertise(my_card)
+        """
+        ...
+
+    async def discover(self, query: Query) -> list[AgentCard]:
+        """Discover agents matching a query.
+
+        Example::
+
+            cards = await comms.discover(Query(capabilities=["sell_data"]))
+        """
+        ...

nest_core-0.1.0/nest_core/layers/coordination.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Coordination layer interface: how groups decide.
+
+Example::
+
+    class MyCoordination(Coordination):
+        async def propose(self, task):
+            return Round(id="r1", task=task)
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from nest_core.types import Bid, Outcome, Round, Task, Vote
+
+
+@runtime_checkable
+class Coordination(Protocol):
+    """Group decision-making protocol.
+
+    Example::
+
+        coord: Coordination = ContractNet()
+        rnd = await coord.propose(task)
+    """
+
+    async def propose(self, task: Task) -> Round:
+        """Propose a task for group coordination.
+
+        Example::
+
+            rnd = await coord.propose(Task(id="t1", description="process data"))
+        """
+        ...
+
+    async def participate(self, round: Round) -> Vote | Bid:
+        """Participate in a coordination round with a vote or bid.
+
+        Example::
+
+            bid = await coord.participate(rnd)
+        """
+        ...
+
+    async def resolve(self, round: Round) -> Outcome:
+        """Resolve a coordination round to an outcome.
+
+        Example::
+
+            outcome = await coord.resolve(rnd)
+        """
+        ...
+
+    async def commit(self, outcome: Outcome) -> None:
+        """Commit to a resolved outcome.
+
+        Example::
+
+            await coord.commit(outcome)
+        """
+        ...

nest_core-0.1.0/nest_core/layers/datafacts.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+"""DataFacts layer interface: dataset metadata, freshness, integrity, access.
+
+Example::
+
+    class MyDataFacts(DataFacts):
+        async def publish(self, dataset):
+            url = DataFactsUrl(f"df://{dataset.name}")
+            self._store[url] = dataset
+            return url
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from nest_core.types import AccessGrant, AgentId, DataFactsUrl, DatasetMetadata
+
+
+@runtime_checkable
+class DataFacts(Protocol):
+    """Dataset metadata exchange protocol.
+
+    Example::
+
+        df: DataFacts = DataFactsV1()
+        url = await df.publish(meta)
+    """
+
+    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")))
+        """
+        ...
+
+    async def fetch(self, url: DataFactsUrl) -> DatasetMetadata:
+        """Fetch metadata for a published dataset.
+
+        Example::
+
+            meta = await df.fetch(DataFactsUrl("df://weather"))
+        """
+        ...
+
+    async def request_access(self, url: DataFactsUrl, requester: AgentId) -> AccessGrant:
+        """Request access to a dataset.
+
+        Example::
+
+            grant = await df.request_access(url, AgentId("a2"))
+        """
+        ...
+
+    async def verify_freshness(self, url: DataFactsUrl) -> bool:
+        """Check if a dataset's metadata is still fresh.
+
+        Example::
+
+            fresh = await df.verify_freshness(url)
+        """
+        ...

nest_core-0.1.0/nest_core/layers/identity.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Identity layer interface: who is this agent, and how do I verify them?
+
+Example::
+
+    class MyIdentity(Identity):
+        def sign(self, payload):
+            return Signature(signer=self.agent_id, value=do_sign(payload))
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from nest_core.types import AgentId, AgentIdentity, Signature
+
+
+@runtime_checkable
+class Identity(Protocol):
+    """Agent identity, signing, and verification.
+
+    Example::
+
+        identity: Identity = DidKeyIdentity(agent_id)
+        sig = identity.sign(b"data")
+    """
+
+    def sign(self, payload: bytes) -> Signature:
+        """Sign a payload with this agent's private key.
+
+        Example::
+
+            sig = identity.sign(b"important data")
+        """
+        ...
+
+    def verify(self, payload: bytes, sig: Signature, agent: AgentId) -> bool:
+        """Verify a signature from a given agent.
+
+        Example::
+
+            ok = identity.verify(b"data", sig, AgentId("a2"))
+        """
+        ...
+
+    async def resolve(self, agent: AgentId) -> AgentIdentity:
+        """Resolve an agent ID to its full identity record.
+
+        Example::
+
+            info = await identity.resolve(AgentId("a2"))
+        """
+        ...

nest_core-0.1.0/nest_core/layers/memory.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Memory layer interface: shared state between agents.
+
+Example::
+
+    class MyMemory(Memory):
+        async def read(self, key):
+            return self._store.get(key)
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Memory(Protocol):
+    """Shared key-value state accessible to agents.
+
+    Example::
+
+        mem: Memory = Blackboard()
+        await mem.write("counter", b"42")
+    """
+
+    async def read(self, key: str) -> bytes | None:
+        """Read a value by key, returning None if absent.
+
+        Example::
+
+            val = await mem.read("counter")
+        """
+        ...
+
+    async def write(self, key: str, value: bytes) -> None:
+        """Write a value for a key.
+
+        Example::
+
+            await mem.write("counter", b"42")
+        """
+        ...
+
+    async def subscribe(self, key: str) -> AsyncIterator[bytes]:
+        """Subscribe to changes for a key.
+
+        Example::
+
+            async for val in mem.subscribe("counter"):
+                print(val)
+        """
+        ...
+
+    async def cas(self, key: str, expected: bytes, new: bytes) -> bool:
+        """Compare-and-swap: update only if the current value matches expected.
+
+        Example::
+
+            ok = await mem.cas("counter", b"42", b"43")
+        """
+        ...

nest_core-0.1.0/nest_core/layers/negotiation.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Negotiation layer interface: bargaining between agents over terms.
+
+Example::
+
+    class MyNegotiation(Negotiation):
+        async def open(self, partner, terms):
+            return NegotiationSession(id="n1", initiator=self._me, partner=partner)
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from nest_core.types import (
+    AgentId,
+    Agreement,
+    NegotiationResponse,
+    NegotiationSession,
+    Terms,
+)
+
+
+@runtime_checkable
+class Negotiation(Protocol):
+    """Bargaining protocol between two or more agents.
+
+    Example::
+
+        neg: Negotiation = AlternatingOffers(agent_id)
+        session = await neg.open(AgentId("a2"), Terms(price=Money(amount=100)))
+    """
+
+    async def open(self, partner: AgentId, terms: Terms) -> NegotiationSession:
+        """Open a negotiation session with initial terms.
+
+        Example::
+
+            session = await neg.open(AgentId("a2"), terms)
+        """
+        ...
+
+    async def offer(self, session: NegotiationSession, terms: Terms) -> None:
+        """Make an offer in an ongoing negotiation.
+
+        Example::
+
+            await neg.offer(session, Terms(price=Money(amount=80)))
+        """
+        ...
+
+    async def respond(self, session: NegotiationSession) -> NegotiationResponse:
+        """Respond to the latest offer in a negotiation.
+
+        Example::
+
+            resp = await neg.respond(session)
+        """
+        ...
+
+    async def close(self, session: NegotiationSession) -> Agreement | None:
+        """Close a negotiation session, returning an agreement if reached.
+
+        Example::
+
+            agreement = await neg.close(session)
+        """
+        ...