mvgeos-core 0.6.6__tar.gz

mvgeos_core-0.6.6/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: mvgeos-core
+Version: 0.6.6
+Summary: Canonical loop vocabulary for MvgeOS: abort, invocations, spells, events, and the pure turn loop
+License-Expression: MIT
+Requires-Dist: pydantic>=2.0
+Requires-Python: >=3.13

mvgeos_core-0.6.6/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "mvgeos-core"
+version = "0.6.6"
+description = "Canonical loop vocabulary for MvgeOS: abort, invocations, spells, events, and the pure turn loop"
+requires-python = ">=3.13"
+license = "MIT"
+dependencies = ["pydantic>=2.0"]
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.13"]
+build-backend = "uv_build"
+
+[tool.ruff]
+extend = "../pyproject.toml"

mvgeos_core-0.6.6/pyproject.toml.orig

@@ -0,0 +1,16 @@
+[project]
+name = "mvgeos-core"
+version = "0.6.6"
+description = "Canonical loop vocabulary for MvgeOS: abort, invocations, spells, events, and the pure turn loop"
+requires-python = ">=3.13"
+license = "MIT"
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.13"]
+build-backend = "uv_build"
+
+[tool.ruff]
+extend = "../pyproject.toml"

mvgeos_core-0.6.6/src/mvgeos_core/__init__.py

