nest-shell 0.1.0__py3-none-any.whl

nest_shell/__init__.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+"""NEST shell: Tier 2 LLM-backed reference agent."""
+
+__version__ = "0.1.0"
+
+from nest_shell.agent import ShellAgent as ShellAgent
+from nest_shell.agent import shell_marketplace_factory as shell_marketplace_factory
+from nest_shell.factories import shell_auction_factory as shell_auction_factory
+from nest_shell.factories import shell_consensus_factory as shell_consensus_factory
+from nest_shell.factories import shell_reputation_factory as shell_reputation_factory
+from nest_shell.factories import shell_supply_chain_factory as shell_supply_chain_factory
+from nest_shell.factories import shell_voting_factory as shell_voting_factory
+from nest_shell.llm import AnthropicBackend as AnthropicBackend
+from nest_shell.llm import LiteLLMBackend as LiteLLMBackend
+from nest_shell.llm import LLMBackend as LLMBackend
+from nest_shell.llm import MockLLMBackend as MockLLMBackend
+from nest_shell.llm import OpenAIBackend as OpenAIBackend
+from nest_shell.templates import AgentTemplate as AgentTemplate
+from nest_shell.templates import TemplateRegistry as TemplateRegistry

nest_shell/agent.py

@@ -0,0 +1,272 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tier 2 LLM-backed shell agent.
+
+Replaces hardcoded state-machine logic with LLM-driven decision making.
+The agent maintains a conversation history and asks the LLM what to do
+on each event.
+
+Example::
+
+    backend = MockLLMBackend()
+    agent = ShellAgent(AgentId("buyer-0"), role="buyer", backend=backend)
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any
+
+from nest_core.sim.agent import AgentContext, StateMachineAgent
+from nest_core.types import AgentId
+
+from nest_shell.llm import LLMBackend
+
+if TYPE_CHECKING:
+    from nest_shell.templates import AgentTemplate
+
+_DEFAULT_SYSTEM_PROMPT = """\
+You are an agent in a multi-agent marketplace simulation.
+Your role is: {role}
+
+When you receive a message, decide what action to take.
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- If you are a buyer, send buy requests to sellers.
+- If you are a seller, respond to buy requests with "sold:" or "reject:".
+- Always include the product and price in messages.
+- Format: buy:<product>:<price> or sold:<product>:<price> or reject:<product>:<min_price>
+"""
+
+
+def parse_action(response: str, sender: AgentId) -> dict[str, Any] | None:
+    """Parse an LLM response into an action dict.
+
+    Example::
+
+        action = parse_action("ACTION: send\\nTO: seller-0\\nMESSAGE: buy:p:50", sender)
+    """
+    response = response.strip()
+
+    action_match = re.search(r"ACTION:\s*(\w+)", response)
+    if not action_match:
+        return None
+
+    action_type = action_match.group(1).lower()
+    if action_type == "none":
+        return None
+
+    if action_type == "send":
+        to_match = re.search(r"TO:\s*(.+)", response)
+        msg_match = re.search(r"MESSAGE:\s*(.+)", response)
+
+        if not msg_match:
+            return None
+
+        target_str = to_match.group(1).strip() if to_match else str(sender)
+        target_str = target_str.replace("{sender}", str(sender))
+
+        message = msg_match.group(1).strip()
+        message = message.replace("{sender}", str(sender))
+
+        return {
+            "action": "send",
+            "to": AgentId(target_str),
+            "message": message.encode("utf-8"),
+        }
+
+    return None
+
+
+class ShellAgent(StateMachineAgent):
+    """LLM-backed agent that uses a language model to decide actions.
+
+    Example::
+
+        agent = ShellAgent(
+            agent_id=AgentId("buyer-0"),
+            role="buyer",
+            backend=MockLLMBackend(),
+        )
+    """
+
+    def __init__(
+        self,
+        agent_id: AgentId,
+        role: str,
+        backend: LLMBackend,
+        system_prompt: str | None = None,
+        num_sellers: int = 10,
+        rounds: int = 10,
+        template: AgentTemplate | None = None,
+    ) -> None:
+        self._id = agent_id
+        self._role = role
+        self._backend = backend
+        if template is not None:
+            self._system_prompt = template.system_prompt
+        else:
+            self._system_prompt = (system_prompt or _DEFAULT_SYSTEM_PROMPT).format(role=role)
+        self._history: list[dict[str, str]] = [
+            {"role": "system", "content": self._system_prompt},
+        ]
+        self._num_sellers = num_sellers
+        self._rounds = rounds
+        self._round = 0
+        self._action_count = 0
+
+    async def on_start(self, ctx: AgentContext) -> None:
+        if self._role == "buyer":
+            seller_idx = ctx.rng.randint(0, self._num_sellers - 1)
+            seller = AgentId(f"seller-{seller_idx}")
+            price = ctx.rng.randint(10, 100)
+
+            self._history.append(
+                {
+                    "role": "user",
+                    "content": f"Simulation started. You are {self._id}. "
+                    f"Send a buy request to a seller. "
+                    f"Suggested target: {seller}, suggested price: {price}.",
+                }
+            )
+
+            response = await self._backend.complete(self._history)
+            self._history.append({"role": "assistant", "content": response})
+
+            action = parse_action(response, seller)
+            if action and action["action"] == "send":
+                await ctx.send(action["to"], action["message"])
+                self._action_count += 1
+            else:
+                await ctx.send(seller, f"buy:product-0:{price}".encode())
+                self._action_count += 1
+
+    async def on_message(self, ctx: AgentContext, sender: AgentId, payload: bytes) -> None:
+        msg = payload.decode("utf-8", errors="replace")
+        self._round += 1
+
+        if self._round > self._rounds:
+            return
+
+        self._history.append(
+            {
+                "role": "user",
+                "content": f"Message from {sender}: {msg}",
+            }
+        )
+
+        if len(self._history) > 20:
+            self._history = [self._history[0]] + self._history[-18:]
+
+        response = await self._backend.complete(self._history)
+        self._history.append({"role": "assistant", "content": response})
+
+        action = parse_action(response, sender)
+        if action and action["action"] == "send":
+            await ctx.send(action["to"], action["message"])
+            self._action_count += 1
+
+    @property
+    def action_count(self) -> int:
+        return self._action_count
+
+    @property
+    def history_length(self) -> int:
+        return len(self._history)
+
+
+def _resolve_template(
+    config: Any,
+    role: str,
+    scenario: str,
+) -> AgentTemplate | None:
+    """Resolve a template for a given role, if configured.
+
+    Example::
+
+        tpl = _resolve_template(config, "buyer", "marketplace")
+    """
+    template_name: str = getattr(config.agents, "template", "")
+    if not template_name:
+        return None
+
+    from nest_shell.templates import TemplateRegistry
+
+    registry = TemplateRegistry()
+
+    if template_name == "auto":
+        try:
+            return registry.get_template(f"{scenario}-{role}")
+        except KeyError:
+            return None
+    try:
+        return registry.get_template(template_name)
+    except KeyError:
+        return None
+
+
+def shell_marketplace_factory(
+    config: Any,
+    plugins: dict[str, Any],
+    backend: LLMBackend | None = None,
+) -> dict[AgentId, StateMachineAgent]:
+    """Create shell agents for the marketplace scenario.
+
+    Example::
+
+        agents = shell_marketplace_factory(config, plugins, backend=MockLLMBackend())
+    """
+    from nest_shell.llm import MockLLMBackend
+
+    if backend is None:
+        backend = MockLLMBackend()
+
+    task_config = config.task.config
+    rounds = task_config.get("rounds", 10)
+
+    agents: dict[AgentId, StateMachineAgent] = {}
+
+    if config.agents.roles:
+        buyer_count = 0
+        seller_count = 0
+        for role in config.agents.roles:
+            if role.name == "buyer":
+                buyer_count = role.count
+            elif role.name == "seller":
+                seller_count = role.count
+    else:
+        buyer_count = config.agents.count // 2
+        seller_count = config.agents.count - buyer_count
+
+    for i in range(seller_count):
+        aid = AgentId(f"seller-{i}")
+        tpl = _resolve_template(config, "seller", "marketplace")
+        agents[aid] = ShellAgent(
+            agent_id=aid,
+            role="seller",
+            backend=backend,
+            num_sellers=seller_count,
+            rounds=rounds,
+            template=tpl,
+        )
+
+    for i in range(buyer_count):
+        aid = AgentId(f"buyer-{i}")
+        tpl = _resolve_template(config, "buyer", "marketplace")
+        agents[aid] = ShellAgent(
+            agent_id=aid,
+            role="buyer",
+            backend=backend,
+            num_sellers=seller_count,
+            rounds=rounds,
+            template=tpl,
+        )
+
+    return agents

