# Euterpe Domain Gap Report

Date: 2026-04-02

Scope: review the implemented Euterpe domain, compare it with the intended Phase
38 scope, and identify gaps for taking full advantage of current ElevenLabs
Music and Google Lyria via OpenRouter capabilities.

## Executive Summary

Euterpe is strong as a pure TypeScript library domain for music primitives,
theory, prompt interpretation, studio logic, mastering, spatial audio, and voice
algorithms. It is not yet a production-ready music generation platform.

The core mismatch is architectural:

- The implemented Euterpe surface is 7 libraries only: `core`, `theory`,
  `genesis`, `studio`, `voice`, `master`, and `spatial`.
- Euterpe has no domain app, no service, no API surface, no persistence layer,
  and no provider runtime inside the domain.
- Provider integrations live outside Euterpe, mainly in
  `apps/lilith/svc-ai/src/providers/`.
- The current OpenRouter provider is not capable of modern Lyria audio flows.
- The current ElevenLabs provider exposes only a narrow subset of current music
  functionality and appears partly out of sync with the latest API.

Conclusion: Euterpe is a solid algorithmic foundation, but it does not yet
contain the orchestration, provider adapters, job lifecycle, editing flows,
provenance, or evaluation stack needed to fully exploit current ElevenLabs Music
or Google Lyria through OpenRouter.

## Method

Local evidence reviewed:

- `TODOS.md`
- `libs/euterpe/*`
- `docs/domains/euterpe/*`
- `docs/releases/v1/domains/euterpe/*`
- `apps/lilith/svc-ai/src/providers/openrouter-provider.ts`
- `apps/lilith/svc-ai/src/providers/elevenlabs-provider.ts`
- `libs/isis/audio-generation/src/generation/music-generator.ts`

External capability checks were verified against current official sources on
2026-04-02:

- ElevenLabs Music docs, product guides, API reference, and changelog
- OpenRouter API docs and Google Lyria model pages on OpenRouter
- Google Cloud Vertex AI Lyria docs
- Google DeepMind Lyria 3 model card
- Google blog posts for Lyria 3 Pro and prompting guidance

## Repo Reality Snapshot

### Implemented Euterpe Surface

The implemented Euterpe domain is limited to 7 libraries:

- `libs/euterpe/core`
- `libs/euterpe/theory`
- `libs/euterpe/genesis`
- `libs/euterpe/studio`
- `libs/euterpe/voice`
- `libs/euterpe/master`
- `libs/euterpe/spatial`

Supporting docs confirm there are currently:

- 0 Euterpe applications
- 0 Euterpe services
- no explicit API-oriented Euterpe projects
- no explicit database-oriented Euterpe projects

The developer guide also states that Euterpe libraries are pure TypeScript with
zero or minimal runtime dependencies and no required external services.

### Verification State

Direct library verification is healthy:

- 57 Euterpe spec files
- 5,726 tests passed via direct `vitest` runs across all 7 libraries

Nx verification did not complete cleanly because the workspace runner failed
before tests started:

- `pnpm nx run-many --target=test ...` failed due Nx daemon/plugin-worker issues
- direct `pnpm vitest run --config ...` for each Euterpe library passed

### Phase 38 Completion State

From `TODOS.md`, only the first 7 sections are completed:

- `38.1` through `38.7`: complete
- `38.8` through `38.34`: not started in the checklist

Counts from Phase 38:

- completed tasks: 855
- uncompleted tasks: 1,800

That means the shipped Euterpe domain aligns with the first 7 libraries only.
Every later library from `@euterpe/virtuoso` through `@euterpe/podcast` is still
gap territory.

## Major Findings

### 1. Critical: Euterpe has no provider-connected generation runtime

Severity: Critical

The most important gap is that Euterpe itself does not contain real provider
connectors for music generation. The code in `libs/euterpe/genesis` is mostly
algorithmic and simulation-oriented:

