Files
hermes-agent/plugins/model-providers/meta-ai/__init__.py
T
Teknium f2f6dce785 feat(providers): flip bundled meta-ai profile to the Responses wire
Reconciles the salvaged Responses-API mandate with the bundled meta-ai
plugin that landed in #88565:

- meta-ai profile api_mode -> codex_responses (prompt caching engages
  only on /v1/responses; 0% vs 93-99% measured). Custom endpoints with a
  non-api.meta.ai base URL still fall through to chat_completions via
  the host-driven mandate design.
- cli-config.yaml.example: point the example at MODEL_API_KEY (Meta's
  documented env var) and note the bundled provider covers the default
  endpoint
- tests/providers/test_meta_ai_profile.py updated for the new wire
2026-08-17 12:58:51 -07:00

119 lines
5.1 KiB
Python

"""Meta Model API (Muse Spark) provider plugin for Hermes Agent.
Provider profile for Meta Superintelligence Labs' Muse Spark family, served
via the OpenAI-compatible Meta Model API at ``https://api.meta.ai/v1``.
Bundled from https://github.com/albertodepaola/hermes-meta-provider. Hermes'
provider discovery (``providers/__init__.py``) imports it on first
``get_provider_profile()`` / ``list_providers()`` call, and the module-level
``register_provider()`` below wires it into the registry.
Design notes
------------
* **Zero core edits.** Everything rides on ``ProviderProfile`` hooks. No changes
to hermes' ``model_metadata.py`` / ``models.py`` / ``run_agent.py`` are needed:
- Context window (1M), reasoning and vision capabilities already resolve from
models.dev for the muse-spark family, so no static ctx table entry is required.
- The reasoning dial is emitted as a **top-level ``reasoning_effort``** kwarg
(returned in the ``top_level`` slot of ``build_api_kwargs_extras``), which the
chat-completions transport merges unconditionally. This deliberately avoids
the ``extra_body.reasoning`` path, whose emission is gated by a hardcoded
host allowlist in core (``AIAgent._supports_reasoning_extra_body``) that a
third-party plugin must not edit.
* **Meta 400 on ``reasoning_effort: "none"``.** Muse rejects ``none``; disabling
reasoning maps to ``"minimal"`` instead.
* **``default_max_tokens=16384``.** Muse spends completion budget on hidden
reasoning tokens first; small caps can finish with empty content.
"""
from __future__ import annotations
import os
from typing import Any
from providers import register_provider
from providers.base import ProviderProfile
def _resolve_effort(reasoning_config: dict | None) -> str:
"""Map Hermes' reasoning_config to a Meta-safe ``reasoning_effort`` value.
- reasoning disabled / effort "none" -> "minimal" (Meta 400s on "none")
- low | medium | high -> passthrough
- max | xhigh | ultra -> "xhigh"
- unset / unknown -> "medium"
"""
rc = reasoning_config or {}
if rc.get("enabled") is False:
return "minimal"
effort = str(rc.get("effort") or "").strip().lower()
if effort in {"", "none"}:
return "minimal" if effort == "none" else "medium"
if effort in {"low", "medium", "high"}:
return effort
if effort in {"max", "xhigh", "ultra"}:
return "xhigh"
return "medium"
class MetaAIProfile(ProviderProfile):
"""Meta Model API — top-level reasoning_effort, self-contained."""
def build_api_kwargs_extras(
self,
*,
reasoning_config: dict | None = None,
supports_reasoning: bool = False, # noqa: ARG002 — we self-gate below
**context: Any,
) -> tuple[dict[str, Any], dict[str, Any]]:
"""Emit ``reasoning_effort`` as a top-level api kwarg.
We ignore the core ``supports_reasoning`` gate on purpose: that flag is
driven by a host allowlist in core we cannot (and should not) edit from
an out-of-tree plugin. Muse Spark always accepts ``reasoning_effort``,
so we resolve it from ``reasoning_config`` directly.
"""
return {}, {"reasoning_effort": _resolve_effort(reasoning_config)}
def _base_url() -> str:
"""Allow a base-URL override via ``META_BASE_URL`` without editing config."""
return os.getenv("META_BASE_URL", "").strip() or "https://api.meta.ai/v1"
meta_ai = MetaAIProfile(
name="meta-ai",
aliases=("meta", "muse", "muse-spark", "model-api", "msl"),
display_name="Meta Model API",
description="Meta Muse Spark family (Meta Superintelligence Labs)",
signup_url="https://developer.meta.com/ai/",
# MODEL_API_KEY is Meta's documented env var; the aliases are conveniences.
env_vars=("MODEL_API_KEY", "META_API_KEY", "META_MODEL_API_KEY", "META_BASE_URL"),
base_url=_base_url(),
auth_type="api_key",
# Responses API is the wire that engages Muse prompt caching: measured
# 0 cached tokens on /v1/chat/completions vs 93-99% cache hits on
# /v1/responses with prompt_cache_retention (see host_mandated_api_mode
# in hermes_cli/providers.py and the retention hint in
# agent/transports/codex.py). The MetaAIProfile chat-completions hook
# above still covers custom OpenAI-compatible endpoints configured with
# a non-api.meta.ai base URL, which fall through to chat_completions.
api_mode="codex_responses",
# Muse Spark is natively multimodal (image/video/pdf/audio in, text out).
supports_vision=True,
# Cheap contributor tier is a good default for auxiliary tasks
# (compaction, title generation, vision) when this is the main provider.
default_aux_model="muse-spark-1.2-contributor",
# Muse spends completion budget on hidden reasoning tokens first; a low cap
# can finish with empty content. 16k is a safe floor.
default_max_tokens=16384,
# Curated safety net shown in the picker when the live /v1/models fetch
# fails or no credentials are configured yet.
fallback_models=(
"muse-spark-1.2",
"muse-spark-1.2-contributor",
),
)
register_provider(meta_ai)