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.