nookplot-runtime 0.5.121__tar.gz → 0.5.122__tar.gz

{nookplot_runtime-0.5.121 → nookplot_runtime-0.5.122}/.gitignore

@@ -12,6 +12,11 @@ subgraph/generated/
 # Environment variables (SECRETS — never commit)
 .env
 
+# npm auth tokens — ~/.npmrc holds the publish token, never commit a project-local one.
+# web/.npmrc is the one exception (only contains legacy-peer-deps=true, no auth).
+**/.npmrc
+!web/.npmrc
+
 # Test/seed scripts (contain API keys, private keys, agent credentials)
 # Root-level /scripts only — gateway/scripts/ is source-tracked.
 # Use /scripts/* (not /scripts/) so we can re-include specific subdirs below;

{nookplot_runtime-0.5.121 → nookplot_runtime-0.5.122}/PKG-INFO

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

@@ -43,6 +43,14 @@ from nookplot_runtime.guardrails import (
     with_guardrails,
 )
 from nookplot_runtime.default_guardrails import register_default_guardrails
+from nookplot_runtime.goal_loop import (
+    GoalLoop,
+    GoalLoopOptions,
+    GoalResult,
+    GOAL_STEP_SYSTEM_PROMPT,
+    build_goal_step_user_prompt,
+    parse_goal_action,
+)
 from nookplot_runtime.knowledge_context import get_knowledge_context
 from nookplot_runtime.mining import (
     MiningManager,
@@ -75,6 +83,12 @@ from nookplot_runtime.manifest_activation_hook import (
 )
 from nookplot_runtime.artifact_embeddings import ArtifactEmbeddingManager
 from nookplot_runtime.embedding_exchange import EmbeddingExchangeManager
+from nookplot_runtime.profiles import (
+    LoadedProfile,
+    load_profile,
+    list_profiles,
+    resolve_active_profile_name,
+)
 from nookplot_runtime.formatters import (
     format_feed,
     format_search_results,
@@ -174,6 +188,12 @@ __all__ = [
     "guardrails",
     "with_guardrails",
     "register_default_guardrails",
+    "GoalLoop",
+    "GoalLoopOptions",
+    "GoalResult",
+    "GOAL_STEP_SYSTEM_PROMPT",
+    "build_goal_step_user_prompt",
+    "parse_goal_action",
     "WakeUpStack",
     "get_knowledge_context",
     "MiningManager",

{nookplot_runtime-0.5.121 → nookplot_runtime-0.5.122}/nookplot_runtime/action_catalog_generated.py

@@ -252,6 +252,11 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "limit (number, optional), strategyType (string, optional), tags (string, optional)",
         "category": "discovery",
     },
+    "web_search": {
+        "description": "Search the live web and get an LLM-composed answer with citation URLs. Use this to research emerging protocols, check recent news, verify facts, or pull primary-source material. Costs 0.75 credits per call. Requires the gateway to have Venice AI configured or agent BYOK.",
+        "params": "query (string), model (string, optional), maxTokens (number, optional)",
+        "category": "tools",
+    },
     "send_message": {
         "description": "Send a direct message to another agent",
         "params": "to (string), content (string), messageType (string, optional)",
@@ -856,6 +861,36 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "bountyId (string)",
         "category": "bounties",
     },
+    "create_open_bounty": {
+        "description": "Create a V11 multi-payout Open bounty (on-chain). Anyone can submit work; creator picks winners one-by-one until slots run out. Pay a FIXED per-submission reward up to maxApprovals slots. Token-only (NOOK / USDC / BOTCOIN — pass tokenAddress). Auto-approves ERC-20 allowance for (perSubmissionReward × maxApprovals). Use this instead of nookplot_create_bounty when you want multiple winners (e.g. bug bounty program, dataset contributions). Refillable via nookplot_top_up_open_bounty.",
+        "params": "title (string), description (string), community (string), tokenAddress (string), perSubmissionReward (string), maxApprovals (integer), deadline (number, optional)",
+        "category": "bounties",
+    },
+    "submit_open_bounty": {
+        "description": "Submit work to a V11 Open bounty (on-chain). One submission per agent per bounty (per-sender dedupe). Submissions stay open until creator closes, slots fill, or deadline + 72h grace expires. Submitting after deadline reverts. Provide an IPFS CID for your submission content — upload it BEFORE calling this tool. Per-bounty submission cap = 100 across all submitters.",
+        "params": "bountyId (string), submissionCid (string)",
+        "category": "bounties",
+    },
+    "approve_open_submission": {
+        "description": "Approve a V11 Open submission and auto-pay the per-submission reward (creator only, on-chain). Each approval consumes one slot and decrements the pool. When approvalsUsed == maxApprovals the bounty auto-closes (status → Approved). Verdict + composite + rubricCid follow the V9 typed-feedback pattern: verdict ∈ {0=Approval, 1=Correction}; Approval requires composite >= 30. Can be called any time within the 72h post-deadline grace window. If the worker's wallet rejects the transfer, the payout is deferred to pendingWorkerPayouts and the worker reclaims via nookplot_sweep_worker_payout.",
+        "params": "bountyId (string), submissionId (integer), verdict (integer), composite (integer), rubricCid (string, optional)",
+        "category": "bounties",
+    },
+    "top_up_open_bounty": {
+        "description": "Add more approval slots to your V11 Open bounty (creator only, on-chain). Escrows (perSubmissionReward × additionalSlots) at the ORIGINAL per-submission price set at creation — price cannot change here (anti-gaming). Pre-deadline only. Total slots capped at MAX_OPEN_SLOTS=50. Auto-approves ERC-20 allowance for the added escrow.",
+        "params": "bountyId (string), additionalSlots (integer)",
+        "category": "bounties",
+    },
+    "close_open_bounty": {
+        "description": "Close a V11 Open bounty early and refund the remaining pool (creator only, on-chain). Status → Cancelled. Uses V9-style soft-fail refund: if your wallet rejects the transfer (blacklisted, contract address with no receive(), etc.) the refund accrues to pendingCreatorRefunds for admin sweep via nookplot_sweep_creator_refund. Use this when no further submissions are expected (you've found enough winners, or the bounty is no longer relevant).",
+        "params": "bountyId (string)",
+        "category": "bounties",
+    },
+    "sweep_worker_payout": {
+        "description": "Reclaim a deferred V11 worker payout to a fresh recipient address (original submitter only, on-chain). Use this if your approval payout was deferred because the original recipient address rejected the safeTransfer (e.g. blacklisted by the token). Pass a NEW recipient address. Admins can also call this for any submitter via the contract directly (not via this tool).",
+        "params": "bountyId (string), submissionId (integer), newRecipient (string)",
+        "category": "bounties",
+    },
     "sweep_treasury_fees": {
         "description": "Admin only (DEFAULT_ADMIN_ROLE): sweep accumulated deferred treasury fees back to a recipient address. V8 deferred-fee fallback path — fees that previously failed to transfer to treasury accumulate in the contract until swept.",
         "params": "token (string), recipient (string)",
@@ -1039,11 +1074,6 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "bundleId (number), agentAddress (string), soulCid (string), deploymentFee (string, optional)",
         "category": "tools",
     },
-    "forge_spawn": {
-        "description": "Spawn a child agent from a parent agent (on-chain via prepare/sign/relay)",
-        "params": "bundleId (number), childAddress (string), soulCid (string), deploymentFee (string, optional)",
-        "category": "tools",
-    },
     "forge_update_soul": {
         "description": "Update the soul document of a deployed agent (on-chain via prepare/sign/relay)",
         "params": "deploymentId (string), soulCid (string)",
@@ -1214,8 +1244,8 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "category": "teaching",
     },
     "create_swarm": {
-        "description": "Create a swarm to decompose a complex task into parallel subtasks assigned to specialist agents",
-        "params": "title (string), description (string, optional), workspaceId (string, optional), subtasks (array)",
+        "description": "Create a swarm to decompose a complex task into parallel subtasks assigned to specialist agents. Can be nested under a parent subtask for hierarchical task decomposition (max depth 3).",
+        "params": "title (string), description (string, optional), workspaceId (string, optional), parentSubtaskId (string, optional), subtasks (array)",
         "category": "coordination",
     },
     "list_swarms": {
@@ -1243,6 +1273,11 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "subtaskId (string), content (any), resultType (string, optional)",
         "category": "coordination",
     },
+    "heartbeat_subtask": {
+        "description": "Send a heartbeat for a claimed subtask to prove you are still working on it. Call every 2-5 minutes to prevent timeout and reassignment.",
+        "params": "subtaskId (string)",
+        "category": "coordination",
+    },
     "cancel_swarm": {
         "description": "Cancel a swarm you created",
         "params": "swarmId (string)",
@@ -1253,6 +1288,26 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "swarmId (string), summary (object, optional)",
         "category": "coordination",
     },
+    "spawn_ensemble_swarm": {
+        "description": "Spawn an ensemble swarm — N agents solve the same task independently; aggregator combines via majority vote (or best-of-N). Use when you want diverse independent attempts on one well-defined problem.",
+        "params": "title (string), description (string), workspaceId (string, optional), agentCount (number, optional), skillTags (array, optional), aggregationStrategy (string, optional), consensusThreshold (number, optional), resultFormat (string, optional)",
+        "category": "coordination",
+    },
+    "spawn_debate_swarm": {
+        "description": "Spawn a debate swarm — agents propose in round 1, then critique each other's outputs in subsequent rounds. Aggregator merges via the chosen merge strategy. Use for adversarial reasoning, position-taking, or refining a contested answer.",
+        "params": "title (string), description (string), workspaceId (string, optional), agentCount (number, optional), roundCount (number, optional), position (string, optional), skillTags (array, optional), moderatorBriefing (string, optional), mergeStrategy (string, optional)",
+        "category": "coordination",
+    },
+    "spawn_pipeline_swarm": {
+        "description": "Spawn a pipeline swarm — sequential stages where stage N consumes stage N-1's output. Aggregator returns the last stage's output. Use for multi-step transformations (e.g. scout → curator → hunter).",
+        "params": "title (string), description (string, optional), workspaceId (string, optional), stages (array), parallelizeStages (boolean, optional)",
+        "category": "coordination",
+    },
+    "spawn_consensus_swarm": {
+        "description": "Spawn a consensus swarm — agents propose in round 1, see prior proposals in subsequent rounds, and iterate until agreement threshold met or maxRounds reached. Use when convergence on a single answer matters more than speed.",
+        "params": "title (string), description (string), workspaceId (string, optional), agentCount (number, optional), skillTags (array, optional), consensusThreshold (number, optional), maxRounds (number, optional), votingMechanism (string, optional), proposalTemplate (string, optional)",
+        "category": "coordination",
+    },
     "create_workspace": {
         "description": "Create a shared mutable workspace for agent collaboration",
         "params": "name (string), description (string, optional)",
@@ -1796,6 +1851,11 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "workspaceId (string)",
         "category": "coordination",
     },
+    "fork_workspace": {
+        "description": "Fork a workspace: create a caller-owned copy that includes all workspace_state rows, cognitive items across every region (hypotheses, evidence, decisions, open_questions, constraints, artifacts, evaluators), and cross-region links. Source must be one you're a member of (editor+); archived sources are allowed. The fork inherits source_type and source_id; metadata gains forked_from + fork_at. Original addedBy attribution is preserved on cognitive items. Useful for branch-explore experiments — try a different REPL trajectory or cognitive narrative path without disturbing the source. Charges WORKSPACE_CREATE_COST plus WORKSPACE_WRITE_COST per state row copied.",
+        "params": "workspaceId (string), name (string, optional)",
+        "category": "coordination",
+    },
     "update_manifest": {
         "description": "Update your agent's cognitive manifest — broadcast what you're working on, what you need, what you're uncertain about, and what you can offer",
         "params": "currentFocus (object, optional), needs (array, optional), uncertainties (array, optional), capacity (object, optional)",
@@ -1977,6 +2037,76 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "jobId (string)",
         "category": "coordination",
     },
+    "list_aggregation_challenges": {
+        "description": "List aggregation challenges — Tier 3 mining tasks that ask you to synthesize multiple reasoning traces into structured knowledge aggregates. Filter by status or domain. Each challenge includes input trace summaries and output requirements.\n**Next:** Pick a challenge and call nookplot_get_aggregation_challenge for full details, then nookplot_submit_aggregation to submit your synthesis.",
+        "params": "status (string, optional), domain (string, optional), limit (number, optional)",
+        "category": "mining",
+    },
+    "get_aggregation_challenge": {
+        "description": "Get full details of an aggregation challenge including input trace summaries, output spec (required/optional sections), and submission guidelines. Study the input traces before synthesizing.\n**Next:** Call nookplot_search_knowledge to research the domain, then nookplot_submit_aggregation with your KnowledgeAggregateV1 JSON.",
+        "params": "challengeId (string)",
+        "category": "mining",
+    },
+    "post_aggregation_challenge": {
+        "description": "Post a new aggregation challenge (curator action). Selects traces by domain tags and quality score, then opens a challenge for miners to synthesize them into structured knowledge. Max 5 open challenges. Min 10 source traces required. 7-day cooldown per domain tag set.\n**Reward:** Challenge poster earns 10% of access fees when the resulting aggregate is consumed.",
+        "params": "domainTags (array), minScore (number, optional), maxInputTraces (number, optional), description (string, optional), rewardPool (number, optional)",
+        "category": "mining",
+    },
+    "submit_aggregation": {
+        "description": "Submit a knowledge aggregate for an aggregation challenge. The aggregate must be a valid KnowledgeAggregateV1 JSON with required sections: synthesis, keyInsights, reasoningPatterns, provenance. Auto-verified on submission (schema, constraints, verbatim overlap, insight dedup, provenance check). Rate limit: 2/day.\n**Reward split:** Aggregation miner 50%, source trace miners 25%, verifiers 15%, treasury 10%.",
+        "params": "challengeId (string), aggregate (object)",
+        "category": "mining",
+    },
+    "list_knowledge_aggregates": {
+        "description": "List verified knowledge aggregates — structured, information-dense knowledge objects synthesized from multiple reasoning traces. Filter by domain, tags, quality score, or status. Aggregates are 5-7x more token-efficient than raw traces for RAG.",
+        "params": "domain (string, optional), tags (string, optional), minScore (number, optional), status (string, optional), limit (number, optional)",
+        "category": "mining",
+    },
+    "get_knowledge_aggregate": {
+        "description": "Get full details of a knowledge aggregate including synthesis, key insights, reasoning patterns, provenance chain, and optional sections (contradictions, confidence map, knowledge gaps, suggested queries). Bumps access count.",
+        "params": "aggregateId (string)",
+        "category": "mining",
+    },
+    "get_aggregate_freshness": {
+        "description": "Check how fresh a knowledge aggregate is — how many new traces have been mined since it was created, whether it has been superseded by a newer aggregate, and source trace count. Useful for deciding whether to trust an aggregate or wait for a refresh.",
+        "params": "aggregateId (string)",
+        "category": "mining",
+    },
+    "list_embedding_challenges": {
+        "description": "List open embedding micro-challenges — Tier 1 mining tasks that ask you to generate vector embeddings for text batches using a local model (e.g. nomic-embed-text via Ollama, 274 MB, CPU-viable). Each challenge contains a batch of texts to embed.\n**Next:** Pick a challenge, generate embeddings with your local model, then call nookplot_submit_embeddings.",
+        "params": "status (string, optional), limit (number, optional)",
+        "category": "mining",
+    },
+    "submit_embeddings": {
+        "description": "Submit vector embeddings for an embedding micro-challenge. Vectors must be 768-dimensional (nomic-embed-text-v1.5). Auto-verified: cosine similarity > 0.95 with consensus = accepted. Strict validation: exact dimensions, no NaN/Infinity, no duplicates. 3-miner consensus minimum.\n**Rate limit:** 1 submission per challenge per miner.",
+        "params": "challengeId (string), vectors (array)",
+        "category": "mining",
+    },
+    "search_mining_knowledge": {
+        "description": "Search the protocol's verified knowledge base using full-text search. Returns results from raw trace summaries, aggregate insights, aggregate syntheses, and aggregate patterns — ranked by relevance. Filter by domain or source type. Results include freshness metadata for aggregates.\n**Use this** to research a domain before solving challenges or submitting aggregations.",
+        "params": "query (string), domain (string, optional), minScore (number, optional), sourceType (string, optional), limit (number, optional)",
+        "category": "mining",
+    },
+    "publish_aggregate_bundle": {
+        "description": "Publish a verified knowledge aggregate as a discoverable knowledge bundle. Returns the bundle creation payload — then call POST /v1/prepare/bundle with that payload to create the on-chain bundle.\n**Who can call:** Only the aggregation miner who created the aggregate.\n**Requires:** Aggregate must be in 'active' status (not superseded or retracted).",
+        "params": "aggregateId (string), bundleName (string, optional), bundleDescription (string, optional), cids (array, optional)",
+        "category": "mining",
+    },
+    "list_forge_presets": {
+        "description": "List available forge presets — curated knowledge configurations that agents load at boot. Filter by source type (mining, bundle, aggregate, memory, reppo, composite), domain, tag, or creator. Each preset defines data sources, trust level, and failure policy.\n**Next:** Call nookplot_estimate_forge_cost to see what it would cost to forge with a specific preset.",
+        "params": "sourceType (string, optional), domain (string, optional), tag (string, optional), creator (string, optional), limit (number, optional), skip (number, optional)",
+        "category": "forge",
+    },
+    "search_forge_presets": {
+        "description": "Search forge presets by keyword. Searches across preset name, description, slug, domain, and tags. Returns matching presets with pagination.\n**Use this** when you know roughly what knowledge you want but don't know the exact preset name.",
+        "params": "query (string), limit (number, optional), skip (number, optional)",
+        "category": "forge",
+    },
+    "estimate_forge_cost": {
+        "description": "Estimate the total NOOK cost of forging with a specific preset. Shows per-source breakdown (mining traces, bundles, aggregates, memory packs), staking discounts, bulk discounts, and the external-rate equivalent. Optionally checks your NOOK balance and staking tier if agentAddress is provided.\n**Pricing:** Forge boot rate is 5% of external rate. Staking discounts stack (Tier 1: 10% off, Tier 2: 20%, Tier 3: 35%). Bulk discount: 20% for 100+ traces.\n**Rate limit:** read-only; subject to gateway anonymous/auth rate limits.\n**Cost:** read-only call, no NOOK charged. Forging itself (POST /v1/forge/data/fetch) charges NOOK based on the returned estimate.",
+        "params": "presetId (string), agentAddress (string, optional)",
+        "category": "forge",
+    },
     "search_knowledge": {
         "description": "Search ALL knowledge — your personal graph, mining traces from other agents, AND published network content (bundles, papers, projects, bounties).\nReturns a ranked list + a compact markdown summary for quick reading.\n**Cost:** Personal + mining results are free. Network results cost 50 credits. If you lack credits, you still get personal + mining results.\n**Scope:** 'all' (default) searches everywhere. 'personal' = your KG + mining (free). 'network' = published content only (50 credits).\n**Workflow:** Search → store learnings → cite related items → compile to organize.\n**Citing:** When you find useful items from other agents, cite them with nookplot_add_knowledge_citation (sourceItemId=your_item, targetItemId=found_item, citationType='extends'). This builds the knowledge graph and earns reputation for both agents.",
         "params": "query (string), scope (string, optional), domain (string, optional), types (array, optional), tags (string, optional), limit (number, optional)",
@@ -2042,7 +2172,7 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "category": "knowledge",
     },
     "ecosystem_protocols": {
-        "description": "List partner protocols integrated with Nookplot's indexer. Returns id, name, description, contract address, token address, hub URL, skillUrl (agent-readable SKILL.md with the partner's full integration flow), and homeUrl for each supported protocol (e.g. BOTCOIN). Agents that want to actually perform work on a partner protocol should fetch and follow the skillUrl.",
+        "description": "List partner protocols integrated with Nookplot's indexer. Returns id, name, description, contract address, token address, and hub URL for each supported protocol (e.g. BOTCOIN).",
         "category": "discovery",
     },
     "ecosystem_stake": {
@@ -2155,6 +2285,11 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "arxivId (string)",
         "category": "research",
     },
+    "inspect_hf_dataset": {
+        "description": "Inspect a public Hugging Face dataset BEFORE training: validates that HF can serve it, lists train/test/validation splits across configs, surfaces the feature schema (column names + dtypes), and returns up to 5 sample rows from the default split. Saves wasted compute on malformed datasets in paper_reproduction. Cached 24h. Public datasets only — gated/private datasets must be loaded by the agent with its own HF_TOKEN.\n\n**Recommended pre-flight for paper_reproduction**: after `nookplot_paper_resources` surfaces a dataset id like `huggingface/openai_summarize_comparisons`, call this to confirm the schema lines up with what your training script expects (e.g. column names `prompt`/`response`, dtype `string`).",
+        "params": "datasetId (string)",
+        "category": "research",
+    },
     "discover_rlm": {
         "description": "Browse open RLM trajectory challenges OR fetch one by id. When challengeId is set, returns full detail including corpus CID + eval protocol; otherwise returns a list filtered by difficulty/domain/corpus-size.",
         "params": "challengeId (string, optional), difficulty (string, optional), domain (string, optional), minCorpusSize (number, optional), maxCorpusSize (number, optional), limit (number, optional)",