@@ -0,0 +1,228 @@
+"""Canonical loop vocabulary for MvgeOS.
+
+Zero first-party dependencies. Leaf packages (provider, runes, tome) and the
+agent depend on core, never the reverse.
+"""
+
+from mvgeos_core.abort import AbortController, AbortError, AbortSignal
+from mvgeos_core.approval import (
+    ApprovalDecision,
+    ApprovalOutcome,
+    ApprovalPresenter,
+    ApprovalReasonCode,
+    ApprovalRequest,
+    ApprovalScope,
+    SpellGateHandler,
+    allow,
+    deny,
+    normalize_arguments,
+)
+from mvgeos_core.channel import (
+    ChannelConfig,
+    Model,
+    MvgeResponse,
+    RealmResponse,
+    StopReason,
+)
+from mvgeos_core.constants import (
+    DEFAULT_AGENT_NAME,
+    DEFAULT_MODEL,
+    GLOBAL_DIR_ENV,
+    PROJECT_RUNE_PATH,
+)
+from mvgeos_core.dispatcher import BatchResult, SpellDispatcher
+from mvgeos_core.errors import (
+    AuthenticationError,
+    MaxTurnsExceededError,
+    MissingApiKeyError,
+    MvgeError,
+    RateLimitError,
+    SpellDiscoveryError,
+    SpellNotFoundError,
+    SpellTimeoutError,
+    TomeIncompatibleError,
+    TomeResumeError,
+    UpstreamTimeoutError,
+    to_error,
+)
+from mvgeos_core.event_bus import EventBus
+from mvgeos_core.events import (
+    ContemplationLevel,
+    ContentType,
+    MvgeEvent,
+    MvgeEventType,
+    PromptSource,
+    QueueMode,
+)
+from mvgeos_core.invocations import MvgeInvocation, SummonerRequest
+from mvgeos_core.layers import (
+    SCOPE_PRECEDENCE,
+    ResolvedLayer,
+    Scope,
+    agent_dir,
+    agent_extensions_dir,
+    agent_skills_dir,
+    agents_dir,
+    approval_dir,
+    auth_dir,
+    auth_file,
+    default_rune_paths,
+    extensions_dir,
+    global_agents_dir,
+    global_file,
+    history_file,
+    models_file,
+    resolve_rune_layers,
+    resolve_rune_paths,
+    scope_rank,
+    sessions_dir,
+    skills_dir,
+)
+from mvgeos_core.loop import (
+    EmitSink,
+    LoopCallbacks,
+    LoopContext,
+    StreamFn,
+    run_loop,
+)
+from mvgeos_core.sandbox import MvgeSandbox, SandboxTimeoutError
+from mvgeos_core.spell_schema import generate_spell_schema
+from mvgeos_core.spells import (
+    ExecutionMode,
+    MvgeSpell,
+    SpellExecutionMode,
+    SpellResult,
+    SpellResultMessage,
+    SpellSignal,
+    SpellStatus,
+    SpellUpdateCallback,
+)
+from mvgeos_core.telemetry import (
+    GEN_AI_AGENT_NAME,
+    GEN_AI_CONVERSATION_ID,
+    GEN_AI_OPERATION_NAME,
+    GEN_AI_REQUEST_MAX_TOKENS,
+    GEN_AI_REQUEST_MODEL,
+    GEN_AI_REQUEST_TEMPERATURE,
+    GEN_AI_REQUEST_TOP_P,
+    GEN_AI_RESPONSE_FINISH_REASONS,
+    GEN_AI_RESPONSE_MODEL,
+    GEN_AI_SYSTEM,
+    GEN_AI_TOOL_CALL_ID,
+    GEN_AI_TOOL_DEFINITIONS,
+    GEN_AI_TOOL_NAME,
+    GEN_AI_TOOL_TYPE,
+    GEN_AI_USAGE_INPUT_TOKENS,
+    GEN_AI_USAGE_OUTPUT_TOKENS,
+    GEN_AI_USAGE_TOTAL_TOKENS,
+    MVGEOS_ORCHESTRATOR,
+    create_genai_chat_attributes,
+    create_genai_tool_attributes,
+    derive_provider_from_model,
+)
+
+__all__ = [
+    "AbortController",
+    "AbortError",
+    "AbortSignal",
+    "ApprovalDecision",
+    "ApprovalOutcome",
+    "ApprovalPresenter",
+    "ApprovalReasonCode",
+    "ApprovalRequest",
+    "ApprovalScope",
+    "SpellGateHandler",
+    "allow",
+    "deny",
+    "normalize_arguments",
+    "AuthenticationError",
+    "BatchResult",
+    "ChannelConfig",
+    "ContemplationLevel",
+    "ContentType",
+    "DEFAULT_AGENT_NAME",
+    "DEFAULT_MODEL",
+    "GLOBAL_DIR_ENV",
+    "EmitSink",
+    "EventBus",
+    "ExecutionMode",
+    "GEN_AI_AGENT_NAME",
+    "GEN_AI_CONVERSATION_ID",
+    "GEN_AI_OPERATION_NAME",
+    "PROJECT_RUNE_PATH",
+    "agent_dir",
+    "agent_extensions_dir",
+    "agent_skills_dir",
+    "agents_dir",
+    "approval_dir",
+    "auth_dir",
+    "auth_file",
+    "global_file",
+    "history_file",
+    "models_file",
+    "skills_dir",
+    "default_rune_paths",
+    "extensions_dir",
+    "global_agents_dir",
+    "GEN_AI_REQUEST_MAX_TOKENS",
+    "GEN_AI_REQUEST_MODEL",
+    "GEN_AI_REQUEST_TEMPERATURE",
+    "GEN_AI_REQUEST_TOP_P",
+    "GEN_AI_RESPONSE_FINISH_REASONS",
+    "GEN_AI_RESPONSE_MODEL",
+    "GEN_AI_SYSTEM",
+    "GEN_AI_TOOL_CALL_ID",
+    "GEN_AI_TOOL_DEFINITIONS",
+    "GEN_AI_TOOL_NAME",
+    "GEN_AI_TOOL_TYPE",
+    "GEN_AI_USAGE_INPUT_TOKENS",
+    "GEN_AI_USAGE_OUTPUT_TOKENS",
+    "GEN_AI_USAGE_TOTAL_TOKENS",
+    "LoopCallbacks",
+    "LoopContext",
+    "MaxTurnsExceededError",
+    "MissingApiKeyError",
+    "Model",
+    "MvgeError",
+    "MvgeEvent",
+    "MvgeEventType",
+    "MvgeInvocation",
+    "MvgeResponse",
+    "MvgeSandbox",
+    "MvgeSpell",
+    "MVGEOS_ORCHESTRATOR",
+    "PromptSource",
+    "QueueMode",
+    "RateLimitError",
+    "RealmResponse",
+    "ResolvedLayer",
+    "SCOPE_PRECEDENCE",
+    "SandboxTimeoutError",
+    "SpellDispatcher",
+    "SpellDiscoveryError",
+    "SpellExecutionMode",
+    "SpellNotFoundError",
+    "SpellResult",
+    "SpellResultMessage",
+    "SpellSignal",
+    "SpellStatus",
+    "SpellTimeoutError",
+    "SpellUpdateCallback",
+    "StopReason",
+    "Scope",
+    "StreamFn",
+    "SummonerRequest",
+    "TomeIncompatibleError",
+    "TomeResumeError",
+    "UpstreamTimeoutError",
+    "create_genai_chat_attributes",
+    "create_genai_tool_attributes",
+    "derive_provider_from_model",
+    "generate_spell_schema",
+    "resolve_rune_layers",
+    "resolve_rune_paths",
+    "scope_rank",
+    "sessions_dir",
+    "run_loop",
+    "to_error",
+]

