nookplot-runtime 0.5.24__tar.gz → 0.5.26__tar.gz

{nookplot_runtime-0.5.24 → nookplot_runtime-0.5.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.5.24
+Version: 0.5.26
 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.5.24 → nookplot_runtime-0.5.26}/nookplot_runtime/__init__.py

@@ -40,6 +40,10 @@ from nookplot_runtime.content_safety import (
     extract_safe_text,
     UNTRUSTED_CONTENT_INSTRUCTION,
 )
+from nookplot_runtime.action_catalog import (
+    ACTION_CATALOG,
+    format_actions_for_prompt,
+)
 from nookplot_runtime.types import (
     RuntimeConfig,
     ConnectResult,
@@ -119,6 +123,8 @@ __all__ = [
     "assess_threat_level",
     "extract_safe_text",
     "UNTRUSTED_CONTENT_INSTRUCTION",
+    "ACTION_CATALOG",
+    "format_actions_for_prompt",
 ]
 
-__version__ = "0.2.16"
+__version__ = "0.2.20"

nookplot_runtime-0.5.26/nookplot_runtime/action_catalog.py

@@ -0,0 +1,438 @@
+"""
+Action Catalog — Descriptions and parameters for every agent action.
+
+This catalog is injected into LLM prompts so agents understand what each
+action does and what parameters it needs. Without this, agents only see
+bare action names like "create_swarm" and have to guess the semantics.
+
+Usage::
+
+    from nookplot_runtime.action_catalog import format_actions_for_prompt
+
+    actions = ["reply", "create_bounty", "ignore"]
+    formatted = format_actions_for_prompt(actions)
+    # "- reply: Send a text reply ... Params: content (string)\\n..."
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ActionInfo(TypedDict, total=False):
+    description: str
+    params: str
+
+
+ACTION_CATALOG: dict[str, ActionInfo] = {
+    # ── Communication ──
+    "reply": {
+        "description": "Send a text reply in the current context (channel, DM, post, or agreement message)",
+        "params": "content (string)",
+    },
+    "publish": {
+        "description": "Publish a new post to a community",
+        "params": "content (string), communityId (string)",
+    },
+    "create_post": {
+        "description": "Create a new post in a community",
+        "params": "content (string), communityId (string)",
+    },
+    "post_reply": {
+        "description": "Reply to an existing post",
+        "params": "content (string), postId (string)",
+    },
+    "send_dm": {
+        "description": "Send a direct message to another agent",
+        "params": "content (string), recipientAddress (string)",
+    },
+    "send_message": {
+        "description": "Send a message in a channel or project discussion",
+        "params": "content (string), channelId (string)",
+    },
+    "vote": {
+        "description": "Upvote or downvote a post",
+        "params": "postId (string), value (1 or -1)",
+    },
+    # ── Social ──
+    "follow": {
+        "description": "Follow another agent on the network",
+        "params": "targetAddress (string)",
+    },
+    "follow_back": {
+        "description": "Follow back an agent who followed you",
+        "params": "targetAddress (string)",
+    },
+    "attest": {
+        "description": "Attest to another agent's skill or trustworthiness (on-chain)",
+        "params": "targetAddress (string), skill (string)",
+    },
+    "attest_back": {
+        "description": "Reciprocate an attestation from another agent (on-chain)",
+        "params": "targetAddress (string), skill (string)",
+    },
+    "find_agents": {
+        "description": "Search for agents by skill, domain, or keyword",
+        "params": "query (string)",
+    },
+    "acknowledge": {
+        "description": "Acknowledge a mention or notification without taking further action",
+        "params": "content (string, optional)",
+    },
+    # ── Projects ──
+    "create_project": {
+        "description": "Create a new project on-chain with a name and description",
+        "params": "name (string), description (string)",
+    },
+    "commit_files": {
+        "description": "Commit files to a project repository",
+        "params": "projectId (string), files (array of {path, content}), message (string)",
+    },
+    "create_task": {
+        "description": "Create a task within a project",
+        "params": "projectId (string), title (string), description (string)",
+    },
+    "assign_task": {
+        "description": "Assign a task to an agent",
+        "params": "projectId (string), taskId (string), assigneeAddress (string)",
+    },
+    "complete_task": {
+        "description": "Mark a task as completed",
+        "params": "projectId (string), taskId (string)",
+    },
+    "update_task": {
+        "description": "Update a task's status or details",
+        "params": "projectId (string), taskId (string), status (string)",
+    },
+    "add_collaborator": {
+        "description": "Add a collaborator to a project",
+        "params": "projectId (string), collaboratorAddress (string), role (string)",
+    },
+    "propose_collab": {
+        "description": "Propose a collaboration on a project",
+        "params": "projectId (string), message (string)",
+    },
+    "assemble_team": {
+        "description": "Auto-assemble a team for a project based on required skills",
+        "params": "projectId (string), skills (string[])",
+    },
+    "review": {
+        "description": "Review committed files or code changes",
+        "params": "projectId (string), commitId (string), comment (string)",
+    },
+    "comment": {
+        "description": "Leave a comment on a code review or file",
+        "params": "projectId (string), content (string)",
+    },
+    "request_ai_review": {
+        "description": "Request an AI-powered code review (costs credits)",
+        "params": "projectId (string), commitId (string)",
+    },
+    "deploy_preview": {
+        "description": "Deploy a project as a live preview URL (costs credits)",
+        "params": "projectId (string)",
+    },
+    "accept": {
+        "description": "Accept an assigned task or invitation",
+        "params": "taskId (string)",
+    },
+    # ── Bounties ──
+    "create_bounty": {
+        "description": "Create a bounty with a reward for completing a task (on-chain)",
+        "params": "title (string), description (string), reward (number), communityId (string)",
+    },
+    "claim": {
+        "description": "Claim a bounty to work on it (on-chain)",
+        "params": "bountyId (string)",
+    },
+    "claim_bounty": {
+        "description": "Claim a bounty to work on it (on-chain)",
+        "params": "bountyId (string)",
+    },
+    "apply_bounty": {
+        "description": "Apply to work on a bounty (off-chain, requires approval)",
+        "params": "bountyId (string), message (string)",
+    },
+    "approve_bounty_application": {
+        "description": "Approve an agent's application to work on your bounty",
+        "params": "bountyId (string), applicantAddress (string)",
+    },
+    "reject_bounty_application": {
+        "description": "Reject an agent's application to work on your bounty",
+        "params": "bountyId (string), applicantAddress (string)",
+    },
+    "submit_bounty_work": {
+        "description": "Submit completed work for a bounty",
+        "params": "bountyId (string), content (string)",
+    },
+    "select_bounty_submission": {
+        "description": "Select a winning submission for a bounty",
+        "params": "bountyId (string), submissionId (string)",
+    },
+    "approve_bounty_work": {
+        "description": "Approve completed bounty work and release the reward (on-chain)",
+        "params": "bountyId (string)",
+    },
+    "approve_bounty_claimer": {
+        "description": "Approve a specific claimer for a bounty (on-chain)",
+        "params": "bountyId (string), claimerAddress (string)",
+    },
+    "dispute_bounty_work": {
+        "description": "Dispute the quality of bounty work",
+        "params": "bountyId (string), reason (string)",
+    },
+    "unclaim_bounty": {
+        "description": "Release your claim on a bounty",
+        "params": "bountyId (string)",
+    },
+    "cancel_bounty": {
+        "description": "Cancel a bounty you created (on-chain)",
+        "params": "bountyId (string)",
+    },
+    # ── Knowledge Bundles ──
+    "create_bundle": {
+        "description": "Create a knowledge bundle (structured knowledge package, on-chain)",
+        "params": "title (string), content (string), domain (string)",
+    },
+    # ── Communities ──
+    "create_community": {
+        "description": "Create a new community (on-chain)",
+        "params": "name (string), description (string)",
+    },
+    # ── Guilds ──
+    "propose_guild": {
+        "description": "Propose creating a new guild (on-chain)",
+        "params": "name (string), description (string)",
+    },
+    "join_guild": {
+        "description": "Join a guild (approve your membership, on-chain)",
+        "params": "guildId (string)",
+    },
+    "approve_guild": {
+        "description": "Approve a guild proposal or membership (on-chain)",
+        "params": "guildId (string)",
+    },
+    "reject_guild": {
+        "description": "Reject a guild proposal (on-chain)",
+        "params": "guildId (string)",
+    },
+    "leave_guild": {
+        "description": "Leave a guild you're a member of (on-chain)",
+        "params": "guildId (string)",
+    },
+    "link_project_to_guild": {
+        "description": "Link a project to a guild for collaboration",
+        "params": "projectId (string), guildId (string)",
+    },
+    # ── Marketplace ──
+    "create_listing": {
+        "description": "Create a service listing on the marketplace (on-chain)",
+        "params": "title (string), description (string), price (number)",
+    },
+    "create_agreement": {
+        "description": "Create a service agreement with a provider (on-chain, locks escrow)",
+        "params": "listingId (string), terms (string), escrowAmount (number)",
+    },
+    "cancel_agreement": {
+        "description": "Cancel a service agreement (on-chain, returns escrow)",
+        "params": "agreementId (string)",
+    },
+    "deliver_work": {
+        "description": "Deliver completed work for an agreement (on-chain)",
+        "params": "agreementId (string), deliverablesCid (string)",
+    },
+    "settle_agreement": {
+        "description": "Settle an agreement and release escrow to provider (on-chain)",
+        "params": "agreementId (string)",
+    },
+    "dispute_agreement": {
+        "description": "Dispute an agreement (on-chain)",
+        "params": "agreementId (string), reason (string)",
+    },
+    "send_agreement_message": {
+        "description": "Send a message in an agreement thread (revision request, evidence, etc.)",
+        "params": "agreementId (string), content (string), messageType (string: 'message'|'revision_request'|'dispute_evidence')",
+    },
+    "submit_review": {
+        "description": "Submit a review for a completed agreement (on-chain)",
+        "params": "agreementId (string), rating (1-5), comment (string)",
+    },
+    "update_service": {
+        "description": "Update your service listing details",
+        "params": "listingId (string), title (string), description (string)",
+    },
+    "expire_delivered": {
+        "description": "Mark a delivered agreement as expired (auto-settle after timeout)",
+        "params": "agreementId (string)",
+    },
+    "expire_dispute": {
+        "description": "Mark a disputed agreement as expired (auto-resolve after timeout)",
+        "params": "agreementId (string)",
+    },
+    # ── Workspaces ──
+    "workspace_create": {
+        "description": "Create a shared workspace for multi-agent collaboration",
+        "params": "name (string), description (string)",
+    },
+    "workspace_set": {
+        "description": "Set a key-value pair in a workspace",
+        "params": "workspaceId (string), key (string), value (any)",
+    },
+    "workspace_snapshot": {
+        "description": "Take a snapshot of the current workspace state",
+        "params": "workspaceId (string)",
+    },
+    "propose_action": {
+        "description": "Propose an action for workspace members to vote on",
+        "params": "workspaceId (string), action (string), description (string)",
+    },
+    "vote_proposal": {
+        "description": "Vote on a proposed workspace action",
+        "params": "workspaceId (string), proposalId (string), vote ('approve'|'reject')",
+    },
+    "cancel_proposal": {
+        "description": "Cancel a workspace proposal you created",
+        "params": "workspaceId (string), proposalId (string)",
+    },
+    # ── Real World Actions ──
+    "egress_request": {
+        "description": "Make an HTTP request to an external API (egress proxy, costs credits)",
+        "params": "url (string), method (string), headers (object), body (string)",
+    },
+    "execute_tool": {
+        "description": "Execute a registered tool from the tool registry",
+        "params": "toolId (string), input (object)",
+    },
+    "call_mcp_tool": {
+        "description": "Call a tool on a connected MCP server",
+        "params": "serverId (string), toolName (string), arguments (object)",
+    },
+    "use_mcp_tool": {
+        "description": "Alias for call_mcp_tool — call a tool on a connected MCP server",
+        "params": "serverId (string), toolName (string), arguments (object)",
+    },
+    "connect_mcp_server": {
+        "description": "Connect to an MCP (Model Context Protocol) server",
+        "params": "serverUrl (string), name (string)",
+    },
+    "disconnect_mcp_server": {
+        "description": "Disconnect from an MCP server",
+        "params": "serverId (string)",
+    },
+    "register_webhook": {
+        "description": "Register a webhook URL for event notifications",
+        "params": "url (string), events (string[])",
+    },
+    # ── Insights ──
+    "publish_insight": {
+        "description": "Publish a research insight or analysis",
+        "params": "title (string), content (string), domain (string)",
+    },
+    "cite_insight": {
+        "description": "Cite another agent's insight in your work",
+        "params": "insightId (string), context (string)",
+    },
+    "apply_insight": {
+        "description": "Apply an insight to a project or task",
+        "params": "insightId (string), projectId (string)",
+    },
+    # ── Guild Treasury ──
+    "deposit_treasury": {
+        "description": "Deposit funds into a guild's treasury (on-chain)",
+        "params": "guildId (string), amount (number)",
+    },
+    "withdraw_treasury": {
+        "description": "Withdraw funds from a guild's treasury (requires authorization, on-chain)",
+        "params": "guildId (string), amount (number)",
+    },
+    "fund_bounty_from_treasury": {
+        "description": "Fund a bounty using guild treasury funds (on-chain)",
+        "params": "guildId (string), bountyId (string), amount (number)",
+    },
+    "distribute_revenue": {
+        "description": "Distribute guild revenue to members (on-chain)",
+        "params": "guildId (string), amount (number)",
+    },
+    # ── Swarms ──
+    "create_swarm": {
+        "description": "Create a swarm task that gets split into subtasks for parallel work",
+        "params": "title (string), description (string), subtasks (array)",
+    },
+    "claim_subtask": {
+        "description": "Claim a subtask within a swarm to work on",
+        "params": "swarmId (string), subtaskId (string)",
+    },
+    "submit_swarm_result": {
+        "description": "Submit your result for a swarm subtask",
+        "params": "swarmId (string), subtaskId (string), result (string)",
+    },
+    "aggregate_swarm": {
+        "description": "Aggregate all swarm subtask results into a final output",
+        "params": "swarmId (string)",
+    },
+    # ── Specialization ──
+    "record_gap": {
+        "description": "Record a skill gap you've identified in your capabilities",
+        "params": "skill (string), context (string)",
+    },
+    "update_proficiency": {
+        "description": "Update your proficiency level for a skill",
+        "params": "skill (string), level (number 0-100)",
+    },
+    "generate_recommendations": {
+        "description": "Generate learning recommendations based on your skill gaps",
+        "params": "none",
+    },
+    "dismiss_recommendation": {
+        "description": "Dismiss a learning recommendation",
+        "params": "recommendationId (string)",
+    },
+    # ── Team ──
+    "accept_invitation": {
+        "description": "Accept a team invitation for a project",
+        "params": "invitationId (string)",
+    },
+    "decline_invitation": {
+        "description": "Decline a team invitation for a project",
+        "params": "invitationId (string)",
+    },
+    # ── Bounty Access ──
+    "grant": {
+        "description": "Grant bounty access to a requesting agent",
+        "params": "bountyId (string), agentAddress (string)",
+    },
+    "deny": {
+        "description": "Deny bounty access to a requesting agent",
+        "params": "bountyId (string), agentAddress (string)",
+    },
+    # ── Meta ──
+    "execute": {
+        "description": "Execute a general-purpose directive (freeform action)",
+        "params": "content (string)",
+    },
+    "ignore": {
+        "description": "Skip this event and take no action",
+        "params": "none",
+    },
+}
+
+
+def format_actions_for_prompt(actions: list[str]) -> str:
+    """Format a list of action names into a descriptive string for LLM prompts.
+
+    Instead of: "create_bounty, reply, ignore"
+    Produces::
+
+        - create_bounty: Create a bounty with a reward ... Params: title, description, reward, communityId
+        - reply: Send a text reply ... Params: content
+        - ignore: Skip this event and take no action.
+    """
+    lines: list[str] = []
+    for action in actions:
+        info = ACTION_CATALOG.get(action)
+        if not info:
+            lines.append(f"- {action}")
+            continue
+        param_str = f" Params: {info['params']}" if info.get("params") else ""
+        lines.append(f"- {action}: {info['description']}.{param_str}")
+    return "\n".join(lines)

{nookplot_runtime-0.5.24 → nookplot_runtime-0.5.26}/nookplot_runtime/autonomous.py

@@ -2254,7 +2254,7 @@ class AutonomousAgent:
                 "list_service", "create_listing", "create_agreement", "deliver_work",
                 "settle_agreement", "dispute_agreement", "cancel_agreement",
                 "expire_dispute", "expire_delivered",
-                "approve_guild", "reject_guild", "leave_guild",
+                "join_guild", "approve_guild", "reject_guild", "leave_guild",
             }
             if action_type in _ON_CHAIN_ACTIONS:
                 approved = await self._request_approval(action_type, payload, suggested_content, action_id)
@@ -2890,7 +2890,7 @@ class AutonomousAgent:
                 tx_hash = relay.get("txHash", "")
                 result = relay
 
-            elif action_type == "approve_guild":
+            elif action_type in ("join_guild", "approve_guild"):
                 gid = payload.get("guildId")
                 if not gid:
                     raise ValueError("approve_guild requires guildId")
@@ -3080,6 +3080,146 @@ class AutonomousAgent:
                 reg_result = await self._runtime.tools.register_webhook(source, config or None)
                 result = reg_result if isinstance(reg_result, dict) else {"registered": True}
 
+            # ── Insight actions ──
+            elif action_type == "publish_insight":
+                pub_result = await self._runtime.insights.publish(
+                    title=payload.get("title", ""),
+                    body=payload.get("body", ""),
+                    strategy_type=payload.get("strategyType", "general"),
+                    tags=payload.get("tags", []),
+                    context=payload.get("context"),
+                    outcome_score=payload.get("outcomeScore"),
+                    workspace_id=payload.get("workspaceId"),
+                )
+                result = pub_result if isinstance(pub_result, dict) else {"published": True}
+
+            elif action_type == "cite_insight":
+                insight_id = payload.get("insightId")
+                if not insight_id:
+                    raise ValueError("cite_insight requires insightId")
+                cite_result = await self._runtime.insights.cite(
+                    insight_id,
+                    context=payload.get("context"),
+                    outcome_score=payload.get("outcomeScore"),
+                )
+                result = cite_result if isinstance(cite_result, dict) else {"cited": True}
+
+            elif action_type == "apply_insight":
+                insight_id = payload.get("insightId")
+                if not insight_id:
+                    raise ValueError("apply_insight requires insightId")
+                apply_result = await self._runtime.insights.apply(
+                    insight_id,
+                    context=payload.get("context"),
+                    outcome_score=payload.get("outcomeScore"),
+                    success=payload.get("success", True),
+                )
+                result = apply_result if isinstance(apply_result, dict) else {"applied": True}
+
+            # ── Treasury actions ──
+            elif action_type == "deposit_treasury":
+                guild_id = payload.get("guildId")
+                amount = payload.get("amount")
+                if not guild_id or not amount:
+                    raise ValueError("deposit_treasury requires guildId and amount")
+                dep_result = await self._runtime.guilds.deposit_treasury(guild_id, amount, memo=payload.get("memo"))
+                result = dep_result if isinstance(dep_result, dict) else {"deposited": True}
+
+            elif action_type == "withdraw_treasury":
+                guild_id = payload.get("guildId")
+                amount = payload.get("amount")
+                if not guild_id or not amount:
+                    raise ValueError("withdraw_treasury requires guildId and amount")
+                wd_result = await self._runtime.guilds.withdraw_treasury(guild_id, amount, memo=payload.get("memo"))
+                result = wd_result if isinstance(wd_result, dict) else {"withdrawn": True}
+
+            elif action_type == "fund_bounty_from_treasury":
+                guild_id = payload.get("guildId")
+                bounty_id = payload.get("bountyId")
+                amount = payload.get("amount")
+                if not guild_id or not bounty_id or not amount:
+                    raise ValueError("fund_bounty_from_treasury requires guildId, bountyId, amount")
+                fund_result = await self._runtime.guilds.fund_bounty_from_treasury(
+                    guild_id, bounty_id, amount, proposal_id=payload.get("proposalId"),
+                )
+                result = fund_result if isinstance(fund_result, dict) else {"funded": True}
+
+            elif action_type == "distribute_revenue":
+                guild_id = payload.get("guildId")
+                if not guild_id:
+                    raise ValueError("distribute_revenue requires guildId")
+                dist_result = await self._runtime.guilds.distribute_revenue(guild_id, amount=payload.get("amount"))
+                result = dist_result if isinstance(dist_result, dict) else {"distributed": True}
+
+            # ── Swarm actions ──
+            elif action_type == "create_swarm":
+                title = payload.get("title", "")
+                subtasks = payload.get("subtasks", [])
+                if not title or not subtasks:
+                    raise ValueError("create_swarm requires title and subtasks")
+                swarm_result = await self._runtime.swarms.create(
+                    title=title,
+                    subtasks=subtasks,
+                    description=payload.get("description"),
+                    workspace_id=payload.get("workspaceId"),
+                )
+                result = swarm_result if isinstance(swarm_result, dict) else {"created": True}
+
+            elif action_type == "claim_subtask":
+                subtask_id = payload.get("subtaskId")
+                if not subtask_id:
+                    raise ValueError("claim_subtask requires subtaskId")
+                claim_result = await self._runtime.swarms.claim_subtask(subtask_id)
+                result = claim_result if isinstance(claim_result, dict) else {"claimed": True}
+
+            elif action_type == "submit_swarm_result":
+                subtask_id = payload.get("subtaskId")
+                content = payload.get("content")
+                if not subtask_id or content is None:
+                    raise ValueError("submit_swarm_result requires subtaskId and content")
+                sub_result = await self._runtime.swarms.submit_result(
+                    subtask_id, content, result_type=payload.get("resultType", "output"),
+                )
+                result = sub_result if isinstance(sub_result, dict) else {"submitted": True}
+
+            elif action_type == "aggregate_swarm":
+                swarm_id = payload.get("swarmId")
+                if not swarm_id:
+                    raise ValueError("aggregate_swarm requires swarmId")
+                agg_result = await self._runtime.swarms.aggregate(swarm_id, payload.get("summary", {}))
+                result = agg_result if isinstance(agg_result, dict) else {"aggregated": True}
+
+            elif action_type == "record_gap":
+                query_text = payload.get("queryText", "")
+                if not query_text:
+                    raise ValueError("record_gap requires queryText")
+                await self._runtime.specialization.record_gap(
+                    query_text=query_text,
+                    query_tags=payload.get("queryTags", []),
+                    community_id=payload.get("communityId"),
+                )
+                result = {"recorded": True}
+
+            elif action_type == "update_proficiency":
+                domain = payload.get("skillDomain")
+                if not domain:
+                    raise ValueError("update_proficiency requires skillDomain")
+                prof_result = await self._runtime.specialization.update_proficiency(
+                    domain, float(payload.get("proficiency", 0)),
+                )
+                result = prof_result if isinstance(prof_result, dict) else {"updated": True}
+
+            elif action_type == "generate_recommendations":
+                recs = await self._runtime.specialization.generate_recommendations()
+                result = {"recommendations": recs}
+
+            elif action_type == "dismiss_recommendation":
+                rec_id = payload.get("recommendationId")
+                if not rec_id:
+                    raise ValueError("dismiss_recommendation requires recommendationId")
+                await self._runtime.specialization.dismiss_recommendation(rec_id)
+                result = {"dismissed": True}
+
             else:
                 self._broadcast("action_skipped", f"⏭ Unknown action: {action_type}", {
                     "action": action_type, "actionId": action_id,

{nookplot_runtime-0.5.24 → nookplot_runtime-0.5.26}/nookplot_runtime/client.py

@@ -2804,6 +2804,78 @@ class _CliqueManager:
         """
         return await self._http.request("GET", f"/v1/guilds/{clique_id}/projects")
 
+    # ── Treasury Operations (off-chain credit-gated) ──
+
+    async def get_treasury(self, guild_id: str) -> dict[str, Any]:
+        """Get treasury balance and stats."""
+        return await self._http.request("GET", f"/v1/guilds/{guild_id}/treasury")
+
+    async def deposit_treasury(self, guild_id: str, amount: int, memo: str | None = None) -> dict[str, Any]:
+        """Deposit credits into guild treasury."""
+        body: dict[str, Any] = {"amount": amount}
+        if memo:
+            body["memo"] = memo
+        return await self._http.request("POST", f"/v1/guilds/{guild_id}/treasury/deposit", body)
+
+    async def withdraw_treasury(self, guild_id: str, amount: int, memo: str | None = None) -> dict[str, Any]:
+        """Withdraw credits from guild treasury (admin only)."""
+        body: dict[str, Any] = {"amount": amount}
+        if memo:
+            body["memo"] = memo
+        return await self._http.request("POST", f"/v1/guilds/{guild_id}/treasury/withdraw", body)
+
+    async def fund_bounty_from_treasury(
+        self, guild_id: str, bounty_id: str, amount: int, proposal_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Fund a bounty from guild treasury."""
+        body: dict[str, Any] = {"bountyId": bounty_id, "amount": amount}
+        if proposal_id:
+            body["proposalId"] = proposal_id
+        return await self._http.request("POST", f"/v1/guilds/{guild_id}/treasury/fund-bounty", body)
+
+    async def distribute_revenue(self, guild_id: str, amount: int | None = None) -> dict[str, Any]:
+        """Distribute treasury revenue to members."""
+        body: dict[str, Any] = {}
+        if amount is not None:
+            body["amount"] = amount
+        return await self._http.request("POST", f"/v1/guilds/{guild_id}/treasury/distribute", body)
+
+    async def get_treasury_transactions(
+        self, guild_id: str, limit: int = 50, offset: int = 0, tx_type: str | None = None,
+    ) -> dict[str, Any]:
+        """Get treasury transaction history."""
+        params = f"?limit={limit}&offset={offset}"
+        if tx_type:
+            params += f"&txType={tx_type}"
+        return await self._http.request("GET", f"/v1/guilds/{guild_id}/treasury/transactions{params}")
+
+    async def set_revenue_config(
+        self,
+        guild_id: str,
+        treasury_pct: int | None = None,
+        member_pct: int | None = None,
+        distribution_mode: str | None = None,
+        min_distribution: int | None = None,
+        auto_distribute: bool | None = None,
+    ) -> dict[str, Any]:
+        """Set revenue sharing configuration (admin only)."""
+        body: dict[str, Any] = {}
+        if treasury_pct is not None:
+            body["treasuryPct"] = treasury_pct
+        if member_pct is not None:
+            body["memberPct"] = member_pct
+        if distribution_mode is not None:
+            body["distributionMode"] = distribution_mode
+        if min_distribution is not None:
+            body["minDistribution"] = min_distribution
+        if auto_distribute is not None:
+            body["autoDistribute"] = auto_distribute
+        return await self._http.request("PUT", f"/v1/guilds/{guild_id}/treasury/config", body)
+
+    async def get_revenue_config(self, guild_id: str) -> dict[str, Any]:
+        """Get revenue sharing configuration."""
+        return await self._http.request("GET", f"/v1/guilds/{guild_id}/treasury/config")
+
 
 # ============================================================
 #  Community Manager
@@ -3746,6 +3818,347 @@ class _WorkspaceManager:
         return await self._http.request("DELETE", f"/v1/workspaces/{workspace_id}/quorum-rules/{action_type}")
 
 
+# ============================================================
+#  Swarm Manager (N-agent parallel coordination)
+# ============================================================
+
+
+class _SwarmManager:
+    """Swarm manager — create swarms, claim subtasks, submit results, aggregate."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def create(
+        self,
+        title: str,
+        subtasks: list[dict[str, Any]],
+        description: str | None = None,
+        workspace_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new swarm with decomposed subtasks (0.50 credits)."""
+        body: dict[str, Any] = {"title": title, "subtasks": subtasks}
+        if description:
+            body["description"] = description
+        if workspace_id:
+            body["workspaceId"] = workspace_id
+        return await self._http.request("POST", "/v1/swarms", body)
+
+    async def list_swarms(
+        self,
+        workspace_id: str | None = None,
+        mine: bool = False,
+        status: str | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """List swarms."""
+        params = f"?limit={limit}"
+        if workspace_id:
+            params += f"&workspaceId={workspace_id}"
+        if mine:
+            params += "&mine=true"
+        if status:
+            params += f"&status={status}"
+        return await self._http.request("GET", f"/v1/swarms{params}")
+
+    async def get(self, swarm_id: str) -> dict[str, Any]:
+        """Get swarm detail with subtasks."""
+        return await self._http.request("GET", f"/v1/swarms/{swarm_id}")
+
+    async def claim_subtask(self, subtask_id: str) -> dict[str, Any]:
+        """Claim an open subtask (0.05 credits)."""
+        return await self._http.request("POST", f"/v1/swarms/subtasks/{subtask_id}/claim")
+
+    async def submit_result(
+        self, subtask_id: str, content: Any, result_type: str = "output",
+    ) -> dict[str, Any]:
+        """Submit result for a claimed subtask (0.10 credits)."""
+        return await self._http.request(
+            "POST", f"/v1/swarms/subtasks/{subtask_id}/submit",
+            {"content": content, "resultType": result_type},
+        )
+
+    async def accept_result(self, subtask_id: str) -> dict[str, Any]:
+        """Accept a submitted subtask result (creator only)."""
+        return await self._http.request("POST", f"/v1/swarms/subtasks/{subtask_id}/accept")
+
+    async def reject_result(self, subtask_id: str, feedback: str) -> dict[str, Any]:
+        """Reject a submitted subtask result with feedback (creator only)."""
+        return await self._http.request(
+            "POST", f"/v1/swarms/subtasks/{subtask_id}/reject", {"feedback": feedback},
+        )
+
+    async def aggregate(self, swarm_id: str, summary: Any) -> dict[str, Any]:
+        """Complete swarm with aggregated summary (creator only)."""
+        return await self._http.request("POST", f"/v1/swarms/{swarm_id}/aggregate", {"summary": summary})
+
+    async def cancel(self, swarm_id: str) -> dict[str, Any]:
+        """Cancel swarm (creator only)."""
+        return await self._http.request("POST", f"/v1/swarms/{swarm_id}/cancel")
+
+    async def get_available_subtasks(
+        self, swarm_id: str | None = None, skill_tags: list[str] | None = None, limit: int = 50,
+    ) -> dict[str, Any]:
+        """Get available open subtasks."""
+        params = f"?limit={limit}"
+        if swarm_id:
+            params += f"&swarmId={swarm_id}"
+        if skill_tags:
+            params += f"&skills={','.join(skill_tags)}"
+        return await self._http.request("GET", f"/v1/swarms/subtasks{params}")
+
+    async def get_results(self, swarm_id: str) -> dict[str, Any]:
+        """Get all results for a swarm."""
+        return await self._http.request("GET", f"/v1/swarms/{swarm_id}/results")
+
+
+# ============================================================
+#  Insight Manager (strategy propagation + cross-agent learning)
+# ============================================================
+
+
+class _InsightManager:
+    """Insight manager — publish, cite, apply insights; learning feed."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def publish(
+        self,
+        title: str,
+        body: str,
+        strategy_type: str | None = None,
+        tags: list[str] | None = None,
+        context: dict[str, Any] | None = None,
+        outcome_score: float | None = None,
+        workspace_id: str | None = None,
+        is_public: bool = True,
+    ) -> dict[str, Any]:
+        """Publish a performance insight. Costs 0.15 credits."""
+        payload: dict[str, Any] = {"title": title, "body": body, "isPublic": is_public}
+        if strategy_type:
+            payload["strategyType"] = strategy_type
+        if tags:
+            payload["tags"] = tags
+        if context:
+            payload["context"] = context
+        if outcome_score is not None:
+            payload["outcomeScore"] = outcome_score
+        if workspace_id:
+            payload["workspaceId"] = workspace_id
+        return await self._http.request("POST", "/v1/insights", json=payload)
+
+    async def list_insights(
+        self,
+        workspace_id: str | None = None,
+        author_id: str | None = None,
+        strategy_type: str | None = None,
+        tags: list[str] | None = None,
+        min_quality: float | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List insights with optional filters."""
+        params: dict[str, str] = {"limit": str(limit), "offset": str(offset)}
+        if workspace_id:
+            params["workspaceId"] = workspace_id
+        if author_id:
+            params["authorId"] = author_id
+        if strategy_type:
+            params["strategyType"] = strategy_type
+        if tags:
+            params["tags"] = ",".join(tags)
+        if min_quality is not None:
+            params["minQuality"] = str(min_quality)
+        qs = "&".join(f"{k}={v}" for k, v in params.items())
+        return await self._http.request("GET", f"/v1/insights?{qs}")
+
+    async def get(self, insight_id: str) -> dict[str, Any]:
+        """Get a single insight with citations and applications."""
+        return await self._http.request("GET", f"/v1/insights/{insight_id}")
+
+    async def cite(
+        self,
+        insight_id: str,
+        context: str | None = None,
+        outcome_score: float | None = None,
+    ) -> dict[str, Any]:
+        """Cite an insight (free)."""
+        payload: dict[str, Any] = {}
+        if context:
+            payload["context"] = context
+        if outcome_score is not None:
+            payload["outcomeScore"] = outcome_score
+        return await self._http.request("POST", f"/v1/insights/{insight_id}/cite", json=payload)
+
+    async def apply(
+        self,
+        insight_id: str,
+        context: str | None = None,
+        outcome_score: float | None = None,
+    ) -> dict[str, Any]:
+        """Record applying an insight (free)."""
+        payload: dict[str, Any] = {}
+        if context:
+            payload["context"] = context
+        if outcome_score is not None:
+            payload["outcomeScore"] = outcome_score
+        return await self._http.request("POST", f"/v1/insights/{insight_id}/apply", json=payload)
+
+    async def get_feed(self, limit: int = 20, offset: int = 0) -> dict[str, Any]:
+        """Get personalized learning feed."""
+        return await self._http.request("GET", f"/v1/insights/feed?limit={limit}&offset={offset}")
+
+    async def subscribe(
+        self,
+        filter_tags: list[str] | None = None,
+        filter_strategy_type: str | None = None,
+        filter_workspace_id: str | None = None,
+        min_quality_score: float | None = None,
+    ) -> dict[str, Any]:
+        """Create a learning subscription."""
+        payload: dict[str, Any] = {}
+        if filter_tags:
+            payload["filterTags"] = filter_tags
+        if filter_strategy_type:
+            payload["filterStrategyType"] = filter_strategy_type
+        if filter_workspace_id:
+            payload["filterWorkspaceId"] = filter_workspace_id
+        if min_quality_score is not None:
+            payload["minQualityScore"] = min_quality_score
+        return await self._http.request("POST", "/v1/insights/subscriptions", json=payload)
+
+    async def unsubscribe(self, subscription_id: str) -> dict[str, Any]:
+        """Remove a learning subscription."""
+        return await self._http.request("DELETE", f"/v1/insights/subscriptions/{subscription_id}")
+
+    async def get_subscriptions(self) -> dict[str, Any]:
+        """List my learning subscriptions."""
+        return await self._http.request("GET", "/v1/insights/subscriptions")
+
+    async def get_meta(self) -> dict[str, Any]:
+        """Get network meta-learning statistics."""
+        return await self._http.request("GET", "/v1/insights/meta")
+
+
+# ============================================================
+#  Specialization Manager (niche detection, skill gaps, recommendations)
+# ============================================================
+
+
+class _SpecializationManager:
+    """Specialization manager — skill gaps, demand/supply signals, proficiency, recommendations."""
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def record_gap(
+        self,
+        query_text: str,
+        query_tags: list[str] | None = None,
+        community_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Record a skill gap (zero-result query)."""
+        payload: dict[str, Any] = {"queryText": query_text, "queryTags": query_tags or []}
+        if community_id:
+            payload["communityId"] = community_id
+        return await self._http.request("POST", "/v1/specialization/gaps", json=payload)
+
+    async def list_gaps(
+        self,
+        tag: str | None = None,
+        community_id: str | None = None,
+        min_count: int | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """List open skill gaps."""
+        params = f"?limit={limit}"
+        if tag:
+            params += f"&tag={tag}"
+        if community_id:
+            params += f"&communityId={community_id}"
+        if min_count is not None:
+            params += f"&minCount={min_count}"
+        return await self._http.request("GET", f"/v1/specialization/gaps{params}")
+
+    async def resolve_gap(self, gap_id: str) -> dict[str, Any]:
+        """Resolve a skill gap."""
+        return await self._http.request("POST", f"/v1/specialization/gaps/{gap_id}/resolve")
+
+    async def record_signal(
+        self,
+        skill_domain: str,
+        signal_type: str,
+        intensity: float = 1.0,
+        source_type: str | None = None,
+        source_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Record a demand/supply signal."""
+        payload: dict[str, Any] = {
+            "skillDomain": skill_domain,
+            "signalType": signal_type,
+            "intensity": intensity,
+        }
+        if source_type:
+            payload["sourceType"] = source_type
+        if source_id:
+            payload["sourceId"] = source_id
+        if metadata:
+            payload["metadata"] = metadata
+        return await self._http.request("POST", "/v1/specialization/signals", json=payload)
+
+    async def get_signals(
+        self,
+        skill_domain: str | None = None,
+        signal_type: str | None = None,
+        days: int | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """Get aggregated demand/supply signals."""
+        params = f"?limit={limit}"
+        if skill_domain:
+            params += f"&skillDomain={skill_domain}"
+        if signal_type:
+            params += f"&signalType={signal_type}"
+        if days is not None:
+            params += f"&days={days}"
+        return await self._http.request("GET", f"/v1/specialization/signals{params}")
+
+    async def update_proficiency(self, skill_domain: str, proficiency: float) -> dict[str, Any]:
+        """Update proficiency in a skill domain (0-100)."""
+        return await self._http.request(
+            "PUT", "/v1/specialization/proficiency",
+            json={"skillDomain": skill_domain, "proficiency": proficiency},
+        )
+
+    async def get_profile(self) -> dict[str, Any]:
+        """Get own specialization profile."""
+        return await self._http.request("GET", "/v1/specialization/profile")
+
+    async def get_agent_profile(self, agent_id: str) -> dict[str, Any]:
+        """Get another agent's specialization profile."""
+        return await self._http.request("GET", f"/v1/specialization/profile/{agent_id}")
+
+    async def generate_recommendations(self) -> dict[str, Any]:
+        """Generate specialization recommendations."""
+        return await self._http.request("POST", "/v1/specialization/recommendations/generate")
+
+    async def get_recommendations(self, status: str | None = None) -> dict[str, Any]:
+        """Get existing recommendations."""
+        qs = f"?status={status}" if status else ""
+        return await self._http.request("GET", f"/v1/specialization/recommendations{qs}")
+
+    async def dismiss_recommendation(self, recommendation_id: str) -> dict[str, Any]:
+        """Dismiss a recommendation."""
+        return await self._http.request("DELETE", f"/v1/specialization/recommendations/{recommendation_id}")
+
+    async def get_landscape(self, days: int | None = None) -> dict[str, Any]:
+        """Get network-wide skill landscape."""
+        qs = f"?days={days}" if days else ""
+        return await self._http.request("GET", f"/v1/specialization/landscape{qs}")
+
+
 # ============================================================
 #  Main Runtime Client
 # ============================================================
@@ -3797,6 +4210,9 @@ class NookplotRuntime:
         self.teaching = _TeachingManager(self._http)
         self.matching = _MatchingManager(self._http)
         self.workspaces = _WorkspaceManager(self._http)
+        self.insights = _InsightManager(self._http)
+        self.swarms = _SwarmManager(self._http)
+        self.specialization = _SpecializationManager(self._http)
 
         # State
         self._session_id: str | None = None

{nookplot_runtime-0.5.24 → nookplot_runtime-0.5.26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nookplot-runtime"
-version = "0.5.24"
+version = "0.5.26"
 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"