- `text-to-music.ts` exports prompt parsing, mood mapping, tempo inference,
  instrumentation suggestion, structure inference, and template filling
- `infrastructure.ts` exports simulated model-registry, routing, batch, stream,
  fine-tune, and quantization primitives

There is no Euterpe-native runtime that:

- calls ElevenLabs Music
- calls OpenRouter for Lyria
- stores generation jobs
- manages async job polling and retries
- persists tracks, stems, lyrics, plans, versions, and provenance
- reconciles provider metadata into Euterpe project/timeline objects

Impact:

- Euterpe cannot currently be the canonical music production layer for Oshun
- provider feature growth does not automatically benefit the Euterpe domain
- there is no stable abstraction for switching or combining music providers

### 2. Critical: OpenRouter integration cannot currently support modern Lyria audio workflows

Severity: Critical

The current OpenRouter implementation in
`apps/lilith/svc-ai/src/providers/openrouter-provider.ts` is chat/image-centric,
not music/audio-centric.

Observed gaps:

- `CompletionParams.messages` only support `content: string`
- no support for multimodal message content arrays
- no support for image-conditioned prompts for music
- no support for audio inputs
- no support for `modalities: ['audio']` or `['audio', 'text']`
- `CompletionResponse` only returns text content
- there is no helper for receiving or decoding audio outputs
- the fallback/routing abstraction is split into `chat`, `embeddings`, and
  `images`, with no `audio` or `music` class

This blocks the key Lyria flows that matter now:

- text-to-audio generation
- text-plus-image-to-music generation
- dual output handling for generated audio plus lyrics/text
- clip-vs-pro model routing
- audio output persistence into Euterpe projects

### 3. Critical: OpenRouter error handling is currently broken in several catch blocks

Severity: Critical

In `apps/lilith/svc-ai/src/providers/openrouter-provider.ts`, multiple catch
blocks record the error and then `throw err;` even though `err` is undefined in
those scopes.

Observed occurrences include:

- `complete()`
- `createEmbedding()`
- `generateImage()`
- multiple A/B routing paths later in the file

Impact:

- real provider failures may be masked by a `ReferenceError`
- debugging provider rollout problems will be materially harder
- this reduces confidence in any future Lyria integration built on top of this
  provider

This is a direct implementation defect, not just a missing feature.

### 4. High: ElevenLabs music support exists, but it is narrow and appears partly stale

Severity: High

There is usable ElevenLabs music support in
`apps/lilith/svc-ai/src/providers/elevenlabs-provider.ts`, but it is not current
enough to claim full SOTA coverage.

What exists:

- basic music generation method
- composition plan generation
- detailed music generation response
- some preset-driven convenience helpers

What is missing or out of date relative to the current official surface:

- local code calls `/v1/music/compose`, while the current official compose route
  is documented as `POST /v1/music`
- local code types use `eleven_music` and `eleven_music_v2`, while current docs
  document `model_id: "music_v1"`
- local code validates duration as `10000-300000ms`; current docs allow
  `3000-600000ms`
- no support for `output_format`
- no support for `seed`
- no support for `force_instrumental`
- no support for `store_for_inpainting`
- no music streaming API support
- no upload-for-inpainting support
- no inpainting workflow
- no support for `finetune_id`
- no support for `sign_with_c2pa`
- no provider-level handling of current copyrighted-material constraints and
  remediation flows

### 5. High: Euterpe has no end-to-end editing flow for modern ElevenLabs Music

Severity: High

Current official ElevenLabs Music supports a much richer product loop than
Euterpe currently models:

- prompt a track
- choose variants and duration
- edit lyrics
- add or remove sections
- adjust section durations
- apply style keywords
- use conversational edits
- generate alternate variations from the same project
- download or share final audio

Euterpe has studio abstractions, but not an integrated provider-backed workflow
that turns:

- prompt
- composition plan
- generated audio
- sections
- lyrics
- variant lineage

into a persistent editable music project.

