StoryTeller/docs/story-teller-specification.md

Story Teller – Application Specification

1. Overview

Story Teller is a web application where an AI collaboratively builds a story step by step with the user.

The user starts from a predefined scenario (starting scene and characters), gives directions about what should happen next, optionally edits the scene and characters, and the AI produces the next part of the story. The system manages scenes, story steps, and automatic context compaction when AI prompts become too large.

---

2. User Roles & Permissions

2.1 Roles

• Regular user

  • Authenticate via simple login.
  • Manage own content:
    • Create, edit, delete scenarios (starting points).
    • Create, edit, delete starting characters associated with their scenarios.
    • Start new stories from scenarios they own.
    • Load existing stories they own and continue them.
    • Edit and merge steps, scenes, and characters within their own stories.
    • Delete their own stories.

• Admin user

  • All capabilities of regular users.
  • Additional capabilities:
    • Create new users.
    • View list of all users.
    • Edit user information (e.g., username, admin flag, active flag, password reset).
    • Delete users (with defined behavior for their content).

Anonymous users are not supported; all access is via login.

---

3. Core Domain Model

3.1 User

• Fields
  • id
  • username (unique)
  • passwordHash
  • isAdmin (boolean)
  • active (boolean)
  • createdAt
  • updatedAt

3.2 Scenario (Starting Point)

• Fields

  • id
  • ownerUserId
  • title
  • description (overall scenario description)
  • startingSceneDescription (initial scene narrative text)
  • startingCharacters (list of ScenarioCharacter)
  • createdAt
  • updatedAt

• ScenarioCharacter

  • id
  • scenarioId
  • name
  • role (e.g., “protagonist”, “villain”, “guide”)
  • description

3.3 Story

• Fields

  • id
  • ownerUserId
  • scenarioId (reference to starting scenario)
  • title
  • currentSceneDescription (full narrative of the current scene)
  • currentSceneCharacters (list of StoryCharacter)
  • status (e.g., ACTIVE, ARCHIVED, DELETED)
  • createdAt
  • updatedAt

• StoryCharacter

  • id
  • storyId
  • name
  • role
  • description
  • (Optional) origin (e.g., FROM_SCENARIO, ADDED_IN_STORY)

3.4 StoryStep

• Represents a continuation segment in the story.

• Fields

  • id
  • storyId
  • stepNumber (monotonic integer starting from 1)
  • content (text for this step: AI-written and/or user-edited)
  • addedToScene (boolean; true if this step has been merged/compacted into the current scene)
  • userDirection (the user’s “what should happen next” text used for this step)
  • createdAt
  • (Optional) aiPromptMetadata (model name, parameters, etc.)

---

4. Functional Requirements

4.1 Authentication & User Management

• Login

  • User provides username and password.
  • On success, user session is established (e.g., cookie or token-based).
  • On failure, an error message is displayed.

• Admin user management

  • List users
    • Paginated list with username, admin flag, active flag, and creation time.
  • Create user
    • Set username, initial password, and admin flag.
  • Edit user
    • Change password (reset).
    • Toggle isAdmin.
    • Toggle active.
  • Delete user
    • Remove user with defined behavior for their content (e.g., soft delete or cascade; to be decided at implementation).

4.2 Scenario & Starting Characters Management

• Create scenario

  • User defines:
    • Title.
    • Overall description (optional).
    • Starting scene description.
    • Initial set of starting characters (name, role, description).

• Edit scenario

  • Update title, descriptions, and characters:
    • Add, edit, remove ScenarioCharacters.

• Delete scenario

  • User can delete their own scenarios.
  • Behavior if stories exist for this scenario (e.g., forbid deletion or only mark the scenario as inactive) is defined at implementation.

• List scenarios

  • Users see only scenarios they own.
  • Admins can see all scenarios.

4.3 Story Lifecycle

• Start new story from a scenario

  • User selects a scenario.
  • System initializes a Story:
    • currentSceneDescription from startingSceneDescription.
    • currentSceneCharacters from startingCharacters.
    • No StorySteps initially.
  • User can optionally set a custom story title.

• Load existing story

  • User sees a list of their stories (title, originating scenario, last updated).
  • Selecting a story shows:
    • Current scene.
    • Current scene characters.
    • Story step list with stepNumber and addedToScene flag.
    • Input area for “what should happen next”.

• Delete story

  • Users can delete their own stories.
  • Implementation can choose soft delete (recommended) or hard delete.

---

5. Story Interaction & AI Behavior

5.1 User Actions Per Step

On an active story, the user can:

• Enter a description of what should happen next

  • Free text input for the direction of the next step.

• Modify the current scene

  • Direct text editing of currentSceneDescription.
  • Or AI-assisted edit:
    • User describes desired changes.
    • AI proposes modified scene text.
    • User can accept, reject, or further edit the proposal.