nest_shell/factories.py

@@ -0,0 +1,632 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shell agent factories for auction, voting, consensus, supply-chain, and reputation scenarios.
+
+These factories create LLM-backed :class:`ShellAgent` instances with
+scenario-appropriate system prompts so users can set ``brain: llm``
+in their YAML files.
+
+Example::
+
+    agents = shell_auction_factory(config, plugins, backend=MockLLMBackend())
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from nest_core.scenario import ScenarioConfig
+from nest_core.sim.agent import StateMachineAgent
+from nest_core.types import AgentId
+
+from nest_shell.agent import ShellAgent, _resolve_template  # pyright: ignore[reportPrivateUsage]
+from nest_shell.llm import LLMBackend
+
+_AUCTION_AUCTIONEER_PROMPT = """\
+You are an auctioneer in a multi-agent auction simulation.
+Your role is: auctioneer
+
+When the simulation starts, announce an item for auction to all bidders.
+When you receive bids, track them and pick the highest bidder.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- Announce items with format: auction:<item>:<base_price>
+- When all bids arrive, notify the winner with: won:<item>:<price>
+- Notify losers with: lost:<item>:<winning_price>
+- Start new rounds after announcing results.
+"""
+
+_AUCTION_BIDDER_PROMPT = """\
+You are a bidder in a multi-agent auction simulation.
+Your role is: bidder
+
+When you receive an auction announcement, decide how much to bid.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- When you see auction:<item>:<base_price>, respond with bid:<item>:<your_bid>
+- Your bid should be at or above the base price but within your budget.
+- If you win, you receive won:<item>:<price>. If you lose, you receive lost:<item>:<price>.
+"""
+
+_VOTING_PROPOSER_PROMPT = """\
+You are a proposer in a multi-agent voting simulation.
+Your role is: proposer
+
+You propose topics for voters to vote on.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- Propose topics with format: propose:<round>:<topic>
+- When you receive result:<round>:<outcome>:<tally>, start a new round.
+- Topics can be: increase-budget, new-policy, elect-leader.
+"""
+
+_VOTING_VOTER_PROMPT = """\
+You are a voter in a multi-agent voting simulation.
+Your role is: voter
+
+When you receive a proposal, cast your vote.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- When you see propose:<round>:<topic>, respond with vote:<round>:<yes_or_no>:<your_id>
+- Send your vote to the coordinator (coordinator-0).
+- Vote yes or no based on the topic.
+"""
+
+_VOTING_COORDINATOR_PROMPT = """\
+You are a coordinator in a multi-agent voting simulation.
+Your role is: coordinator
+
+You tally votes and announce results.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- Collect vote:<round>:<yes_or_no>:<voter_id> messages from voters.
+- When all votes arrive, announce result:<round>:<passed_or_rejected>:<tally> to the proposer.
+"""
+
+
+def shell_auction_factory(
+    config: ScenarioConfig,
+    plugins: dict[str, Any],
+    backend: LLMBackend | None = None,
+) -> dict[AgentId, StateMachineAgent]:
+    """Create shell agents for the auction scenario.
+
+    Example::
+
+        agents = shell_auction_factory(config, plugins, backend=MockLLMBackend())
+    """
+    from nest_shell.llm import MockLLMBackend
+
+    if backend is None:
+        backend = MockLLMBackend()
+
+    task_config = config.task.config
+    rounds = task_config.get("rounds", 5)
+
+    agents: dict[AgentId, StateMachineAgent] = {}
+
+    if config.agents.roles:
+        bidder_count = 0
+        for role in config.agents.roles:
+            if role.name == "bidder":
+                bidder_count = role.count
+        if bidder_count == 0:
+            bidder_count = config.agents.count - 1
+    else:
+        bidder_count = config.agents.count - 1
+
+    auctioneer_id = AgentId("auctioneer-0")
+    tpl = _resolve_template(config, "auctioneer", "auction")
+    agents[auctioneer_id] = ShellAgent(
+        agent_id=auctioneer_id,
+        role="auctioneer",
+        backend=backend,
+        system_prompt=_AUCTION_AUCTIONEER_PROMPT,
+        num_sellers=bidder_count,
+        rounds=rounds,
+        template=tpl,
+    )
+
+    for i in range(bidder_count):
+        aid = AgentId(f"bidder-{i}")
+        tpl = _resolve_template(config, "bidder", "auction")
+        agents[aid] = ShellAgent(
+            agent_id=aid,
+            role="bidder",
+            backend=backend,
+            system_prompt=_AUCTION_BIDDER_PROMPT,
+            num_sellers=bidder_count,
+            rounds=rounds,
+            template=tpl,
+        )
+
+    return agents
+
+
+def shell_voting_factory(
+    config: ScenarioConfig,
+    plugins: dict[str, Any],
+    backend: LLMBackend | None = None,
+) -> dict[AgentId, StateMachineAgent]:
+    """Create shell agents for the voting scenario.
+
+    Example::
+
+        agents = shell_voting_factory(config, plugins, backend=MockLLMBackend())
+    """
+    from nest_shell.llm import MockLLMBackend
+
+    if backend is None:
+        backend = MockLLMBackend()
+
+    task_config = config.task.config
+    rounds = task_config.get("rounds", 3)
+
+    agents: dict[AgentId, StateMachineAgent] = {}
+
+    if config.agents.roles:
+        voter_count = 0
+        for role in config.agents.roles:
+            if role.name == "voter":
+                voter_count = role.count
+        if voter_count == 0:
+            voter_count = max(1, config.agents.count - 2)
+    else:
+        voter_count = max(1, config.agents.count - 2)
+
+    proposer_id = AgentId("proposer-0")
+    coordinator_id = AgentId("coordinator-0")
+
+    tpl_proposer = _resolve_template(config, "proposer", "voting")
+    agents[proposer_id] = ShellAgent(
+        agent_id=proposer_id,
+        role="proposer",
+        backend=backend,
+        system_prompt=_VOTING_PROPOSER_PROMPT,
+        num_sellers=voter_count,
+        rounds=rounds,
+        template=tpl_proposer,
+    )
+    tpl_coord = _resolve_template(config, "coordinator", "voting")
+    agents[coordinator_id] = ShellAgent(
+        agent_id=coordinator_id,
+        role="coordinator",
+        backend=backend,
+        system_prompt=_VOTING_COORDINATOR_PROMPT,
+        num_sellers=voter_count,
+        rounds=rounds,
+        template=tpl_coord,
+    )
+
+    for i in range(voter_count):
+        aid = AgentId(f"voter-{i}")
+        tpl_voter = _resolve_template(config, "voter", "voting")
+        agents[aid] = ShellAgent(
+            agent_id=aid,
+            role="voter",
+            backend=backend,
+            system_prompt=_VOTING_VOTER_PROMPT,
+            num_sellers=voter_count,
+            rounds=rounds,
+            template=tpl_voter,
+        )
+
+    return agents
+
+
+# ---------------------------------------------------------------------------
+# Consensus
+# ---------------------------------------------------------------------------
+
+_CONSENSUS_LEADER_PROMPT = """\
+You are a leader in a quorum-based consensus simulation.
+Your role is: leader
+
+Propose values to followers and collect their votes.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- Propose values with format: propose:<round>:<value>
+- Collect vote:<round>:<accept_or_reject> from followers.
+- When all votes arrive, announce result:<round>:<committed_or_aborted>:<tally>.
+"""
+
+_CONSENSUS_FOLLOWER_PROMPT = """\
+You are a follower in a quorum-based consensus simulation.
+Your role is: follower
+
+Vote on proposals from the leader.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- When you see propose:<round>:<value>, respond with vote:<round>:<accept_or_reject>.
+- Send your vote to the leader (leader-0).
+"""
+
+
+def shell_consensus_factory(
+    config: ScenarioConfig,
+    plugins: dict[str, Any],
+    backend: LLMBackend | None = None,
+) -> dict[AgentId, StateMachineAgent]:
+    """Create shell agents for the consensus scenario.
+
+    Example::
+
+        agents = shell_consensus_factory(config, plugins, backend=MockLLMBackend())
+    """
+    from nest_shell.llm import MockLLMBackend
+
+    if backend is None:
+        backend = MockLLMBackend()
+
+    task_config = config.task.config
+    rounds = task_config.get("rounds", 5)
+
+    agents: dict[AgentId, StateMachineAgent] = {}
+
+    if config.agents.roles:
+        follower_count = 0
+        for role in config.agents.roles:
+            if role.name == "follower":
+                follower_count = role.count
+        if follower_count == 0:
+            follower_count = config.agents.count - 1
+    else:
+        follower_count = config.agents.count - 1
+
+    leader_id = AgentId("leader-0")
+    tpl_leader = _resolve_template(config, "leader", "consensus")
+    agents[leader_id] = ShellAgent(
+        agent_id=leader_id,
+        role="leader",
+        backend=backend,
+        system_prompt=_CONSENSUS_LEADER_PROMPT,
+        num_sellers=follower_count,
+        rounds=rounds,
+        template=tpl_leader,
+    )
+
+    for i in range(follower_count):
+        aid = AgentId(f"follower-{i}")
+        tpl_follower = _resolve_template(config, "follower", "consensus")
+        agents[aid] = ShellAgent(
+            agent_id=aid,
+            role="follower",
+            backend=backend,
+            system_prompt=_CONSENSUS_FOLLOWER_PROMPT,
+            num_sellers=follower_count,
+            rounds=rounds,
+            template=tpl_follower,
+        )
+
+    return agents
+
+
+# ---------------------------------------------------------------------------
+# Supply-chain
+# ---------------------------------------------------------------------------
+
+_SUPPLY_CHAIN_SUPPLIER_PROMPT = """\
+You are a supplier in a multi-hop supply-chain simulation.
+Your role is: supplier
+
+Produce raw materials and send them to manufacturers.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- Send materials with format: material:<round>:<batch_id>
+- Your target is manufacturer-0.
+"""
+
+_SUPPLY_CHAIN_MFG_PROMPT = """\
+You are a manufacturer in a multi-hop supply-chain simulation.
+Your role is: manufacturer
+
+Receive materials, produce goods, and send to distributors.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- When you receive material:<round>:<batch>, produce and send product:<round>:<product_id>.
+- Your target is distributor-0.
+"""
+
+_SUPPLY_CHAIN_DIST_PROMPT = """\
+You are a distributor in a multi-hop supply-chain simulation.
+Your role is: distributor
+
+Receive goods and forward shipments to retailers.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- When you receive product:<round>:<product>, forward as shipment:<round>:<product>.
+- Your target is retailer-0.
+"""
+
+_SUPPLY_CHAIN_RETAILER_PROMPT = """\
+You are a retailer in a multi-hop supply-chain simulation.
+Your role is: retailer
+
+Receive goods and report delivery back to the supplier.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- When you receive shipment:<round>:<product>, report delivered:<round>:<product>.
+- Your target is supplier-0.
+"""
+
+
+def shell_supply_chain_factory(
+    config: ScenarioConfig,
+    plugins: dict[str, Any],
+    backend: LLMBackend | None = None,
+) -> dict[AgentId, StateMachineAgent]:
+    """Create shell agents for the supply-chain scenario.
+
+    Example::
+
+        agents = shell_supply_chain_factory(config, plugins, backend=MockLLMBackend())
+    """
+    from nest_shell.llm import MockLLMBackend
+
+    if backend is None:
+        backend = MockLLMBackend()
+
+    task_config = config.task.config
+    rounds = task_config.get("rounds", 3)
+
+    agents: dict[AgentId, StateMachineAgent] = {}
+
+    for role_name, prompt in [
+        ("supplier", _SUPPLY_CHAIN_SUPPLIER_PROMPT),
+        ("manufacturer", _SUPPLY_CHAIN_MFG_PROMPT),
+        ("distributor", _SUPPLY_CHAIN_DIST_PROMPT),
+        ("retailer", _SUPPLY_CHAIN_RETAILER_PROMPT),
+    ]:
+        aid = AgentId(f"{role_name}-0")
+        tpl_sc = _resolve_template(config, role_name, "supply-chain")
+        agents[aid] = ShellAgent(
+            agent_id=aid,
+            role=role_name,
+            backend=backend,
+            system_prompt=prompt,
+            num_sellers=1,
+            rounds=rounds,
+            template=tpl_sc,
+        )
+
+    return agents
+
+
+# ---------------------------------------------------------------------------
+# Reputation
+# ---------------------------------------------------------------------------
+
+_REPUTATION_HONEST_PROMPT = """\
+You are an honest trader in a reputation simulation.
+Your role is: honest
+
+Always deliver on trades and report bad actors.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- Initiate trades with format: trade:<round>:<your_id>
+- Always respond to trades with: deliver:<round>:<your_id>
+- Report outcomes to observer-0 with: report:<round>:<agent>:<good_or_bad>
+"""
+
+_REPUTATION_MALICIOUS_PROMPT = """\
+You are a malicious trader in a reputation simulation.
+Your role is: malicious
+
+Sometimes cheat on trades to game the system.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- Initiate trades with format: trade:<round>:<your_id>
+- Sometimes respond with: cheat:<round>:<your_id> instead of delivering.
+- You may also deliver honestly to build reputation.
+"""
+
+_REPUTATION_OBSERVER_PROMPT = """\
+You are an observer in a reputation simulation.
+Your role is: observer
+
+Track reputation scores and broadcast warnings about bad actors.
+
+Respond in this exact format:
+
+ACTION: send
+TO: <agent-id>
+MESSAGE: <message-content>
+
+Or if no action is needed:
+ACTION: none
+
+Rules:
+- Collect report:<round>:<agent>:<good_or_bad> messages.
+- Track scores: +1 for good, -2 for bad.
+- When an agent's score drops to -3 or below, broadcast warning:<round>:<agent>:untrusted.
+"""
+
+
+def shell_reputation_factory(
+    config: ScenarioConfig,
+    plugins: dict[str, Any],
+    backend: LLMBackend | None = None,
+) -> dict[AgentId, StateMachineAgent]:
+    """Create shell agents for the reputation scenario.
+
+    Example::
+
+        agents = shell_reputation_factory(config, plugins, backend=MockLLMBackend())
+    """
+    from nest_shell.llm import MockLLMBackend
+
+    if backend is None:
+        backend = MockLLMBackend()
+
+    task_config = config.task.config
+    rounds = task_config.get("rounds", 5)
+    malicious_fraction = task_config.get("malicious_fraction", 0.2)
+
+    agents: dict[AgentId, StateMachineAgent] = {}
+
+    trader_count = config.agents.count - 1
+    malicious_count = max(1, int(trader_count * malicious_fraction))
+    honest_count = trader_count - malicious_count
+
+    if config.agents.roles:
+        for role in config.agents.roles:
+            if role.name == "honest":
+                honest_count = role.count
+            elif role.name == "malicious":
+                malicious_count = role.count
+
+    observer_id = AgentId("observer-0")
+    tpl_obs = _resolve_template(config, "observer", "reputation")
+    agents[observer_id] = ShellAgent(
+        agent_id=observer_id,
+        role="observer",
+        backend=backend,
+        system_prompt=_REPUTATION_OBSERVER_PROMPT,
+        num_sellers=honest_count + malicious_count,
+        rounds=rounds,
+        template=tpl_obs,
+    )
+
+    for i in range(honest_count):
+        aid = AgentId(f"honest-{i}")
+        tpl_honest = _resolve_template(config, "honest", "reputation")
+        agents[aid] = ShellAgent(
+            agent_id=aid,
+            role="honest",
+            backend=backend,
+            system_prompt=_REPUTATION_HONEST_PROMPT,
+            num_sellers=honest_count + malicious_count,
+            rounds=rounds,
+            template=tpl_honest,
+        )
+
+    for i in range(malicious_count):
+        aid = AgentId(f"malicious-{i}")
+        tpl_mal = _resolve_template(config, "malicious", "reputation")
+        agents[aid] = ShellAgent(
+            agent_id=aid,
+            role="malicious",
+            backend=backend,
+            system_prompt=_REPUTATION_MALICIOUS_PROMPT,
+            num_sellers=honest_count + malicious_count,
+            rounds=rounds,
+            template=tpl_mal,
+        )
+
+    return agents

