Skip to main content

Hyperion Service

Hyperion extends Artemis with AI-assisted authoring features for programming exercises. It offers consistency checks for problem statements and exercise artefacts and can rewrite instructions with the help of generative AI. The functionality is provided entirely by Artemis and Spring AI, so no EduTelligence service needs to be deployed.

ℹ️

For local development setups using LM Studio, refer to the Spring AI Development Guide in the Staff documentation.

Prerequisites​

  • A running Artemis instance that loads the core profile.
  • Network access to an LLM provider that is supported by Spring AI (for example OpenAI or Azure OpenAI).
  • A valid API key for the chosen provider.

Enable the Hyperion module​

Hyperion is disabled by default. Activate it by overriding the artemis.hyperion.enabled property in the configuration that the server reads on startup (for example application-prod.yml).

artemis:
  hyperion:
    enabled: true

Configure Spring AI​

Hyperion delegates all model interactions to Spring AI. Configure exactly one provider; Artemis currently ships the Azure OpenAI starter, but classic OpenAI endpoints work as well when configured through Spring AI.

OpenAI​

spring:
  ai:
    azure:
      openai:
        open-ai-api-key: <openai-api-key> # automatically sets the azure endpoint to https://api.openai.com/v1
        chat:
          options:
            deployment-name: gpt-5-mini # Or another (reasonably capable) model
            temperature: 1.0 # Required to be 1.0 for gpt-5
    # Retry/response handling tuning for AI providers
    retry:
      # Treat HTTP 429 as transient to allow auto-retry by Spring AI
      on-http-codes: [429]
      # Conservative defaults; adjust if needed
      max-attempts: 5
      backoff:
        initial-interval: 1000ms
        multiplier: 2.0
        max-interval: 30000ms

Azure OpenAI​

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
    # Retry/response handling tuning for AI providers
    retry:
      # Treat HTTP 429 as transient to allow auto-retry by Spring AI
      on-http-codes: [429]
      # Conservative defaults; adjust if needed
      max-attempts: 5
      backoff:
        initial-interval: 1000ms
        multiplier: 2.0
        max-interval: 30000ms

Observability (Optional)​

Enabling observability during development helps you understand how LLM-based features behave, why they produce certain outputs, and how to optimize them. Since LLMs are non-deterministic and sensitive to prompts, parameters, and context, traditional logging is often not enough.

Key benefits of adding observability:

  • Full visibility into prompts, responses, parameters, and token usage
  • Reproducible debugging through stored traces
  • Faster prompt iteration with comparison and tracking
  • Early cost and token monitoring
  • Insight into multi-step pipelines and performance bottlenecks
  • Primarily used in development, but can also be enabled in production environments if deeper analysis or incident debugging is required

Langfuse​

Langfuse is a platform for observability and tracing of LLM applications and agents. It captures everything happening during an LLM interaction: inputs, outputs, tool usage, retries, latencies and costs.

Setup Guide​

  1. See how to create and setup a Langfuse account (See only "Get API keys") here.

  2. Request to join a Organization from an Edutelligence maintainer.

  3. You will be added to the Project as Member.

ℹ️ Note Project Members can use Langfuse and access existing API keys. Only Project Admins can create new API keys. If you cannot view API keys, ask the maintainer to generate them for you.

  1. Once the Project Admin provides the Public Key and Secret Key, store them securely. These keys authenticate your application when sending observability data to Langfuse.

  2. Identify your Langfuse host URL. It appears in the Langfuse UI as: https://<host>.

Your OTLP HTTP ingestion endpoint follows the standard OTLP HTTP spec and is constructed as: https://<host>/api/public/otel/v1/traces

  • /api/public/otel → Langfuse OTLP receiver root
  • /v1/traces → Standard OTLP HTTP route

For more info: See how Langfuse can receive traces on the OLTP endpoint here

  1. Generate the Basic Authentication token for Langfuse. Use Base64 encoding with the format: base64(public_key:secret_key)

Example generation command:

echo -n "<public_key>:<secret_key>" | base64
  1. Add the OTLP endpoint and authorization header to your Spring configuration.

Use the OTLP endpoint constructed in Step 5 and the Base64 token generated in Step 6. These values can be provided through active Spring profile YAML (e.g. application-local.yaml, application-dev.yaml) or via environment variables.

You will need to set the following properties:

  • management.otlp.tracing.endpoint → https://<host>/api/public/otel/v1/traces
  • management.otlp.tracing.headers.Authorization → Basic <base64(public_key:secret_key)>

To avoid committing secrets, prefer supplying these values via environment variables and referencing them in YAML.

Configure Langfuse​

Below is the current configuration used in development profile to view the LLM traces of Hyperion services on Langfuse.

management:
  # Set true to display contextual name in @Observed on Langfuse
  observations:
    annotations:
      enabled: true
  # Configuration for exporting LLM traces to Langfuse (set to true to enable Artemis' custom exporter)
  langfuse:
    enabled: true
  tracing:
    sampling:
      probability: 1.0
  otlp:
    tracing:
      # LangFuse accepts OTLP over HTTP at the traces path only
      # (example: https://langfuse.aet.cit.tum.de/api/public/otel/v1/traces)
      endpoint: https://example.com
      transport: http
      headers:
        # Provide "Basic <base64(public_key:secret_key)>" via env var to avoid committing secrets
        Authorization: "Basic <base64(public_key:secret_key)>"
      # Important: Set export.enabled: false to disable the *default* OTLP exporter.
      # Artemis uses its own custom exporter to send Spring AI LLM traces to Langfuse.
      # so disabling the default exporter will NOT stop LLM trace export.
      export:
        enabled: false

Verifying the integration​

  1. Restart the Artemis server and confirm that hyperion appears in activeModuleFeatures on /management/info.
  2. Log in as an instructor and open the programming exercise problem statement editor. New Hyperion actions appear in the markdown editor toolbar (rewrite and consistency check).
  3. Run a consistency check to ensure the LLM call succeeds. Inspect the server logs for Hyperion entries if the request fails; misconfigured credentials and missing network egress are the most common causes.

Operational considerations​

  • Cost control: Define usage policies and rate limits with your provider. Hyperion requests can process the full problem statement, so costs scale with exercise size.
  • Data protection: Model providers receive exercise content. Obtain consent and align with institutional policies before enabling Hyperion in production.