abstractcore 2.20.0__tar.gz → 2.20.2__tar.gz

{abstractcore-2.20.0 → abstractcore-2.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractcore
-Version: 2.20.0
+Version: 2.20.2
 Summary: Unified interface to all LLM providers with essential infrastructure for tool calling, streaming, and model management
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 Maintainer-email: Laurent-Philippe Albou <contact@abstractcore.ai>

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/comms/email/__init__.py

@@ -23,8 +23,8 @@ credentials), `oauth` (OAuth2 / XOAUTH2), `store` (settings + secret + status),
 (the guarded send), `errors` (typed errors), `legacy` (one-time import of pre-2.20 settings).
 """
 
-from .client import DEFAULT_MAX_MESSAGE_BYTES, MAX_LIST_LIMIT, EmailClient, tls_context
-from .context import EmailContext, guarded_send
+from .client import DEFAULT_MAX_MESSAGE_BYTES, MAX_LIST_LIMIT, EmailClient, auto_submitted_value, tls_context
+from .context import EmailContext, guarded_send, mark_automatic
 from .errors import (
     EmailAgentToolsOff,
     EmailAttachmentNotFound,
@@ -54,6 +54,11 @@ from .errors import (
 )
 from .limits import SendRateLimiter
 from .models import (
+    AUTO_SUBMITTED_GENERATED,
+    AUTO_SUBMITTED_HEADER,
+    AUTO_SUBMITTED_REPLIED,
+    AUTO_SUBMITTED_VALUES,
+    AUTOMATION_MARKER_HEADER,
     Attachment,
     AttachmentInfo,
     EmailAccount,
@@ -68,6 +73,7 @@ from .models import (
     SendLimits,
     SendResult,
     SmtpSettings,
+    automation_marker_value,
 )
 from .oauth import (
     BUILTIN_CLIENTS,
@@ -87,6 +93,14 @@ from .store import EmailAccountStore, EmailSettings
 from .vault import SecretVault
 
 __all__ = [
+    "AUTO_SUBMITTED_GENERATED",
+    "AUTO_SUBMITTED_HEADER",
+    "AUTO_SUBMITTED_REPLIED",
+    "AUTO_SUBMITTED_VALUES",
+    "AUTOMATION_MARKER_HEADER",
+    "auto_submitted_value",
+    "automation_marker_value",
+    "mark_automatic",
     "DEFAULT_MAX_MESSAGE_BYTES",
     "MAX_LIST_LIMIT",
     "BUILTIN_CLIENTS",

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/comms/email/client.py

@@ -61,6 +61,9 @@ from .errors import (
     classify_smtp_code,
 )
 from .models import (
+    AUTO_SUBMITTED_HEADER,
+    AUTO_SUBMITTED_VALUES,
+    AUTOMATION_MARKER_HEADER,
     Attachment,
     AttachmentInfo,
     EmailAccount,
@@ -72,6 +75,7 @@ from .models import (
     OutgoingMessage,
     SendResult,
     ServerSettings,
+    automation_marker_value,
 )
 from .oauth import OAuthTokenProvider, xoauth2_string
 from .policy import normalize_address, parse_recipients
@@ -87,6 +91,7 @@ MAX_LIST_LIMIT = 100
 
 _SUMMARY_HEADERS = (
     "FROM TO CC SUBJECT DATE MESSAGE-ID REPLY-TO IN-REPLY-TO IMPORTANCE X-PRIORITY PRIORITY LIST-UNSUBSCRIBE"
+    " AUTO-SUBMITTED X-ABSTRACTFRAMEWORK-AUTOMATION"
 )
 _SUMMARY_ITEMS = f"(UID FLAGS RFC822.SIZE INTERNALDATE BODYSTRUCTURE BODY.PEEK[HEADER.FIELDS ({_SUMMARY_HEADERS})])"
 _DETAIL_ITEMS = "(UID FLAGS RFC822.SIZE INTERNALDATE BODYSTRUCTURE BODY.PEEK[HEADER])"
@@ -348,6 +353,22 @@ def x_priority_value(header_value: str) -> Optional[int]:
     return None
 
 
+def auto_submitted_value(header_value: str) -> Optional[str]:
+    """`Auto-Submitted:` (RFC 3834) as its lower-cased keyword without parameters.
+
+    `auto-replied; owner-email="a@b"` -> "auto-replied"; absent or empty -> None. The keyword
+    is returned as sent (an extension keyword stays itself); a value that is not a keyword
+    (spaces, punctuation) is returned as "unknown" (present and not "no").
+    """
+
+    v = str(header_value or "").split(";", 1)[0].strip().lower()
+    if not v:
+        return None
+    if all(c.isascii() and (c.isalnum() or c in "-_.") for c in v):
+        return v
+    return "unknown"
+
+
 def _structure(attrs: dict) -> Optional[MimePart]:
     tok = attrs.get("BODYSTRUCTURE")
     if not isinstance(tok, list):
@@ -733,6 +754,8 @@ class EmailClient:
             x_priority=x_priority_value(_header(msg, "X-Priority")),
             priority=priority_value(_header(msg, "Priority")),
             list_unsubscribe=bool(_header(msg, "List-Unsubscribe")),
+            auto_submitted=auto_submitted_value(_header(msg, AUTO_SUBMITTED_HEADER)),
+            framework_marker=automation_marker_value(_header(msg, AUTOMATION_MARKER_HEADER)),
         )
 
     def _cap(self, max_message_bytes: Optional[int]) -> int:
@@ -1194,6 +1217,21 @@ class EmailClient:
                 mime["In-Reply-To"] = message.in_reply_to
             if message.references:
                 mime["References"] = " ".join(message.references)
+            if message.auto_submitted:
+                if message.auto_submitted not in AUTO_SUBMITTED_VALUES:
+                    raise EmailInvalidMessage(
+                        f"Auto-Submitted must be one of {', '.join(AUTO_SUBMITTED_VALUES)}, got {message.auto_submitted!r}.",
+                        "Use auto-generated for automatic mail, auto-replied for an automatic answer to one message.",
+                    )
+                mime[AUTO_SUBMITTED_HEADER] = message.auto_submitted
+            if message.automation_marker:
+                marker = automation_marker_value(message.automation_marker)
+                if not marker:
+                    raise EmailInvalidMessage(
+                        "The automation marker must be one line of printable ASCII (at most 200 characters).",
+                        "Give an identifier such as occurrence:<run id>.",
+                    )
+                mime[AUTOMATION_MARKER_HEADER] = marker
         except (ValueError, TypeError) as exc:
             raise EmailInvalidMessage(
                 "A message header is not valid (line breaks are not allowed in headers).",

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/comms/email/context.py

@@ -18,13 +18,22 @@ policy and the limits run here, always, for every caller.
 from __future__ import annotations
 
 import ssl
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from typing import Any, Callable, Dict, Optional
 
 from .client import DEFAULT_MAX_MESSAGE_BYTES, EmailClient
 from .errors import EmailDisabled, EmailInvalidMessage, EmailNotConfigured
 from .limits import SendRateLimiter
-from .models import EmailAccount, EmailSecret, OutgoingMessage, SendLimits, SendResult
+from .models import (
+    AUTO_SUBMITTED_GENERATED,
+    AUTO_SUBMITTED_REPLIED,
+    EmailAccount,
+    EmailSecret,
+    OutgoingMessage,
+    SendLimits,
+    SendResult,
+    automation_marker_value,
+)
 from .oauth import OAuthTokenProvider
 from .policy import PolicyDecision, RecipientPolicy, evaluate, parse_recipients
 
@@ -46,6 +55,11 @@ class EmailContext:
     # are not fetched; the read returns a typed skip record instead (never a cut body).
     max_message_bytes: int = DEFAULT_MAX_MESSAGE_BYTES
     on_sent: Optional[Callable[[Dict[str, Any]], None]] = field(default=None, repr=False)
+    # Set by a host for a context used by something that sends automatically (an automation
+    # occurrence, a notification): every message sent through it carries RFC 3834
+    # `Auto-Submitted` and the framework marker (`X-AbstractFramework-Automation: <value>`),
+    # so this account's own mail watcher never admits it (no self-triggering loop).
+    automation_marker: str = ""
 
     def __repr__(self) -> str:
         return f"EmailContext(address={self.account.address!r}, enabled={self.enabled}, source={self.source!r})"
@@ -81,8 +95,27 @@ class EmailContext:
         return guarded_send(self, message)
 
 
+def mark_automatic(message: OutgoingMessage, marker: str) -> OutgoingMessage:
+    """`message` with the framework marker and RFC 3834 `Auto-Submitted` (kept when set).
+
+    `Auto-Submitted` is `auto-replied` for an answer to one message (In-Reply-To set), else
+    `auto-generated`.
+    """
+
+    marker_value = automation_marker_value(marker)
+    if not marker_value:
+        raise EmailInvalidMessage(
+            "The automation marker must be one line of printable ASCII (at most 200 characters).",
+            "Give an identifier such as occurrence:<run id>.",
+        )
+    auto = message.auto_submitted or (AUTO_SUBMITTED_REPLIED if message.in_reply_to else AUTO_SUBMITTED_GENERATED)
+    return replace(message, auto_submitted=auto, automation_marker=message.automation_marker or marker_value)
+
+
 def guarded_send(ctx: EmailContext, message: OutgoingMessage) -> SendResult:
     ctx.require_enabled()
+    if ctx.automation_marker:
+        message = mark_automatic(message, ctx.automation_marker)
     if not ctx.account.can_send:
         raise EmailNotConfigured(
             "This account has no SMTP (send) settings.",
@@ -100,7 +133,15 @@ def guarded_send(ctx: EmailContext, message: OutgoingMessage) -> SendResult:
         raise
     if ctx.on_sent is not None:
         try:
-            ctx.on_sent({"message_id": result.message_id, "accepted": list(result.accepted), "refused": dict(result.refused)})
+            ctx.on_sent(
+                {
+                    "message_id": result.message_id,
+                    "accepted": list(result.accepted),
+                    "refused": dict(result.refused),
+                    "auto_submitted": message.auto_submitted,
+                    "automation_marker": message.automation_marker,
+                }
+            )
         except Exception:
             pass
     return result

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/comms/email/models.py

@@ -486,6 +486,32 @@ class Attachment:
         return b""
 
 
+# RFC 3834 section 5: a message sent automatically carries `Auto-Submitted: auto-generated`
+# (not a response to one message) or `auto-replied` (a response to one message); mail
+# written by a person carries none (or `no`). Responders must not answer such messages.
+AUTO_SUBMITTED_HEADER = "Auto-Submitted"
+AUTO_SUBMITTED_GENERATED = "auto-generated"
+AUTO_SUBMITTED_REPLIED = "auto-replied"
+AUTO_SUBMITTED_VALUES = (AUTO_SUBMITTED_GENERATED, AUTO_SUBMITTED_REPLIED)
+# The framework's own marker on every message it sends automatically (notifications, digests,
+# send-email actions, agent sends from automations): the value names what sent it (e.g.
+# `occurrence:<run id>`, `notification:<key>`). A mail watcher never admits a message that
+# carries it and comes from its own account, so an automation can never trigger itself.
+AUTOMATION_MARKER_HEADER = "X-AbstractFramework-Automation"
+MAX_AUTOMATION_MARKER = 200
+
+
+def automation_marker_value(value: Any) -> str:
+    """A marker value as sent: one line of printable ASCII, at most 200 characters, else ""."""
+
+    text = str(value or "").strip()
+    if not text or len(text) > MAX_AUTOMATION_MARKER:
+        return ""
+    if any(not (32 <= ord(c) < 127) for c in text):
+        return ""
+    return text
+
+
 @dataclass(frozen=True)
 class OutgoingMessage:
     to: Tuple[str, ...] = ()
@@ -497,6 +523,11 @@ class OutgoingMessage:
     attachments: Tuple[Attachment, ...] = ()
     in_reply_to: str = ""
     references: Tuple[str, ...] = ()
+    # RFC 3834 `Auto-Submitted` ("auto-generated" | "auto-replied"; "" = written by a person)
+    # and the framework marker (`X-AbstractFramework-Automation`, "" = none). Set by the
+    # sender for automatic mail, or stamped by `guarded_send` from `EmailContext.automation_marker`.
+    auto_submitted: str = ""
+    automation_marker: str = ""
 
     @property
     def recipients(self) -> List[str]:
@@ -564,6 +595,11 @@ class MessageSummary:
     x_priority: Optional[int] = None
     priority: Optional[str] = None
     list_unsubscribe: bool = False
+    # RFC 3834 `Auto-Submitted`, lower-cased keyword without parameters ("no", "auto-generated",
+    # "auto-replied", or an extension keyword); None when the header is absent or empty.
+    auto_submitted: Optional[str] = None
+    # The framework marker header's value (`X-AbstractFramework-Automation`); "" when absent.
+    framework_marker: str = ""
 
     @property
     def seen(self) -> bool:
@@ -592,6 +628,8 @@ class MessageSummary:
             "x_priority": self.x_priority,
             "priority": self.priority,
             "list_unsubscribe": self.list_unsubscribe,
+            "auto_submitted": self.auto_submitted,
+            "framework_marker": self.framework_marker,
         }
 
 

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/config/capability_defaults.py

@@ -625,6 +625,32 @@ def _host_platform(host: Mapping[str, Any]) -> Tuple[str, str, Optional[str]]:
     return os_id or "unknown", arch or "unknown", accelerator if isinstance(accelerator, str) else None
 
 
+def recommended_engine_missing_reason(provider: Any, host: Mapping[str, Any]) -> Optional[str]:
+    """Why a recommended provider's IN-PROCESS engine is not installed in this install, or None.
+
+    Read from the host profile's `engines_installed` (utils/host_profile.py, from
+    `route_engines.provider_engine_installed`): the light install profile has no MLX, MLX-Gen
+    or PyTorch, so a recommendation naming one would fail at first use (0.7.0 end-to-end: a
+    128 GB Mac on the light profile got mlx/Qwen3.8-Flash-Next-4bit as its text default and
+    every call, voice included, failed with "MLX dependencies not installed"). A host mapping
+    without that key (a synthetic host, an older profile) is not judged. The sentence is
+    `route_engines.route_engine_missing`'s own (it names the install setting to add).
+    Configured routes are judged by `route_engines.routes_engine_missing` (`engine_missing`),
+    never folded into `route_unavailable`.
+    """
+
+    installed = host.get("engines_installed")
+    pid = str(provider or "").strip().lower()
+    if not isinstance(installed, Mapping) or installed.get(pid) is not False:
+        return None
+    from .route_engines import route_engine_missing
+
+    flag = route_engine_missing(pid)
+    if flag is not None and flag.get("reason"):
+        return str(flag["reason"])
+    return f"the {pid} engine is not installed in this Python environment (the light install profile has no local engines)"
+
+
 def recommended_route_unavailable_reason(
     provider: Any, host: Mapping[str, Any], key: Optional[str] = None
 ) -> Optional[str]:
@@ -632,7 +658,8 @@ def recommended_route_unavailable_reason(
 
     `key` (the route) only words the sentence ("MLX-Gen video generation").
     Engine support only: the memory gate of fit-gated routes is
-    `recommended_unavailable_routes`.
+    `recommended_unavailable_routes`; whether THIS install has the engine is
+    `recommended_engine_missing_reason`.
     """
 
     from .engines import _support