nest_shell/llm.py

@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: Apache-2.0
+"""LLM backend abstraction for shell agents.
+
+Example::
+
+    backend = OpenAIBackend(model="gpt-4o-mini")
+    response = await backend.complete(messages)
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LLMBackend(Protocol):
+    """Protocol for LLM completion backends.
+
+    Example::
+
+        class MyBackend:
+            async def complete(self, messages):
+                return "I'll buy that for 50 credits."
+    """
+
+    async def complete(self, messages: list[dict[str, str]]) -> str:
+        """Send messages to the LLM and return the assistant response text.
+
+        Example::
+
+            response = await backend.complete([{"role": "user", "content": "hello"}])
+        """
+        ...
+
+
+class OpenAIBackend:
+    """LLM backend using the OpenAI SDK.
+
+    Reads API key from ``OPENAI_API_KEY`` environment variable.
+
+    Example::
+
+        backend = OpenAIBackend(model="gpt-4o-mini", temperature=0.7)
+        response = await backend.complete(messages)
+    """
+
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        temperature: float = 0.7,
+        max_tokens: int = 256,
+        api_key: str | None = None,
+    ) -> None:
+        self._model = model
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+        self._api_key = api_key  # None = use env var
+
+    async def complete(self, messages: list[dict[str, str]]) -> str:
+        import openai  # pyright: ignore[reportMissingModuleSource]
+
+        client = openai.AsyncOpenAI(  # pyright: ignore[reportUnknownMemberType]
+            api_key=self._api_key,
+        )
+        response = await client.chat.completions.create(  # pyright: ignore[reportUnknownMemberType]
+            model=self._model,
+            messages=messages,  # pyright: ignore[reportArgumentType]
+            temperature=self._temperature,
+            max_tokens=self._max_tokens,
+        )
+        content: str = response.choices[0].message.content or ""  # pyright: ignore[reportUnknownMemberType]
+        return content
+
+
+class AnthropicBackend:
+    """LLM backend using the Anthropic SDK.
+
+    Reads API key from ``ANTHROPIC_API_KEY`` environment variable.
+
+    Example::
+
+        backend = AnthropicBackend(model="claude-sonnet-4-20250514")
+        response = await backend.complete(messages)
+    """
+
+    def __init__(
+        self,
+        model: str = "claude-sonnet-4-20250514",
+        temperature: float = 0.7,
+        max_tokens: int = 256,
+        api_key: str | None = None,
+    ) -> None:
+        self._model = model
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+        self._api_key = api_key
+
+    async def complete(self, messages: list[dict[str, str]]) -> str:
+        import anthropic  # pyright: ignore[reportMissingImports]
+
+        client = anthropic.AsyncAnthropic(  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType]
+            api_key=self._api_key,
+        )
+        # Extract system message; Anthropic requires it as a separate parameter.
+        system = ""
+        chat_messages: list[dict[str, str]] = []
+        for m in messages:
+            if m["role"] == "system":
+                system = m["content"]
+            else:
+                chat_messages.append(m)
+        response: object = await client.messages.create(  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType]
+            model=self._model,
+            system=system,
+            messages=chat_messages,
+            temperature=self._temperature,
+            max_tokens=self._max_tokens,
+        )
+        content_blocks: list[object] = getattr(response, "content", [])  # pyright: ignore[reportUnknownArgumentType]
+        block: object = content_blocks[0] if content_blocks else None
+        return str(getattr(block, "text", "")) if block else ""
+
+
+class LiteLLMBackend:
+    """LLM backend using litellm for multi-provider support.
+
+    .. deprecated::
+        Use :class:`OpenAIBackend` or :class:`AnthropicBackend` instead.
+
+    Example::
+
+        backend = LiteLLMBackend(model="gpt-4o-mini", temperature=0.7)
+        response = await backend.complete(messages)
+    """
+
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        temperature: float = 0.7,
+        max_tokens: int = 256,
+    ) -> None:
+        warnings.warn(
+            "LiteLLMBackend is deprecated; use OpenAIBackend or AnthropicBackend instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self._model = model
+        self._temperature = temperature
+        self._max_tokens = max_tokens
+
+    async def complete(self, messages: list[dict[str, str]]) -> str:
+        import litellm  # pyright: ignore[reportUnknownVariableType]
+
+        response = await litellm.acompletion(  # pyright: ignore[reportUnknownMemberType]
+            model=self._model,
+            messages=messages,
+            temperature=self._temperature,
+            max_tokens=self._max_tokens,
+        )
+        choices: list[object] = getattr(response, "choices", [])
+        if choices:
+            msg: object = getattr(choices[0], "message", None)
+            content: str = str(getattr(msg, "content", "") or "") if msg else ""
+            return content
+        return ""
+
+
+class MockLLMBackend:
+    """Deterministic mock backend for testing without API keys.
+
+    Returns canned responses based on simple keyword matching.
+
+    Example::
+
+        backend = MockLLMBackend()
+        response = await backend.complete([{"role": "user", "content": "buy request"}])
+    """
+
+    def __init__(self, responses: dict[str, str] | None = None) -> None:
+        self._responses = responses or {}
+        self._call_count = 0
+
+    @property
+    def call_count(self) -> int:
+        return self._call_count
+
+    async def complete(self, messages: list[dict[str, str]]) -> str:
+        self._call_count += 1
+        last_msg = messages[-1]["content"] if messages else ""
+
+        for keyword, response in self._responses.items():
+            if keyword in last_msg:
+                return response
+
+        if "buy:" in last_msg or "purchase" in last_msg.lower():
+            return "ACTION: send\nTO: {sender}\nMESSAGE: sold:product:50"
+        if "sold:" in last_msg:
+            return "ACTION: send\nTO: {sender}\nMESSAGE: buy:product-next:60"
+        if "reject:" in last_msg:
+            return "ACTION: send\nTO: {sender}\nMESSAGE: buy:product-retry:70"
+
+        return "ACTION: none"

nest_shell/templates.py

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Agent template management for NEST shell agents.
+
+Templates are YAML files that define how a Tier 2 (LLM-backed) agent behaves.
+Each template specifies the system prompt, provider, model, and behavior
+parameters.
+
+Example::
+
+    registry = TemplateRegistry()
+    template = registry.get_template("marketplace-buyer")
+    template.to_yaml(Path("my-buyer.yaml"))
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel
+
+
+class AgentTemplate(BaseModel):
+    """Schema for an agent template loaded from YAML.
+
+    Example::
+
+        template = AgentTemplate(
+            name="my-agent",
+            system_prompt="You are a helpful agent.",
+        )
+    """
+
+    name: str
+    description: str = ""
+    provider: str = "openai"
+    model: str = "gpt-4o-mini"
+    system_prompt: str
+    temperature: float = 0.7
+    max_tokens: int = 256
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> AgentTemplate:
+        """Load an agent template from a YAML file.
+
+        Example::
+
+            template = AgentTemplate.from_yaml("templates/agents/marketplace-buyer.yaml")
+        """
+        with Path(path).open() as f:
+            data: dict[str, object] = yaml.safe_load(f)  # type: ignore[assignment]
+        return cls.model_validate(data)
+
+    def to_yaml(self, path: str | Path) -> Path:
+        """Save the template to a YAML file.
+
+        Example::
+
+            saved = template.to_yaml("my-template.yaml")
+        """
+        out = Path(path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        data = self.model_dump()
+        with out.open("w") as f:
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+        return out
+
+
+def _builtin_templates_dir() -> Path:
+    """Return the path to the built-in templates/agents directory.
+
+    Searches relative to the nest_shell package and CWD.
+
+    Example::
+
+        d = _builtin_templates_dir()
+    """
+    # Relative to the nest_shell package: ../../templates/agents
+    pkg_dir = Path(__file__).resolve().parent
+    for ancestor in [
+        pkg_dir.parent,
+        pkg_dir.parent.parent,
+        pkg_dir.parent.parent.parent,
+    ]:
+        candidate = ancestor / "templates" / "agents"
+        if candidate.is_dir():
+            return candidate
+
+    # Fall back to CWD
+    cwd_candidate = Path.cwd() / "templates" / "agents"
+    if cwd_candidate.is_dir():
+        return cwd_candidate
+
+    return cwd_candidate
+
+
+class TemplateRegistry:
+    """Discovers built-in and user templates.
+
+    Example::
+
+        registry = TemplateRegistry()
+        templates = registry.list_templates()
+    """
+
+    def __init__(self, user_dir: str | Path | None = None) -> None:
+        self._user_dir = Path(user_dir) if user_dir else None
+        self._builtin_dir = _builtin_templates_dir()
+
+    def _search_dirs(self) -> list[Path]:
+        """Return directories to search for templates, in priority order.
+
+        Example::
+
+            dirs = registry._search_dirs()
+        """
+        dirs: list[Path] = []
+        if self._user_dir and self._user_dir.is_dir():
+            dirs.append(self._user_dir)
+        if self._builtin_dir.is_dir():
+            dirs.append(self._builtin_dir)
+        return dirs
+
+    def list_templates(self) -> list[AgentTemplate]:
+        """List all available templates (user overrides first, then built-in).
+
+        Example::
+
+            templates = registry.list_templates()
+        """
+        seen: set[str] = set()
+        results: list[AgentTemplate] = []
+        for d in self._search_dirs():
+            for yaml_file in sorted(d.glob("*.yaml")):
+                try:
+                    tpl = AgentTemplate.from_yaml(yaml_file)
+                except Exception:  # noqa: BLE001
+                    continue
+                if tpl.name not in seen:
+                    seen.add(tpl.name)
+                    results.append(tpl)
+        return results
+
+    def get_template(self, name: str) -> AgentTemplate:
+        """Get a template by name.
+
+        Raises ``KeyError`` if not found.
+
+        Example::
+
+            tpl = registry.get_template("marketplace-buyer")
+        """
+        for d in self._search_dirs():
+            candidate = d / f"{name}.yaml"
+            if candidate.exists():
+                return AgentTemplate.from_yaml(candidate)
+        msg = f"Template not found: {name!r}"
+        raise KeyError(msg)
+
+    def save_template(self, template: AgentTemplate) -> Path:
+        """Save a template to the user directory.
+
+        Example::
+
+            path = registry.save_template(template)
+        """
+        target_dir = self._user_dir or (Path.cwd() / "templates" / "agents")
+        target_dir.mkdir(parents=True, exist_ok=True)
+        return template.to_yaml(target_dir / f"{template.name}.yaml")
+
+    def duplicate_template(self, name: str, new_name: str) -> AgentTemplate:
+        """Duplicate an existing template under a new name.
+
+        Example::
+
+            new_tpl = registry.duplicate_template("marketplace-buyer", "my-buyer")
+        """
+        original = self.get_template(name)
+        copy = original.model_copy(update={"name": new_name})
+        self.save_template(copy)
+        return copy

nest_shell-0.1.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: nest-shell
+Version: 0.1.0
+Summary: NEST shell: Tier 2 LLM-backed reference agent
+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
+Requires-Dist: openai>=1.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.30; extra == 'all'
+Requires-Dist: litellm>=1.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0; extra == 'litellm'
+Description-Content-Type: text/markdown
+
+# nest-shell
+
+NEST shell: Tier 2 LLM-backed reference agent
+
+Part of [NEST](https://github.com/mariagorskikh/nest) (Network Environment for Swarm Testing), built at MIT Media Lab.
+
+## Installation
+
+```bash
+pip install nest-shell
+```
+
+See the [main repository](https://github.com/mariagorskikh/nest) for full documentation.

nest_shell-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+nest_shell/__init__.py,sha256=ynXv-aCpbj0datxuv4qqIlEDy2SOaumsGMEVnJm1teA,1099
+nest_shell/agent.py,sha256=eFXgMwxYPin_8dG0dln5kTyJNStHwmOQYm9RCtp1GqA,7843
+nest_shell/factories.py,sha256=HCb5p_tnTweQzcrw3VhJseHJXteHHLh81pyC6XODJGI,16841
+nest_shell/llm.py,sha256=2WTmtfey4I0G7FPxcE6mG2MK12OwDgFaX0eoBTF5UnQ,6555
+nest_shell/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nest_shell/templates.py,sha256=RqU22ODAOJTb6ecSY6jVQ_QrImro18D2QCIsaii_w3g,5256
+nest_shell-0.1.0.dist-info/METADATA,sha256=3K7WSQR2cbebTqTjvRLbJXtm2PrK31-eQxzFBqhU-IU,1348
+nest_shell-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+nest_shell-0.1.0.dist-info/RECORD,,

nest_shell-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