mvgeos_core-0.6.6/src/mvgeos_core/abort.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Callable
+
+
+class AbortError(Exception):
+    """Raised when an operation is cancelled via AbortSignal."""
+
+
+class AbortSignal:
+    """Cancellation signal, mirroring the web AbortSignal API (Pi-compatible).
+
+    A signal is created with ``aborted`` False. Calling ``controller.abort()``
+    flips the flag and fires any registered callbacks. Consumers should check
+    ``aborted`` or call ``raise_if_aborted()`` at safe checkpoints.
+    """
+
+    def __init__(self, controller: AbortController) -> None:
+        self._controller = controller
+        self._aborted = False
+        self._callbacks: list[Callable[[], None]] = []
+        self._wait_future: asyncio.Future[None] | None = None
+
+    @property
+    def aborted(self) -> bool:
+        return self._aborted
+
+    def on_abort(self, callback: Callable[[], None]) -> None:
+        if self._aborted:
+            callback()
+        else:
+            self._callbacks.append(callback)
+
+    def raise_if_aborted(self) -> None:
+        if self._aborted:
+            raise AbortError("Operation aborted")
+
+    async def wait(self) -> None:
+        """Block until the signal is aborted or the await is cancelled.
+
+        Multiple concurrent calls to wait() will all resolve when the signal is aborted.
+        """
+        if self._aborted:
+            return
+        if self._wait_future is not None and not self._wait_future.done():
+            await self._wait_future
+            return
+        self._wait_future = asyncio.get_event_loop().create_future()
+
+        def _set_result() -> None:
+            if self._wait_future is not None and not self._wait_future.done():
+                self._wait_future.set_result(None)
+
+        self._callbacks.append(_set_result)
+        try:
+            await self._wait_future
+        finally:
+            if _set_result in self._callbacks:
+                self._callbacks.remove(_set_result)
+
+
+class AbortController:
+    """Controller that owns an :class:`AbortSignal` and can abort it.
+
+    Mirrors the web ``AbortController`` API and Pi's cancellation model.
+    """
+
+    def __init__(self) -> None:
+        self._signal = AbortSignal(self)
+
+    @property
+    def signal(self) -> AbortSignal:
+        return self._signal
+
+    def abort(self) -> None:
+        if self._signal._aborted:
+            return
+        self._signal._aborted = True
+        for callback in list(self._signal._callbacks):
+            with contextlib.suppress(Exception):
+                callback()
+        self._signal._callbacks.clear()
+        wait_future = self._signal._wait_future
+        if wait_future is not None and not wait_future.done():
+            wait_future.set_result(None)
+
+
+__all__ = [
+    "AbortController",
+    "AbortError",
+    "AbortSignal",
+]

mvgeos_core-0.6.6/src/mvgeos_core/approval.py

