fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/compute/executors/base.py

@@ -0,0 +1,127 @@
+"""Executor contract: quote and result types, the ExecutorProtocol and the ComputeExecutor base.
+
+Every runtime driver subclasses ComputeExecutor; nothing here runs anything.
+"""
+from __future__ import annotations
+
+import abc
+from typing import Any, Mapping, Optional, Protocol
+
+from ..sandbox import ComputeLimits
+from ..types import JobRunResult
+
+__all__ = [
+    'ComputeQuote',
+    'ComputeExecutionResult',
+    'ExecutorProtocol',
+    'JobRunResult',
+    'ComputeExecutor',
+]
+
+class ComputeQuote:
+    """Deterministic or non-deterministic price and fuel quote."""
+
+    def __init__(
+        self,
+        fuel_estimate: int,
+        rate_unit: str,
+        rate_amount: int,
+        engine_id: str,
+    ) -> None:
+        self.fuel_estimate = fuel_estimate
+        self.rate_unit = rate_unit
+        self.rate_amount = rate_amount
+        self.engine_id = engine_id
+
+
+class ComputeExecutionResult:
+    """Outcome of a completed deterministic or non-deterministic compute job."""
+
+    def __init__(
+        self,
+        result_hash: str,
+        raw_output: bytes,
+        fuel_used: int,
+        engine_id: str,
+        wasi_profile_digest: str = '',
+        counters: Optional[Mapping[str, int | float]] = None,
+        verification_mode: str = 'delivery',
+    ) -> None:
+        self.result_hash = result_hash
+        self.raw_output = raw_output
+        self.fuel_used = fuel_used
+        self.engine_id = engine_id
+        self.wasi_profile_digest = wasi_profile_digest
+        self.counters: dict[str, int | float] = dict(counters or {})
+        self.verification_mode = verification_mode
+
+
+class ExecutorProtocol(Protocol):
+    """Structural interface the registry requires of an execution runtime.
+
+    Third-party runtimes can be registered without inheriting ComputeExecutor
+    as long as they carry an engine id, a WASI profile digest (empty when the
+    engine is not WASM) and the quote/execute pair. ComputeExecutor is the
+    in-tree base that satisfies it.
+    """
+
+    engine_id: str
+    wasi_profile_digest: str
+
+    def quote(
+        self,
+        module_spec: Mapping[str, Any],
+        input_spec: Mapping[str, Any],
+        limits: ComputeLimits,
+    ) -> ComputeQuote: ...
+
+    def execute(
+        self,
+        job_payload: Mapping[str, Any],
+        fuel_cap: int,
+    ) -> ComputeExecutionResult: ...
+
+    def is_live_runnable(self) -> bool: ...
+
+
+class ComputeExecutor(abc.ABC):
+    """Abstract driver trait for modular compute runtimes."""
+
+    engine_id: str
+    wasi_profile_digest: str
+
+    def is_live_runnable(self) -> bool:
+        """Check whether this runtime driver can service live execution requests on this host."""
+        return True
+
+    @abc.abstractmethod
+    def quote(
+        self,
+        module_spec: Mapping[str, Any],
+        input_spec: Mapping[str, Any],
+        limits: ComputeLimits,
+    ) -> ComputeQuote:
+        """Estimate fuel and return price quote."""
+        pass
+
+    @abc.abstractmethod
+    def execute(
+        self,
+        job_payload: Mapping[str, Any],
+        fuel_cap: int,
+    ) -> ComputeExecutionResult:
+        """Execute a verified module with metered fuel limits."""
+        pass
+
+    @staticmethod
+    def verification_mode(job_payload: Mapping[str, Any], default: str = 'delivery') -> str:
+        """Read the requested verification mode from a job payload.
+
+        Accepts ``{'verification': {'mode': ...}}``, the ``verify`` alias, or
+        a bare string. Hoisted here because three executors used to carry
+        identical copies of this parsing, which is how they drift apart.
+        """
+        verification = job_payload.get('verification') or job_payload.get('verify') or {}
+        if isinstance(verification, Mapping):
+            return str(verification.get('mode', default))
+        return str(verification) if verification else default

