# krishnaag23/narrative-core architecture

> Architecture diagram of the GitHub repository krishnaag23/narrative-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krishnaag23/narrative-core
- Repository: https://github.com/krishnaag23/narrative-core

## Overview

##### Main Components
- Input Processing: This module (found under src/input_processing) is responsible for analyzing the raw story ideas. It includes components for concept analysis, genre classification, cultural context detection, and story element extraction.
- Character System: Located in src/character_system, this module deals with character generation, character embeddings, dialogue generation, and managing relationships and profiles. It is key for ensuring narrative coherence and emotional depth.
- Memory Management: Under src/memory_management, the system handles various types of memory (episodic, character, plot, theme, and world memory). It also includes memory retrieval and optimization to ensure consistent narrative context over multiple episodes.
- Episode Generator: Housed in src/episode_generator, this component takes the processed input and organized narrative elements to check continuity, construct scenes, and build scripts for individual episodes.
- Story Blueprint: Found in src/story_blueprint, this is where the high-level narrative structure is built. Components here focus on mapping episodes, building narrative graphs, and generating overall plot arcs.
- API & Integration: Although minimal from the file structure, the src/api folder and models (e.g., ChatGPT.py) hint at external service interactions, possibly to leverage language models for generating creative text or integrating with other services.
- Utilities & Config: Across src/utils and src/config, utility functions (LLM integrations, prompt management, vector stores) and configuration files (including YAML templates for character genesis) support the main components.

##### Relationships and Interactions
- The processed data then feeds into the Character System to generate an immersive set of characters and profiles.
- Both the Input Processing and Character System outputs converge into Memory Management, which stores and optimizes narrative context.
- Episode Generator takes over to create coherent scenes and scripts while referencing insights from the Memory Management module.
- Finally, the Story Blueprint module organizes the episodes into a structured, cohesive narrative arc.
- An API layer acts as the interface between external requests and internal processing, interfacing with language models (such as the one in models/ChatGPT.py) and possibly external data sources.

##### Architectural Patterns and Design Principles
- Modular Design: The clear separation into modules (input, character, memory, episode, blueprint) supports maintainability and scalability.
- Pipeline Architecture: There is an evident sequential flow where each module builds on the output of the previous one.
- Microservice-Like Separation: Although it runs as a single project, each component (or folder) can be thought of as an isolated service with well-defined responsibilities.
- Utility Layers: Common functions such as LLM utilities, prompt management, and vector store management are centralized to promote code reuse.

##### Relevant Technologies and Frameworks
- The project uses Python (as seen by .py files and the requirements.txt).
- AI and LLM integration is central (under models/ChatGPT.py and within various utils like llm_utils.py).
- YAML configuration is used (from src/config/prompts/character_genesis.yaml) for flexible configuration.

##### Capturing Essential Architectural Elements
- Modular structure, emphasizing clean separation of concerns while highlighting the integration points between the different narrative system segments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entity
    User("User Input"):::external

    %% API & External Integrations Subgraph
    subgraph "API & External Integrations"
        API("API"):::api
        CHAT("ChatGPT Model"):::api
    end

    %% Core Modules Subgraph
    subgraph "Core Modules"
        IP("Input Processing"):::core
        CS("Character System"):::core
        MM("Memory Management"):::core
        EG("Episode Generator"):::core
        SB("Story Blueprint"):::core
        FN("Final Narrative Output"):::core
    end

    %% Utilities & Config Subgraph
    subgraph "Utilities & Config"
        UT("Utilities"):::util
        CFG("Config"):::util
    end

    %% Main Data Flow
    User --> API
    API -->|"forwards input"| IP
    IP -->|"generates characters"| CS
    IP -->|"provides data"| MM
    CS -->|"enriches context"| MM
    MM -->|"builds episodes"| EG
    EG -->|"assembles narrative"| SB
    SB --> FN

    %% API Integrations
    API -->|"invokes LLM"| CHAT

    %% Supporting Utilities Connections (dashed)
    UT --- IP
    UT --- CS
    UT --- MM
    UT --- EG
    UT --- SB

    CFG --- IP
    CFG --- CS
    CFG --- MM
    CFG --- EG
    CFG --- SB

    %% Click Events
    click IP "https://github.com/krishnaag23/narrative-core/tree/main/src/input_processing"
    click CS "https://github.com/krishnaag23/narrative-core/tree/main/src/character_system"
    click MM "https://github.com/krishnaag23/narrative-core/tree/main/src/memory_management"
    click EG "https://github.com/krishnaag23/narrative-core/tree/main/src/episode_generator"
    click SB "https://github.com/krishnaag23/narrative-core/tree/main/src/story_blueprint"
    click API "https://github.com/krishnaag23/narrative-core/tree/main/src/api"
    click CHAT "https://github.com/krishnaag23/narrative-core/blob/main/models/ChatGPT.py"
    click UT "https://github.com/krishnaag23/narrative-core/tree/main/src/utils"
    click CFG "https://github.com/krishnaag23/narrative-core/blob/main/src/config/prompts/character_genesis.yaml"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#F4A460,stroke:#000,stroke-width:2px;
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
