Development: Add Hyperion admin setup docs

[FelixTJDietrich]

Checklist

General

• I chose a title conforming to the naming conventions for pull requests.

Motivation and Context

We want to document how to use Hyperion for Artemis administrators.

Description

This PR adds setup documentation for Hyperion, detailing how to enable Hyperion and how to configure Spring AI with either OpenAI oder Azure OpenAI

Testserver States

You can manage test servers using Helios. Check environment statuses in the environment list. To deploy to a test server, go to the CI/CD page, find your PR or branch, and trigger the deployment.

Review Progress

Code Review

• Code Review 1
• Code Review 2

Summary by CodeRabbit

• Documentation
  • Added Hyperion Service docs covering features, prerequisites, and enablement in production.
  • Added configuration guidance and examples for supported LLM providers (OpenAI, Azure OpenAI) and how to supply credentials.
  • Documented verification steps, troubleshooting hints, cost-control and data-protection considerations.
  • Linked Hyperion into extension services navigation for easier discovery.

[coderabbitai]

Walkthrough

Adds new Hyperion Service documentation under admin setup, links it from the extension-services toctree, and references it from the developer server production setup guidance. No code, runtime, or public API changes.

Changes

Cohort / File(s)	Summary
Admin extension services toctree docs/admin/extension-services.rst	Added setup/hyperion entry to the “Other Extension Services” toctree.
Hyperion admin setup docs docs/admin/setup/hyperion.rst	New page describing the Hyperion Service: purpose, prerequisites, how to enable via artemis.hyperion.enabled, Spring AI provider configuration (OpenAI/Azure examples), verification steps, and operational considerations (costs, data protection).
Dev server docs reference docs/dev/setup/server.rst	Added a “Production setup” subsection referencing the Hyperion admin guide for production enablement and LLM credential configuration.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "Development: Add Hyperion admin setup docs" is a concise, single-sentence summary that accurately reflects the primary change of adding Hyperion administration/setup documentation as described in the PR objectives and raw_summary; it is clear and readable for a teammate scanning history. The prefix appears to be a workflow/branch label and does not obscure the main intent. There is no misleading or irrelevant content in the title.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/hyperion/add-admin-docs

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 27d7d51 and 85e30b8.

📒 Files selected for processing (1)

• docs/admin/setup/hyperion.rst (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/admin/setup/hyperion.rst

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Codacy Static Code Analysis

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (3)

docs/admin/setup/hyperion.rst (3)

57-67: Azure snippet: clarify deployment name vs. model; make temperature optional.

In Azure, deployment-name must be the name of your Azure resource deployment (not the raw model name). Temperature is configurable, not mandated to be 1.0.

Apply this diff:

    spring:
      ai:
        azure:
          openai:
            api-key: <azure-openai-api-key>
            endpoint: https://<your-resource-name>.openai.azure.com
            chat:
              options:
-               deployment-name: <azure-deployment> # gpt-5-mini deployment recommended
-               temperature: 1.0 # Required to be 1.0 for gpt-5
+               deployment-name: <your-azure-deployment-name>  # the Azure deployment name you created (not the model name)
+               # model: <model-id>  # optional; if supported by your Spring AI version
+               temperature: 1.0  # optional

---

71-76: Verification: add fallback if management endpoint is disabled.

If /management/info is not exposed, admins won’t see activeModuleFeatures. Add a note about enabling the actuator info endpoint or alternatively checking logs at startup for “Hyperion enabled”.

Would you like me to add a short “Troubleshooting” subsection with actuator exposure example?

---

81-84: Optional: add logging/privacy knobs.

Consider pointing to ways to avoid sensitive data in logs (e.g., reduce log level for Hyperion/Azure/OpenAI clients) and reminding admins not to store API keys in VCS; prefer env vars or externalized config.

I can draft a short “Security & privacy tips” box with env var mappings for the shown properties.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between acbae2a and 27d7d51.

📒 Files selected for processing (3)

• docs/admin/extension-services.rst (1 hunks)
• docs/admin/setup/hyperion.rst (1 hunks)
• docs/dev/setup/server.rst (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Codacy Static Code Analysis

🔇 Additional comments (2)

docs/dev/setup/server.rst (1)

294-299: Good cross-reference; fits the structure.

The “Production setup” pointer to the admin guide is clear and consistent with the new label. No action needed.

docs/admin/extension-services.rst (1)

35-35: LGTM — Hyperion added to toctree.

Entry renders fine and matches the new page label.

[Elfari1028]

LGTM