# amanattar/talesmith_ai architecture

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

- Interactive diagram: https://gitdiagram.com/amanattar/talesmith_ai
- Repository: https://github.com/amanattar/talesmith_ai

## Overview

##### Project Type and Purpose
- Talesmith AI is clearly a full-stack (but not web-based) multimedia processing application. Its primary purpose is to generate and compile digital storytelling content (text, images, audio) into finished artifacts like video and PDFs.
- The system leverages external services (e.g., OpenAI for text generation and cloud providers for audio via Polly, possibly using gTTS) and local tools (MoviePy, FFmpeg, Pillow).

##### Main Components
a. Entry Point:
- The main.py file is the starting point. It handles command-line arguments (e.g., generating new stories from a prompt vs. loading an existing story’s pickle file).
b. Story Provider:
- Story Provider (story_provider.py) that orchestrates the story generation, including text, image, and audio content.
c. Story Manager:
- Story Manager (story_manager.py) responsible for managing multimedia content, organizing assets, and invoking processors.
d. Generators:
- Text generation (text_generator.py, story_content_generator.py)
- Image generation (image_generator.py)
- Audio generation (audio_generator_gtts.py and audio_generator_polly.py)
- Keyword extraction (keywords_generator.py)
e. Processors:
- “processors” directory. List the components for:
- Video processing (video_processor.py)
- Text processing (text_processor.py)
- PDF processing (pdf_processor.py)
- Page processing (page_processor.py)
f. Utility Components:
- The “util” directory includes helpers such as story_utility.py, gradient_image.py, and credentials providers (openai_credentials_provider.py). This layer supports configuration and ancillary operations.
g. Data Models:
- Data_models.py file as the foundation for the story/page data structures.
h. External Resources:
- External artifact directories like “music”, “fonts”, “images”, and “_stories,” which hint at asset storage and final outputs.
i. External Dependencies:
- That the system depends on external libraries and services like:
- OpenAI API (for GPT story generation)
- MoviePy and FFmpeg (for video and audio synthesis)
- Pillow (for image manipulation)
- AWS Polly (for one type of audio generation)

##### Relationships and Interactions
- The Story Provider should branch out to the various Generator modules, indicating that it requests text, image, and audio generation.
- Story Manager receives output from the generators and then coordinates with the Processor modules to compile the final multimedia outputs (video, PDF, audio).
- The Utility layer is connected to both the Generators and the main orchestration components, providing necessary credentials and helper functions.

