mppi-protocol 0.1.0__py3-none-any.whl

mppi/v1/mppi_pb2_grpc.py

@@ -0,0 +1,185 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from mppi.v1 import mppi_pb2 as mppi_dot_v1_dot_mppi__pb2
+
+GRPC_GENERATED_VERSION = '1.84.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in mppi/v1/mppi_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class ChatStub:
+    """Binary protobuf is the v1 transport. Semantic requirements, including scalar
+    presence, widths, directions and accounting rules, are in docs/protocol.md.
+    A successfully parsed message is not proof of payment authority.
+
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Completions = channel.unary_stream(
+                '/mppi.v1.Chat/Completions',
+                request_serializer=mppi_dot_v1_dot_mppi__pb2.CompleteRequest.SerializeToString,
+                response_deserializer=mppi_dot_v1_dot_mppi__pb2.ChatChunk.FromString,
+                _registered_method=True)
+
+
+class ChatServicer:
+    """Binary protobuf is the v1 transport. Semantic requirements, including scalar
+    presence, widths, directions and accounting rules, are in docs/protocol.md.
+    A successfully parsed message is not proof of payment authority.
+
+    """
+
+    def Completions(self, request, context):
+        """One request, provider JSON payloads, then one definitive final record when
+        available. Cancellation and transport failure may prevent final delivery.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_ChatServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Completions': grpc.unary_stream_rpc_method_handler(
+                    servicer.Completions,
+                    request_deserializer=mppi_dot_v1_dot_mppi__pb2.CompleteRequest.FromString,
+                    response_serializer=mppi_dot_v1_dot_mppi__pb2.ChatChunk.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'mppi.v1.Chat', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('mppi.v1.Chat', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class Chat:
+    """Binary protobuf is the v1 transport. Semantic requirements, including scalar
+    presence, widths, directions and accounting rules, are in docs/protocol.md.
+    A successfully parsed message is not proof of payment authority.
+
+    """
+
+    @staticmethod
+    def Completions(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(
+            request,
+            target,
+            '/mppi.v1.Chat/Completions',
+            mppi_dot_v1_dot_mppi__pb2.CompleteRequest.SerializeToString,
+            mppi_dot_v1_dot_mppi__pb2.ChatChunk.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+
+class ControlStub:
+    """Missing associated documentation comment in .proto file."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Session = channel.stream_stream(
+                '/mppi.v1.Control/Session',
+                request_serializer=mppi_dot_v1_dot_mppi__pb2.ControlMessage.SerializeToString,
+                response_deserializer=mppi_dot_v1_dot_mppi__pb2.ControlMessage.FromString,
+                _registered_method=True)
+
+
+class ControlServicer:
+    """Missing associated documentation comment in .proto file."""
+
+    def Session(self, request_iterator, context):
+        """The actual authenticated stream owns one session attachment. No prompts or
+        inference output travel on this stream. Vouchers have no per-message ACK.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_ControlServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Session': grpc.stream_stream_rpc_method_handler(
+                    servicer.Session,
+                    request_deserializer=mppi_dot_v1_dot_mppi__pb2.ControlMessage.FromString,
+                    response_serializer=mppi_dot_v1_dot_mppi__pb2.ControlMessage.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'mppi.v1.Control', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('mppi.v1.Control', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class Control:
+    """Missing associated documentation comment in .proto file."""
+
+    @staticmethod
+    def Session(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(
+            request_iterator,
+            target,
+            '/mppi.v1.Control/Session',
+            mppi_dot_v1_dot_mppi__pb2.ControlMessage.SerializeToString,
+            mppi_dot_v1_dot_mppi__pb2.ControlMessage.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

mppi_protocol/__init__.py

@@ -0,0 +1,45 @@
+"""Shared MPPI primitives; runtime boundaries live in dedicated typed modules."""
+
+from .accounting import AccountingTransition, RunAccounting, RunStatus, report_transition
+from .amounts import (
+    MAX_UINT64,
+    RATE_SCALE,
+    Rates,
+    TokenCounts,
+    cumulative_usage,
+    decimal_uint64,
+    funding_amount,
+    priced_numerator,
+    remaining_funding_tokens,
+    required_coverage,
+    top_up_total,
+    uint64,
+)
+from .catalog import Catalog, CatalogRow, parse_catalog, publish_catalog, validate_model
+from .errors import ValidationCode, ValidationError
+
+__all__ = [
+    "MAX_UINT64",
+    "RATE_SCALE",
+    "AccountingTransition",
+    "Catalog",
+    "CatalogRow",
+    "Rates",
+    "RunAccounting",
+    "RunStatus",
+    "TokenCounts",
+    "ValidationCode",
+    "ValidationError",
+    "cumulative_usage",
+    "decimal_uint64",
+    "funding_amount",
+    "parse_catalog",
+    "priced_numerator",
+    "publish_catalog",
+    "remaining_funding_tokens",
+    "report_transition",
+    "required_coverage",
+    "top_up_total",
+    "uint64",
+    "validate_model",
+]

mppi_protocol/_observers.py

@@ -0,0 +1,121 @@
+"""Bounded, best-effort lifecycle observers; never a payment control path."""
+
+from collections import deque
+from collections.abc import Callable
+from copy import deepcopy
+from dataclasses import dataclass, fields, is_dataclass
+from inspect import iscoroutinefunction
+from threading import Condition, Thread
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ObserverStats:
+    delivered: int
+    dropped: int
+    failed: int
+    queued: int
+
+
+@dataclass(frozen=True, slots=True)
+class HookError:
+    """Sanitized SDK boundary error; no prompt, credentials or upstream body."""
+
+    operation: str
+    code: str
+    session_id: bytes | None = None
+    run_id: bytes | None = None
+
+
+class Observers:
+    """One worker, at most 64 queued records/1 MiB, plus one running callback.
+
+    Records are copied before enqueue. Full queues drop the newest record.
+    close discards pending records and never waits for caller code. Python
+    cannot terminate a blocked callback: it may retain this one daemon thread.
+    """
+
+    def __init__(self, hooks: Any) -> None:
+        self._callbacks: dict[str, Callable[[Any], None]] = {}
+        if hooks is not None:
+            for name in hooks.__dataclass_fields__:
+                value = getattr(hooks, name)
+                if value is not None:
+                    if (
+                        not callable(value)
+                        or iscoroutinefunction(value)
+                        or iscoroutinefunction(type(value).__call__)
+                    ):
+                        raise ValueError(f"{name} must be a synchronous callable")
+                    self._callbacks[name] = value
+        self._condition = Condition()
+        self._queue: deque[tuple[str, Any, int]] = deque()
+        self._bytes = self._delivered = self._dropped = self._failed = 0
+        self._started = self._closed = False
+
+    def emit(self, name: str, value: Any) -> None:
+        if name not in self._callbacks:
+            return
+        # Protobuf records obey the wire limit. Other records are bounded SDK
+        # value objects. Do not serialize arbitrary application objects here.
+        size = _size(value)
+        with self._condition:
+            if self._closed or len(self._queue) >= 64 or self._bytes + size > 1048576:
+                self._dropped += 1
+                return
+            if not self._started:
+                try:
+                    Thread(target=self._run, name="mppi-observers", daemon=True).start()
+                except RuntimeError:
+                    self._failed += 1
+                    return
+                self._started = True
+            self._queue.append((name, deepcopy(value), size))
+            self._bytes += size
+            self._condition.notify()
+
+    def _run(self) -> None:
+        while True:
+            with self._condition:
+                while not self._queue and not self._closed:
+                    self._condition.wait()
+                if self._closed:
+                    return
+                name, value, size = self._queue.popleft()
+                self._bytes -= size
+            try:
+                self._callbacks[name](value)
+            except BaseException:
+                # Caller callback failures, including SystemExit, cannot affect
+                # the SDK event loop, payment state or other queued callbacks.
+                with self._condition:
+                    self._failed += 1
+            else:
+                with self._condition:
+                    self._delivered += 1
+
+    def stats(self) -> ObserverStats:
+        with self._condition:
+            return ObserverStats(self._delivered, self._dropped, self._failed, len(self._queue))
+
+    def close(self) -> None:
+        with self._condition:
+            self._closed = True
+            self._dropped += len(self._queue)
+            self._queue.clear()
+            self._bytes = 0
+            self._condition.notify_all()
+
+
+def _size(value: Any) -> int:
+    if hasattr(value, "ByteSize"):
+        return int(value.ByteSize())
+    if isinstance(value, bytes):
+        return len(value)
+    if isinstance(value, str):
+        return len(value) * 4
+    if isinstance(value, tuple):
+        return sum(_size(item) for item in value)
+    if is_dataclass(value) and not isinstance(value, type):
+        return sum(_size(getattr(value, field.name)) for field in fields(value))
+    return 32

mppi_protocol/accounting.py

@@ -0,0 +1,95 @@
+"""Pure provider-report validation; callers supply and own their payment state."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from .amounts import Rates, TokenCounts, numerator, priced_numerator
+from .errors import ValidationCode, ValidationError
+
+
+class RunStatus(StrEnum):
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+    NOT_ADMITTED = "NOT_ADMITTED"
+
+
+@dataclass(frozen=True, slots=True)
+class RunAccounting:
+    counts: TokenCounts
+    remaining_numerator: int
+    final_status: RunStatus | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.counts, TokenCounts):
+            raise ValidationError(ValidationCode.INVALID_VALUE, "counts must be TokenCounts")
+        numerator(self.remaining_numerator, field="remaining reservation")
+        if self.final_status is not None:
+            if (
+                not isinstance(self.final_status, RunStatus)
+                or self.final_status is RunStatus.NOT_ADMITTED
+            ):
+                raise ValidationError(
+                    ValidationCode.INVALID_VALUE, "admitted run requires a definitive final status"
+                )
+            if self.remaining_numerator != 0:
+                raise ValidationError(
+                    ValidationCode.INVALID_VALUE, "final accounting has no remaining reservation"
+                )
+
+
+@dataclass(frozen=True, slots=True)
+class AccountingTransition:
+    state: RunAccounting
+    delta_numerator: int
+    released_numerator: int
+    duplicate: bool
+
+
+def report_transition(
+    previous: RunAccounting,
+    counts: TokenCounts,
+    rates: Rates,
+    *,
+    final_status: RunStatus | None = None,
+) -> AccountingTransition:
+    """Validate cumulative usage, conserve coverage and release only final slack.
+
+    This returns a calculation, not an admission grant, a commit operation,
+    proof of termination, or a new meter sequence. Runtime integration applies
+    it to a consistent authoritative session view supplied by the provider.
+    """
+    if final_status is not None and (
+        not isinstance(final_status, RunStatus) or final_status is RunStatus.NOT_ADMITTED
+    ):
+        raise ValidationError(ValidationCode.INVALID_VALUE, "invalid admitted-run final status")
+    old_numerator = priced_numerator(previous.counts, rates)
+    new_numerator = priced_numerator(counts, rates)
+    if previous.final_status is not None:
+        if counts == previous.counts and final_status == previous.final_status:
+            return AccountingTransition(previous, 0, 0, True)
+        raise ValidationError(
+            ValidationCode.INCONSISTENT_USAGE, "report conflicts with definitive final accounting"
+        )
+    old_counts = previous.counts
+    if (
+        counts.input_tokens < old_counts.input_tokens
+        or counts.cache_tokens < old_counts.cache_tokens
+        or counts.output_tokens < old_counts.output_tokens
+        or new_numerator < old_numerator
+    ):
+        raise ValidationError(
+            ValidationCode.INCONSISTENT_USAGE,
+            "cumulative counts or exact recognized cost regressed",
+        )
+    delta = new_numerator - old_numerator
+    if delta > previous.remaining_numerator:
+        raise ValidationError(
+            ValidationCode.UNCOVERED_USAGE, "reported usage exceeds remaining funded reservation"
+        )
+    remaining = previous.remaining_numerator - delta
+    released = remaining if final_status is not None else 0
+    result = RunAccounting(counts, 0 if final_status is not None else remaining, final_status)
+    return AccountingTransition(
+        result, delta, released, counts == old_counts and final_status is None
+    )

mppi_protocol/amounts.py

@@ -0,0 +1,124 @@
+"""Exact MPPI amounts. All monetary outputs are six-decimal USDC base units."""
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from .errors import ValidationCode, ValidationError
+
+MAX_UINT64 = (1 << 64) - 1
+RATE_SCALE = 1_000_000
+_DECIMAL = re.compile(r"(?:0|[1-9][0-9]*)\Z", re.ASCII)
+
+
+def uint64(value: int, *, field: str = "value", positive: bool = False) -> int:
+    """Reject booleans, coercions and out-of-range integers before encoding."""
+    minimum = 1 if positive else 0
+    if type(value) is not int or not minimum <= value <= MAX_UINT64:
+        raise ValidationError(
+            ValidationCode.INVALID_VALUE, f"{field} must be a uint64 integer >= {minimum}"
+        )
+    return value
+
+
+def decimal_uint64(value: str, *, field: str = "value") -> int:
+    """Parse the exact catalog/TOML decimal-string grammar without float use."""
+    if type(value) is not str or len(value) > 20 or _DECIMAL.fullmatch(value) is None:
+        raise ValidationError(
+            ValidationCode.INVALID_VALUE, f"{field} must be a canonical decimal string"
+        )
+    return uint64(int(value), field=field)
+
+
+def numerator(value: int, *, field: str = "numerator") -> int:
+    """Validate a wide nonnegative integer; no uint64 intermediate truncation."""
+    if type(value) is not int or value < 0:
+        raise ValidationError(
+            ValidationCode.INVALID_VALUE, f"{field} must be a nonnegative integer"
+        )
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class Rates:
+    input: int
+    output: int
+    cache: int | None = None
+
+    def __post_init__(self) -> None:
+        uint64(self.input, field="input rate")
+        uint64(self.output, field="output rate")
+        if self.cache is not None:
+            uint64(self.cache, field="cache rate")
+
+    @property
+    def greatest(self) -> int:
+        return max(self.input, self.output, *(() if self.cache is None else (self.cache,)))
+
+
+@dataclass(frozen=True, slots=True)
+class TokenCounts:
+    """Provider-supplied cumulative counts; cached input is a subset of input."""
+
+    input_tokens: int
+    cache_tokens: int
+    output_tokens: int
+
+    def __post_init__(self) -> None:
+        uint64(self.input_tokens, field="input_tokens")
+        uint64(self.cache_tokens, field="cache_tokens")
+        uint64(self.output_tokens, field="output_tokens")
+        if self.cache_tokens > self.input_tokens:
+            raise ValidationError(ValidationCode.INVALID_VALUE, "cache_tokens exceeds input_tokens")
+
+
+def priced_numerator(counts: TokenCounts, rates: Rates) -> int:
+    """Price supplied counts without rounding or adding a missing cache rate."""
+    if counts.cache_tokens and rates.cache is None:
+        raise ValidationError(
+            ValidationCode.INCONSISTENT_USAGE, "positive cache count has no accepted cache price"
+        )
+    return (
+        (counts.input_tokens - counts.cache_tokens) * rates.input
+        + (counts.cache_tokens * rates.cache if rates.cache is not None else 0)
+        + counts.output_tokens * rates.output
+    )
+
+
+def cumulative_usage(numerators: Iterable[int]) -> int:
+    """One floor after summing every accepted run/model/version numerator."""
+    return uint64(sum(numerator(n) for n in numerators) // RATE_SCALE, field="cumulative usage")
+
+
+def required_coverage(numerators: Iterable[int]) -> int:
+    """One ceiling over usage and all remaining/new bounds, never per row."""
+    total = sum(numerator(n) for n in numerators)
+    whole, remainder = divmod(total, RATE_SCALE)
+    return uint64(whole + bool(remainder), field="required coverage")
+
+
+def funding_amount(tokens: int, rates: Rates) -> int:
+    """Caller-chosen positive funding tokens at the greatest accepted rate."""
+    uint64(tokens, field="funding tokens", positive=True)
+    amount = required_coverage((tokens * rates.greatest,))
+    return uint64(amount, field="funding amount", positive=True)
+
+
+def top_up_total(deposit: int, amount: int) -> int:
+    """Validate positive raw-unit funding and cumulative deposit capacity."""
+    uint64(deposit, field="deposit", positive=True)
+    uint64(amount, field="top-up amount", positive=True)
+    return uint64(deposit + amount, field="cumulative deposit", positive=True)
+
+
+def remaining_funding_tokens(
+    deposit: int, usage_numerator: int, reservation_numerators: Iterable[int], rates: Rates
+) -> int | None:
+    """Advisory deposit headroom; all-zero pricing has no token estimate."""
+    uint64(deposit, field="deposit")
+    numerator(usage_numerator)
+    reserved = sum(numerator(n) for n in reservation_numerators)
+    if rates.greatest == 0:
+        return None
+    available = max(0, deposit * RATE_SCALE - usage_numerator - reserved)
+    return min(MAX_UINT64, available // rates.greatest)

mppi_protocol/capabilities.py

@@ -0,0 +1,79 @@
+"""Wallet capability contracts. No wallet adapter is supplied by this module."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .amounts import uint64
+from .errors import ValidationCode, ValidationError
+from .types import Domain, OperationResult, RunContext, fixed_bytes, uint256
+
+
+@dataclass(frozen=True, slots=True)
+class WalletCall:
+    """A nonpayable MPPI/registry call made by the configured wallet."""
+
+    chain_id: int
+    to: bytes
+    data: bytes
+
+    def __post_init__(self) -> None:
+        uint64(self.chain_id, field="chain_id", positive=True)
+        fixed_bytes(self.to, 20, field="to", nonzero=True)
+        if type(self.data) is not bytes:
+            raise ValidationError(ValidationCode.INVALID_VALUE, "calldata must be bytes")
+
+
+@dataclass(frozen=True, slots=True)
+class FundingAuthorization:
+    """USDC receiveWithAuthorization input, in the token's separate domain."""
+
+    chain_id: int
+    token: bytes
+    domain_name: str
+    domain_version: str
+    owner: bytes
+    recipient: bytes
+    value: int
+    valid_after: int
+    valid_before: int
+    nonce: bytes
+
+    def __post_init__(self) -> None:
+        uint64(self.chain_id, field="chain_id", positive=True)
+        for name in ("token", "owner", "recipient"):
+            fixed_bytes(getattr(self, name), 20, field=name, nonzero=True)
+        for name in ("value", "valid_after", "valid_before"):
+            uint256(getattr(self, name), field=name)
+        fixed_bytes(self.nonce, 32, field="nonce")
+        if not self.domain_name or not self.domain_version or self.valid_after >= self.valid_before:
+            raise ValidationError(
+                ValidationCode.INVALID_VALUE, "invalid token domain or authorization interval"
+            )
+
+
+class TransactionWallet(Protocol):
+    @property
+    def address(self) -> bytes: ...
+
+    def execute(self, call: WalletCall, *, operation_ref: str) -> OperationResult: ...
+
+    def reconcile(self, *, operation_ref: str) -> OperationResult: ...
+
+
+class FundingWallet(TransactionWallet, Protocol):
+    def sign_funding_authorization(self, authorization: FundingAuthorization) -> bytes: ...
+
+
+class SessionSigner(Protocol):
+    """The fixed ECDSA capability, separate from wallet identity and authority."""
+
+    @property
+    def address(self) -> bytes: ...
+
+    def sign_voucher(self, domain: Domain, session_id: bytes, cumulative_amount: int) -> bytes: ...
+
+    def sign_run(self, domain: Domain, context: RunContext) -> bytes: ...
+
+    def sign_close(self, domain: Domain, session_id: bytes) -> bytes: ...
+
+    def sign_reconnect(self, domain: Domain, session_id: bytes, nonce: bytes) -> bytes: ...