Source code for fleetmesh_core.services.dvm

"""NIP-90 ingress (profile `nip90-ingress`): the bytes a DVM gateway speaks.

Three things are pinned here and in vectors/nip90.json, nothing else:

  1. A request (kind 5000-5999) parses to one `ParsedRequest`: `i` tags are
     inputs, `param` tags a str->str map (last wins), `output` the mime,
     `bid` msat, `relays` only ws/wss entries.
  2. A parsed request maps to a job descriptor by executor, chosen in the
     order zk, llm, bacalhau, agent, then WASM - from the kind first, then
     the `executor`/`engine` params. The WASM job's `input.sha256` is the
     sha256 of the canonical JSON of {prompt, inputs, params}.
  3. Feedback is kind 7000 with tags e, p, status[, extra]; a result is
     kind request+1000 with tags e, p, request (the request event in the
     protocol's canonical form - constants.json `canonical.form`),
     then amount / commit when non-zero.

The job descriptor is what the gateway hands its compute compartment; a
second node may run a different executor set but MUST produce these
descriptors for these requests, since the result's `request` tag and
`commit` are compared against them downstream.
"""
from __future__ import annotations

import json
import math
from typing import Any, Mapping, Optional, Sequence, TypedDict

from ..crypto import crypto

from ..storage import store
from ..wire.interfaces import EventLike, NostrEvent

FEEDBACK_KIND: int = 7000
REQUEST_RANGE: tuple[int, int] = (5000, 6000)
RESULT_RANGE: tuple[int, int] = (6000, 7000)
FEEDBACK_STATES: tuple[str, ...] = ('payment-required', 'processing', 'error', 'success', 'partial')

# The kinds the reference gateway answers by default. A node may narrow this
# in its configuration; it must not answer a kind it does not list.
DEFAULT_KINDS: tuple[int, ...] = (5000, 5001, 5050, 5055, 5100, 5200, 5300, 5905)

ZK_KINDS: tuple[int, ...] = (5055, 5905)
ZK_NAMES: tuple[str, ...] = ('zk-verify-groth16', 'zk', 'zkvm')
LLM_KIND: int = 5050
LLM_NAMES: tuple[str, ...] = ('llm', 'ai', 'inference', 'vllm', 'ollama')
TRANSCODE_KIND: int = 5201
MEDIA_NAMES: tuple[str, ...] = ('ffmpeg', 'media-transcode', 'transcode', 'video-transcode')
BACALHAU_NAMES: tuple[str, ...] = ('bacalhau', 'docker', 'container')
AGENT_NAMES: tuple[str, ...] = ('agent', 'react')
DEFAULT_FUEL: int = 2500000000
DEFAULT_MODEL: str = 'meta-llama/Llama-3.3-70B-Instruct'


def _int_param(params: Mapping[str, str], key: str, default: int) -> int:
    """An integer param; a non-integer value is a refusal, not a rounding."""
    raw = params.get(key)
    if raw is None:
        return default
    try:
        return int(str(raw).strip())
    except ValueError:
        raise DVMError('param %s must be an integer, got %r' % (key, raw))