The practical gap is not “can Euterpe represent music.” It is “can Euterpe run
the contemporary music-creation workflow users actually expect.” Today, the
answer is no.

### 6. High: Lyria-specific product strategy is absent

Severity: High

There is no Lyria-specific orchestration anywhere in the Euterpe domain or the
current OpenRouter integration.

Missing capabilities include:

- model selection between short-clip and longer-structure Lyria modes
- support for Lyria clip ideation flow vs longer composition flow
- handling generated lyrics/text alongside generated audio
- image-conditioned music prompting
- structural prompting for intro, verse, chorus, bridge
- watermark/provenance capture
- evaluation of prompt adherence, structure, and fidelity

The repo has no explicit place where Lyria becomes a first-class music engine.

### 7. High: Provider integration is fragmented outside the music domain

Severity: High

Even where provider code exists, it lives outside Euterpe. The adjacent music
generator abstraction in
`libs/isis/audio-generation/src/generation/music-generator.ts` is also stale
relative to the current provider landscape.

Its `MusicProviderType` is:

- `suno`
- `udio`
- `stable-audio`
- `local`

Notably absent:

- `elevenlabs`
- `openrouter`
- `lyria`

That means the ecosystem-level generator abstraction is not aligned with the
providers now under review.

### 8. Medium: Documentation overstates implemented reality

Severity: Medium

There are several documentation-quality gaps:

- `docs/releases/v1/domains/euterpe/implementation-map.md` says no test files
  were discovered, but the domain has 57 spec files
- generated inventories use broad terms like `implementation-backed` for major
  pillars, while the actual provider runtime, service layer, API layer, and
  storage layer do not exist

This is not just cosmetic. It makes it easy to overestimate how “production
complete” the domain really is.

## External Capability Snapshot

### ElevenLabs Music: Current Useful Surface

Verified from current official docs:

- Eleven Music supports vocals or instrumental generation
- composition plans are first-class
- the API supports music composition plus streaming
- current docs show a music compose endpoint at `POST /v1/music`
- current docs show `POST /v1/music/stream`
- current docs show `POST /v1/music/upload` for later inpainting use
- current request fields include modern controls such as:
  - `output_format`
  - `music_length_ms`
  - `model_id`
  - `seed`
  - `force_instrumental`
  - `store_for_inpainting`
- December 8, 2025 changelog added:
  - `finetune_id` to compose music
  - `sign_with_c2pa` to compose music
  - `finetune_id` to stream music

Product-level current workflows also support:

- variants
- fixed or auto duration
- section editing
- lyric editing
- style keyword application
- conversational iterative edits
- new variations from the same prompt/project

### Google Lyria and Lyria via OpenRouter: Current Useful Surface

Verified from current official docs:

- OpenRouter chat completions support output modalities `text`, `image`, and
  `audio`
- OpenRouter also supports provider selection, `session_id`, and tracing
- OpenRouter’s `google/lyria-3-clip-preview` page states:
  - released March 30, 2026
  - 30-second clips
  - 48kHz stereo audio
  - generation from text prompts or from images
  - vocals
  - timed lyrics
  - full instrumental arrangements
- Google Cloud documents `lyria-002` as GA with:
  - text input
  - audio output
  - negative prompting
  - max clip length 32.8 seconds
  - up to 4 clips per prompt
  - 48kHz sample rate
- Google’s March 25, 2026 Lyria 3 Pro announcement states:
  - tracks up to 3 minutes
  - structural awareness
  - better handling of intros, verses, choruses, and bridges
  - outputs are watermarked
- DeepMind’s Lyria 3 model card states the system outputs both:
  - audio (music)
  - text (lyrics)

Important nuance:

- The DeepMind model card summarizes Lyria 3 as text-input music generation
- Google product docs and OpenRouter model pages describe richer surfaced flows
  including image-conditioned prompting and lyrics-aware generation

Inference:

- image conditioning appears to be exposed at the product/API layer even if the
  base model card describes the core model more narrowly

