kalmiya/hermes-anthropic-api
Watch
1
0
Fork
You've already forked hermes-anthropic-api
 0
Code Issues 12 Pull requests Projects Releases Packages Wiki Activity Actions
Hermes gateway plugin exposing an Anthropic Messages-compatible API (mirrors the OpenAI-compatible api_server channel).
2 commits 1 branch 0 tags 15 KiB
  • Python 100%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Kalmiya ddc2bf23d0 feat(scaffold): plugin manifest, adapter, constants, smoke tests 
Initial scaffolding for the hermes-anthropic-api plugin. Mirrors the
api_server.py OpenAI-compatible channel using only Anthropic's canonical
endpoint shapes — no custom /api/sessions, /v1/runs, /v1/responses,
/v1/capabilities, or /health/detailed surfaces.

What's in the scaffold:
- plugin.yaml: registers as a 'platform' plugin via the entry-point group
  'hermes_agent.plugins'.
- hermes_anthropic_api/__init__.py: register(ctx) entry point that
  constructs a PlatformEntry and forwards to ctx.register_platform.
- hermes_anthropic_api/adapter.py: AnthropicAPIServer class with default
  host/port (127.0.0.1:8643 — one above api_server's 8642), config extra
  parsing for api_key_env/cors_origins/etc., and an empty _http_route_table
  that subsequent tickets will populate.
- hermes_anthropic_api/constants.py: single source of truth for Anthropic's
  error types, content block types, SSE event names, stop_reason values,
  and HTTP status codes.
- tests/test_scaffold.py: 7 smoke tests verifying import-time contracts
  and check_fn compliance (literal True, per the registry gate).
- pyproject.toml: setuptools-build backend with the entry-point group.
- README.md: scope statement, endpoint table, install, minimal usage.

End-to-end verification:
- pip install -e . into the Hermes venv succeeds.
- hermes plugins list shows 'anthropic_api 0.1.0' as a discoverable
  entrypoint.
- pytest tests/ passes 7/7.
- check_requirements() returns literal True (avoids the pitfall #6
  bool(None) -> False gate trap).

Refs: kanban tickets t_ce96d9b1 (scaffold), t_1b3032aa (server bootstrap),
t_a445eb1a (POST /v1/messages), t_4048d742 (streaming), t_b4f0a18a
(models), t_337cd973 (count_tokens), t_7ec0a1c1 (batches), t_7b15fba2
(errors), t_5b38ef4d (auth), t_19dacbdd (health), t_4f84900e (docs),
t_10f70e4d (CI). All twelve have matching Forgejo issues #1-#12.
2026-08-03 17:05:23 -07:00
hermes_anthropic_api feat(scaffold): plugin manifest, adapter, constants, smoke tests 2026-08-03 17:05:23 -07:00
tests feat(scaffold): plugin manifest, adapter, constants, smoke tests 2026-08-03 17:05:23 -07:00
.gitignore feat(scaffold): plugin manifest, adapter, constants, smoke tests 2026-08-03 17:05:23 -07:00
plugin.yaml feat(scaffold): plugin manifest, adapter, constants, smoke tests 2026-08-03 17:05:23 -07:00
pyproject.toml feat(scaffold): plugin manifest, adapter, constants, smoke tests 2026-08-03 17:05:23 -07:00
README.md feat(scaffold): plugin manifest, adapter, constants, smoke tests 2026-08-03 17:05:23 -07:00

README.md

hermes-anthropic-api

Hermes gateway plugin exposing an Anthropic Messages-compatible HTTP API.

Mirrors the per-endpoint coverage of gateway/platforms/api_server.py (the OpenAI-compatible api_server channel) using only Anthropic's canonical endpoint shapes — no custom extensions, no api_server-specific surfaces like /api/sessions, /v1/runs, /v1/responses, /v1/capabilities, or /health/detailed.

Status: scaffolding only. See the issue tracker for the per-endpoint tickets.

Endpoints exposed

Method Path Anthropic endpoint Ticket
POST /v1/messages create a message (sync) #9
POST /v1/messages (stream: true) create a message (SSE) #10
GET /v1/models list models #4
GET /v1/models/{model_id} get a model #4
POST /v1/messages/count_tokens count tokens #5
POST /v1/messages/batches create batch #1
GET /v1/messages/batches list batches #1
GET /v1/messages/batches/{id} retrieve batch #1
GET /v1/messages/batches/{id}/results batch results (.jsonl) #1
DELETE /v1/messages/batches/{id} cancel batch #1

Multi-profile prefix support: /p/<profile>/v1/messages, etc., mirroring api_server.py's /p/<profile>/ convention.

Endpoints deliberately NOT exposed

These are part of api_server.py but have no Anthropic equivalent — by user direction, this plugin does not implement them:

  • /v1/responses* (OpenAI Responses API)
  • /v1/runs* (Hermes-async runs)
  • /api/sessions* (Hermes session store)
  • /v1/capabilities
  • /health/detailed
  • /health is opt-in only (default off) — see #2.

Install

git clone https://git.anteater-wall.ts.net/kalmiya/hermes-anthropic-api.git
cd hermes-anthropic-api
pip install -e .

hermes plugins enable anthropic_api

Set the auth key (Anthropic clients send Authorization: Bearer <key>):

export ANTHROPIC_API_KEY=sk-...

The plugin listens on 127.0.0.1:8643 by default (one port above api_server's 8642).

Minimal usage

# non-streaming
curl -sS http://127.0.0.1:8643/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 256,
    "system": "You are concise.",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# streaming
curl -N http://127.0.0.1:8643/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "claude-opus-4-7", "max_tokens": 256, "messages": [{"role": "user", "content": "Hello"}], "stream": true}'

Reference

  • Source of truth for the Anthropic Messages API: https://docs.anthropic.com/en/api/messages
  • The OpenAI-compatible channel being mirrored: gateway/platforms/api_server.py in NousResearch/hermes-agent
  • Plugin authoring contract: ~/.hermes/skills/software-development/hermes-backend-plugin-authoring/SKILL.md