story-weaver-ai/assets/scripts_README.md

A narrative development system for AI-driven storytelling with Jungian psychology

# Story Weaver - Script Documentation

This folder contains the scripts that power Story Weaver, a story writing management system with Jungian psychology influences. The system revolves around analyzing and refining narrative elements, with special focus on psychological depth and character development.

## Overview

Story Weaver helps writers develop rich, psychologically complex narratives by:

1. **Analyzing** story plots and structures with AI-powered insights
2. **Refining** stories based on literary and psychological analysis
3. **Breaking down** story concepts into structured narrative elements
4. **Organizing** elements with Jungian archetypes and psychological patterns
5. **Tracking** dependencies between narrative components
6. **Generating** well-formatted output in multiple formats (Markdown, JSON, YAML)
7. **Managing** the progress of story development

## Configuration

The system can be configured through environment variables in a `.env` file at the root of the project:

### Required Configuration
- `ANTHROPIC_API_KEY`: Your Anthropic API key for Claude

### Optional Configuration
- `MODEL_ANALYSIS`: Model to use for story analysis (default: "claude-3-sonnet-20240229")
- `MODEL_REFINEMENT`: Model to use for story refinement (default: "claude-3-opus-20240229")
- `DEFAULT_MAX_TOKENS`: Maximum tokens for model responses (default: 4000)
- `TEMPERATURE_ANALYSIS`: Temperature for analysis (default: 0.2)
- `TEMPERATURE_REFINEMENT`: Temperature for refinement (default: 0.3)
- `DEBUG`: Enable debug logging (default: false)
- `LOG_LEVEL`: Log level - debug, info, warn, error (default: info)
- `STORY_NAME`: Override default story name in elements.json
- `ELEMENTS_OUTPUT_FORMAT`: Default output format (markdown, json, yaml)

## Key Features

### 1. Story Analysis

The `analyze-story` command analyzes a story's narrative structure, providing insights on:

- Plot structure and effectiveness
- Character development and arcs
- Pacing and flow
- Thematic elements
- Narrative coherence
- Psychological depth (optional)
- Improvement recommendations (optional)

Usage:
```bash
story-weaver analyze-story -i story.txt -o analysis.md
story-weaver analyze-story -i story.txt -o analysis.json -f json
story-weaver analyze-story -i story.txt -d # Deep psychological analysis
```

### 2. Story Refinement

The `refine-story` command enhances a story based on analysis and user preferences:

- Focuses on specific improvement areas
- Adjusts tone as requested
- Maintains the author's voice and style
- Integrates psychological refinements

Usage:
```bash
story-weaver refine-story -i story.txt -a analysis.json -o refined.md
story-weaver refine-story -i story.txt -a analysis.json -f "pacing" -t "darker"
story-weaver refine-story -i story.txt -a analysis.json -g "Emphasize the protagonist's inner conflict"
```

### 3. Element Management

The system manages story elements with a Jungian psychology influence:

- Parse story concepts into structured elements
- Track dependencies between narrative components
- Organize elements with archetypes and themes
- Generate element files in various formats

Usage:
```bash
story-weaver parse-concept -i concept.txt
story-weaver list
story-weaver generate --format yaml
```

## File Formats

The system supports multiple output formats:

1. **Markdown (.md)**: Human-readable documentation with formatted sections
2. **JSON (.json)**: Structured data for programmatic processing
3. **YAML (.yaml)**: Human-readable structured data

All outputs include comprehensive metadata to ensure content can be parsed and processed programmatically.

## Integration with Cursor AI

Story Weaver is designed to work seamlessly with [Cursor AI](https://www.cursor.so/), providing a structured workflow for AI-assisted story development.

### Setting Up with Cursor

1. After initializing your project, open it in Cursor
2. Place your story document in the `stories/` directory (e.g., `stories/my-story.txt`)
3. Open Cursor's AI chat and switch to Agent mode
4. Ask the agent to analyze or refine your story using Story Weaver commands

## Element Structure

Story elements in `elements.json` have the following structure:

- `id`: Unique identifier for the element (Example: `1`)
- `title`: Brief, descriptive title of the element (Example: `"The Protagonist's Shadow"`)
- `description`: Concise description of what the element involves (Example: `"The protagonist confronts their repressed rage"`)
- `status`: Current state of the element (Example: `"draft"`, `"developing"`, `"complete"`)
- `dependencies`: IDs of elements that must be developed before this element (Example: `[1, 2]`)
- `archetypes`: Jungian archetypes involved in this element (Example: `["Hero", "Shadow"]`)
- `themes`: Psychological themes or motifs (Example: `["Rebirth", "Integration"]`)
- `priority`: Importance level of the element (Example: `"high"`, `"medium"`, `"low"`)
- `details`: In-depth narrative development (Example: `"In a dream sequence, the protagonist faces their dark impulses..."`)
- `criticalAnalysis`: Jungian psychological interpretation (Example: `"This represents the shadow integration phase..."`)
- `subelements`: List of smaller, more specific narrative components

## Command Reference

### analyze-story
```
story-weaver analyze-story [options]

Options:
  -i, --input <file>          The story file to analyze (required)
  -o, --output <file>         File to save the analysis results to
  -f, --format <format>       Output format (markdown, json, yaml) (default: "markdown")
  -d, --deep-analysis         Perform deep psychological analysis
  -r, --no-recommendations    Exclude recommendations from the analysis
  -m, --model <model>         Claude model to use for analysis
  -t, --temperature <value>   Temperature for generation (0-1)
```

### refine-story
```
story-weaver refine-story [options]

Options:
  -i, --input <file>          The story file to refine (required)
  -a, --analysis <file>       The analysis file to use for refinement (required)
  -o, --output <file>         File to save the refined story to
  -f, --focus <areas...>      Areas to focus on (e.g., "pacing", "characters")
  -t, --tone <adjustment>     Desired tone adjustment (e.g., "darker", "lighter")
  -g, --guidance <text>       Additional refinement guidance
  -m, --model <model>         Claude model to use for refinement
  --temperature <value>       Temperature for generation (0-1)
```

### generate
```
story-weaver generate [options]

Options:
  -f, --file <file>           Path to the elements file (default: "elements/elements.json")
  -o, --output <dir>          Output directory (default: "elements")
  --format <format>           Output format (markdown, json, yaml) (default: "markdown")
```

## Jungian Psychology Elements

Story Weaver incorporates key concepts from Jungian psychology to enrich storytelling:

### Core Archetypes
- **Hero/Heroine**: The protagonist on a journey of growth
- **Shadow**: The dark, rejected aspects of the self
- **Anima/Animus**: Feminine/masculine aspects within the psyche
- **Mentor/Wise Old Man/Woman**: Guide providing wisdom
- **Trickster**: Agent of chaos and transformation
- **Self**: The integrated whole, representing completeness

### Psychological Concepts
- **Collective Unconscious**: Shared archetypal patterns
- **Individuation**: Process of integrating the unconscious
- **Shadow Integration**: Confronting repressed aspects
- **Synchronicity**: Meaningful coincidences
- **Symbolism**: Unconscious expression through symbols