## Concrete Gap Matrix

### Gap: Euterpe provider abstraction

Current:

- no provider abstraction inside Euterpe for music generation

Needed:

- `MusicGenerationProvider` abstraction inside Euterpe
- providers for ElevenLabs Music and OpenRouter Lyria
- shared normalization of prompt, lyrics, sections, stems, metadata, and
  provenance

### Gap: ElevenLabs advanced generation controls

Current:

- compose
- composition-plan
- compose-detailed

Needed:

- stream preview
- output format selection
- seed/variation control
- forced instrumental mode
- upload for inpainting
- store for inpainting
- inpainting edit cycle
- custom finetune routing
- C2PA signing support
- copyrighted-material remediation path

### Gap: OpenRouter Lyria audio support

Current:

- generic text completion
- image generation only

Needed:

- audio output modality support
- text-plus-image prompt payloads
- dual output parsing: audio plus lyrics/text
- Lyria model discovery and capability routing
- clip-preview vs pro-preview workflow decisions
- audio asset persistence into Euterpe projects

### Gap: Production workflow

Current:

- library logic only

Needed:

- async job orchestration
- persistent project entities
- generation history and lineage
- retry and fallback policies
- provider cost tracking for music jobs
- waveform/section/timeline editing sync

### Gap: Evaluation and QA

Current:

- strong unit coverage for library logic
- no provider e2e evidence for music generation

Needed:

- live smoke tests against ElevenLabs Music
- live smoke tests against Lyria via OpenRouter
- golden prompt set for prompt adherence
- structure and section validation
- audio metadata validation
- latency and cost benchmarks
- regression tests for lyrics/audio pairing and image-conditioned prompting

### Gap: Trust, provenance, and compliance

Current:

- no first-class music provenance flow in Euterpe

Needed:

- C2PA support where provider exposes it
- provider watermark capture and storage
- rights/commercial-use metadata persistence
- artist/style safety policy enforcement
- copyrighted-material rejection and fallback UX

## Recommended Flows To Add

### P0: ElevenLabs “full current product loop”

Implement this exact workflow:

1. prompt -> composition plan
2. composition plan -> detailed generation
3. stream or preview candidate variants
4. section-aware editor:
   - lyrics edit
   - add section
   - remove section
   - resize section
   - style-keyword refine
5. final compose/export with:
   - selected output format
   - optional forced instrumental mode
   - optional C2PA signing
6. optional:
   - store for inpainting
   - upload existing song
   - re-inpaint selected region/section

### P0: Lyria via OpenRouter “clip-to-song workflow”

Implement this workflow:

1. discover compatible Google audio-output models through OpenRouter metadata
2. route:
   - `google/lyria-3-clip-preview` for ideation, hooks, loops, and fast variants
   - longer-capability Lyria route when available for structured songs
3. request `modalities: ['audio', 'text']`
4. parse:
   - audio output
   - lyrics/text output
5. support multimodal prompt input:
   - text-only
   - text + image
6. persist generated clips to an Euterpe project timeline
7. evaluate best clip, then extend/arrange/master downstream

### P1: Unified provider-normalized music project model

Create a canonical Euterpe project entity that stores:

- provider
- provider model
- prompt
- reference assets
- composition plan
- section breakdown
- lyrics
- output audio
- stems if available
- provenance/watermark/C2PA fields
- cost
- latency
- seed
- variant lineage

### P1: Real evaluation harness

Create a provider evaluation package that scores:

- prompt adherence
- structure adherence
- vocal quality
- instrumental quality
- lyric intelligibility
- timing alignment
- loop quality
- loudness/basic technical compliance
- cost per usable result
- p50 and p95 latency

### P1: Euterpe-native service layer

Add a real service surface for music jobs:

- submit generation job
- poll/cancel job
- list variants
- branch variant
- edit sections
- export deliverables
- capture provenance and provider metadata

## Prioritized Remediation Plan