[docs]class DVMError(ValueError): pass
[docs]class ParsedRequest(TypedDict): id: str pubkey: str kind: int content: str inputs: list[list[str]] params: dict[str, str] output_mime: str bid_msat: int relays: list[str]
[docs]class ZkProof(TypedDict, total=False): pi_a: Sequence[str] pi_b: Sequence[Sequence[str]] pi_c: Sequence[str] protocol: str curve: str
[docs]class ZkInput(TypedDict, total=False): request_id: str curve: str proof: ZkProof | Mapping[str, Any] public_inputs: list[Any] vk: Any vk_sha256: str
[docs]class LLMSampling(TypedDict, total=False): max_tokens: int temperature: float top_p: float seed: int
[docs]class LLMGrammar(TypedDict, total=False): type: str definition: str json_schema: Any response_format: str guided_regex: str
[docs]class LLMMessage(TypedDict, total=False): role: str content: str
[docs]class WasmModule(TypedDict, total=False): runtime: str sha256: str url: str
[docs]class WasmInput(TypedDict, total=False): request_id: str sha256: str raw: str
[docs]class StorageMount(TypedDict, total=False): cas_provider: str source_cid: str mount_path: str
[docs]class MediaInput(TypedDict, total=False): request_id: str profile: str source_url: str source_sha256: str source_tree_root: str duration_sec: float duration_limit_sec: float start_sec: float is_audio: bool width: int height: int video_bitrate_kbps: int audio_bitrate_kbps: int audio_sample_rate_hz: int vod_id: str source_path: str output_path: str allow_synthetic: bool sha256: str data: str type: str start: float duration: float
[docs]class JobVerify(TypedDict, total=False): mode: str proof_system: str sample_rate: float
[docs]class Job(TypedDict, total=False): executor: str module: WasmModule | Mapping[str, Any] input: ZkInput | WasmInput | MediaInput | Mapping[str, Any] verify: JobVerify | Mapping[str, Any] fuel_max: int model: str prompt: str messages: list[LLMMessage | Mapping[str, Any]] sampling: LLMSampling | Mapping[str, Any] grammar: LLMGrammar | Mapping[str, Any] engine: str image: str entrypoint: list[str] storage_mounts: list[StorageMount | Mapping[str, Any]] resources: Mapping[str, int | str | float] task: str max_steps: int wasi_profile: str nonce: str blob_store: Any blossom_servers: Sequence[str]
[docs]def is_request(ev: EventLike) -> bool: k = ev.get('kind', 0) return isinstance(k, int) and REQUEST_RANGE[0] <= k < REQUEST_RANGE[1]
[docs]def is_result(ev: EventLike) -> bool: k = ev.get('kind', 0) return isinstance(k, int) and RESULT_RANGE[0] <= k < RESULT_RANGE[1]
[docs]def result_kind(request_kind: int) -> int: return request_kind + 1000
[docs]def parse_request(ev: EventLike) -> ParsedRequest: inputs: list[list[str]] = [] params: dict[str, str] = {} relays: list[str] = [] output_mime = 'text/plain' bid_msat = 0 tags = ev.get('tags', []) for t in tags if isinstance(tags, list) else []: if not t or not isinstance(t, list): continue name = t[0] if name == 'i' and len(t) > 1: inputs.append([str(x) for x in t[1:]]) elif name == 'param' and len(t) > 2: params[str(t[1])] = str(t[2]) elif name == 'output' and len(t) > 1: output_mime = str(t[1]) elif name == 'bid' and len(t) > 1: msats = store.ascii_int(t[1]) if msats is not None: bid_msat = msats elif name == 'relays': relays.extend(str(r) for r in t[1:] if str(r).startswith(('ws://', 'wss://'))) kind = ev.get('kind', 5000) return { 'id': str(ev.get('id', '')), 'pubkey': str(ev.get('pubkey', '')), 'kind': kind if isinstance(kind, int) else 5000, 'content': str(ev.get('content', '')), 'inputs': inputs, 'params': params, 'output_mime': output_mime, 'bid_msat': bid_msat, 'relays': relays, }
# ---- executor selection -------------------------------------------------------- def _names(p: ParsedRequest) -> tuple[str, str]: return p['params'].get('executor', '').lower(), p['params'].get('engine', '').lower()
[docs]def is_zk(p: ParsedRequest) -> bool: e, g = _names(p) return p['kind'] in ZK_KINDS or e in ZK_NAMES or g in ZK_NAMES
[docs]def is_llm(p: ParsedRequest) -> bool: e, g = _names(p) return p['kind'] == LLM_KIND or e in LLM_NAMES or g in LLM_NAMES
[docs]def is_bacalhau(p: ParsedRequest) -> bool: e, g = _names(p) return (5900 <= p['kind'] < 6000 and not is_zk(p)) or e in BACALHAU_NAMES or g in BACALHAU_NAMES
[docs]def is_agent(p: ParsedRequest) -> bool: e, g = _names(p) return e in AGENT_NAMES or g in AGENT_NAMES
[docs]def is_media(p: ParsedRequest) -> bool: e, g = _names(p) return p['kind'] == TRANSCODE_KIND or e in MEDIA_NAMES or g in MEDIA_NAMES
[docs]def executor_of(p: ParsedRequest) -> str: if is_zk(p): return 'zk' if is_llm(p): return 'llm' if is_media(p): return 'ffmpeg' if is_bacalhau(p): return 'bacalhau' if is_agent(p): return 'agent' return 'wasm'
# ---- job descriptors ----------------------------------------------------------- def _json_or(text: str, open_ch: str) -> Any: if text.startswith(open_ch): try: return json.loads(text) except ValueError: return text return text
[docs]def zk_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job: """Groth16 proof verification: proof, public inputs and vk from content or `i` tags.""" exec_param, _ = _names(p) target = 'zk-verify-groth16' if ('groth16' in exec_param or p['kind'] in ZK_KINDS) else (exec_param or 'zk-verify-groth16') curve = p['params'].get('curve', 'bn254') proof: Any = None inputs: list[Any] = [] vk: Any = None vk_sha256: Optional[str] = p['params'].get('vk_sha256') content = p['content'].strip() if content.startswith('{') and content.endswith('}'): try: c = json.loads(content) except ValueError: c = None if isinstance(c, dict): proof = c.get('proof') pi = c.get('public_inputs', []) inputs = list(pi) if isinstance(pi, list) else [pi] if 'curve' in c: curve = str(c['curve']) if 'vk' in c: vk = c['vk'] if 'vk_sha256' in c: vk_sha256 = str(c['vk_sha256']) for inp in p['inputs']: if len(inp) < 2: continue val, role = inp[0], inp[1].lower() if role in ('proof', 'zk-proof'): proof = _json_or(val, '{') elif role in ('inputs', 'public_inputs'): got = _json_or(val, '[') inputs = got if isinstance(got, list) else [val] elif role in ('input', 'public_input'): inputs.append(val) elif role in ('vk', 'verification_key'): vk = _json_or(val, '{') zk_input: ZkInput = {'request_id': p['id'], 'curve': curve, 'proof': proof or {}, 'public_inputs': inputs} if vk is not None: zk_input['vk'] = vk if vk_sha256 is not None: zk_input['vk_sha256'] = vk_sha256 return { 'executor': target, 'module': {'runtime': target, 'sha256': crypto.sha256(('nip90-zk-verify-%s' % curve).encode())}, 'input': zk_input, 'verify': {'mode': 'proof', 'proof_system': target}, 'fuel_max': fuel_max, }
[docs]def llm_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job: """An inference request: messages, sampling and an optional grammar.""" params = p['params'] model = params.get('model', DEFAULT_MODEL) prompt = p['content'] messages: list[LLMMessage | Mapping[str, Any]] = [] for inp in p['inputs']: if not inp: continue val = inp[0] role = inp[1].lower() if len(inp) > 1 else 'text' if role == 'json' and val.startswith('{'): try: j = json.loads(val) except ValueError: continue if isinstance(j, dict): if 'messages' in j and isinstance(j['messages'], list): messages.extend(j['messages']) elif 'prompt' in j: prompt = str(j['prompt']) elif role in ('text', 'prompt') and not prompt: prompt = val if not messages and prompt: messages = [{'role': 'user', 'content': prompt}] sampling: LLMSampling = { 'max_tokens': _int_param(params, 'max_tokens', 512), 'temperature': float(params.get('temperature', 0.7)), 'top_p': float(params.get('top_p', 1.0)), } if 'seed' in params: seed = store.ascii_int(params['seed']) if seed is not None: sampling['seed'] = seed grammar: LLMGrammar = {} if 'schema' in params: sv = params['schema'] grammar['type'] = 'json_schema' grammar['definition'] = sv grammar['json_schema'] = _json_or(sv, '{') elif params.get('response_format') == 'json_object': grammar['type'] = 'json_schema' grammar['definition'] = '{"type": "object"}' grammar['response_format'] = 'json_object' elif 'response_format' in params: grammar['response_format'] = params['response_format'] if 'regex' in params: grammar['type'] = 'regex' grammar['definition'] = params['regex'] grammar['guided_regex'] = params['regex'] verify = params.get('verify', 'schema-bounds' if ('schema' in params or 'response_format' in params) else 'delivery') return { 'executor': 'llm', 'model': model, 'prompt': prompt, 'messages': messages, 'sampling': sampling, 'grammar': grammar, 'verify': {'mode': verify}, 'fuel_max': fuel_max, }
[docs]def bacalhau_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job: """A container job: image, entrypoint, Blossom-mounted inputs, resources.""" params = p['params'] entry = params.get('entrypoint', '/bin/sh -c') mounts: list[StorageMount | Mapping[str, Any]] = [ {'cas_provider': 'blossom', 'source_cid': inp[0], 'mount_path': inp[2] if len(inp) > 2 else '/inputs'} for inp in p['inputs'] if inp ] return { 'executor': 'bacalhau', 'engine': 'docker', 'image': params.get('image', 'alpine:latest'), 'entrypoint': entry.split(), 'storage_mounts': mounts, 'resources': { 'cpu': _int_param(params, 'cpu', 2), 'gpu': _int_param(params, 'gpu', 0), 'memory_gib': float(params.get('memory_gib', 4.0)), 'timeout_seconds': _int_param(params, 'timeout', 300), }, 'verify': {'mode': params.get('verify', 'delivery')}, 'fuel_max': fuel_max, }
[docs]def agent_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job: """A ReAct agent task with a step cap.""" return { 'executor': 'agent', 'task': p['content'], 'max_steps': _int_param(p['params'], 'max_steps', 25), 'verify': {'mode': 'delivery'}, 'fuel_max': fuel_max, }
[docs]def media_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job: """A NIP-90 kind=5201 video/audio transcode job for FfmpegTranscodeExecutor.""" params = p['params'] source_url = params.get('source_url', '').strip() source_sha256 = params.get('source_sha256', '').strip().lower() source_tree_root = params.get('source_tree_root', '').strip().lower() for inp in p['inputs']: if not inp: continue val = inp[0].strip() role = inp[1].lower() if len(inp) > 1 else 'url' if role in ('url', 'source_url') and not source_url: source_url = val elif role in ('sha256', 'source_sha256', 'hash') and not source_sha256: source_sha256 = val.lower() elif role == 'tree_root' and not source_tree_root: source_tree_root = val.lower() elif not source_url and val.startswith(('http://', 'https://', 'file://', '/')): source_url = val elif not source_sha256 and len(val) == 64: source_sha256 = val.lower() content_obj: Mapping[str, Any] = {} content_str = p['content'].strip() if content_str.startswith('{'): try: loaded = json.loads(content_str) except (ValueError, TypeError) as e: raise DVMError(f'malformed JSON content: {e}') if not isinstance(loaded, dict): raise DVMError('JSON content must be an object') content_obj = loaded if not source_url and isinstance(content_obj.get('source_url'), str): source_url = content_obj['source_url'] if not source_sha256 and isinstance(content_obj.get('source_sha256'), str): source_sha256 = content_obj['source_sha256'].lower() if not source_tree_root and isinstance(content_obj.get('source_tree_root'), str): source_tree_root = content_obj['source_tree_root'].lower() profile = str(params.get('profile') or content_obj.get('profile') or '720p') try: duration_sec = float(params.get('duration_sec') or content_obj.get('duration_sec') or 0.0) duration_limit_sec_raw = params.get('duration_limit_sec') or content_obj.get('duration_limit_sec') duration_limit_sec: Optional[float] = float(duration_limit_sec_raw) if duration_limit_sec_raw is not None else None start_sec = float(params.get('start_sec') or content_obj.get('start_sec') or 0.0) except (ValueError, TypeError) as e: raise DVMError(f'invalid media timing parameter: {e}') if ( not math.isfinite(duration_sec) or not math.isfinite(start_sec) or (duration_limit_sec is not None and not math.isfinite(duration_limit_sec)) ): raise DVMError('media timing parameters must be finite numbers') width = _int_param(params, 'width', int(content_obj.get('width') or 0)) height = _int_param(params, 'height', int(content_obj.get('height') or 0)) video_bitrate_kbps = _int_param(params, 'video_bitrate_kbps', int(content_obj.get('video_bitrate_kbps') or 0)) audio_bitrate_kbps = _int_param(params, 'audio_bitrate_kbps', int(content_obj.get('audio_bitrate_kbps') or 0)) audio_sample_rate_hz = _int_param(params, 'audio_sample_rate_hz', int(content_obj.get('audio_sample_rate_hz') or 0)) is_audio = str(params.get('is_audio') or content_obj.get('is_audio') or '').lower() in ('1', 'true', 'yes') vod_id = str(params.get('vod_id') or content_obj.get('vod_id') or '') input_spec: MediaInput = { 'request_id': p['id'], 'profile': profile, 'source_url': source_url, 'source_sha256': source_sha256, 'source_tree_root': source_tree_root, 'duration_sec': duration_sec, 'start_sec': start_sec, 'is_audio': is_audio, } if duration_limit_sec is not None: input_spec['duration_limit_sec'] = duration_limit_sec if width > 0: input_spec['width'] = width if height > 0: input_spec['height'] = height if video_bitrate_kbps > 0: input_spec['video_bitrate_kbps'] = video_bitrate_kbps if audio_bitrate_kbps > 0: input_spec['audio_bitrate_kbps'] = audio_bitrate_kbps if audio_sample_rate_hz > 0: input_spec['audio_sample_rate_hz'] = audio_sample_rate_hz if vod_id: input_spec['vod_id'] = vod_id if isinstance(content_obj.get('source_path'), str): input_spec['source_path'] = content_obj['source_path'] if isinstance(content_obj.get('output_path'), str): input_spec['output_path'] = content_obj['output_path'] if str(params.get('allow_synthetic') or content_obj.get('allow_synthetic') or '').lower() in ('1', 'true', 'yes'): input_spec['allow_synthetic'] = True canon_inp = json.dumps(input_spec, sort_keys=True, separators=(',', ':')) input_spec['sha256'] = source_sha256 if len(source_sha256) == 64 else crypto.sha256(canon_inp.encode('utf-8')) return { 'executor': 'ffmpeg', 'engine': 'ffmpeg', 'module': { 'runtime': 'ffmpeg', 'type': 'ffmpeg', 'sha256': crypto.sha256(('nip90-media-transcode-%s' % profile).encode('utf-8')), }, 'input': input_spec, 'verify': {'mode': params.get('verify', 'delivery')}, 'fuel_max': fuel_max, }
[docs]def wasm_job(p: ParsedRequest, executor: str = 'wasm', fuel_max: int = DEFAULT_FUEL) -> Job: """The deterministic WASM job. The module is named by the requester (`param module <sha256>`, optional `param module_url`); with none named there is nothing real to run and a gateway refuses rather than inventing.""" encoded = json.dumps({'prompt': p['content'], 'inputs': p['inputs'], 'params': p['params']}, sort_keys=True, separators=(',', ':')) module: WasmModule = {'runtime': executor} sha = p['params'].get('module', '').strip().lower() if sha: module['sha256'] = sha if p['params'].get('module_url'): module['url'] = p['params']['module_url'] return { 'executor': executor, 'module': module, 'input': {'request_id': p['id'], 'sha256': crypto.sha256(encoded.encode()), 'raw': encoded}, 'wasi_profile': 'fleetmesh-wasi-v1', 'nonce': p['id'], 'verify': {'mode': 'none'}, 'fuel_max': fuel_max, }
[docs]def request_to_job(ev: EventLike, executor: str = 'wasm', fuel_max: int = DEFAULT_FUEL) -> Job: """Map a NIP-90 request into the job descriptor the mesh runs.""" p = parse_request(ev) which = executor_of(p) if which == 'zk': return zk_job(p, fuel_max) if which == 'llm': return llm_job(p, fuel_max) if which == 'ffmpeg': return media_job(p, fuel_max) if which == 'bacalhau': return bacalhau_job(p, fuel_max) if which == 'agent': return agent_job(p, fuel_max) return wasm_job(p, executor, fuel_max)
# ---- the events a gateway emits -----------------------------------------------
[docs]def feedback(signer_sk: str, request_ev: EventLike, status: str, now: int, extra: str = '', extra_tags: Optional[Sequence[Sequence[str]]] = None) -> NostrEvent: """Kind 7000: tags e, p, status[, extra]; content is extra or the status.""" if status not in FEEDBACK_STATES: raise DVMError('unknown feedback status %r' % status) tags: list[list[str]] = [['e', str(request_ev.get('id', ''))], ['p', str(request_ev.get('pubkey', ''))], ['status', status]] if extra: tags[-1].append(extra) for xt in extra_tags or []: if xt: tags.append([str(x) for x in xt]) return store.make_signed_event(signer_sk, now, FEEDBACK_KIND, tags, extra or status)
[docs]def result(signer_sk: str, request_ev: EventLike, content: str, now: int, amount_msat: int = 0, commit: str = '', extra_tags: Optional[Sequence[Sequence[str]]] = None) -> NostrEvent: """Kind request+1000: tags e, p, request, then amount / commit / extras.""" k = request_ev.get('kind', 5000) tags: list[list[str]] = [['e', str(request_ev.get('id', ''))], ['p', str(request_ev.get('pubkey', ''))], ['request', crypto.canonical(request_ev).decode()]] if amount_msat > 0: tags.append(['amount', str(int(amount_msat))]) if commit: tags.append(['commit', commit]) for xt in extra_tags or []: if xt: tags.append([str(x) for x in xt]) return store.make_signed_event(signer_sk, now, result_kind(k if isinstance(k, int) else 5000), tags, content)