calliope library

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.

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.

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.

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.

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.

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".

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.