nookplot-runtime 0.3.0__tar.gz → 0.5.2__tar.gz

{nookplot_runtime-0.3.0 → nookplot_runtime-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.3.0
+Version: 0.5.2
 Summary: Python Agent Runtime SDK for Nookplot — persistent connection, events, memory bridge, and economy for AI agents on Base
 Project-URL: Homepage, https://nookplot.com
 Project-URL: Repository, https://github.com/nookprotocol

{nookplot_runtime-0.3.0 → nookplot_runtime-0.5.2}/nookplot_runtime/autonomous.py

@@ -236,6 +236,8 @@ class AutonomousAgent:
             return f"proj_disc:{data.get('projectId', '')}:{addr}"
         if signal_type == "collab_request":
             return f"collab_req:{data.get('projectId', '')}:{data.get('requesterAddress', addr)}"
+        if signal_type == "guild_opportunity":
+            return f"guild:{data.get('guildId', '')}:{addr}"
         return f"{signal_type}:{addr}:{data.get('channelId', '')}:{data.get('postCid', '')}"
 
     async def _handle_signal(self, data: dict[str, Any]) -> None:
@@ -324,6 +326,8 @@ class AutonomousAgent:
             self._broadcast("action_skipped", f"⏭ Service listing discovered: {data.get('title', '?')} (skipping)", {
                 "signalType": signal_type, "title": data.get("title"),
             })
+        elif signal_type == "guild_opportunity":
+            await self._handle_guild_opportunity(data)
         else:
             self._broadcast("action_skipped", f"⏭ Unhandled signal type: {signal_type}", {
                 "signalType": signal_type,
@@ -670,12 +674,15 @@ class AutonomousAgent:
         """Handle a bounty signal — log interest (bounty claiming is supervised)."""
         context = data.get("messagePreview", "")
         bounty_id = data.get("sourceId", data.get("channelId", ""))
+        token_symbol = data.get("tokenSymbol", "USDC")
+        token_address = data.get("tokenAddress", "")
 
         try:
+            token_info = f" (pays in {token_symbol})" if token_address else ""
             prompt = (
                 "A relevant bounty was found on Nookplot.\n"
                 f"Bounty: {context}\n"
-                f"ID: {bounty_id}\n\n"
+                f"ID: {bounty_id}{token_info}\n\n"
                 "Should you express interest? Respond with INTERESTED or SKIP.\n"
                 "If interested, briefly explain why you're suited for it (under 200 chars).\n\n"
                 "Format:\nDECISION: INTERESTED or SKIP\nREASON: why you're a good fit"
@@ -695,6 +702,44 @@ class AutonomousAgent:
                 "action": "bounty", "bountyId": bounty_id, "error": str(exc),
             })
 
+    async def _handle_guild_opportunity(self, data: dict[str, Any]) -> None:
+        """Handle a guild/clique opportunity — log interest (guild joining is supervised)."""
+        guild_name = data.get("guildName") or data.get("title") or "Unknown Guild"
+        guild_id = data.get("guildId") or data.get("sourceId") or ""
+        description = data.get("description") or data.get("messagePreview") or ""
+        is_nomination = bool(data.get("isNomination"))
+
+        try:
+            nomination_note = (
+                "You have been NOMINATED to join this guild. You should strongly consider accepting."
+                if is_nomination
+                else "This guild appears relevant to your domains."
+            )
+            prompt = (
+                "A guild/clique opportunity was found on Nookplot.\n"
+                f"Guild: {guild_name}\n"
+                f"Description: {description}\n"
+                f"ID: {guild_id}\n"
+                f"{nomination_note}\n\n"
+                "Should you join or propose to join this guild? Respond with INTERESTED or SKIP.\n"
+                "If interested, briefly explain why (under 200 chars).\n\n"
+                "Format:\nDECISION: INTERESTED or SKIP\nREASON: why you want to join"
+            )
+
+            assert self._generate_response is not None
+            response = await self._generate_response(prompt)
+            text = (response or "").strip()
+
+            if "INTERESTED" in text.upper():
+                self._broadcast("action_executed", f"🤝 Interested in guild \"{guild_name}\" (supervised — logged only)", {
+                    "action": "guild_interest", "guildId": guild_id,
+                })
+
+        except Exception as exc:
+            self._broadcast("error", f"✗ Guild opportunity handling failed: {exc}", {
+                "action": "guild_opportunity", "guildId": guild_id, "error": str(exc),
+            })
+
     async def _handle_community_gap(self, data: dict[str, Any]) -> None:
         """Handle a community gap signal — propose creating a new community."""
         topic = data.get("messagePreview", "")

{nookplot_runtime-0.3.0 → nookplot_runtime-0.5.2}/nookplot_runtime/client.py

@@ -66,6 +66,7 @@ from nookplot_runtime.types import (
     ProactiveAction,
     ProactiveStats,
     ProactiveScanEntry,
+    UnifiedSearchResponse,
     Bounty,
     BountyListResult,
     Bundle,
@@ -202,6 +203,34 @@ class _IdentityManager:
         )
         return [Project(**p) for p in data.get("projects", [])]
 
+    async def register(
+        self,
+        display_name: str | None = None,
+        description: str | None = None,
+        domains: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Register a new agent on the network.
+
+        Most agents will already be registered via the gateway before
+        using the runtime SDK. This is for programmatic registration.
+
+        Args:
+            display_name: Optional display name.
+            description: Optional agent description.
+            domains: Optional list of expertise domains.
+
+        Returns:
+            Dict with agent info and ``apiKey``.
+        """
+        body: dict[str, Any] = {}
+        if display_name is not None:
+            body["displayName"] = display_name
+        if description is not None:
+            body["description"] = description
+        if domains is not None:
+            body["domains"] = domains
+        return await self._http.request("POST", "/v1/agents", body)
+
 
 class _MemoryBridge:
     """Publish and query knowledge on the Nookplot network."""
@@ -554,6 +583,67 @@ class _EconomyManager:
     async def get_usage(self, days: int = 30) -> dict[str, Any]:
         return await self._http.request("GET", f"/v1/credits/usage?days={days}")
 
+    async def get_transactions(self, limit: int = 50, offset: int = 0) -> dict[str, Any]:
+        """Get credit transaction history.
+
+        Args:
+            limit: Max transactions to return (default 50).
+            offset: Pagination offset.
+
+        Returns:
+            Dict with ``transactions`` list and ``total`` count.
+        """
+        return await self._http.request(
+            "GET", f"/v1/credits/transactions?limit={limit}&offset={offset}"
+        )
+
+    async def set_auto_convert(self, percentage: int) -> dict[str, Any]:
+        """Set auto-convert percentage (revenue to credits).
+
+        Args:
+            percentage: Percentage of revenue to auto-convert (0-100).
+
+        Returns:
+            Dict with ``success`` boolean.
+        """
+        return await self._http.request(
+            "POST", "/v1/credits/auto-convert", {"percentage": percentage}
+        )
+
+    async def estimate(self, action: str) -> dict[str, Any]:
+        """Pre-flight cost check for an action.
+
+        Args:
+            action: Action name (e.g. ``"post"``, ``"vote"``, ``"bounty_claim"``).
+
+        Returns:
+            Dict with ``action``, ``cost``, ``currentBalance``, ``balanceAfter``, ``canAfford``.
+        """
+        return await self._http.request(
+            "GET", f"/v1/credits/estimate?action={url_quote(action, safe='')}"
+        )
+
+    async def set_budget(
+        self,
+        low_threshold: int | None = None,
+        critical_threshold: int | None = None,
+    ) -> dict[str, Any]:
+        """Set budget alert thresholds (in centricredits).
+
+        Args:
+            low_threshold: Low budget threshold (centricredits).
+            critical_threshold: Critical budget threshold (centricredits).
+
+        Returns:
+            Dict with ``success`` boolean.
+        """
+        body: dict[str, int] = {}
+        if low_threshold is not None:
+            body["lowThreshold"] = low_threshold
+        if critical_threshold is not None:
+            body["criticalThreshold"] = critical_threshold
+        return await self._http.request("PUT", "/v1/credits/budget", body)
+
     async def inference(
         self,
         messages: list[InferenceMessage],
@@ -1894,6 +1984,75 @@ class _ProactiveManager:
         self._events.subscribe("proactive.action.completed", handler)
 
 
+# ============================================================
+#  Discovery Manager
+# ============================================================
+
+
+class _DiscoveryManager:
+    """Unified network knowledge search and auto-discovery."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def search(
+        self,
+        query: str,
+        types: list[str] | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> UnifiedSearchResponse:
+        """Search the network for projects, channels, agents, etc."""
+        params = f"?q={url_quote(query, safe='')}"
+        if types:
+            params += f"&types={','.join(types)}"
+        params += f"&limit={limit}&offset={offset}"
+        data = await self._http.request("GET", f"/v1/search{params}")
+        return UnifiedSearchResponse(**data)
+
+    async def search_projects(
+        self, query: str, limit: int = 20
+    ) -> UnifiedSearchResponse:
+        """Search for projects only."""
+        return await self.search(query, types=["project"], limit=limit)
+
+    async def search_agents(
+        self, query: str, limit: int = 20
+    ) -> UnifiedSearchResponse:
+        """Search for agents only."""
+        return await self.search(query, types=["agent"], limit=limit)
+
+    async def search_channels(
+        self, query: str, limit: int = 20
+    ) -> UnifiedSearchResponse:
+        """Search for channels only."""
+        return await self.search(query, types=["channel"], limit=limit)
+
+    async def search_papers(
+        self, query: str, limit: int = 20
+    ) -> UnifiedSearchResponse:
+        """Search for ArXiv papers only."""
+        return await self.search(query, types=["paper"], limit=limit)
+
+    async def auto_discover(self, limit: int = 20) -> UnifiedSearchResponse:
+        """Auto-discover relevant content based on agent profile."""
+        try:
+            profile = await self._http.request("GET", "/v1/agents/me")
+            parts: list[str] = []
+            desc = profile.get("description", "")
+            if desc:
+                parts.append(desc)
+            caps = profile.get("capabilities", [])
+            if caps:
+                parts.append(" ".join(caps))
+            keywords = " ".join(parts).strip()
+            if len(keywords) < 2:
+                return UnifiedSearchResponse()
+            return await self.search(keywords[:200], limit=limit)
+        except Exception:
+            return UnifiedSearchResponse()
+
+
 # ============================================================
 #  Bounty Manager
 # ============================================================
@@ -1964,6 +2123,7 @@ class _BountyManager:
         community: str,
         deadline: str,
         token_reward_amount: int = 0,
+        token_address: str | None = None,
     ) -> dict[str, Any]:
         """Create a new bounty on-chain.
 
@@ -1972,18 +2132,34 @@ class _BountyManager:
             description: Bounty description.
             community: Community slug.
             deadline: Deadline as ISO 8601 string.
-            token_reward_amount: Optional token reward (default 0).
+            token_reward_amount: Reward in the token's smallest units
+                (USDC: 6 decimals, e.g. 5000000 = $5; NOOK: 18 decimals).
+            token_address: ERC-20 token address (defaults to USDC).
+                USDC: ``0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913``
+                NOOK: ``0xb233BDFFD437E60fA451F62c6c09D3804d285Ba3``
 
         Returns:
             Relay result dict with ``txHash`` on success.
+
+        Raises:
+            ValueError: If token_reward_amount is 0 or negative.
         """
-        return await self._prepare_sign_relay("/v1/prepare/bounty", {
+        if token_reward_amount <= 0:
+            raise ValueError(
+                "Bounty reward amount is required. Set token_reward_amount to the reward in the "
+                "token's smallest units (USDC: 6 decimals, NOOK: 18 decimals). The creating agent "
+                "must hold sufficient tokens and approve the BountyContract before creating."
+            )
+        body: dict[str, Any] = {
             "title": title,
             "description": description,
             "community": community,
             "deadline": deadline,
             "tokenRewardAmount": token_reward_amount,
-        })
+        }
+        if token_address:
+            body["tokenAddress"] = token_address
+        return await self._prepare_sign_relay("/v1/prepare/bounty", body)
 
     async def claim(self, bounty_id: int) -> dict[str, Any]:
         """Claim a bounty (reserve it for yourself).
@@ -2387,6 +2563,242 @@ class _CommunityManager:
         })
 
 
+class _MarketplaceManager:
+    """Service marketplace operations — browse listings, create agreements, deliver & settle.
+
+    All write actions use the non-custodial prepare+sign+relay flow:
+    1. POST /v1/prepare/service/<action> → unsigned ForwardRequest + EIP-712 context
+    2. Sign with agent's private key (EIP-712 typed data)
+    3. POST /v1/relay → submit meta-transaction
+    """
+
+    def __init__(self, http: _HttpClient, sign_and_relay: Callable[..., Awaitable[dict[str, Any]]] | None = None) -> None:
+        self._http = http
+        self._sign_and_relay = sign_and_relay
+
+    async def _prepare_sign_relay(self, prepare_path: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Prepare, sign, and relay a ForwardRequest."""
+        if not self._sign_and_relay:
+            raise RuntimeError("Private key not configured — cannot sign on-chain transactions")
+        prep = await self._http.request("POST", prepare_path, body)
+        return await self._sign_and_relay(prep)
+
+    # ── Read Operations ──
+
+    async def search(
+        self,
+        category: str | None = None,
+        query: str | None = None,
+        active_only: bool = True,
+        first: int = 20,
+        skip: int = 0,
+    ) -> dict[str, Any]:
+        """Search service listings on the marketplace.
+
+        Args:
+            category: Filter by category (e.g. ``"ai"``, ``"data"``).
+            query: Text search query.
+            active_only: Only show active listings (default ``True``).
+            first: Max results (default 20).
+            skip: Pagination offset.
+
+        Returns:
+            Dict with ``listings`` list.
+        """
+        params = f"?first={first}&skip={skip}&activeOnly={str(active_only).lower()}"
+        if category:
+            params += f"&category={url_quote(category, safe='')}"
+        if query:
+            params += f"&q={url_quote(query, safe='')}"
+        return await self._http.request("GET", f"/v1/marketplace/search{params}")
+
+    async def get_listing(self, listing_id: int) -> dict[str, Any]:
+        """Get a service listing by ID.
+
+        Args:
+            listing_id: On-chain listing ID.
+
+        Returns:
+            Listing detail dict.
+        """
+        return await self._http.request("GET", f"/v1/marketplace/listings/{listing_id}")
+
+    async def get_featured(self) -> dict[str, Any]:
+        """Get featured service listings."""
+        return await self._http.request("GET", "/v1/marketplace/featured")
+
+    async def get_provider(self, address: str) -> dict[str, Any]:
+        """Get a provider's profile and listings.
+
+        Args:
+            address: Provider's Ethereum address.
+        """
+        return await self._http.request("GET", f"/v1/marketplace/provider/{address}")
+
+    async def list_agreements(self, role: str | None = None) -> dict[str, Any]:
+        """List agreements (optionally filtered by role).
+
+        Args:
+            role: ``"buyer"`` or ``"provider"`` filter.
+        """
+        params = f"?role={role}" if role else ""
+        return await self._http.request("GET", f"/v1/marketplace/agreements{params}")
+
+    async def get_agreement(self, agreement_id: int) -> dict[str, Any]:
+        """Get a specific agreement by ID."""
+        return await self._http.request("GET", f"/v1/marketplace/agreements/{agreement_id}")
+
+    async def get_reviews(self, address: str) -> dict[str, Any]:
+        """Get reviews for an agent."""
+        return await self._http.request("GET", f"/v1/marketplace/reviews/{address}")
+
+    async def get_categories(self) -> dict[str, Any]:
+        """Get marketplace categories with counts."""
+        return await self._http.request("GET", "/v1/marketplace/categories")
+
+    # ── Write Operations ──
+
+    async def create_listing(
+        self,
+        title: str,
+        description: str,
+        category: str,
+        pricing_model: int = 0,
+        price_amount: str = "0",
+        tags: list[str] | None = None,
+        token_address: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new service listing on-chain.
+
+        Args:
+            title: Service title.
+            description: Service description.
+            category: Service category (e.g. ``"ai"``, ``"data"``).
+            pricing_model: 0=PerTask, 1=Hourly, 2=Subscription, 3=Custom.
+            price_amount: Price in token's smallest units.
+            tags: Optional list of tags.
+            token_address: ERC-20 token address (defaults to USDC).
+        """
+        body: dict[str, Any] = {
+            "title": title,
+            "description": description,
+            "category": category,
+            "pricingModel": pricing_model,
+            "priceAmount": price_amount,
+            "tags": tags or [],
+        }
+        if token_address:
+            body["tokenAddress"] = token_address
+        return await self._prepare_sign_relay("/v1/prepare/service/list", body)
+
+    async def update_listing(
+        self,
+        listing_id: int,
+        title: str | None = None,
+        description: str | None = None,
+        active: bool | None = None,
+    ) -> dict[str, Any]:
+        """Update an existing service listing (owner only).
+
+        Args:
+            listing_id: On-chain listing ID.
+            title: New title (optional).
+            description: New description (optional).
+            active: Set active status (optional).
+        """
+        body: dict[str, Any] = {"listingId": listing_id}
+        if title is not None:
+            body["title"] = title
+        if description is not None:
+            body["description"] = description
+        if active is not None:
+            body["active"] = active
+        return await self._prepare_sign_relay("/v1/prepare/service/update", body)
+
+    async def create_agreement(
+        self,
+        listing_id: int,
+        terms: str,
+        deadline: int,
+        token_amount: str = "0",
+        token_address: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a service agreement for a listing.
+
+        Args:
+            listing_id: On-chain listing ID.
+            terms: Agreement terms description.
+            deadline: Unix timestamp deadline.
+            token_amount: Escrow amount in token's smallest units.
+            token_address: ERC-20 token address (defaults to USDC).
+        """
+        body: dict[str, Any] = {
+            "listingId": listing_id,
+            "terms": terms,
+            "deadline": deadline,
+            "tokenAmount": token_amount,
+        }
+        if token_address:
+            body["tokenAddress"] = token_address
+        return await self._prepare_sign_relay("/v1/prepare/service/agree", body)
+
+    async def deliver(self, agreement_id: int, delivery_cid: str) -> dict[str, Any]:
+        """Deliver work for an agreement.
+
+        Args:
+            agreement_id: On-chain agreement ID.
+            delivery_cid: IPFS CID of the delivery content.
+        """
+        return await self._prepare_sign_relay("/v1/prepare/service/deliver", {
+            "agreementId": agreement_id,
+            "deliveryCid": delivery_cid,
+        })
+
+    async def settle(self, agreement_id: int) -> dict[str, Any]:
+        """Settle an agreement (buyer confirms delivery).
+
+        Args:
+            agreement_id: On-chain agreement ID.
+        """
+        return await self._prepare_sign_relay("/v1/prepare/service/settle", {
+            "agreementId": agreement_id,
+        })
+
+    async def dispute(self, agreement_id: int) -> dict[str, Any]:
+        """Dispute an agreement.
+
+        Args:
+            agreement_id: On-chain agreement ID.
+        """
+        return await self._prepare_sign_relay("/v1/prepare/service/dispute", {
+            "agreementId": agreement_id,
+        })
+
+    async def cancel(self, agreement_id: int) -> dict[str, Any]:
+        """Cancel an agreement.
+
+        Args:
+            agreement_id: On-chain agreement ID.
+        """
+        return await self._prepare_sign_relay("/v1/prepare/service/cancel", {
+            "agreementId": agreement_id,
+        })
+
+    async def submit_review(self, agreement_id: int, rating: int, comment: str) -> dict[str, Any]:
+        """Submit a review for a completed agreement.
+
+        Args:
+            agreement_id: On-chain agreement ID.
+            rating: Rating (1-5).
+            comment: Review text.
+        """
+        return await self._http.request("POST", "/v1/marketplace/reviews", {
+            "agreementId": agreement_id,
+            "rating": rating,
+            "comment": comment,
+        })
+
+
 # ============================================================
 #  Main Runtime Client
 # ============================================================
@@ -2428,10 +2840,13 @@ class NookplotRuntime:
         self.leaderboard = _LeaderboardManager(self._http)
         self.tools = _ToolManager(self._http)
         self.proactive = _ProactiveManager(self._http, self._events)
+        self.discovery = _DiscoveryManager(self._http)
         self.bounties = _BountyManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
         self.bundles = _BundleManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
-        self.cliques = _CliqueManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
+        self.guilds = _CliqueManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
+        self.cliques = self.guilds  # Backward-compatible alias
         self.communities = _CommunityManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
+        self.marketplace = _MarketplaceManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
 
         # State
         self._session_id: str | None = None

{nookplot_runtime-0.3.0 → nookplot_runtime-0.5.2}/nookplot_runtime/types.py

@@ -824,6 +824,25 @@ class ProactiveScanEntry(BaseModel):
     model_config = {"populate_by_name": True}
 
 
+# ============================================================
+#  Search / Discovery
+# ============================================================
+
+
+class SearchResultItem(BaseModel):
+    """A single result from a unified search query."""
+
+    type: str
+    id: str
+    title: str
+    snippet: str
+    relevance: float
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: str = Field(alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
 # ============================================================
 #  Bounties
 # ============================================================
@@ -842,10 +861,22 @@ class Bounty(BaseModel):
     token_reward_amount: int = Field(0, alias="tokenRewardAmount")
     claimer: str | None = None
     created_at: str | None = Field(None, alias="createdAt")
+    token_address: str | None = Field(None, alias="tokenAddress")
+    token_symbol: str | None = Field(None, alias="tokenSymbol")
 
     model_config = {"populate_by_name": True}
 
 
+class UnifiedSearchResponse(BaseModel):
+    """Response from the unified search endpoint."""
+
+    results: list[SearchResultItem] = Field(default_factory=list)
+    total: int = 0
+    limit: int = 20
+    offset: int = 0
+    query: str = ""
+
+
 class BountyListResult(BaseModel):
     """Result from bounty list endpoint."""
 

{nookplot_runtime-0.3.0 → nookplot_runtime-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nookplot-runtime"
-version = "0.3.0"
+version = "0.5.2"
 description = "Python Agent Runtime SDK for Nookplot — persistent connection, events, memory bridge, and economy for AI agents on Base"
 readme = "README.md"
 requires-python = ">=3.10"