##### Architectural Patterns & Design Details
- That the design follows a modular, layered architecture where each module (generators, processors, utilities) is independent but coordinated through the main orchestrator(s).
- Data flow from input (user prompt in main.py) through processing layers (generation → post-processing) to output (multimedia story artifacts in _stories).
- The separation of concerns is evident: generation logic is isolated from processing/compilation logic, making maintenance and future extensions (e.g., additional generators) easier.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    M["main.py (Entry Point)"]:::orchestration

    %% Core Services
    SP["Story Provider"]:::orchestration
    SM["Story Manager"]:::orchestration

    M -->|"triggers"| SP
    M -->|"triggers"| SM

    %% Generators Subsystem
    subgraph "Generators"
        T1["Text Generator: text_generator.py"]:::generator
        T2["Story Content Generator: story_content_generator.py"]:::generator
        I["Image Generator: image_generator.py"]:::generator
        A1["Audio Generator GTTS: audio_generator_gtts.py"]:::generator
        A2["Audio Generator Polly: audio_generator_polly.py"]:::generator
        K["Keyword Extraction: keywords_generator.py"]:::generator
    end

    %% Story Provider calls Generators
    SP -->|"calls_Generation"| T1
    SP -->|"calls_Generation"| T2
    SP -->|"calls_Generation"| I
    SP -->|"calls_Generation"| A1
    SP -->|"calls_Generation"| A2
    SP -->|"calls_Generation"| K

    %% Utility Components Subsystem
    subgraph "Utility"
        OC["OpenAI Credentials: openai_credentials_provider.py"]:::utility
        AC["AWS Polly Credentials: aws_polly_credentials_provider.py"]:::utility
        G["Gradient Image: gradient_image.py"]:::utility
        SU["Story Utility: story_utility.py"]:::utility
    end

    %% Utility injections to main orchestration and generators
    SU --> SP
    OC --> T1
    OC --> T2
    OC --> I
    OC --> A1
    OC --> A2
    G --> I

    %% Processors Subsystem
    subgraph "Processors"
        VP["Video Processing: video_processor.py"]:::processor
        TP["Text Processing: text_processor.py"]:::processor
        PP["PDF Processing: pdf_processor.py"]:::processor
        PAP["Page Processing: page_processor.py"]:::processor
    end

    %% Story Manager routes processed content to Processors
    SM -->|"sends_to"| VP
    SM -->|"sends_to"| TP
    SM -->|"sends_to"| PP
    SM -->|"sends_to"| PAP

    %% Data Models
    DM["Data Models: data_models.py"]:::data

    %% External Assets
    subgraph "External Assets"
        ST["_stories"]:::external
        MU["music"]:::external
        FO["fonts"]:::external
        IM["images"]:::external
    end

    %% External Dependencies
    subgraph "External Dependencies"
        OA["OpenAI_API"]:::external_api
        MP["MoviePy_FFmpeg"]:::external_api
        PL["Pillow"]:::external_api
        AP["AWS_Polly"]:::external_api
    end

    %% Storage and Updates Flows
    VP -->|"stores_to"| ST
    PP -->|"stores_to"| ST
    TP -->|"updates"| DM
    PAP -->|"updates"| DM

    %% External API Interactions
    SP -->|"uses"| OA
    SP -->|"uses"| MP
    SP -->|"uses"| PL
    A2 -->|"uses"| AP

    %% Click Events
    click M "https://github.com/amanattar/talesmith_ai/blob/master/main.py"
    click SP "https://github.com/amanattar/talesmith_ai/blob/master/story_provider.py"
    click SM "https://github.com/amanattar/talesmith_ai/blob/master/story_manager.py"
    click T1 "https://github.com/amanattar/talesmith_ai/blob/master/generators/text_generator.py"
    click T2 "https://github.com/amanattar/talesmith_ai/blob/master/generators/story_content_generator.py"
    click I "https://github.com/amanattar/talesmith_ai/blob/master/generators/image_generator.py"
    click A1 "https://github.com/amanattar/talesmith_ai/blob/master/generators/audio_generator_gtts.py"
    click A2 "https://github.com/amanattar/talesmith_ai/blob/master/generators/audio_generator_polly.py"
    click K "https://github.com/amanattar/talesmith_ai/blob/master/generators/keywords_generator.py"
    click VP "https://github.com/amanattar/talesmith_ai/blob/master/processors/video_processor.py"
    click TP "https://github.com/amanattar/talesmith_ai/blob/master/processors/text_processor.py"
    click PP "https://github.com/amanattar/talesmith_ai/blob/master/processors/pdf_processor.py"
    click PAP "https://github.com/amanattar/talesmith_ai/blob/master/processors/page_processor.py"
    click OC "https://github.com/amanattar/talesmith_ai/blob/master/util/openai_credentials_provider.py"
    click AC "https://github.com/amanattar/talesmith_ai/blob/master/util/aws_polly_credentials_provider.py"
    click G "https://github.com/amanattar/talesmith_ai/blob/master/util/gradient_image.py"
    click SU "https://github.com/amanattar/talesmith_ai/blob/master/util/story_utility.py"
    click DM "https://github.com/amanattar/talesmith_ai/blob/master/data_models.py"
    click ST "https://github.com/amanattar/talesmith_ai/tree/master/_stories"
    click MU "https://github.com/amanattar/talesmith_ai/tree/master/music"
    click FO "https://github.com/amanattar/talesmith_ai/tree/master/fonts"
    click IM "https://github.com/amanattar/talesmith_ai/tree/master/images"

    %% Styles
    classDef orchestration fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef generator fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef processor fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef data fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external_api fill:#FFDEAD,stroke:#000,stroke-width:2px;
```
