npc-protocol 0.1.0__tar.gz

npc_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: npc-protocol
+Version: 0.1.0
+Summary: Python SDK for building NPC Protocol servers
+Project-URL: Homepage, https://github.com/macropulse/npc-protocol
+Project-URL: Documentation, https://github.com/macropulse/npc-protocol/tree/main/spec
+Project-URL: Repository, https://github.com/macropulse/npc-protocol
+Project-URL: Issues, https://github.com/macropulse/npc-protocol/issues
+License: Apache-2.0
+Keywords: agent,ai,mcp,npc,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# npc-protocol
+
+Python SDK for building [NPC Protocol](https://github.com/macropulse/npc-protocol) servers.
+
+**Stop selling APIs. Wrap yourself into an NPC and let it earn for you while you sleep.**
+
+---
+
+## What is NPC Protocol?
+
+NPC Protocol is an open standard for packaging domain knowledge as a "black box" agent service that AI agents can delegate to — in natural language, with persistent memory and explicit safety contracts. Built on top of MCP.
+
+> *Your coworker became a skill. Your ex became a skill. Now it's your turn.*
+
+## Install
+
+```bash
+pip install npc-protocol
+```
+
+## Quick Start
+
+```python
+from npc import NPCServer, NPCCard, NPCContext
+from npc.response import GateLevel
+
+card = NPCCard(
+    name="DNS Manager",
+    domain="DNS record management",
+    confirmation_gates=[
+        {"id": "delete_zone", "level": "destructive", "description": "Deleting a DNS zone"}
+    ],
+)
+
+npc = NPCServer(card=card)
+
+@npc.instruction_handler
+async def handle(instruction: str, session_id: str, ctx: NPCContext):
+    if "delete" in instruction.lower():
+        return ctx.require_confirmation(
+            gate_id="delete_zone",
+            gate_level=GateLevel.DESTRUCTIVE,
+            prompt="This will permanently delete the zone and all its records.",
+            protected_resources=[
+                {"type": "dns_zone", "name": "example.com", "risk": "All DNS records deleted"}
+            ],
+        )
+    return ctx.complete(result="DNS record updated")
+
+npc.run()
+```
+
+## Links
+
+- [Full spec and docs](https://github.com/macropulse/npc-protocol)
+- [NPC Card spec](https://github.com/macropulse/npc-protocol/blob/main/spec/npc-card.md)
+- [Confirmation Gates spec](https://github.com/macropulse/npc-protocol/blob/main/spec/confirmation-gate.md)
+
+## License
+
+Apache 2.0

npc_protocol-0.1.0/README.md

@@ -0,0 +1,61 @@
+# npc-protocol
+
+Python SDK for building [NPC Protocol](https://github.com/macropulse/npc-protocol) servers.
+
+**Stop selling APIs. Wrap yourself into an NPC and let it earn for you while you sleep.**
+
+---
+
+## What is NPC Protocol?
+
+NPC Protocol is an open standard for packaging domain knowledge as a "black box" agent service that AI agents can delegate to — in natural language, with persistent memory and explicit safety contracts. Built on top of MCP.
+
+> *Your coworker became a skill. Your ex became a skill. Now it's your turn.*
+
+## Install
+
+```bash
+pip install npc-protocol
+```
+
+## Quick Start
+
+```python
+from npc import NPCServer, NPCCard, NPCContext
+from npc.response import GateLevel
+
+card = NPCCard(
+    name="DNS Manager",
+    domain="DNS record management",
+    confirmation_gates=[
+        {"id": "delete_zone", "level": "destructive", "description": "Deleting a DNS zone"}
+    ],
+)
+
+npc = NPCServer(card=card)
+
+@npc.instruction_handler
+async def handle(instruction: str, session_id: str, ctx: NPCContext):
+    if "delete" in instruction.lower():
+        return ctx.require_confirmation(
+            gate_id="delete_zone",
+            gate_level=GateLevel.DESTRUCTIVE,
+            prompt="This will permanently delete the zone and all its records.",
+            protected_resources=[
+                {"type": "dns_zone", "name": "example.com", "risk": "All DNS records deleted"}
+            ],
+        )
+    return ctx.complete(result="DNS record updated")
+
+npc.run()
+```
+
+## Links
+
+- [Full spec and docs](https://github.com/macropulse/npc-protocol)
+- [NPC Card spec](https://github.com/macropulse/npc-protocol/blob/main/spec/npc-card.md)
+- [Confirmation Gates spec](https://github.com/macropulse/npc-protocol/blob/main/spec/confirmation-gate.md)
+
+## License
+
+Apache 2.0

npc_protocol-0.1.0/examples/swiftdeploy_case_study.md

@@ -0,0 +1,169 @@
+# SwiftDeploy — NPC Protocol Case Study
+
+[SwiftDeploy](https://swiftdeploy.ai) is a cloud infrastructure deployment service that independently converged on the NPC Protocol pattern before the spec was written. It is used here as the production reference implementation to demonstrate what a real-world NPC looks like at scale.
+
+---
+
+## NPC Card
+
+```json
+{
+  "npc_protocol_version": "0.1.0",
+  "name": "SwiftDeploy",
+  "version": "1.5.0",
+  "domain": "cloud infrastructure deployment and management on AWS",
+  "description": "Deploys, manages, and decommissions cloud infrastructure. Handles ECS, RDS, Redis, S3, ACM, Route53, and related services via OpenTofu (Terraform-compatible). Maintains project memory across sessions.",
+  "instruction_interface": "natural_language",
+  "capability_opacity": "opaque",
+  "session_model": "persistent",
+  "confirmation_gates": [
+    {
+      "id": "production_deploy",
+      "level": "required",
+      "description": "Deploying to a production environment (affects live traffic)"
+    },
+    {
+      "id": "decommission",
+      "level": "destructive",
+      "description": "Destroying all infrastructure for an environment, including stateful resources"
+    }
+  ],
+  "pricing_hints": {
+    "model": "credits",
+    "unit": "session",
+    "approximate_cost": "10-50 credits"
+  },
+  "contact": "https://swiftdeploy.ai",
+  "mcp_tools": ["execute", "get_status", "write_memory", "cancel_deployment"]
+}
+```
+
+Note that SwiftDeploy exposes additional tools beyond `execute` (`get_status`, `write_memory`, `cancel_deployment`). This is valid — the spec requires `execute` for natural language instructions but does not restrict additional tools.
+
+---
+
+## Interaction Trace: Full Deployment Flow
+
+This is a real interaction trace showing the NPC Protocol primitives in action.
+
+### Step 1: Calling agent reads the NPC Card
+
+```
+GET npc://card
+--> NPC Card JSON (above)
+```
+
+The calling agent now knows: domain is cloud infrastructure, session is persistent, two confirmation gates exist (production_deploy: required, decommission: destructive).
+
+### Step 2: Initial instruction
+
+```
+execute(instruction="deploy my app to staging with mysql and redis")
+--> {
+      "type": "in_progress",
+      "session_id": "sess_a1b2c3d4",
+      "message": "No infrastructure found for this project. Generating infrastructure plan first...",
+      "progress": { "step": "generating_infrastructure" }
+    }
+```
+
+The NPC detects that no infrastructure exists yet (reads project memory) and autonomously decides to generate it before deploying. The calling agent does not need to know this — it just sees `in_progress`.
+
+### Step 3: Polling for progress
+
+```
+get_status(project_id="...", environment="staging")
+--> {
+      "status": "deploying",
+      "current_step": "aws_ecs_service.app: Still creating...",
+      "elapsed_seconds": 87,
+      "recent_logs": [...]
+    }
+```
+
+### Step 4: Completion
+
+```
+get_status(project_id="...", environment="staging")
+--> {
+      "type": "completed",
+      "session_id": "sess_a1b2c3d4",
+      "result": "Staging environment deployed successfully",
+      "data": {
+        "app_url": "https://my-app-staging.app.swiftdeploy.ai",
+        "ecr_push_command": "docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:latest"
+      }
+    }
+```
+
+---
+
+## Interaction Trace: Decommission with Destructive Gate
+
+### Step 1: Instruction
+
+```
+execute(instruction="tear down the staging environment")
+--> {
+      "type": "needs_confirmation",
+      "session_id": "sess_x9y8z7w6",
+      "gate_id": "decommission",
+      "gate_level": "destructive",
+      "prompt": "This will permanently destroy all infrastructure for 'my-app' in staging.",
+      "protected_resources": [
+        {
+          "type": "aws_rds_instance",
+          "name": "my-app-staging-db",
+          "risk": "All database data will be permanently deleted"
+        },
+        {
+          "type": "aws_secretsmanager_secret",
+          "name": "my-app-staging-credentials",
+          "risk": "Credentials will be permanently deleted"
+        }
+      ]
+    }
+```
+
+The calling agent MUST show this full list to the human user. It cannot auto-confirm.
+
+### Step 2: Human confirms, calling agent relays
+
+```
+execute(instruction="yes, confirmed", session_id="sess_x9y8z7w6", confirm=true)
+--> {
+      "type": "completed",
+      "session_id": "sess_x9y8z7w6",
+      "result": "Staging environment decommissioned. All resources destroyed."
+    }
+```
+
+---
+
+## Memory Architecture
+
+SwiftDeploy uses all three memory tiers defined in the NPC Protocol session model:
+
+| Tier | What SwiftDeploy stores |
+|---|---|
+| **Ephemeral** | In-flight terraform plan, intermediate reasoning steps |
+| **Session** | Current deployment conversation: what was asked, what decisions were made, pending confirmations |
+| **Persistent** | Project memory: AWS account ID, architecture plan, deployment history, known issues, manual changes recorded via `write_memory` |
+
+The persistent memory is what enables the NPC to say things like "you already have an RDS instance from your last deployment — I'll reuse it" or "last time you deployed this, the Secrets Manager deletion window caused a 7-day delay — I'll handle that automatically this time."
+
+---
+
+## What Was Hard Without the Spec
+
+Before NPC Protocol named these patterns, SwiftDeploy had to:
+
+1. **Invent its own confirmation gate format** — the `needs_confirmation` / `needs_decommission_confirmation` response types were invented ad-hoc. Calling agents had to read SwiftDeploy-specific documentation to understand them.
+
+2. **Document its session model informally** — there was no standard way to communicate "I maintain persistent project memory" to a calling agent. This was buried in the skills file.
+
+3. **Explain `recovery_hint` as a custom convention** — the fact that every `failed` response includes a recovery hint was a SwiftDeploy design decision, not a known standard.
+
+4. **Define capability opacity without a term for it** — SwiftDeploy's `execute` tool intentionally doesn't expose its internal tool list, but there was no standard way to declare this. Calling agents sometimes tried to enumerate tools and got confused.
+
+NPC Protocol names all of these patterns and makes them discoverable via the NPC Card, so calling agents can handle them generically without reading NPC-specific documentation.

npc_protocol-0.1.0/npc/__init__.py

@@ -0,0 +1,73 @@
+"""
+NPC Protocol — Python SDK
+
+Build domain-expert agent services that AI agents can delegate to.
+
+Quick start:
+
+    from npc import NPCServer, NPCCard, NPCContext
+    from npc.response import GateLevel
+
+    card = NPCCard(
+        name="My NPC",
+        domain="describe what your NPC does",
+    )
+
+    npc = NPCServer(card=card)
+
+    @npc.instruction_handler
+    async def handle(instruction: str, session_id: str, ctx: NPCContext):
+        return ctx.complete(result="Done")
+
+    npc.run()
+"""
+
+from .card import (
+    CapabilityOpacity,
+    ConfirmationGateDeclaration,
+    InstructionInterface,
+    NPCCard,
+    PricingHints,
+    PricingModel,
+    SessionModelType,
+)
+from .context import NPCContext
+from .response import (
+    CompletedResponse,
+    FailedResponse,
+    GateLevel,
+    InProgressResponse,
+    NeedsConfirmationResponse,
+    NeedsInputResponse,
+    NPCResponse,
+    ProtectedResource,
+    ResponseType,
+)
+from .server import NPCServer
+from .session import InMemorySessionStore, SessionStore
+
+__version__ = "0.1.0"
+__all__ = [
+    "NPCServer",
+    "NPCCard",
+    "NPCContext",
+    "SessionStore",
+    "InMemorySessionStore",
+    # Response types
+    "NPCResponse",
+    "InProgressResponse",
+    "NeedsInputResponse",
+    "NeedsConfirmationResponse",
+    "CompletedResponse",
+    "FailedResponse",
+    "ProtectedResource",
+    # Enums
+    "ResponseType",
+    "GateLevel",
+    "InstructionInterface",
+    "CapabilityOpacity",
+    "SessionModelType",
+    "PricingModel",
+    "ConfirmationGateDeclaration",
+    "PricingHints",
+]

npc_protocol-0.1.0/npc/card.py

@@ -0,0 +1,87 @@
+"""
+NPC Card — the identity and capability declaration for an NPC server.
+
+Published as an MCP resource at npc://card.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class InstructionInterface(str, Enum):
+    NATURAL_LANGUAGE = "natural_language"
+    STRUCTURED = "structured"
+
+
+class CapabilityOpacity(str, Enum):
+    OPAQUE = "opaque"
+    TRANSPARENT = "transparent"
+
+
+class SessionModelType(str, Enum):
+    EPHEMERAL = "ephemeral"
+    SESSION = "session"
+    PERSISTENT = "persistent"
+
+
+class GateLevel(str, Enum):
+    ADVISORY = "advisory"
+    REQUIRED = "required"
+    DESTRUCTIVE = "destructive"
+
+
+class PricingModel(str, Enum):
+    CREDITS = "credits"
+    SUBSCRIPTION = "subscription"
+    PAY_PER_USE = "pay_per_use"
+    FREE = "free"
+
+
+class ConfirmationGateDeclaration(BaseModel):
+    id: str = Field(..., description="Machine-readable gate identifier")
+    level: GateLevel
+    description: str = Field(..., description="Human-readable explanation of when this gate triggers")
+
+
+class PricingHints(BaseModel):
+    model: PricingModel
+    unit: str = Field(..., description="Billing unit: session, instruction, token, minute")
+    approximate_cost: str | None = None
+    free_tier: str | None = None
+
+
+class NPCCard(BaseModel):
+    """
+    The NPC Card identifies an NPC server and declares its capabilities.
+    Published as an MCP resource at npc://card.
+    """
+
+    npc_protocol_version: str = Field(default="0.1.0", description="NPC Protocol spec version")
+    name: str = Field(..., description="Human-readable name of the NPC service")
+    domain: str = Field(..., description="Plain-language description of the domain this NPC covers")
+    instruction_interface: InstructionInterface = InstructionInterface.NATURAL_LANGUAGE
+    capability_opacity: CapabilityOpacity = CapabilityOpacity.OPAQUE
+    session_model: SessionModelType = SessionModelType.SESSION
+    mcp_tools: list[str] = Field(default_factory=lambda: ["execute"])
+
+    # Optional fields
+    version: str | None = None
+    description: str | None = None
+    confirmation_gates: list[ConfirmationGateDeclaration] = Field(default_factory=list)
+    pricing_hints: PricingHints | None = None
+    contact: str | None = None
+
+    def model_post_init(self, __context: Any) -> None:
+        # Enforce spec: natural_language NPCs must expose execute
+        if (
+            self.instruction_interface == InstructionInterface.NATURAL_LANGUAGE
+            and "execute" not in self.mcp_tools
+        ):
+            self.mcp_tools = ["execute", *self.mcp_tools]
+
+    def to_json(self) -> dict[str, Any]:
+        return self.model_dump(exclude_none=True)

npc_protocol-0.1.0/npc/context.py

@@ -0,0 +1,144 @@
+"""
+NPCContext — per-request context passed to instruction handlers.
+
+Provides helper methods to construct spec-compliant responses without
+manually building response dicts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .response import (
+    CompletedResponse,
+    FailedResponse,
+    GateLevel,
+    InProgressResponse,
+    NeedsConfirmationResponse,
+    NeedsInputResponse,
+    NPCResponse,
+    ProtectedResource,
+)
+from .session import SessionStore
+
+
+class NPCContext:
+    """
+    Context object injected into every instruction handler call.
+
+    Provides the current session state and helper methods for building
+    spec-compliant NPC Protocol responses.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        session_store: SessionStore,
+        session_data: dict[str, Any],
+    ) -> None:
+        self.session_id = session_id
+        self._store = session_store
+        self._data = session_data
+
+    # -- Session helpers --
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value from the current session data."""
+        return self._data.get(key, default)
+
+    async def set(self, key: str, value: Any) -> None:
+        """Persist a value to the current session."""
+        self._data[key] = value
+        await self._store.update(self.session_id, {key: value})
+
+    async def clear(self) -> None:
+        """Terminate the current session."""
+        await self._store.delete(self.session_id)
+
+    # -- Response builders --
+
+    def in_progress(
+        self,
+        message: str,
+        progress: dict[str, Any] | None = None,
+    ) -> NPCResponse:
+        return InProgressResponse(
+            session_id=self.session_id,
+            message=message,
+            progress=progress,
+        )
+
+    def needs_input(
+        self,
+        question: str,
+        options: list[str] | None = None,
+        message: str | None = None,
+    ) -> NPCResponse:
+        return NeedsInputResponse(
+            session_id=self.session_id,
+            question=question,
+            options=options,
+            message=message,
+        )
+
+    def require_confirmation(
+        self,
+        gate_id: str,
+        gate_level: GateLevel,
+        prompt: str,
+        details: dict[str, Any] | None = None,
+        protected_resources: list[dict[str, str]] | None = None,
+        message: str | None = None,
+    ) -> NPCResponse:
+        """
+        Emit a confirmation gate. The calling agent must resolve this before
+        the NPC can proceed.
+
+        For gate_level=DESTRUCTIVE, protected_resources should list all
+        resources that will be permanently affected.
+        """
+        resources = None
+        if protected_resources:
+            resources = [ProtectedResource(**r) for r in protected_resources]
+
+        return NeedsConfirmationResponse(
+            session_id=self.session_id,
+            gate_id=gate_id,
+            gate_level=gate_level,
+            prompt=prompt,
+            details=details,
+            protected_resources=resources,
+            message=message,
+        )
+
+    def complete(
+        self,
+        result: str,
+        data: dict[str, Any] | None = None,
+        message: str | None = None,
+    ) -> NPCResponse:
+        return CompletedResponse(
+            session_id=self.session_id,
+            result=result,
+            data=data,
+            message=message,
+        )
+
+    def fail(
+        self,
+        error: str,
+        recovery_hint: str,
+        retryable: bool = False,
+        message: str | None = None,
+    ) -> NPCResponse:
+        """
+        Return a failure response. recovery_hint is required by the NPC Protocol spec
+        and must always be a concrete, actionable instruction.
+        """
+        return FailedResponse(
+            session_id=self.session_id,
+            error=error,
+            recovery_hint=recovery_hint,
+            retryable=retryable,
+            message=message,
+        )

npc_protocol-0.1.0/npc/response.py

@@ -0,0 +1,74 @@
+"""
+Standard response types for NPC Protocol.
+
+All execute() calls return one of these response envelopes.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ResponseType(str, Enum):
+    IN_PROGRESS = "in_progress"
+    NEEDS_INPUT = "needs_input"
+    NEEDS_CONFIRMATION = "needs_confirmation"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class GateLevel(str, Enum):
+    ADVISORY = "advisory"
+    REQUIRED = "required"
+    DESTRUCTIVE = "destructive"
+
+
+class ProtectedResource(BaseModel):
+    type: str = Field(..., description="Resource type identifier (e.g. 'aws_rds_instance')")
+    name: str = Field(..., description="Resource name or identifier")
+    risk: str = Field(..., description="Human-readable description of what will be permanently lost")
+
+
+class NPCResponse(BaseModel):
+    type: ResponseType
+    session_id: str | None = None
+    message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(exclude_none=True)
+
+
+class InProgressResponse(NPCResponse):
+    type: ResponseType = ResponseType.IN_PROGRESS
+    progress: dict[str, Any] | None = None
+
+
+class NeedsInputResponse(NPCResponse):
+    type: ResponseType = ResponseType.NEEDS_INPUT
+    question: str
+    options: list[str] | None = None
+
+
+class NeedsConfirmationResponse(NPCResponse):
+    type: ResponseType = ResponseType.NEEDS_CONFIRMATION
+    gate_id: str
+    gate_level: GateLevel
+    prompt: str
+    details: dict[str, Any] | None = None
+    protected_resources: list[ProtectedResource] | None = None
+
+
+class CompletedResponse(NPCResponse):
+    type: ResponseType = ResponseType.COMPLETED
+    result: str
+    data: dict[str, Any] | None = None
+
+
+class FailedResponse(NPCResponse):
+    type: ResponseType = ResponseType.FAILED
+    error: str
+    recovery_hint: str  # Required by spec — always present on failed
+    retryable: bool = False

npc_protocol-0.1.0/npc/server.py

@@ -0,0 +1,197 @@
+"""
+NPCServer — the core class for building NPC Protocol servers.
+
+Wraps an MCP server and automatically:
+- Registers the NPC Card as an MCP resource at npc://card
+- Registers the execute tool with the standard NPC Protocol schema
+- Manages sessions via the provided SessionStore
+- Routes execute calls to the registered instruction handler
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    CallToolResult,
+    ReadResourceResult,
+    Resource,
+    TextContent,
+    TextResourceContents,
+    Tool,
+)
+
+from .card import NPCCard
+from .context import NPCContext
+from .response import FailedResponse, NPCResponse
+from .session import SessionStore
+
+# Type for the instruction handler function
+InstructionHandler = Callable[
+    [str, str, NPCContext],
+    Coroutine[Any, Any, NPCResponse],
+]
+
+
+class NPCServer:
+    """
+    An NPC Protocol server. Wraps an MCP server with protocol scaffolding.
+
+    Usage:
+
+        card = NPCCard(
+            name="My NPC",
+            domain="your domain description",
+        )
+
+        npc = NPCServer(card=card)
+
+        @npc.instruction_handler
+        async def handle(instruction: str, session_id: str, ctx: NPCContext) -> NPCResponse:
+            # Your domain logic here
+            return ctx.complete(result="Done")
+
+        npc.run()  # starts the MCP server on stdio
+    """
+
+    def __init__(
+        self,
+        card: NPCCard,
+        session_store: SessionStore | None = None,
+    ) -> None:
+        self.card = card
+        self._session_store = session_store or SessionStore.in_memory()
+        self._handler: InstructionHandler | None = None
+        self._mcp = Server(card.name)
+        self._register_mcp_handlers()
+
+    def instruction_handler(self, fn: InstructionHandler) -> InstructionHandler:
+        """Decorator to register the instruction handler for this NPC."""
+        self._handler = fn
+        return fn
+
+    def _register_mcp_handlers(self) -> None:
+        mcp = self._mcp
+
+        @mcp.list_resources()
+        async def list_resources() -> list[Resource]:
+            return [
+                Resource(
+                    uri="npc://card",
+                    name="NPC Card",
+                    description=f"Identity and capability declaration for {self.card.name}",
+                    mimeType="application/json",
+                )
+            ]
+
+        @mcp.read_resource()
+        async def read_resource(uri: str) -> ReadResourceResult:
+            if uri == "npc://card":
+                return ReadResourceResult(
+                    contents=[
+                        TextResourceContents(
+                            uri="npc://card",
+                            mimeType="application/json",
+                            text=json.dumps(self.card.to_json(), indent=2),
+                        )
+                    ]
+                )
+            raise ValueError(f"Unknown resource: {uri}")
+
+        @mcp.list_tools()
+        async def list_tools() -> list[Tool]:
+            tools = [
+                Tool(
+                    name="execute",
+                    description=(
+                        f"Send a natural language instruction to {self.card.name}. "
+                        f"Domain: {self.card.domain}"
+                    ),
+                    inputSchema={
+                        "type": "object",
+                        "required": ["instruction"],
+                        "properties": {
+                            "instruction": {
+                                "type": "string",
+                                "description": "A natural language instruction or reply",
+                            },
+                            "session_id": {
+                                "type": "string",
+                                "description": "Resume an existing session. Omit to start a new session.",
+                            },
+                            "confirm": {
+                                "type": "boolean",
+                                "description": "Confirmation reply to a needs_confirmation gate",
+                            },
+                            "choice": {
+                                "type": "string",
+                                "description": "Selection reply to a needs_input response with options",
+                            },
+                        },
+                    },
+                )
+            ]
+            return tools
+
+        @mcp.call_tool()
+        async def call_tool(name: str, arguments: dict[str, Any]) -> CallToolResult:
+            if name != "execute":
+                raise ValueError(f"Unknown tool: {name}")
+            return await self._handle_execute(arguments)
+
+    async def _handle_execute(self, arguments: dict[str, Any]) -> CallToolResult:
+        if self._handler is None:
+            raise RuntimeError("No instruction handler registered. Use @npc.instruction_handler.")
+
+        instruction = arguments.get("instruction", "")
+        session_id = arguments.get("session_id")
+
+        # Resolve or create session
+        if session_id and await self._session_store.exists(session_id):
+            session_data = (await self._session_store.get(session_id)) or {}
+        else:
+            session_id = await self._session_store.create(
+                data={
+                    "confirm": arguments.get("confirm"),
+                    "choice": arguments.get("choice"),
+                }
+            )
+            session_data = {}
+
+        ctx = NPCContext(
+            session_id=session_id,
+            session_store=self._session_store,
+            session_data=session_data,
+        )
+
+        try:
+            response: NPCResponse = await self._handler(instruction, session_id, ctx)
+        except Exception as e:
+            response = FailedResponse(
+                session_id=session_id,
+                error=str(e),
+                recovery_hint="An unexpected error occurred. Please try again or contact support.",
+            )
+
+        return CallToolResult(
+            content=[
+                TextContent(
+                    type="text",
+                    text=json.dumps(response.to_dict(), indent=2),
+                )
+            ]
+        )
+
+    def run(self) -> None:
+        """Start the NPC server using stdio transport (default MCP transport)."""
+        import asyncio
+
+        async def _run() -> None:
+            async with stdio_server() as (read_stream, write_stream):
+                await self._mcp.run(read_stream, write_stream, self._mcp.create_initialization_options())
+
+        asyncio.run(_run())

npc_protocol-0.1.0/npc/session.py

@@ -0,0 +1,109 @@
+"""
+Session store interface and built-in implementations.
+
+Sessions are NPC-owned. The calling agent only carries the opaque session_id token.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class SessionStore(ABC):
+    """
+    Abstract interface for NPC session storage.
+    Implement this to plug in Redis, a database, or any other backend.
+    """
+
+    @abstractmethod
+    async def create(self, data: dict[str, Any] | None = None) -> str:
+        """Create a new session and return its session_id."""
+        ...
+
+    @abstractmethod
+    async def get(self, session_id: str) -> dict[str, Any] | None:
+        """
+        Retrieve session data by session_id.
+        Returns None if the session does not exist or has expired.
+        """
+        ...
+
+    @abstractmethod
+    async def update(self, session_id: str, data: dict[str, Any]) -> bool:
+        """
+        Update session data. Returns False if the session does not exist.
+        """
+        ...
+
+    @abstractmethod
+    async def delete(self, session_id: str) -> bool:
+        """Terminate a session. Returns False if it did not exist."""
+        ...
+
+    @abstractmethod
+    async def exists(self, session_id: str) -> bool:
+        """Check whether a session exists and has not expired."""
+        ...
+
+    @classmethod
+    def in_memory(cls, ttl_seconds: int = 86400) -> "InMemorySessionStore":
+        """Factory: create an in-memory session store (default, suitable for development)."""
+        return InMemorySessionStore(ttl_seconds=ttl_seconds)
+
+
+class InMemorySessionStore(SessionStore):
+    """
+    Simple in-memory session store. Not suitable for production multi-process deployments.
+    Sessions expire after ttl_seconds of inactivity (default 24 hours).
+    """
+
+    def __init__(self, ttl_seconds: int = 86400) -> None:
+        self._store: dict[str, dict[str, Any]] = {}
+        self._ttl = ttl_seconds
+
+    def _is_expired(self, session: dict[str, Any]) -> bool:
+        return time.time() - session.get("_last_accessed", 0) > self._ttl
+
+    async def create(self, data: dict[str, Any] | None = None) -> str:
+        session_id = f"sess_{uuid.uuid4().hex[:16]}"
+        self._store[session_id] = {
+            **(data or {}),
+            "_created_at": time.time(),
+            "_last_accessed": time.time(),
+        }
+        return session_id
+
+    async def get(self, session_id: str) -> dict[str, Any] | None:
+        session = self._store.get(session_id)
+        if session is None:
+            return None
+        if self._is_expired(session):
+            del self._store[session_id]
+            return None
+        session["_last_accessed"] = time.time()
+        return {k: v for k, v in session.items() if not k.startswith("_")}
+
+    async def update(self, session_id: str, data: dict[str, Any]) -> bool:
+        if session_id not in self._store or self._is_expired(self._store[session_id]):
+            return False
+        self._store[session_id].update(data)
+        self._store[session_id]["_last_accessed"] = time.time()
+        return True
+
+    async def delete(self, session_id: str) -> bool:
+        if session_id in self._store:
+            del self._store[session_id]
+            return True
+        return False
+
+    async def exists(self, session_id: str) -> bool:
+        session = self._store.get(session_id)
+        if session is None:
+            return False
+        if self._is_expired(session):
+            del self._store[session_id]
+            return False
+        return True

npc_protocol-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "npc-protocol"
+version = "0.1.0"
+description = "Python SDK for building NPC Protocol servers"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+keywords = ["npc", "mcp", "agent", "protocol", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+redis = ["redis>=5.0.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/macropulse/npc-protocol"
+Documentation = "https://github.com/macropulse/npc-protocol/tree/main/spec"
+Repository = "https://github.com/macropulse/npc-protocol"
+Issues = "https://github.com/macropulse/npc-protocol/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["npc"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"