• Modify current characters

  • Directly:
    • Change name, role, or description of existing characters.
    • Remove characters.
    • Add new characters.
  • Or AI-assisted:
    • User describes desired character changes (e.g., “make the mentor more mysterious”).
    • AI proposes updates to character fields.
    • User confirms or edits these suggestions.

5.2 Request Payload to AI (Normal Case)

When generating the next story step without compaction:

• Request to AI must include:

  • Current scene
    • currentSceneDescription.
    • currentSceneCharacters (list of name, role, description).
  • User direction
    • The user’s text describing what should happen next for this step.
  • Unmerged steps
    • All StoryStep entries where addedToScene == false.
    • Steps are sent in chronological order as additional context after the scene.

• AI output

  • Narrative text for the next part of the story (step content).

• System actions

  • Create a new StoryStep with:
    • stepNumber = max(existing stepNumber) + 1.
    • content = AI response (subsequently editable by user).
    • addedToScene = false.
    • userDirection stored for this step.

5.3 Context Compaction Flow (When Prompt Too Large)

If the combined size of:

• Current scene description,
• Current characters,
• All unmerged steps,
• And the new user direction

exceeds the AI model’s context limits, the system performs a compaction phase before requesting a new step.

Compaction phase (first AI call):

• Send to the AI:
  • The current scene (description and characters).
  • A subset of the unmerged StorySteps, typically the oldest half of them.
• Ask the AI to:
  • Merge and compact this information into a new, coherent scene description.
  • Optionally adjust character descriptions to reflect changes implied by the merged steps.

Update of domain state:

• Replace currentSceneDescription with the compacted scene from the AI.
• Update currentSceneCharacters if the AI returned updated characters.
• Mark the merged StorySteps as:
  • addedToScene = true.

Repeated compaction (if needed):

• If context is still too large, repeat the compaction step with the remaining unmerged steps until:
  • The full story history is representable by:
    • One current scene,
    • Current characters,
    • A small remaining set of unmerged steps.

User review after compaction:

• Show the new current scene and characters to the user.
• Allow:
  • Direct editing of the compacted scene and characters.
  • AI-assisted modification (prompt–suggest–accept/edit loop).
• Once the user is satisfied, they can:
  • Enter new “what should happen next” text.
  • Trigger the normal “generate next step” AI call, which uses the compacted scene plus remaining unmerged steps.

---

6. Frontend UX Requirements

6.1 Login & Admin Screens

• Login page

  • Username and password fields.
  • Button to log in.
  • Display of error messages for invalid credentials.

• Admin user management

  • User list table showing:
    • Username.
    • Admin flag.
    • Active flag.
  • Actions:
    • Create user (form).
    • Edit user (change password, toggle admin/active).
    • Delete user.

6.2 Scenario Management UI

• Scenario list

  • Displays scenarios owned by the logged-in user.
  • Actions:
    • Create scenario.
    • Edit scenario.
    • Delete scenario.

• Scenario editor

  • Fields:
    • Title.
    • Scenario description.
    • Starting scene description.
    • Character list:
      • For each character: name, role, description.
      • Add / edit / delete characters.

6.3 Story Workspace UI

For a selected story, the workspace should provide:

• Current scene panel

  • Read-only by default with buttons:
    • “Edit Scene” (direct text edit).
    • “AI Edit Scene” (prompt-based suggestion).

• Characters panel

  • List of characters with name, role, and description.
  • Actions:
    • Add character.
    • Edit character.
    • Remove character.
    • “AI Suggest Character Changes”.

• Steps panel

  • List of steps with:
    • Step number.
    • Short preview of content.
    • Badge or indicator for addedToScene vs not.
  • Clicking a step expands to show full content.

• Next step input

  • Text area: “What should happen next?”
  • Button: “Generate Next Step”.

• Compaction UX

  • When compaction is triggered:
    • Show progress indication.
    • After completion, present the updated current scene and characters.
    • Provide:
      • “Accept Scene” (continue).
      • “Edit Scene” (direct or AI-assisted).

---

7. Non-Functional Requirements (High-Level)

• Persistence

  • Use a relational database to store User, Scenario, ScenarioCharacter, Story, StoryCharacter, and StoryStep.

• AI integration

  • Backend component to:
    • Build AI prompts from current scene, characters, user direction, and steps.
    • Check approximate prompt size against model limits.
    • Trigger compaction workflow when limits are exceeded.

• Security

  • Authorization checks ensure:
    • Users only access and modify their own scenarios and stories.
    • Admin endpoints/actions are restricted to admin users.

• Auditability

  • Store:
    • userDirection and AI-generated content per StoryStep.
    • Optional metadata about AI calls for debugging and analysis.

This specification describes the intended behavior and structure of the Story Teller application across users, scenarios, stories, AI integration, and frontend UX.