Skip to content

feat(achievements): add export endpoint and agent summary (#18472) - #58012

Closed
frirenai wants to merge 1 commit into
NousResearch:mainfrom
frirenai:feat/achievements-export-agent-summary
Closed

feat(achievements): add export endpoint and agent summary (#18472)#58012
frirenai wants to merge 1 commit into
NousResearch:mainfrom
frirenai:feat/achievements-export-agent-summary

Conversation

@frirenai

@frirenai frirenai commented Jul 4, 2026

Copy link
Copy Markdown

What does this PR do?

Implements the export & agent-communication workstream from the achievements upgrades tracking issue (#18472, spec in closed PR #18151). Achievements are currently trapped in state.json and the dashboard tab; this adds the two surfaces the spec defines for getting them out:

  • GET /api/plugins/hermes-achievements/export?format=json|markdown|svg&state=... — renders the current snapshot as machine-readable JSON, a README-pasteable Markdown badge table (shields.io badges + ██░░ progress bars, unlocked badges by default), or an SVG badge sheet with tier-colored markers. Unknown formats return a 400 JSON error instead of guessing.
  • GET /api/plugins/hermes-achievements/achievements/summary — the compact agent profile from the spec (strengths, gaps, top_tier, unlocked_ids, unlocked_count, total_count, session/tool totals), small enough for context injection.
  • agent_summary.json — the same payload is written next to state.json after every finished scan (best-effort, never fails the scan) and removed on /reset-state, so agents and external tools can read the profile without the dashboard running.

Scope notes, per the issue's guidance that the four workstreams land as separate PRs:

  • filter_and_sort_achievements() is added as the minimal state-filter seam the export formatters need; the filtering/sorting workstream can extend the same function with category/sort_by/limit without rework.
  • The hermes achievements CLI and TUI panel workstream is intentionally not included here; the CLI's export path can delegate to these formatters when it lands.

Two small deviations from the spec's reference snippets, both deliberate:

FastAPI response classes are stubbed in the existing no-FastAPI fallback so the plugin's dependency-free unit tests keep working.

Related Issue

Addresses the export/agent-summary section of #18472 (spec: #18151).

Type of Change

  • ✨ New feature (non-breaking change that adds functionality)

Changes Made

  • plugins/hermes-achievements/dashboard/plugin_api.py: add TIER_ORDER, agent_summary_path(), filter_and_sort_achievements(), export_json(), export_markdown(), export_svg(), _build_agent_summary(), _write_agent_summary(); new /export and /achievements/summary routes; write agent_summary.json in _run_scan_and_update_cache(); clear it in /reset-state; stub JSONResponse/PlainTextResponse in the FastAPI fallback.
  • plugins/hermes-achievements/tests/test_export_and_summary.py: 13 new unit tests (state filtering, JSON structure/filter, Markdown header/categories/badges/bad-timestamp handling, SVG rows/escaping/empty sheet, agent summary strengths/gaps/top-tier/empty data, agent_summary.json persistence).
  • plugins/hermes-achievements/README.md: document the new endpoints and the agent_summary.json artifact.

How to Test

  1. cd plugins/hermes-achievements && python3 -m unittest discover -s tests -v — 21 tests (13 new + 8 existing engine tests) pass without dashboard dependencies.
  2. Start the Hermes dashboard, open the Achievements tab once so a scan completes, then:
    • curl 'localhost:<port>/api/plugins/hermes-achievements/export?format=markdown' → Markdown badge table
    • curl 'localhost:<port>/api/plugins/hermes-achievements/export?format=svg' > badges.svg → renderable badge sheet
    • curl 'localhost:<port>/api/plugins/hermes-achievements/achievements/summary' → compact profile
  3. Check $HERMES_HOME/plugins/hermes-achievements/agent_summary.json exists after the scan and disappears after POST /reset-state.

…ch#18472)

Implement the export & agent-communication workstream from the
achievements upgrades spec (issue NousResearch#18472, spec PR NousResearch#18151):

- GET /export?format=json|markdown|svg&state=... renders the current
  snapshot as machine-readable JSON, a README-pasteable Markdown badge
  table (shields.io badges + progress bars, unlocked-only by default),
  or an SVG badge sheet with tier-colored markers. Unknown formats
  return a 400 JSON error.
- GET /achievements/summary returns the compact agent profile
  (strengths, gaps, top tier, unlocked ids, session/tool totals).
- agent_summary.json is written next to state.json after every finished
  scan (best-effort) and removed on /reset-state, so agents and external
  tools can read the profile without the dashboard running.
- filter_and_sort_achievements() is the minimal state-filter seam that
  the filtering/sorting workstream in NousResearch#18472 can extend with category,
  sort, and limit parameters.

SVG output escapes badge names/tiers to keep markup out of rendered
sheets. The agent summary path uses get_hermes_home() rather than a
hardcoded ~/.hermes so Windows-aware homes keep working. FastAPI
response classes are stubbed in the no-FastAPI fallback so the plugin
unit tests keep running without dashboard dependencies.

Tested: python3 -m unittest discover -s tests (21 tests: 13 new for
filtering, JSON/Markdown/SVG formatters, escaping, agent summary
builder, and agent_summary.json persistence; 8 existing engine tests
unchanged), plus an async endpoint smoke over stubbed snapshot data.
@frirenai

frirenai commented Jul 4, 2026

Copy link
Copy Markdown
Author

Closing — reopening this from my main account.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant