# Calliope — Systems Deep Dive

> The `libs/calliope/` area: thirty Nx libraries that build and operate
> **autonomous fictional music artists** — birthing a persona, giving it a
> voice, face, choreography, songs, shows, fandom and lore, then running its
> career through quality gates, compliance, an agentic runtime and a bridge to
> the wider Oshun universe.

## What this area is

Calliope (the muse of epic poetry) is the synthetic-artist domain: a stack of
TypeScript libraries that conceive a fictional recording artist from a seed,
generate every creative surface that artist needs, and run the day-to-day
operations of its career. It is not one package but **thirty separate Nx
libraries** under `libs/calliope/`, every one tagged `scope:calliope`,
`layer:domain`, `type:lib`, and published under the `@calliope/*` npm scope.

The libraries are real implementations, not scaffolds. The pattern is consistent
across the area: each service file declares a Zod input schema, runs a
deterministic domain algorithm (statistical deviation checks, logistic
win-probability proxies, color-harmony scoring, beat-timing windows, vocal
fingerprint classifiers, hash-chained provenance), and returns a
schema-validated result — verified by an extensive `*.spec.ts` suite living next
to each service. Most libraries are large (10k–32k LOC of source); the few small
ones (`@calliope/composer`, `@calliope/sound-design`,
`@calliope/match-commentary`, `@calliope/v4-narrative`) are honest
single-purpose packages described as such below.

At the centre sits `@calliope/core`, imported by every other library (371
cross-references across the area). It owns the Drizzle/pgvector database schema
(`core/src/db-schema.ts`), the Postgres primary+replica topology
(`core/src/database.ts`), the Avro/Kafka event pipeline with a hash-chained
ledger (`core/src/events/`), and the shared domain types (`Artist`, `ArtistEra`,
`PersonaSeed`, `SonicProfile`, `VisualProfile`, …). The other libraries layer on
top of it: identity and creation (`genesis`, `voice`, `visage`, `glamour`,
`kinesis`), music (`muse`, `pathos`, `synesthesia`), presentation (`cinema`,
`stage`, `nexus`), audience and brand (`presence`, `fandom`, `brand`,
`artifacts`, `persona-live`, `lore`), business and lifecycle (`distro`, `label`,
`evolution`, `duet`), governance (`muse-gate`, `compliance`), and the platform
seams (`agents`, `bridge`).

## How it fits the wider system

These libraries compose two ways. Internally, they form a dependency pyramid on
`@calliope/core`, with a second tier of heavily-reused libraries (`brand`,
`muse`, `visage`, `presence`, `genesis`) that the creative and operational
services build on. Externally, `@calliope/bridge` is the single integration
seam: it carries typed contracts and adapters for other Oshun domains (Aja, Aje,
Aphrodite, Euterpe, Hathor, Isis, Maya, Psyche, Sophia, Themis, Uzume, plus
Galatea/Iris/Nyx/Yemaya adapters) and a cross-domain Avro event bus, so Calliope
talks to the rest of the platform without those domains importing Calliope's
internals.

A second integration surface is the **V4 game tie-in**:
`@calliope/match-commentary` and `@calliope/v4-narrative` route gated creative
prose through shared platform infrastructure (`@oshun/ai`'s provider-agnostic
`LLMProviderInterface`, `@oshun/content-quality-judge`,
`@oshun/content-release-gates`) for the V4 codebase to consume. The
`@calliope/composer` and `@calliope/sound-design` facades emit deterministic
temp-score / Foley packages for a CGI/production review pipeline. Walk the "used
by" edges on any node below to see exactly who depends on it.

## Entity reference

### @calliope/core

The foundation every other Calliope library imports (`libs/calliope/core`, 371
in-area references). It owns the persistence and domain spine: a Drizzle schema
with pgvector columns and Postgres enums for artist/career/song/album status
(`core/src/db-schema.ts`), a primary+replica database topology with distinct
OLTP/OLAP connection profiles over `@oshun/database` (`core/src/database.ts`),
an Avro+Kafka event pipeline with a hash-chained ledger and topic config
(`core/src/events/`), OpenAPI schemas, and the shared domain types (`Artist`,
`ArtistEra`, `PersonaSeed`, `SonicProfile`, `SynestheticProfile`,
`VisualProfile`, …). It also exposes cross-cutting services —
`consistency-enforcer` (Qdrant vector-similarity drift detection with
statistical deviation thresholds), `artist-identity-validator`,
`creative-brief-builder`, asset storage, rate limiting, logging and metrics.

### @calliope/genesis

The artist-birth pipeline (`libs/calliope/genesis`, ~24k LOC, 51 source files —
the largest library by file count). It turns an artist concept into a complete
identity: name and dual-name systems, Big Five and attachment-style personality
profiles, backstory and origin story, mythology graphs, cultural-authenticity
validation, and physical/visual specs. Its `artist-dna-encoder` composes these
into a versioned, sha256-hashed DNA document chained to its previous hash, and a
`persona-seed-immutability-guard` enforces that the seed cannot drift —
provenance is first-class here, not decorative.

### @calliope/voice

The vocal-identity engine (`libs/calliope/voice`, 58 source files). It models a
synthetic artist's singing and speaking voice end to end: vocal-signature
generation and evolution tracking, dynamic-range and emotional-arc mapping,
genre-specific technique, rap flow/cadence/freestyle, harmony and group-vocal
chemistry, ad-libs, laughs and natural imperfection injection. Its
`recognizability-scorer` builds a vocal fingerprint and runs a classifier-margin
comparison against rival signatures to estimate 3-second recognition accuracy
and a "radio test" pass — concrete domain math, not a placeholder.

### @calliope/visage

The face/body and avatar-generation library (`libs/calliope/visage`, 57 source
files). It covers facial generation and consistency validation, expression and
gesture/posture vocabularies, LoRA training orchestration, aging models,
body-proportion specs, makeup variation, and a full avatar pipeline (generation,
LOD management, export, platform-specific export). It also owns the photography
and album-art surfaces (character sheets, era lookbooks, magazine-cover and
photoshoot simulators, press kits), several of which are shared with
`@calliope/glamour`.

### @calliope/glamour

The fashion, beauty and visual-campaign library (`libs/calliope/glamour`, ~19k
LOC). It designs the artist's styling: hair (architecture, physics profile,
cultural advisor, evolution timeline), makeup (designer, look library, prompt
engine, evolution tracker), tattoos and piercings with consistency tracking,
accessories and nail art, outfit generation, and avant-garde beauty direction. A
`glamour-coherence-validator` and `cultural-fashion-validator` keep looks
internally consistent and culturally vetted; it composes types from
`@calliope/core` and `@calliope/cinema`.

### @calliope/kinesis

The movement and choreography engine (`libs/calliope/kinesis`, 52 source files).
It generates dance from music: a `beat-synchronizer` with per-mode timing
windows (`k_pop_precision`, `concert_grade`, `loose_ensemble`,
`intentional_offset`), formation design and transition choreography,
signature-move and movement-DNA generation, canon-and-cascade group structures,
motion-capture adapters (markerless mocap, retargeting), TikTok/viral
choreography prediction, and a choreography-to-video renderer. The algorithms
are quantitative (timing windows in frames, difficulty calibration), grounded in
`core` movement types.

### @calliope/muse

The songwriting and music-production library (`libs/calliope/muse`, ~32k LOC —
the largest by source size). It composes songs end to end: melody/harmony
architecture, hook craftsmanship, lyric writing, arrangement, bridge and ad-lib
specialists, mixing/mastering directors, stem separation, and a
production-prompt compiler. Above the song level it handles album concept,
cohesion analysis, rollout orchestration, deluxe-edition planning, track
sequencing, genre blending/taxonomy, and discography-coherence and
style-evolution engines.

### @calliope/pathos

The psychoacoustic / emotional-architecture library (`libs/calliope/pathos`,
~12k LOC). It engineers how the music _feels_: emotional-arc and tension-release
design, goosebump and euphoria architects, nostalgia and melancholy engines,
binaural/spatial design, frequency-spectrum optimization, personalized HRTF,
rhythmic entrainment, and crowd-scale psychoacoustic engineering. It targets
emotional and contextual-listening outcomes rather than the notes themselves,
complementing `@calliope/muse`.

### @calliope/synesthesia

The cross-modal mapping library (`libs/calliope/synesthesia`, ~13k LOC). It
translates between sensory modalities — sound→color/shape/texture/space/motion
mappers, visual→sonic and fashion→sound and environment→soundscape translators —
plus a coherence scorer, a cross-modal-consistency guard, modality-transfer
learning, and a real-time audio-reactive generator. It keeps an artist's sonic
and visual identities aligned so a song, its artwork and its staging share one
synesthetic signature.

### @calliope/sound-design

A focused **facade** package (`libs/calliope/sound-design`, single
`src/index.ts`, ~682 LOC) for AI sound-design and Foley over CGI environment
audio. It is real deterministic logic, not a stub:
`createCalliopeSoundDesignPackage` generates Foley assets (sync-frame-aligned),
ambience layers and supplemental room-tone/designed-effect assets from
environment briefs, and `validateCalliopeSoundDesignPackage` enforces coverage,
spatial-emitter, stem-handoff and AI-provenance rules with blocking/warning
severities. It self- describes as a "facade for CGI environment audio" in
`CALLIOPE_SOUND_DESIGN_METADATA`.

### @calliope/composer

The sibling facade for temporary soundtrack / rough-cut score
(`libs/calliope/composer`, single `src/index.ts`, ~456 LOC). Like `sound-design`
it is real deterministic code: `createCalliopeComposerScorePackage` builds cues
per scene-brief with emotion-driven instrumentation and stem targets, and
`validateCalliopeComposerScorePackage` checks purpose coverage, duration
coverage (≥90%), sync points, stem handoff and AI provenance. It is explicitly a
"temp soundtrack and rough-cut score facade for production review," not a full
DAW.

### @calliope/cinema

The video-production library (`libs/calliope/cinema`, ~23k LOC, 32 source
files). It covers the music-video and visual-album pipeline: scene/storyboard
generation, narrative direction, camera virtual operation, lighting and color
grading, VFX supervision, character-consistency enforcement and IP-Adapter
management, cinematic transitions, motion graphics, lyric-video and
vertical-video adapters, wardrobe direction, batch rendering and final output.
It exports a `MusicVideoStyleGuideSchema` consumed by governance libraries such
as `@calliope/muse-gate`.

### @calliope/stage

The live-performance library (`libs/calliope/stage`, ~22k LOC). It designs
concerts, tours, festival sets and residencies: setlist architecture, stage and
lighting design, screen-content direction, choreography coordination, encore and
costume-change dramaturgy, pyrotechnics, real-time VFX, spatial-audio mixing,
holographic and AR experiences, immersive world-building, audience simulation
and wearable orchestration, virtual venue/camera systems, and streaming
integration.

### @calliope/nexus

The gaming and metaverse library (`libs/calliope/nexus`, ~12k LOC). It places
the artist inside virtual worlds: in-game concert design with setlist adaptation
and analytics, metaverse space building and event coordination, virtual avatars
and merch shops, character-skin design, game-soundtrack placement, esports
partnerships, cross-platform identity bridging, and metaverse platform/roadmap
evaluation. It is the bridge from Calliope's artist into playable/virtual
venues.

### @calliope/presence

The social-presence library (`libs/calliope/presence`, ~12k LOC, and one of the
most-reused — 74 in-area references). It runs the artist's social identity:
post/story/short-form generation, conversation-style and contextual-tone
adaptation, cross-platform narrative threading, community-mood tracking,
reputation monitoring, crisis-response, platform-algorithm optimization, hashtag
strategy, UGC curation, and a `parasocial-safety-guard`. It is how the artist
"behaves" online across platforms.

### @calliope/fandom