### Phase A: Fix blocking implementation defects

- Fix all `throw err;` bugs in the OpenRouter provider
- Add OpenRouter audio output support
- Add multimodal message payload support for image-conditioned Lyria prompts
- Add an `audio` capability class beside `chat`, `embeddings`, and `images`

### Phase B: Modernize ElevenLabs music integration

- Update compose endpoint usage to match current docs
- update model ID handling
- expand duration validation to current provider limits
- add output format, seed, forced instrumental, store-for-inpainting
- add stream and upload endpoints
- add finetune and C2PA support

### Phase C: Move provider ownership into Euterpe

- create `@euterpe/providers` or `@euterpe/connectors`
- create `@euterpe/workflows` for music-job orchestration
- create `@euterpe/evals` for live provider evaluation

### Phase D: Build the real product loop

- project persistence
- variant lineage
- section editor
- lyrics editor
- preview/export pipeline
- provenance and compliance

## Bottom Line

Euterpe is not missing musical intelligence. It is missing the runtime layer
that turns that intelligence into a current provider-native music product.

For current-state SOTA alignment, the biggest immediate gaps are:

1. no Euterpe-native provider orchestration
2. OpenRouter provider cannot do Lyria audio workflows yet
3. ElevenLabs music integration is only partial and partly stale
4. no persistent editing, provenance, or evaluation loop

If the goal is to make Euterpe genuinely best-in-class for AI music production,
the next work should not start with more theory primitives. It should start with
provider runtime, workflow orchestration, and live evaluation.

## Sources

Local repository evidence:

- `TODOS.md`
- `libs/euterpe/*`
- `docs/domains/euterpe/*`
- `docs/releases/v1/domains/euterpe/*`
- `apps/lilith/svc-ai/src/providers/openrouter-provider.ts`
- `apps/lilith/svc-ai/src/providers/elevenlabs-provider.ts`
- `libs/isis/audio-generation/src/generation/music-generator.ts`

Official external sources used:

- ElevenLabs Music quickstart: `https://elevenlabs.io/docs/cookbooks/music`
- ElevenLabs Music product overview:
  `https://elevenlabs.io/docs/eleven-creative/products/music`
- ElevenLabs Music capability overview:
  `https://elevenlabs.io/docs/capabilities/music`
- ElevenLabs compose endpoint:
  `https://elevenlabs.io/docs/api-reference/music/compose`
- ElevenLabs stream endpoint:
  `https://elevenlabs.io/docs/api-reference/music/stream`
- ElevenLabs upload endpoint:
  `https://elevenlabs.io/docs/api-reference/music/upload`
- ElevenLabs changelog, 2025-12-08:
  `https://elevenlabs.io/docs/changelog/2025/12/8`
- OpenRouter chat completion API:
  `https://openrouter.ai/docs/api-reference/chat-completion`
- OpenRouter image generation docs:
  `https://openrouter.ai/docs/guides/overview/multimodal/image-generation`
- OpenRouter audio input docs:
  `https://openrouter.ai/docs/guides/overview/multimodal/audio`
- OpenRouter Google Lyria 3 Clip Preview:
  `https://openrouter.ai/google/lyria-3-clip-preview`
- Google Cloud Lyria generation guide:
  `https://docs.cloud.google.com/vertex-ai/generative-ai/docs/music/generate-music`
- Google Cloud Lyria prompt guide:
  `https://docs.cloud.google.com/vertex-ai/generative-ai/docs/music/music-gen-prompt-guide`
- Google Cloud Lyria 2 model page:
  `https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/lyria/lyria-002`
- Google blog, Lyria 3 Pro:
  `https://blog.google/innovation-and-ai/technology/ai/lyria-3-pro/`
- Google blog, tips for using Lyria 3:
  `https://blog.google/products-and-platforms/products/gemini/tips-prompting-lyria-3/`
- Google DeepMind Lyria 3 model card:
  `https://deepmind.google/models/model-cards/lyria-3/`
