Vellium: Slider-Based AI Story Mood Control Tool

from vellium import StoryGenerator

story = StoryGenerator()
story.set_mood(darkness=0.8, tension=0.6, whimsy=0.2)
output = story.generate("A detective enters an abandoned warehouse")

This code snippet demonstrates Vellium’s core functionality: adjusting narrative mood through numerical sliders before generating AI-written content. The tool provides writers with granular control over emotional tone, allowing them to dial specific atmospheric qualities up or down rather than relying on text prompts alone.

How Vellium Works

Vellium operates as a middleware layer between writers and large language models, translating slider positions into weighted prompt modifications. The system supports multiple mood dimensions simultaneously, including darkness, tension, whimsy, romance, mystery, and action intensity. Each slider operates on a 0-1 scale, with values combining to create a mood vector that influences the underlying AI’s output.

The tool integrates with popular language models including GPT-4, Claude, and open-source alternatives through a unified API. Writers install Vellium via pip and configure their preferred model backend through environment variables or a configuration file. The slider interface exists both as a Python library for programmatic control and as a web-based GUI for interactive experimentation.

Unlike traditional prompt engineering, which requires careful word choice and iterative refinement, Vellium’s numerical approach offers reproducibility. A mood configuration of (darkness=0.7, tension=0.5) produces consistent atmospheric results across multiple generation attempts, making it valuable for maintaining tonal consistency across chapters or scenes.

Setting Up the Environment

Installation requires Python 3.8 or higher and an API key for the chosen language model backend. The basic setup process involves:

pip install vellium
export OPENAI_API_KEY="your-key-here"

For local model deployment, Vellium supports Ollama and llama.cpp backends, eliminating API costs for writers working with open-source models. The configuration file accepts custom mood dimensions beyond the defaults, allowing genre-specific adjustments like “cosmic horror” or “noir atmosphere.”

The web interface launches through a simple command that starts a local server on port 5000. This GUI displays real-time previews as sliders adjust, showing how mood changes affect sample text before committing to full generation. Writers can save preset configurations as JSON files for reuse across projects.

Practical Applications

Vellium excels at maintaining atmospheric consistency across long-form fiction. A writer working on a mystery novel might establish baseline settings (mystery=0.8, tension=0.6, darkness=0.4) for investigation scenes, then adjust individual sliders for specific moments. A confrontation scene could increase tension to 0.9 while maintaining other values, ensuring tonal coherence with the broader narrative.

The tool also supports A/B testing different emotional approaches to the same scene:

# Generate two versions with different mood profiles
version_a = story.set_mood(romance=0.8, whimsy=0.6).generate(scene_prompt)
version_b = story.set_mood(romance=0.8, tension=0.5).generate(scene_prompt)

Interactive fiction developers use Vellium to create dynamic narratives that shift mood based on player choices. By linking slider values to game state variables, the system adjusts atmospheric tone in response to player decisions without requiring manually written variations for every emotional permutation.

Content teams working on branded storytelling appreciate the reproducibility factor. Once a brand’s tonal guidelines are translated into slider configurations, multiple writers can generate on-brand content without extensive style guide consultation.

Constraints and Considerations

Vellium’s effectiveness depends heavily on the underlying language model’s capabilities. Smaller models may not respond predictably to subtle slider adjustments, producing inconsistent results when mood values change by small increments. The tool works best with models that have been fine-tuned on diverse creative writing datasets.

The slider abstraction, while intuitive, introduces a layer of indirection between writer intent and output. Complex emotional nuances that require specific cultural context or subtle tonal shifts may not map cleanly to numerical values. A scene requiring “melancholic hope” might need careful balancing of multiple sliders plus supplementary prompt text.

Processing overhead increases with the number of active mood dimensions. Each slider adds computational complexity to the prompt construction process, potentially slowing generation times when working with six or more simultaneous dimensions. Writers must balance granular control against performance requirements.

The tool currently lacks memory of previous generations within a session, treating each request independently. Long-form projects requiring narrative continuity still need traditional context management approaches alongside mood control. Vellium handles atmosphere but not plot coherence or character consistency across extended narratives.