@@ -0,0 +1,217 @@
+"""Gate vocabulary for the critical spell-approval path.
+
+These types are the contract between the spell dispatcher (which builds the
+request), the critical gate handlers registered by runes (which decide), and
+the host-bound presenter (which surfaces the decision to the Summoner).
+
+The gate is fail-closed: any exception, cancellation, malformed response, or
+stale digest denies the cast. This module carries no I/O and no first-party
+dependencies.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Any
+
+
+class ApprovalOutcome(StrEnum):
+    ALLOW = "allow"
+    DENY = "deny"
+
+
+class ApprovalScope(StrEnum):
+    ONCE = "once"
+    SPELL = "spell"
+    SESSION = "session"
+    PROJECT = "project"
+
+
+class ApprovalReasonCode(StrEnum):
+    USER = "user"
+    RULE = "rule"
+    READ_ONLY = "read_only"
+    FAILURE = "failure"
+
+
+def _coerce_outcome(value: ApprovalOutcome | str) -> ApprovalOutcome:
+    try:
+        return ApprovalOutcome(value)
+    except ValueError as exc:
+        raise ValueError(f"Unknown approval outcome: {value!r}") from exc
+
+
+def _coerce_scope(value: ApprovalScope | str) -> ApprovalScope:
+    try:
+        return ApprovalScope(value)
+    except ValueError as exc:
+        raise ValueError(f"Unknown approval scope: {value!r}") from exc
+
+
+def _coerce_reason_code(value: ApprovalReasonCode | str) -> ApprovalReasonCode:
+    try:
+        return ApprovalReasonCode(value)
+    except ValueError as exc:
+        raise ValueError(f"Unknown approval reason code: {value!r}") from exc
+
+
+def _freeze_mapping(value: Mapping[str, Any]) -> Mapping[str, Any]:
+    if isinstance(value, MappingProxyType):
+        return value
+    return MappingProxyType(dict(value))
+
+
+@dataclass(frozen=True)
+class ApprovalRequest:
+    """One immutable approval question for a single spell cast.
+
+    The dispatcher builds this from the validated, normalized argument copy
+    and the gate approves exactly this data; the dispatcher then executes the
+    approved copy. ``spell_identity`` is engine-derived (never rune-chosen)
+    attribution the policy layer matches rules against.
+    """
+
+    cast_id: str
+    spell_name: str
+    spell_identity: Mapping[str, str] = field(default_factory=dict)
+    arguments: Mapping[str, Any] = field(default_factory=dict)
+    argument_digest: str = ""
+    project_root: str = ""
+    tome_id: str = ""
+    agent_name: str = ""
+    # True when the spell carried a parameter schema and the dispatcher
+    # validated/normalized arguments against it before building this
+    # request. False marks a schemaless cast: policy may never match an
+    # allow rule against it, and presenters must show an "unvalidated
+    # arguments" warning.
+    schema_validated: bool = True
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "spell_identity", _freeze_mapping(self.spell_identity))
+        object.__setattr__(self, "arguments", _freeze_mapping(self.arguments))
+
+
+@dataclass(frozen=True)
+class ApprovalDecision:
+    """The verdict for one :class:`ApprovalRequest`.
+
+    ``request_digest`` must equal the request's ``argument_digest``; a
+    decision bound to any other digest is stale and denies the cast.
+    """
+
+    outcome: ApprovalOutcome
+    scope: ApprovalScope = ApprovalScope.ONCE
+    reason_code: ApprovalReasonCode = ApprovalReasonCode.RULE
+    request_digest: str = ""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "outcome", _coerce_outcome(self.outcome))
+        object.__setattr__(self, "scope", _coerce_scope(self.scope))
+        object.__setattr__(self, "reason_code", _coerce_reason_code(self.reason_code))
+
+
+def deny(
+    request: ApprovalRequest,
+    reason_code: ApprovalReasonCode | str = ApprovalReasonCode.FAILURE,
+    scope: ApprovalScope | str = ApprovalScope.ONCE,
+) -> ApprovalDecision:
+    """Build a denial decision already bound to ``request``."""
+    return ApprovalDecision(
+        outcome=ApprovalOutcome.DENY,
+        scope=_coerce_scope(scope),
+        reason_code=_coerce_reason_code(reason_code),
+        request_digest=request.argument_digest,
+    )
+
+
+def allow(
+    request: ApprovalRequest,
+    reason_code: ApprovalReasonCode | str = ApprovalReasonCode.RULE,
+    scope: ApprovalScope | str = ApprovalScope.ONCE,
+) -> ApprovalDecision:
+    """Build an allow decision already bound to ``request``."""
+    return ApprovalDecision(
+        outcome=ApprovalOutcome.ALLOW,
+        scope=_coerce_scope(scope),
+        reason_code=_coerce_reason_code(reason_code),
+        request_digest=request.argument_digest,
+    )
+
+
+def _deep_freeze(value: Any) -> Any:
+    """Recursively freeze JSON-like data into immutable containers.
+
+    dicts become ``MappingProxyType``, lists/tuples become tuples; scalars
+    pass through. The frozen tree shares no mutable state with the input.
+    """
+    if isinstance(value, dict):
+        return MappingProxyType(
+            {key: _deep_freeze(item) for key, item in value.items()}
+        )
+    if isinstance(value, (list, tuple)):
+        return tuple(_deep_freeze(item) for item in value)
+    return value
+
+
+def normalize_arguments(
+    arguments: Any,
+) -> tuple[Mapping[str, Any], str]:
+    """Freeze arguments to canonical JSON and digest them.
+
+    Args:
+        arguments: The validated argument mapping for one cast.
+
+    Returns:
+        A tuple of (recursively immutable argument view, ``"sha256:<hex>"``
+        digest) where the digest is computed over ``json.dumps`` with
+        ``sort_keys=True, separators=(",", ":"), ensure_ascii=True``.
+
+    Raises:
+        ValueError: If ``arguments`` is not a dict or is not JSON-serializable.
+    """
+    if not isinstance(arguments, dict):
+        raise ValueError(
+            "Spell arguments must be a JSON object (dict); "
+            f"got {type(arguments).__name__}"
+        )
+    try:
+        canonical = json.dumps(
+            arguments, sort_keys=True, separators=(",", ":"), ensure_ascii=True
+        )
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"Spell arguments are not JSON-serializable: {exc}") from exc
+    digest = "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    # Freeze after dumping: the frozen tree shares no mutable state with the
+    # input, so a gate cannot mutate nested values after display and change
+    # what the dispatcher executes.
+    frozen = _deep_freeze(arguments)
+    # `arguments` is a dict, so `_deep_freeze` returned a MappingProxyType.
+    return frozen, digest
+
+
+SpellGateHandler = Callable[
+    [ApprovalRequest], "ApprovalDecision | Awaitable[ApprovalDecision]"
+]
+"""A critical gate handler: receives the request, returns or awaits a decision."""
+
+ApprovalPresenter = Callable[[ApprovalRequest], Awaitable[ApprovalDecision]]
+"""Host-bound UI surface: awaits the Summoner's decision for one request."""
+
+
+__all__ = [
+    "ApprovalDecision",
+    "ApprovalOutcome",
+    "ApprovalPresenter",
+    "ApprovalReasonCode",
+    "ApprovalRequest",
+    "ApprovalScope",
+    "SpellGateHandler",
+    "allow",
+    "deny",
+    "normalize_arguments",
+]