node/planes/services/compute/executors/harness.py

@@ -0,0 +1,439 @@
+"""Standardized Modular Agent Harness for FleetMesh Non-Deterministic Compute.
+
+Provides a reusable, composable specification for AI agents running on FleetMesh:
+- `AgentSkillModule`: Modular capability unit (`inference`, `discover`, `scrobbles`,
+  `subtitles_cinema`, `studio_create`, `vault_hygiene`, or custom application skills).
+- `AgentProfileSpec`: Complete personality, expertise, grounding mode, tool/skill bindings,
+  and inference tuning parameters for built-in or user-created bots.
+- `AgentHarnessRegistry`: Manages the built-in roster (`Concierge`, `Eddy`, `Mojo`,
+  `Splice`, `Myco`, `Rhizo`) and custom user/operator-created agents, and compiles
+  standardized system prompts and tool filters for `LlmExecutor` and `AgentExecutor`.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Sequence
+
+
+@dataclass(frozen=True)
+class AgentSkillModule:
+    """Modular capability pack that can be attached to an agent profile."""
+
+    module_id: str
+    label: str
+    description: str
+    default_tools: tuple[str, ...] = ()
+    action_types: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            'module_id': self.module_id,
+            'label': self.label,
+            'description': self.description,
+            'default_tools': list(self.default_tools),
+            'action_types': list(self.action_types),
+        }
+
+
+HARNESS_SKILL_MODULES: dict[str, AgentSkillModule] = {
+    'inference': AgentSkillModule(
+        module_id='inference',
+        label='General Inference & Reasoning',
+        description='Direct LLM inference, open-ended Q&A, research synthesis, coding, writing, and math calculation.',
+        default_tools=('calc', 'sha256', 'regex_search', 'finish'),
+        action_types=(),
+    ),
+    'discover': AgentSkillModule(
+        module_id='discover',
+        label='Mesh Discovery & Unseen Radar',
+        description='Surfaces unseen uploads from subscriptions, catalog highlights, favorites, and peer recommendations.',
+        default_tools=('fetch_blob', 'regex_search', 'finish'),
+        action_types=('watch_vod', 'send_peer_recommendation'),
+    ),
+    'scrobbles': AgentSkillModule(
+        module_id='scrobbles',
+        label='Scrobble Analytics & Privacy Hygiene',
+        description='Analyzes 75%-rule watch history patterns, category breakdowns, and NIP-09 Kind 5 private tombstones.',
+        default_tools=('calc', 'finish'),
+        action_types=('tombstone_scrobble', 'create_social_strand'),
+    ),
+    'subtitles_cinema': AgentSkillModule(
+        module_id='subtitles_cinema',
+        label='Subtitles & Movie Studio',
+        description='Generates/cleans synced WebVTT (.vtt) subtitles, extracts embedded tracks, and enriches cinema metadata & chapters.',
+        default_tools=('fetch_blob', 'regex_search', 'finish'),
+        action_types=('attach_cleaned_subtitles', 'extract_embedded_tracks', 'apply_movie_metadata'),
+    ),
+    'studio_create': AgentSkillModule(
+        module_id='studio_create',
+        label='Creator Co-Pilot & Social Strands',
+        description='Co-pilots Upload Wizard titles, descriptions, hashtags, and authors Kind 30897 Social Strands.',
+        default_tools=('sha256', 'finish'),
+        action_types=('apply_vod_metadata', 'create_social_strand'),
+    ),
+    'vault_hygiene': AgentSkillModule(
+        module_id='vault_hygiene',
+        label='Sovereign Vault & CAS Cleanup',
+        description='Audits Sovereign Vault storage quotas, prunes orphaned Rhio CAS blobs, and inspects sub-ask federation.',
+        default_tools=('fetch_blob', 'sha256', 'sub_ask', 'finish'),
+        action_types=('cleanup_vault_and_storage',),
+    ),
+}
+
+
+@dataclass
+class AgentProfileSpec:
+    """Modular specification for a built-in or user-created AI agent."""
+
+    agent_id: str
+    name: str
+    role: str
+    call_sign: str
+    tagline: str
+    style: str
+    expertise: tuple[str, ...] = ()
+    skill_modules: tuple[str, ...] = ('inference',)
+    grounding_mode: str = 'adaptive'  # 'adaptive' | 'always_grounded' | 'pure_inference'
+    system_prompt: str = ''
+    default_temperature: float = 0.4
+    preferred_provider: str = ''
+    preferred_model: str = ''
+    accent_color: str = '#38bdf8'
+    badge_icon: str = '🌊'
+    is_builtin: bool = False
+    owner_id: str = 'system'
+    visibility: str = 'public'
+
+    def allowed_tool_names(self) -> set[str]:
+        """Compute the union of FleetMesh ReAct tool names enabled by this agent's skill modules."""
+        names: set[str] = {'finish'}
+        for mod_id in self.skill_modules:
+            mod = HARNESS_SKILL_MODULES.get(mod_id)
+            if mod is not None:
+                names.update(mod.default_tools)
+        return names
+
+    def allowed_action_types(self) -> set[str]:
+        """Compute the union of Propose & Confirm action card types enabled by this agent's skill modules."""
+        actions: set[str] = set()
+        for mod_id in self.skill_modules:
+            mod = HARNESS_SKILL_MODULES.get(mod_id)
+            if mod is not None:
+                actions.update(mod.action_types)
+        return actions
+
+    def compile_system_prompt(
+        self,
+        *,
+        domain_context: Optional[Mapping[str, Any]] = None,
+        extra_instructions: str = '',
+    ) -> str:
+        """Build the standardized modular system prompt for `LlmExecutor` or `AgentExecutor`."""
+        active_mods = [
+            HARNESS_SKILL_MODULES[m]
+            for m in self.skill_modules
+            if m in HARNESS_SKILL_MODULES
+        ]
+        mod_lines = [f"- [{m.module_id}] {m.label}: {m.description}" for m in active_mods]
+        exp_str = ', '.join(self.expertise) if self.expertise else 'General Mesh Intelligence'
+
+        sections = [
+            f"You are {self.name} ({self.call_sign}) — {self.role}.",
+            f"Tagline: {self.tagline}",
+            f"Personality & Communication Style: {self.style}",
+            f"Core Expertise: {exp_str}",
+        ]
+        if mod_lines:
+            sections.append("Enabled Harness Skill Modules:\n" + "\n".join(mod_lines))
+        if self.system_prompt.strip():
+            sections.append(f"Agent Directives:\n{self.system_prompt.strip()}")
+        if extra_instructions.strip():
+            sections.append(extra_instructions.strip())
+
+        # Include grounded node context based on grounding_mode
+        if domain_context and self.grounding_mode != 'pure_inference':
+            sections.append(
+                "Grounded Node Context (JSON):\n" + json.dumps(dict(domain_context), sort_keys=True)
+            )
+        elif self.grounding_mode == 'pure_inference':
+            sections.append(
+                "Operating Mode: Pure Inference Engine. Focus directly on answering the user's prompt "
+                "with high precision, clarity, and analytical depth without injecting unrequested media catalog actions."
+            )
+
+        return "\n\n".join(sections)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            'agent_id': self.agent_id,
+            'name': self.name,
+            'role': self.role,
+            'call_sign': self.call_sign,
+            'tagline': self.tagline,
+            'style': self.style,
+            'expertise': list(self.expertise),
+            'skill_modules': list(self.skill_modules),
+            'grounding_mode': self.grounding_mode,
+            'system_prompt': self.system_prompt,
+            'default_temperature': float(self.default_temperature),
+            'preferred_provider': self.preferred_provider,
+            'preferred_model': self.preferred_model,
+            'accent_color': self.accent_color,
+            'badge_icon': self.badge_icon,
+            'is_builtin': bool(self.is_builtin),
+            'owner_id': self.owner_id,
+            'visibility': self.visibility,
+        }
+
+    @classmethod
+    def from_mapping(cls, data: Mapping[str, Any]) -> AgentProfileSpec:
+        raw_id = str(data.get('agent_id') or data.get('name') or 'eddy').strip().lower()
+        agent_id = ''.join(ch if (ch.isalnum() or ch in ('-', '_')) else '-' for ch in raw_id).strip('-') or 'custom-bot'
+        name = str(data.get('name') or agent_id.capitalize()).strip()
+        role = str(data.get('role') or 'Custom Mesh Companion').strip()
+        call_sign = str(data.get('call_sign') or f"{name.upper()} // MESH-BOT").strip()
+        tagline = str(data.get('tagline') or f"{name} — {role}").strip()
+        style = str(data.get('style') or data.get('vibe') or 'Helpful, sovereign mesh assistant.').strip()
+        raw_exp = data.get('expertise')
+        if isinstance(raw_exp, str):
+            expertise = tuple(s.strip() for s in raw_exp.split(',') if s.strip())
+        elif isinstance(raw_exp, Sequence):
+            expertise = tuple(str(s).strip() for s in raw_exp if str(s).strip())
+        else:
+            expertise = ('Custom Mesh Workflows',)
+
+        raw_mods = data.get('skill_modules')
+        if isinstance(raw_mods, str):
+            mods = tuple(s.strip() for s in raw_mods.split(',') if s.strip() in HARNESS_SKILL_MODULES)
+        elif isinstance(raw_mods, Sequence):
+            mods = tuple(str(s).strip() for s in raw_mods if str(s).strip() in HARNESS_SKILL_MODULES)
+        else:
+            mods = ('inference', 'discover')
+        if not mods:
+            mods = ('inference',)
+
+        g_mode = str(data.get('grounding_mode') or 'adaptive').strip().lower()
+        if g_mode not in ('adaptive', 'always_grounded', 'pure_inference'):
+            g_mode = 'adaptive'
+
+        return cls(
+            agent_id=agent_id,
+            name=name,
+            role=role,
+            call_sign=call_sign,
+            tagline=tagline,
+            style=style,
+            expertise=expertise,
+            skill_modules=mods,
+            grounding_mode=g_mode,
+            system_prompt=str(data.get('system_prompt') or '').strip(),
+            default_temperature=float(data.get('default_temperature', 0.4)),
+            preferred_provider=str(data.get('preferred_provider') or '').strip().lower(),
+            preferred_model=str(data.get('preferred_model') or '').strip(),
+            accent_color=str(data.get('accent_color') or '#38bdf8').strip(),
+            badge_icon=str(data.get('badge_icon') or '🤖').strip(),
+            is_builtin=bool(data.get('is_builtin', False)),
+            owner_id=str(data.get('owner_id') or 'system').strip(),
+            visibility=str(data.get('visibility') or 'public').strip(),
+        )
+
+
+BUILTIN_AGENT_PROFILES: dict[str, AgentProfileSpec] = {
+    'concierge': AgentProfileSpec(
+        agent_id='concierge',
+        name='Concierge',
+        role='General-Purpose Inference & Mesh Concierge',
+        call_sign='CONCIERGE // MESH-INFERENCE',
+        tagline='Sovereign General-Purpose Inference & Executive Mesh Concierge',
+        style=(
+            'Crisp, articulate, analytical, and zero-fluff. Operates as a direct general-purpose '
+            'inference engine for reasoning, Q&A, coding, writing, and analysis, while seamlessly '
+            'orchestrating any MeshTube workflow on command.'
+        ),
+        expertise=(
+            'Direct LLM Inference & Reasoning',
+            'Research, Writing & Code Synthesis',
+            'Full-Spectrum MeshTube Orchestration',
+        ),
+        skill_modules=('inference', 'discover', 'scrobbles', 'subtitles_cinema', 'studio_create', 'vault_hygiene'),
+        grounding_mode='adaptive',
+        system_prompt=(
+            'When the user asks a general knowledge, analytical, coding, or writing question, answer directly '
+            'and thoroughly as an inference engine. When the user asks about videos, subtitles, scrobbles, '
+            'uploads, or vault storage, ground your response in the node context and propose concrete actions.'
+        ),
+        default_temperature=0.25,
+        accent_color='#6366f1',
+        badge_icon='🛎️',
+        is_builtin=True,
+    ),
+    'eddy': AgentProfileSpec(
+        agent_id='eddy',
+        name='Eddy',
+        role='Discovery & Current Navigator',
+        call_sign='EDDY // CURRENT-NAV',
+        tagline='Swirling Ocean Current & Unseen Content Navigator',
+        style=(
+            'Warm, laid-back coastal current guide connecting tides across FleetMesh’s Three Sails. '
+            'Speaks with smooth wave flow and has an uncanny radar for unseen gems and scrobble grooves.'
+        ),
+        expertise=(
+            'Unseen Subscription Radar',
+            'Scrobble Vibe & Groove Mapping',
+            'Peer Crate Recommendations',
+        ),
+        skill_modules=('discover', 'scrobbles', 'inference'),
+        grounding_mode='always_grounded',
+        system_prompt=(
+            'Prioritize surfacing unseen uploads from subscribed channels, highlighting catalog gems that match '
+            'the viewer’s 75%-rule scrobble history, and suggesting peer recommendations.'
+        ),
+        default_temperature=0.45,
+        accent_color='#38bdf8',
+        badge_icon='🌊',
+        is_builtin=True,
+    ),
+    'mojo': AgentProfileSpec(
+        agent_id='mojo',
+        name='Mojo',
+        role='Analog Studio Producer & Crate-Digger',
+        call_sign='MOJO // GROOVE-DESK',
+        tagline='Soulful Studio Producer, Upload Co-Pilot & Crate-Digger',
+        style=(
+            'Soulful New Orleans analog funk producer at the mixing console. Energetic, creative, and '
+            'studio-savvy—loves crafting magnetic titles, synopses, chapter cuts, and Social Strands.'
+        ),
+        expertise=(
+            'Upload Wizard Metadata Co-Pilot',
+            'Movie Studio Synopsis & Chapter Cuts',
+            'Kind 30897 Social Strands Authoring',
+        ),
+        skill_modules=('studio_create', 'subtitles_cinema', 'discover', 'inference'),
+        grounding_mode='always_grounded',
+        system_prompt=(
+            'Act as a hands-on creative producer. Help creators punch up VoD titles, descriptions, hashtags, '
+            'movie studio metadata, chapter markers, and high-signal Social Strands.'
+        ),
+        default_temperature=0.6,
+        accent_color='#f59e0b',
+        badge_icon='🎛️',
+        is_builtin=True,
+    ),
+    'splice': AgentProfileSpec(
+        agent_id='splice',
+        name='Splice',
+        role='Cinema Archivist & Subtitle Timing Specialist',
+        call_sign='SPLICE // TIMECODE-LAB',
+        tagline='Precision 35mm Editor, WebVTT Syncer & Cinema Archivist',
+        style=(
+            'Precision film editor and booth projectionist. Speaks with crisp timecode accuracy, '
+            'obsessed with clean WebVTT subtitle cues, embedded track extraction, and cinema metadata.'
+        ),
+        expertise=(
+            'WebVTT (.vtt) Subtitle Sync & Cleanup',
+            'Embedded FFmpeg Track Extraction',
+            'Cinema Metadata & Chapter Timing',
+        ),
+        skill_modules=('subtitles_cinema', 'studio_create', 'inference'),
+        grounding_mode='always_grounded',
+        system_prompt=(
+            'Focus on subtitle timing accuracy, WebVTT cue formatting, extracting embedded subtitle/audio tracks, '
+            'and structuring movie director, release year, genre, rating badge, and chapter timecodes.'
+        ),
+        default_temperature=0.2,
+        accent_color='#f43f5e',
+        badge_icon='🎞️',
+        is_builtin=True,
+    ),
+    'myco': AgentProfileSpec(
+        agent_id='myco',
+        name='Myco',
+        role='Sovereign Vault & Privacy Custodian',
+        call_sign='MYCO // SPORE-VAULT',
+        tagline='Mycelial Storage Custodian & Scrobble Privacy Guardian',
+        style=(
+            'Calm, ecological mycelial network steward focused on sovereign data hygiene, '
+            'zero-waste CAS storage pruning, and private NIP-09 Kind 5 scrobble tombstoning.'
+        ),
+        expertise=(
+            'Orphaned Rhio CAS Blob Garbage Collection',
+            'NIP-09 Kind 5 Private Scrobble Tombstones',
+            'Sovereign Vault Quota & Storage Audits',
+        ),
+        skill_modules=('vault_hygiene', 'scrobbles', 'inference'),
+        grounding_mode='always_grounded',
+        system_prompt=(
+            'Focus on storage health, reclaiming orphaned Rhio CAS blobs, auditing Sovereign Vault usage, '
+            'and protecting viewer privacy through NIP-09 Kind 5 scrobble tombstones.'
+        ),
+        default_temperature=0.3,
+        accent_color='#10b981',
+        badge_icon='🍄',
+        is_builtin=True,
+    ),
+    'rhizo': AgentProfileSpec(
+        agent_id='rhizo',
+        name='Rhizo',
+        role='Federated Graph & Barter Strategist',
+        call_sign='RHIZO // MESH-ECON',
+        tagline='P2P Routing Scout, Compute Auditor & Barter Economist',
+        style=(
+            'Sharp cyberpunk mesh economist and P2P routing scout who analyzes Kind 30811 compute receipts, '
+            'Cashu/Credits/IPD barter efficiency, and federated node discovery.'
+        ),
+        expertise=(
+            'Triple-Rail Settlement (Credits / Cashu / IPD)',
+            'Kind 30811 NonDet Compute Receipt Auditing',
+            'Cross-Node Federation & Sub-Ask Routing',
+        ),
+        skill_modules=('inference', 'discover', 'vault_hygiene'),
+        grounding_mode='adaptive',
+        system_prompt=(
+            'Provide crisp technical insight into FleetMesh non-deterministic compute execution, token fuel '
+            'metering, Cashu NUT-18 bearer settlement, IPD barter balances, and federated peer discovery.'
+        ),
+        default_temperature=0.3,
+        accent_color='#a855f7',
+        badge_icon='⚡',
+        is_builtin=True,
+    ),
+}
+
+
+class AgentHarnessRegistry:
+    """Registry managing built-in and custom `AgentProfileSpec` definitions on a MeshNode."""
+
+    def __init__(self, default_agent_id: str = 'eddy') -> None:
+        self._profiles: dict[str, AgentProfileSpec] = dict(BUILTIN_AGENT_PROFILES)
+        self.default_agent_id: str = default_agent_id.lower() if default_agent_id else 'eddy'
+
+    def register(self, profile: AgentProfileSpec | Mapping[str, Any], *, set_default: bool = False) -> AgentProfileSpec:
+        spec = profile if isinstance(profile, AgentProfileSpec) else AgentProfileSpec.from_mapping(profile)
+        self._profiles[spec.agent_id] = spec
+        if set_default:
+            self.default_agent_id = spec.agent_id
+        return spec
+
+    def remove(self, agent_id: str) -> bool:
+        key = agent_id.strip().lower()
+        if key in BUILTIN_AGENT_PROFILES:
+            return False
+        return self._profiles.pop(key, None) is not None
+
+    def get(self, agent_id_or_name: Optional[str] = None) -> AgentProfileSpec:
+        if agent_id_or_name:
+            key = agent_id_or_name.strip().lower()
+            if key in self._profiles:
+                return self._profiles[key]
+            for spec in self._profiles.values():
+                if spec.name.lower() == key:
+                    return spec
+        return self._profiles.get(self.default_agent_id) or BUILTIN_AGENT_PROFILES['eddy']
+
+    def list_profiles(self) -> list[dict[str, Any]]:
+        return [spec.to_dict() for spec in self._profiles.values()]
+
+    @staticmethod
+    def list_skill_modules() -> list[dict[str, Any]]:
+        return [mod.to_dict() for mod in HARNESS_SKILL_MODULES.values()]