Calliope Example Story Strategies: The Complete Guide to 8 Built-in Generators

Calliope provides eight production-ready story-generation strategies—including simple-one-frame, tamarisk, continuous-v0, continuous-v1, lavender, fern, narcissus, and literal—that implement the abstract StoryStrategy interface to transform text prompts and contextual metadata into sequential narrative frames.

The chrisimmel/calliope repository is an open-source AI storytelling engine that uses pluggable example story strategies to control how narratives evolve from input to output. Each concrete strategy extends the base class defined in calliope/strategies/base.py and registers itself with the StoryStrategyRegistry located in calliope/strategies/registry.py via the @StoryStrategyRegistry.register() decorator, enabling runtime selection through the strategy_name attribute.

How Calliope Story Strategies Work

Every strategy inherits from the abstract StoryStrategy class and implements the async method get_frame_sequence(). This method receives parameters, optional image analysis, and location metadata, then follows a standardized five-step workflow: collect context, build an LLM prompt, call inference utilities (such as text_to_text_inference or text_to_image_file_inference), create a StoryFrame via the protected _add_frame() helper, and return a StoryFrameSequenceResponseModel containing the new frames and debug data.

The registry maintains a mapping from strategy_name → class, allowing the API to look up implementations dynamically using StoryStrategyRegistry.get_strategy_class(name).

Simple Frame Generation Strategies

These strategies focus on generating individual frames with minimal narrative continuity, ideal for one-off images or literal prompt interpretation.

simple-one-frame

The SimpleOneFrameStoryStrategy class in calliope/strategies/simple_one_frame.py provides the original /story/ endpoint behavior. It generates a single frame based on the input text or image description, returning both the generated image and accompanying text without narrative continuation.

narcissus

Implemented in calliope/strategies/narcissus.py, the NarcissusStrategy ignores generated text and produces an image solely from the image description input. It mirrors the input description directly into the visual output, making it useful for pure image-generation workflows without narrative elaboration.

literal

The LiteralStrategy in calliope/strategies/literal.py parses a pipe-delimited list of prompts from input_text (e.g., "prompt one | prompt two") and generates a separate frame for each segment. Each prompt yields its own image and echoes the prompt text exactly, enabling batch generation from a single input string.

Continuous and Evolutionary Strategies

These strategies implement "exquisite corpse" style continuity, where each new frame builds upon the previous text to create ongoing narratives.

continuous-v0

The ContinuousStoryV0Strategy in calliope/strategies/continuous_v0.py implements the classic continuous approach. It extracts the last few sentences of the existing story, feeds them to a lightweight language model (such as gpt-neo-2.7B), and generates a single new frame from the model's output, preserving narrative flow through textual context.

continuous-v1

Found in calliope/strategies/continuous_v1.py, ContinuousStoryV1Strategy follows the same architectural pattern as v0 but incorporates updated prompting logic and refined inference parameters to improve coherence and stylistic consistency.

tamarisk

The TamariskStrategy in calliope/strategies/tamarisk.py represents an evolution of the continuous-v0 approach. It constructs frames from short, translated prompts and employs GPT-4-o to clean and refine the generated text, producing higher-quality narrative continuations with optimized linguistic structure.

Context-Aware and Multi-Modal Strategies

These advanced strategies leverage environmental metadata and structured state to create richer, contextually grounded narratives.

lavender

Implemented in calliope/strategies/lavender.py, the LavenderStrategy utilizes situational metadata—including location, weather, and time—alongside prompt templates to generate nuanced story continuations. This strategy enriches outputs by grounding the narrative in the simulated or real-world context of the story environment.

fern

The FernStrategy in calliope/strategies/fern.py is the most sophisticated example strategy. It initializes a structured story state tracking genre, cast, and settings, consults a dedicated "muse" model for chaotic inspiration, constructs multi-part LLM prompts, and can generate both image and short video for each frame, enabling complex multi-modal storytelling.

Working with the Strategy Registry

You can programmatically inspect and instantiate these strategies using the registry API.

List all available strategies

from calliope.strategies.registry import StoryStrategyRegistry

available = StoryStrategyRegistry.get_all_strategy_names()
print("Calliope strategies:", list(available))

# Output: ['simple-one-frame', 'tamarisk', 'continuous-v0', 'continuous-v1', 

#          'lavender', 'fern', 'narcissus', 'literal']

Instantiate and use a specific strategy

from calliope.strategies.registry import StoryStrategyRegistry
from calliope.models import FramesRequestParamsModel

# Configure request parameters

params = FramesRequestParamsModel(
    client_id="example-client",
    input_text="A moonlit forest with whispering leaves",
    output_image_style="A dreamy watercolor style.",
)

# Retrieve strategy class by name

strategy_cls = StoryStrategyRegistry.get_strategy_class("lavender")
strategy = strategy_cls()

# Execute generation (inside async context)

# frame_sequence = await strategy.get_frame_sequence(

#     parameters=params,

#     image_analysis=None,

#     location_metadata=location_data,

#     strategy_config=config,

#     keys=keys,

#     sparrow_state=sparrow,

#     story=story_state,

#     httpx_client=client,

# )

Register a custom strategy

from calliope.strategies.registry import StoryStrategyRegistry
from calliope.strategies.base import StoryStrategy

@StoryStrategyRegistry.register()
class MyCustomStrategy(StoryStrategy):
    strategy_name = "my-custom"

    async def get_frame_sequence(self, parameters, image_analysis,
                                 location_metadata, strategy_config,
                                 keys, sparrow_state, story, httpx_client):
        # Custom generation logic

        return await self._add_frame(...)

Summary

• Calliope provides eight active story strategies ranging from simple single-frame generation to complex narrative engines with video support.
• Each strategy implements the StoryStrategy interface and registers via StoryStrategyRegistry using the strategy_name attribute.
• Simple strategies (simple-one-frame, narcissus, literal) handle discrete image generation without narrative continuity.
• Continuous strategies (continuous-v0, continuous-v1, tamarisk) use previous story context to drive ongoing narratives.
• Advanced strategies (lavender, fern) incorporate environmental metadata and structured story state for context-aware, multi-modal output.
• The registry pattern in calliope/strategies/registry.py enables dynamic strategy lookup and supports custom strategy registration through decorators.

Frequently Asked Questions

How do I list all available example story strategies in Calliope?

Import StoryStrategyRegistry from calliope/strategies/registry.py and call the class method get_all_strategy_names(). This returns a collection of registered strategy identifiers such as simple-one-frame, fern, and lavender that you can pass to get_strategy_class() for instantiation.

Which Calliope strategy supports video generation?

The fern strategy (FernStrategy in calliope/strategies/fern.py) is the only built-in strategy capable of generating both image and short video content. It achieves this through sophisticated prompt engineering and structured story state management that includes cast, genre, and setting tracking.

What is the difference between continuous-v0 and continuous-v1?

Both strategies implement continuous narrative generation using previous story context, but continuous-v0 (calliope/strategies/continuous_v0.py) uses the original prompting approach optimized for smaller models like gpt-neo-2.7B, while continuous-v1 (calliope/strategies/continuous_v1.py) applies updated prompting logic and parameter tuning for improved coherence with modern language models.

How do I create a custom story strategy for Calliope?

Extend the abstract StoryStrategy class from calliope/strategies/base.py, implement the get_frame_sequence() async method to define your generation logic, and decorate your class with @StoryStrategyRegistry.register(). Set the strategy_name class attribute to expose your strategy to the API, then use _add_frame() to construct and return valid StoryFrame objects within your implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}