mvgeos_core-0.6.6/src/mvgeos_core/channel.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class StopReason(StrEnum):
+    PENDING = "pending"
+    STOP = "stop"
+    LENGTH = "length"
+    SPELL_USE = "spellUse"
+    ERROR = "error"
+    ABORTED = "aborted"
+
+
+@dataclass
+class MvgeResponse:
+    role: str = "assistant"
+    content: list[dict[str, Any]] = field(default_factory=list)
+    realm: str = ""
+    model: str = ""
+    mana_usage: dict[str, float] = field(default_factory=dict)
+    stop_reason: StopReason = StopReason.PENDING
+    error_message: str | None = None
+    timestamp: float = 0.0
+
+
+@dataclass
+class Model:
+    id: str
+    name: str
+    realm: str
+    base_url: str
+    api_key: str
+    max_completion_mana: int = 0
+    context_window: int = 128000
+    max_tokens: int = 4096
+    headers: dict[str, str] = field(default_factory=dict)
+    supported_parameters: list[str] = field(default_factory=list)
+    supported_contemplation_levels: list[str] = field(default_factory=list)
+    is_free: bool = False
+
+    @property
+    def free(self) -> bool:
+        """Return True if the model is free of charge."""
+        return self.is_free or self.id.endswith(":free") or self.id == "openrouter/free"
+
+    @property
+    def provider(self) -> str:
+        """The organization that provides this model (derived from the model ID)."""
+        return self.id.split("/")[0] if "/" in self.id else self.realm
+
+    @property
+    def provider_prefix(self) -> str:
+        """The provider prefix before '/' in id, or realm, or id."""
+        return self.id.split("/")[0] if "/" in self.id else (self.realm or self.id)
+
+    @property
+    def supports_contemplation(self) -> bool:
+        """Return True if the model supports contemplation/reasoning."""
+        return (
+            bool(self.supported_contemplation_levels)
+            or "reasoning" in self.supported_parameters
+            or "thinking" in self.supported_parameters
+        )
+
+
+@dataclass
+class ChannelConfig:
+    model: Model
+    temperature: float = 0.7
+    max_tokens: int = 4096
+    max_output_mana: int | None = None
+    timeout_ms: int = 120000
+    max_retries: int = 3
+    contemplation_level: str = "medium"
+    contemplation_budget: int | None = None
+    exclude_contemplation: bool = False
+    spells: list[dict[str, Any]] = field(default_factory=list)
+    tools: list[dict[str, Any]] = field(default_factory=list)
+    meta_data: dict[str, Any] = field(default_factory=dict)
+    system_prompt: str = ""
+
+    def __post_init__(self) -> None:
+        if self.tools and not self.spells:
+            self.spells = self.tools
+        elif self.spells and not self.tools:
+            self.tools = self.spells
+
+
+@dataclass
+class RealmResponse:
+    model: Model
+    invocation: Any | None = None
+    mana_used: int = 0
+    stop_reason: str = "stop"
+    error_message: str | None = None
+    error_code: str | None = None
+    retry_after: float | None = None
+    limit_source: str | None = None
+    remedy_hint: str | None = None
+    reset_at: float | None = None
+    quota_limit: int | None = None
+    quota_remaining: int | None = None
+
+
+__all__ = [
+    "ChannelConfig",
+    "Model",
+    "MvgeResponse",
+    "RealmResponse",
+    "StopReason",
+]