hermes-meta-provider

# hermes-meta-provider

A [Hermes Agent](https://github.com/NousResearch/hermes-agent) model-provider
plugin for the **Meta Model API** — Meta Superintelligence Labs' **Muse Spark**
family, including the low-cost `muse-spark-1.2-contributor` tier.

It's a **standalone, out-of-tree plugin**: nothing in the Hermes repo changes.
You install it into your Hermes home and Hermes discovers it automatically.

## What you get

- Provider id `meta-ai` (aliases: `meta`, `muse`, `muse-spark`, `model-api`, `msl`)
- Base URL `https://api.meta.ai/v1` (override with `META_BASE_URL`)
- Auth via `MODEL_API_KEY` (also accepts `META_API_KEY` / `META_MODEL_API_KEY`)
- OpenAI-compatible Chat Completions: tool calling, 1M context, multimodal input
- Reasoning effort dial (Instant/Contemplating → `reasoning_effort`), with the
  Meta-specific `none → minimal` guard so requests never 400
- `muse-spark-1.2` and `muse-spark-1.2-contributor` in the picker (live catalog
  is fetched from `/v1/models`; these are the offline fallback)

## Install

```bash
git clone https://github.com/betodepaola/hermes-meta-provider
cd hermes-meta-provider
./install.sh
```

This copies `meta_ai/` into `$HERMES_HOME/plugins/model-providers/meta-ai/`
(default `~/.hermes/...`). To uninstall: `./install.sh --uninstall`.

Manual alternative:

```bash
cp -r meta_ai ~/.hermes/plugins/model-providers/meta-ai
```

## Configure

```bash
export MODEL_API_KEY=LLM_...      # your Meta Model API key
hermes model                      # pick "Meta Model API"
```

or set it directly in `~/.hermes/config.yaml`:

```yaml
model:
  provider: meta-ai
  model: muse-spark-1.2-contributor
```

> **Testing from scratch?** See [TESTING.md](TESTING.md) for a full end-to-end
> walkthrough on an existing Hermes install (throwaway `HERMES_HOME`, live
> catalog check, real turns, the picker, and cleanup).

## The contributor tier

`muse-spark-1.2-contributor` is Meta's low-cost tier ($0.10/M in, $0.20/M out,
$0.002 cached). In exchange, **Meta trains on your prompts and completions**, and
the rate limit is lower (≈60 rpm). Don't use it for confidential data — use
`muse-spark-1.2` (standard pricing, no training) for that.

## Why a plugin, and not a PR to Hermes?

Hermes' contribution policy (`AGENTS.md`) keeps third-party vendor backends
**out of the core tree** — they're maintained as standalone plugins users install
into `$HERMES_HOME`