@@ -746,7 +773,8 @@ def _unavailable_reasons(
     routes: Mapping[str, CapabilityRouteDefault], downloads: Mapping[str, Mapping[str, str]], host: Mapping[str, Any]
 ) -> Dict[str, str]:
     """`{key: reason}` for every recommended row this host cannot run: its
-    engine has no build here, or (fit-gated rows) its model does not fit."""
+    engine has no build here, this install does not have its in-process engine
+    (`recommended_engine_missing_reason`), or (fit-gated rows) its model does not fit."""
 
     out: Dict[str, str] = {}
     for key, route in routes.items():
@@ -757,6 +785,12 @@ def _unavailable_reasons(
                 reason = f"{reason}; {next_step}"
             out[key] = reason
             continue
+        # The host runs the engine, but this install does not have it (the light profile):
+        # never recommend (seed, apply-recommended) a route that fails at first use.
+        reason = recommended_engine_missing_reason(route.provider, host)
+        if reason:
+            out[key] = reason
+            continue
         if key in _FIT_GATED_ROUTES:
             reason = _fit_gate_reason(key, downloads[key], host)
             if reason:

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/config/email_cli.py

@@ -13,7 +13,11 @@
     abstractcore email registered-address me@example.com
 
 Credentials are direct parameters (`--password <value>`, `--client-secret <value>`) and are
-stored encrypted; they are never printed. Every verb takes `--json` (the `email_settings_v1`
+stored encrypted; they are never printed. A script or program passes them on stdin instead, so
+the secret never appears on a command line (where other local users can read it while the
+command runs): `--password-stdin` / `--client-secret-stdin` read exactly one line from stdin
+(the trailing newline is removed, nothing else), e.g.
+`printf '%s\n' "$PW" | abstractcore email connect --address me@example.com ... --password-stdin`. Every verb takes `--json` (the `email_settings_v1`
 document of `EmailAccountStore.public()`, or `{ok: false, error: {code, cause, fix}}`).
 Exit codes: 0 ok, 1 error, 2 refused (a failed connection test, or `disconnect` without
 `--yes`).
@@ -187,6 +191,61 @@ def _obtain_oauth_tokens(args: argparse.Namespace, oauth: Any, client_secret: st
     return loop.finish(timeout_s=float(args.oauth_timeout))
 
 
+def _read_stdin_secret(flag: str, what: str) -> str:
+    """One secret from stdin: exactly one line, the trailing newline removed (nothing else)."""
+    from abstractcore.comms.email import EmailInvalidSettings
+
+    stream = sys.stdin
+    if stream is None:
+        raise EmailInvalidSettings(
+            f"{flag} was given but this process has no stdin.",
+            f"Pipe the {what} into the command (printf '%s\\n' \"$SECRET\" | abstractcore email connect ... {flag}).",
+        )
+    line = stream.readline()
+    if line.endswith("\n"):
+        line = line[:-1]
+        if line.endswith("\r"):
+            line = line[:-1]
+    if not line:
+        raise EmailInvalidSettings(
+            f"{flag} read an empty {what} from stdin.",
+            f"Write the {what} as the first line of stdin (printf '%s\\n' \"$SECRET\" | abstractcore email connect ... {flag}).",
+        )
+    return line
+
+
+def _stdin_secrets(args: argparse.Namespace) -> None:
+    """Resolve `--password-stdin` / `--client-secret-stdin` into args.password / args.client_secret."""
+    from abstractcore.comms.email import EmailInvalidSettings
+
+    if args.password_stdin and args.client_secret_stdin:
+        raise EmailInvalidSettings(
+            "--password-stdin and --client-secret-stdin cannot be combined (stdin carries one secret).",
+            "Use --password-stdin for a password account, or --client-secret-stdin with --oauth.",
+        )
+    if args.password_stdin:
+        if args.password:
+            raise EmailInvalidSettings(
+                "--password and --password-stdin were both given.",
+                "Give the password once: --password <value>, or --password-stdin with the password on stdin.",
+            )
+        if args.oauth:
+            raise EmailInvalidSettings("--password-stdin is not used with --oauth.", "Remove --password-stdin; OAuth2 signs in through the browser.")
+        args.password = _read_stdin_secret("--password-stdin", "password")
+    if args.client_secret_stdin:
+        if args.client_secret:
+            raise EmailInvalidSettings(
+                "--client-secret and --client-secret-stdin were both given.",
+                "Give the client secret once: --client-secret <value>, or --client-secret-stdin with the secret on stdin.",
+            )
+        if not args.oauth:
+            raise EmailInvalidSettings(
+                "--client-secret-stdin is only used with --oauth.",
+                "Add --oauth google|microsoft|custom, or remove --client-secret-stdin.",
+            )
+        args.client_secret = _read_stdin_secret("--client-secret-stdin", "client secret")
+
+
 def cmd_connect(args: argparse.Namespace) -> int:
     from abstractcore.comms.email import (
         EmailAccount,
@@ -203,6 +262,7 @@ def cmd_connect(args: argparse.Namespace) -> int:
 
     as_json = bool(args.json)
     try:
+        _stdin_secrets(args)
         preset = provider_preset(args.oauth, tenant=args.tenant or "") if args.oauth and args.oauth != "custom" else {}
         address = (args.address or "").strip() or (args.username or "").strip()
         if not address:
@@ -254,7 +314,8 @@ def cmd_connect(args: argparse.Namespace) -> int:
             if not args.password:
                 raise EmailInvalidSettings(
                     "The password is missing.",
-                    "Give --password <value> (an app password for providers with two-step verification), or --oauth <provider>.",
+                    "Give --password <value> (an app password for providers with two-step verification; "
+                    "--password-stdin reads it from stdin), or --oauth <provider>.",
                 )
             account = EmailAccount.build(
                 address=address, username=args.username or address, imap=imap, smtp=smtp,
@@ -475,6 +536,10 @@ def build_parser() -> argparse.ArgumentParser:
     c.add_argument("--display-name", help="Name shown to recipients")
     c.add_argument("--username", help="Sign-in user name (default: the address)")
     c.add_argument("--password", help="Password or app password (stored encrypted)")
+    c.add_argument(
+        "--password-stdin", action="store_true",
+        help="Read the password from stdin (one line; for scripts: the password never appears on a command line)",
+    )
     c.add_argument("--imap-host")
     c.add_argument("--imap-port", type=int)
     c.add_argument("--imap-security", choices=("ssl", "starttls"))
@@ -490,6 +555,10 @@ def build_parser() -> argparse.ArgumentParser:
     c.add_argument("--oauth", choices=("google", "microsoft", "custom"), help="Sign in with OAuth2 instead of a password")
     c.add_argument("--client-id", help="Your own OAuth client id (default: the built-in AbstractFramework client, when one is registered for the provider)")
     c.add_argument("--client-secret", help="Your own OAuth client secret (stored encrypted)")
+    c.add_argument(
+        "--client-secret-stdin", action="store_true",
+        help="Read the OAuth client secret from stdin (one line; the secret never appears on a command line)",
+    )
     c.add_argument("--tenant", help="Microsoft tenant (default common)")
     c.add_argument("--oauth-flow", choices=("device", "loopback"), help="device code (Microsoft default) or browser on this machine (Google default)")
     c.add_argument("--token-endpoint")

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/config/manager.py

@@ -117,6 +117,34 @@ _PROVIDER_MODEL_PREFIXES = {
 }
 
 
+def route_provider_changed(stored: Any, requested: Any) -> bool:
+    """True when a route write names a provider other than the stored one (case-insensitive).
+
+    Such a write that names no options drops the old engine's speculation request
+    (`options_after_provider_change`; AbstractGateway's route save applies the same rule).
+    """
+
+    if requested is None:
+        return False
+    old = str(stored or "").strip().lower()
+    new = str(requested or "").strip().lower()
+    return bool(old) and old != new
+
+
+def options_after_provider_change(options: Any) -> Dict[str, Any]:
+    """The stored route options a write that moves the route to ANOTHER provider keeps.
+
+    A speculation REQUEST (`speculation: {mode: native_mtp, ...}` or `true`) names how the old
+    engine loads the model (an MLX MTP head, a drafter), so it is dropped; `speculation: false`
+    (off) is valid for every engine and is kept, like every other option.
+    """
+
+    out = dict(options) if isinstance(options, dict) else {}
+    if "speculation" in out and out["speculation"] is not False:
+        out.pop("speculation")
+    return out
+
+
 def _split_provider_model(value: str, *, default_provider: str) -> Tuple[str, str]:
     raw = str(value or "").strip()
     if not raw:
@@ -2032,6 +2060,11 @@ class ConfigurationManager:
                 task=task,
             )
         merged_options = options if isinstance(options, dict) else stored.get("options")
+        if not isinstance(options, dict) and route_provider_changed(stored.get("provider"), provider):
+            # A write that moves the route to another provider and names no options drops the
+            # old engine's speculation request (0.7.0 end-to-end: an LM Studio text route kept
+            # the MLX tier's `speculation: native_mtp`); every other option is kept.
+            merged_options = options_after_provider_change(merged_options)
         return self.set_capability_default(
             kind,
             modality,

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/config/model_catalog.py

@@ -141,6 +141,10 @@ APPLE_TEXT_TIERS: Tuple[Dict[str, Any], ...] = (
      "plain": "mlx-community/Qwen3.8-Flash-Next-4bit", "mtp": "Jundot/Qwen3.8-Flash-Next-oQ4e-mtp"},
 )
 _TIER_PROVIDER = "mlx"
+# The tier's engine when this install has no MLX (the light profile): LM Studio serves the same
+# rows (`qwen/qwen3.5-9b@q4_k_m`, `qwen/qwen3.8-27b@q4_k_m`) from its own app, nothing to
+# install in this Python (`recommended_text_model`, basis `apple_silicon_engine_fallback`).
+_SERVER_TIER_PROVIDER = "lmstudio"
 
 # The portable text model on an engine that runs where LM Studio does not
 # (Intel Macs). Same catalog row as the portable default; Ollama's bare tag
@@ -292,7 +296,9 @@ def recommended_text_model(
       model      the id the route stores (the served id; for MLX the repo id)
       options    route options: the portable route's MTP policy
                  (`speculation`), overlaid with the artifact's own options
-      basis      `apple_silicon_tiers`, `portable_default`,
+      basis      `apple_silicon_tiers`, `apple_silicon_engine_fallback` (Apple
+                 silicon without MLX in this install: the tier's LM Studio build,
+                 else the nearest smaller tier's), `portable_default`,
                  `portable_engine_fallback` (the portable engine has no build
                  on this host, e.g. LM Studio on an Intel Mac), or
                  `no_supported_engine` (neither has one, e.g. FreeBSD: the
@@ -319,7 +325,51 @@ def recommended_text_model(
     accelerator = str(profile.get("accelerator") or "none")
     memory = _memory_gib(profile)
     use_mtp = MTP_RECOMMENDED if mtp is None else bool(mtp)
+    from .model_materializer import split_artifact as _split_artifact
+
+    mlx_missing = None
     if accelerator == "metal":
+        from .capability_defaults import recommended_engine_missing_reason
+
+        mlx_missing = recommended_engine_missing_reason(_TIER_PROVIDER, profile)
+    if accelerator == "metal" and mlx_missing:
+        # The tiers are MLX builds, and this install has no MLX (the light profile): the
+        # tier's model on LM Studio (a server route, nothing to install in this Python), else
+        # the nearest SMALLER tier that has an LM Studio build (Flash-Next has none) -- never
+        # an engine that fails at first use (0.7.0 end-to-end, light install on a 128 GB Mac).
+        tier, rule = _apple_tier(memory)
+        order = list(APPLE_TEXT_TIERS)
+        start = order.index(tier)
+        chosen = None
+        for candidate in reversed(order[: start + 1]):
+            for seed_row in _load_seed_cached().get("rows") or []:
+                if seed_row.get("id") != candidate["row"]:
+                    continue
+                art0 = next((a for a in seed_row.get("artifacts") or [] if a.get("provider") == _SERVER_TIER_PROVIDER), None)
+                if art0 is not None:
+                    chosen = (candidate, seed_row, art0)
+                    break
+            if chosen:
+                break
+        if chosen is None:
+            raise LookupError("no Apple silicon tier row has an LM Studio build")
+        cand, row, art = chosen
+        which = (
+            "the tier's LM Studio build" if cand is tier
+            else f"the LM Studio build of the nearest smaller tier ({cand['row']}; {tier['row']} has no LM Studio build)"
+        )
+        out = {
+            "provider": _SERVER_TIER_PROVIDER,
+            "artifact": str(art["artifact"]),
+            "model": _split_artifact(str(art["artifact"]))[0],  # LM Studio serves the id without `@quant`
+            # The host-wide MTP policy, as on the portable LM Studio route of every other host.
+            "options": dict(_portable_text_default()["options"], **json.loads(json.dumps(art.get("options") or {}))),
+            "catalog_id": row["id"],
+            "basis": "apple_silicon_engine_fallback",
+            "tier": f"{rule}: {which}, because the tier's MLX build cannot run in this install ({mlx_missing.rstrip('.')})",
+            "mtp": False,
+        }
+    elif accelerator == "metal":
         tier, rule = _apple_tier(memory)
         provider, artifact = _TIER_PROVIDER, _tier_artifact(tier, use_mtp)
         row, art = _seed_row_and_artifact(str(tier["row"]), provider, artifact)
@@ -1664,7 +1714,7 @@ def catalog(
             if arts:
                 tier = tier_by_row.get(seed_row["id"]) if accelerator == "metal" else None
                 forced = (_TIER_PROVIDER, _tier_artifact(tier)) if tier is not None else None
-                if text_pick["basis"] == "portable_engine_fallback" and seed_row["id"] == text_pick["catalog_id"]:
+                if text_pick["basis"] in ("portable_engine_fallback", "apple_silicon_engine_fallback") and seed_row["id"] == text_pick["catalog_id"]:
                     forced = (text_pick["provider"], text_pick["artifact"])
                 if forced is not None and not any((a["provider"], a["artifact"]) == forced for a in arts):
                     forced = None  # an engine filter (`engine=ollama`) removed the tier artifact

{abstractcore-2.20.0 → abstractcore-2.20.2}/abstractcore/config/route_engines.py

@@ -49,7 +49,13 @@ import shlex
 from importlib import metadata
 from typing import Any, Dict, Mapping, Optional, Tuple
 
-__all__ = ["ABSTRACTVOICE_ENGINE_RUNTIME_FLOOR", "route_engine_missing", "routes_engine_missing"]
+__all__ = [
+    "ABSTRACTVOICE_ENGINE_RUNTIME_FLOOR",
+    "provider_engine_installed",
+    "provider_engines_installed",
+    "route_engine_missing",
+    "routes_engine_missing",
+]
 
 # The first AbstractVoice with `abstractvoice.engine_runtime` (the public
 # runtime probe). Mirrors the floor of the `voice` extra in pyproject.toml;
@@ -219,6 +225,36 @@ def _dist_version(dist: str) -> str:
         return "(unknown version)"
 
 
+# In-process providers a RECOMMENDATION may name, and what makes each usable in this Python
+# environment (the host profile's `engines_installed`, read by the recommendation so the light
+# install profile is never handed an engine it does not have). Voice engines are AbstractVoice's
+# own answer (`route_engine_missing(..., key=)`), not judged here: they ship with the light
+# profile and asking needs AbstractVoice imported.
+def provider_engine_installed(provider: Any) -> Optional[bool]:
+    """True / False for an in-process provider a recommendation can name (mlx, mlx-gen,
+    diffusers, acestep), None for any other provider (not judged). Lookups only."""
+
+    pid = str(provider or "").strip().lower()
+    if pid == "mlx":
+        return _importable("mlx_lm")
+    if pid == "mlx-gen":
+        return _distributed("abstractvision") and _distributed("mlx-gen")
+    if pid in ("diffusers", "acestep"):
+        return _importable("torch")
+    return None
+
+
+def provider_engines_installed() -> Dict[str, bool]:
+    """`{provider: installed}` for every provider `provider_engine_installed` judges."""
+
+    out: Dict[str, bool] = {}
+    for pid in ("mlx", "mlx-gen", "diffusers", "acestep"):
+        value = provider_engine_installed(pid)
+        if value is not None:
+            out[pid] = bool(value)
+    return out
+
+
 def route_engine_missing(provider: Any, model: Any = None, key: Any = None) -> Optional[Dict[str, Any]]:
     """`{engine, name, reason, install[, engine_row]}` when the in-process
     engine behind this route is not installed here, else None.