The fan-community library (`libs/calliope/fandom`, ~15k LOC). It builds and runs
the artist's fanbase: community-space and Discord-server architecture, fan
challenges, collaboration platforms, content vaults, art showcases, journey
mapping, a points/token economy, tier and club systems, segment analysis,
moderation toolkits, global fandom mapping, fandom-name generation, and
inside-joke evolution. It is the structural counterpart to `presence` (the
audience, vs. the artist's own voice).

### @calliope/brand

The brand-and-marketing library (`libs/calliope/brand`, ~12k LOC, and the
most-reused after `core` — 159 in-area references). It owns brand strategy and
architecture, brand-voice writing, audit and performance tracking, competitive
landscape monitoring, licensing-opportunity detection, merch design/strategy, PR
narrative, visual brand systems, and the full campaign apparatus (architect,
budget simulator, ROI analyzer, content calendar, teaser and viral-moment
designers, audience personas/insights). It is the commercial identity layer many
other libraries reference.

### @calliope/artifacts

The physical-media and collectibles library (`libs/calliope/artifacts`, ~12k
LOC). It designs tangible products: vinyl (standard and specialty), CD, cassette
and USB media, album packaging and unboxing-experience architecture, photocards
and trading cards (with a `random-packing-algorithm` and card-trade hub),
figures, light sticks, NFC bridges, and fictional-brand merch. It adds
print-spec generation, production-cost calculation, sustainability advice and
seasonal-collectible planning — the manufacturing-aware side of merchandise.

### @calliope/persona-live

The media-personality library (`libs/calliope/persona-live`, ~11k LOC). It
models the artist as an interview/press subject: anecdote libraries, interview
personality and response models, media-training protocols, press-conference and
red-carpet handlers, podcast-guest and live-Q&A engines, speech and quote
writers, documentary participation, and a text-personality engine. It also
exports a `CommentatorPersonaAuthoring` surface (with manifest validation) used
for the V4 two-host commentary personas.

### @calliope/lore

The narrative-universe library (`libs/calliope/lore`, ~22k LOC). It builds the
fictional world around the artist: a universe architect/canon manager with a
consistency guard, mystery-arc and red-herring design, ARG engines (geotag
triggers, phone-voicemail puzzles), interactive fiction, transmedia content
production, cross-artist narrative weaving, fan-theory tracking, timeline
management, and a lore compendium generator. It treats canon as a managed,
consistency-checked database rather than free text.

### @calliope/distro

The distribution and music-industry library (`libs/calliope/distro`, ~16k LOC).
It handles the release-to-revenue path: a distribution orchestrator and release
scheduler, DDEX and mechanical-licensing compliance, metadata management,
audio-fingerprint registration, chart and playlist strategy, radio promotion,
Shazam/cross-platform discovery optimization, sync and territory licensing,
royalty calculation, revenue tracking, monetization optimization, back-catalog
management, award campaigns, and industry-network mapping.

### @calliope/label

The roster-and-label-operations library (`libs/calliope/label`, ~13k LOC). It
manages a label of artists rather than a single one: roster architecture and
relationship management, artist onboarding and retirement planning, group
formation, sub-unit/solo management, release-calendar coordination,
cross-promotion, A&R, label brand and narrative, finance and resource
allocation, performance benchmarking, and fan-shipping-dynamics management. It
is the portfolio layer above the individual-artist libraries.

### @calliope/evolution

The career-evolution library (`libs/calliope/evolution`, ~13k LOC). It models
how an artist changes over time: a career-arc designer, artistic-maturity model,
era architect/consistency manager and parallel-era manager, creative-renewal and
pivot-advisor engines, growth tracking, legacy building, timing optimization,
competitive positioning, era-transition design/communication/retrospective, and
songwriting/vocal evolution trackers. It operates on `core`'s `ArtistEra` and
`CareerPhase` types.

### @calliope/duet

The human-AI collaboration library (`libs/calliope/duet`, ~14k LOC). It brokers
collaborations between the synthetic artist and human creators: a collaboration
broker and portfolio, creative-session manager, real-time call-and-response,
topline and feature-verse crafters, songwriting-partner interface,
producer-brief/feedback/relationship management, writing-camp simulator,
festival integration, collaborative marketing/performance planning, and a
credit-attribution engine for fair co-authorship records.

### @calliope/muse-gate

The artistic quality-gate library (`libs/calliope/muse-gate`, ~17k LOC). It is
the release-readiness governor: aesthetic, holistic-aesthetic, song, video and
choreography quality scorers, authenticity and emotional-authenticity
validators, AI-artifact detection, persona-consistency and visual-consistency
checking, a cultural-sensitivity gate, human-override protocol, regression
detector, feedback loop, dashboard, and a `gate-orchestrator` that composes
them. Its scorers pull real types from `@calliope/core` and `@calliope/cinema`
and compute concrete metrics (e.g. color-harmony assessment, standard deviation
across samples) rather than truthiness.

### @calliope/compliance

The AI-ethics and compliance library (`libs/calliope/compliance`, ~18k LOC). It
enforces responsible-AI and legal guardrails: AI-disclosure management, an
ethics advisor, consent framework, content-safety and explicit-content scanners,
copyright-compliance and IP-protection engines, deepfake-prevention guard,
cultural-respect and representation/inclusivity auditors, data-privacy guard,
legal-risk and platform-policy/regulatory compliance trackers, plus
training-data-provenance, fair-revenue and compute-environmental auditors. It is
the "is this allowed and fair" layer parallel to `muse-gate`'s "is this good".

### @calliope/agents

The agentic-operations runtime (`libs/calliope/agents`, ~22k LOC). It is the
autonomous-operator layer: an `AgentOrchestrator` that schedules agents under
CPU/ GPU/memory/budget constraints and a quality floor, an escalation handler,
audit log, memory store and tool registry, plus a roster of role agents (artist
genesis, album/single/song production, music-video and concert production,
collaboration, fan engagement, era launch, crisis response, analytics, QA,
lore-keeper, daily operations). The orchestrator's Zod schema models real
resource economics (per-agent GPU slots, daily USD budget, consecutive-failure
and stall tracking), not a toy loop.

### @calliope/bridge

The cross-domain integration seam (`libs/calliope/bridge`, ~20k LOC, 35 source
files). It is how Calliope talks to the rest of Oshun: typed contracts for Aja,
Aje, Aphrodite, Euterpe, Hathor, Isis, Maya, Psyche, Sophia, Themis and Uzume,
matching per-domain adapters (plus Galatea, Iris, Nyx and Yemaya adapters), a
`CrossDomainEventBus` that emits Avro-typed cross-domain events keyed by the
`@calliope/core` `ArtistIdSchema`, a knowledge-pipeline manager, audio-tools and
visual-pipeline orchestration, and a `VirtuosoMigrationBridge`. It keeps the
integration surface in one library so consumers don't reach into Calliope's
internals.

### @calliope/match-commentary

A focused V4 tie-in package (`libs/calliope/match-commentary`, ~1.5k LOC, no
spec files but a documented module surface). Its `package.json` describes it as
"V4 end-of-match and live commentary: moment scoring, highlight reel selection,
two-host persona commentary on the shared agentic runtime, and the bias-review
broadcast gate." The deterministic core (`moment-scoring.ts`) scores match
events with explicit base weights, multi-kill chaining and clutch bonuses,
derives turning points from a logistic win-probability proxy, and selects reel
segments; the `MatchCommentaryGenerator` routes prose through `@oshun/ai`'s
provider-agnostic `LLMProviderInterface` with structure pinned by the scored
data, and `gateCommentaryForBroadcast` blocks unreviewed/biased output from
broadcast.

### @calliope/v4-narrative

The V4 codex/mission narrative package (`libs/calliope/v4-narrative`, ~926 LOC).
Its `package.json` and module header describe it precisely: V4 narrative routed
through the Phase-1/2 quality stack — best-of-N generation, a judge gate,
self-refine, and a corpus-diversity gate — emitting gated, provenance-bound
artifacts for V4Procgen consumption (ledger §9.3a). It composes
`@oshun/content-quality-judge` and `@oshun/content-release-gates` rather than
re-implementing them, adds a V4-specific grounding gate (`v4-grounding.ts`) that
checks prose against a canon corpus, and surfaces a
`V4NarrativeQualityPipeline`. The deterministic V4 planner still owns structure;
this package surfaces the player-facing prose under quality control.