# eeman1113/story architecture

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

- Interactive diagram: https://gitdiagram.com/eeman1113/story
- Repository: https://github.com/eeman1113/story

## Overview

##### Project type and purpose
- This is a Python-based, single-process, command-line “pipeline” application (no separate frontend/backend) that orchestrates a sequence of Langchain/LLM “chains” to generate a complete long-form narrative (a novel) from inputs (PDF resume, story premise, author style, genre). It uses Ollama-hosted LLMs locally and produces a `.docx` output.

##### File structure
Top-level:
- main.py / supercomputer_wont_be_enough_main.py / ULTIMATE_POWER.py / novel_generator.py – potential orchestration/entry-point scripts
- character.py, subject.py – specialized chain modules (e.g., MainCharacterChain)
- docs/ – stores resumes (PDFs), intermediary `.ipynb` experiments, story drafts, and final output folder
- requirements.txt – Python dependencies
- numerous notebooks (.ipynb) and throwaway scripts (100.py, try.py, etc.) – for prototyping
No separate “frontend” or “backend” folders; everything lives in one codebase.

##### README for additional insights
- The README describes a linear pipeline of nine specialized Langchain chains (MainCharacterChain, SettingChain, ThemeChain, TitleChain, PlotChain, ChaptersChain, EventChain, WriterChain, RefinementChain) orchestrated by `app_v2.py` (or its analog in your code: main.py or supercomputer_wont_be_enough_main.py).
- It also references a `DocWriter` class to assemble and write the `.docx` file.

a. Main Components
1. Inputs
- PDF Resume (docs/divi_1.pdf or similar)
- Story Premise/Subject (CLI argument or config in main)
- Author Style (CLI/config)
- Genre (CLI/config)
2. Orchestrator Script
- main.py (or supercomputer_wont_be_enough_main.py) – glues everything together
3. LLM Host
- Ollama Service (gemma2, llama3, etc.)
4. Chain Modules
- MainCharacterChain (character.py)
- SettingChain, ThemeChain, TitleChain, PlotChain, ChaptersChain, EventChain, WriterChain, RefinementChain (may be defined in main.py or separate modules)
5. DocWriter
- Assembles front matter and full narrative, writes `.docx` via python-docx
6. Output
- Sanitized_Title.docx in docs/ (or configured output folder)

b. Relationships and Data Flow
1. User inputs → Orchestrator
2. Orchestrator initializes LLM connection via `create_llm()`
3. For each chain i=1..9:
- Orchestrator calls Chain_i.run(...)
- Chain_i invokes LLMChain → Ollama → returns structured result
- Orchestrator collects and passes outputs as inputs to the next chain
4. After all narrative chains complete, Orchestrator passes accumulated data → DocWriter
5. DocWriter writes `.docx` → Output folder

c. Architectural Patterns & Design Principles
- Pipeline pattern – sequential data processing stages
- Separation of concerns – each narrative component is its own “chain” module
- Dependency injection of LLM config via `create_llm()` (temperature, top_k, top_p)
- Robust error handling at each stage to continue generation where possible

d. Key Technologies & Libraries
- Python 3.x
- Ollama (local LLM service)
- Langchain: `OllamaLLM`, `LLMChain`, `PromptTemplate`, `PyPDFLoader`
- python-docx for output
- python-dotenv for config
- re (regex) for parsing

##### Detail to capture
- Chain sequence and handoff of context variables (character profile → setting → themes → title → plot → chapters → events → paragraphs → optional refinement)
- Configuration injection (`.env` / constants)
- Error-handling branches (e.g., if a chain fails, pass “N/A” forward)
- Document assembly step

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Inputs
    subgraph "Inputs"
        Resume["Resume PDF"]:::data
        Premise["Story Premise (CLI)"]:::data
        Style["Author Style (CLI)"]:::data
        Genre["Genre (CLI)"]:::data
        Config["requirements.txt"]:::code
    end

    %% Orchestrator
    Orchestrator["Orchestrator Script\n(main.py)"]:::code

    %% Alternative entry points
    alt1["supercomputer_wont_be_enough_main.py"]:::code
    alt2["ULTIMATE_POWER.py"]:::code
    alt3["novel_generator.py"]:::code

    %% LLM Service
    LLM["Ollama LLM Service"]:::external

    %% Chains Pipeline
    subgraph "Narrative Chains"
        MC["MainCharacterChain"]:::code
        SC["SubjectChain"]:::code
        Setting["SettingChain"]:::code
        Theme["ThemeChain"]:::code
        Title["TitleChain"]:::code
        Plot["PlotChain"]:::code
        Chapters["ChaptersChain"]:::code
        Event["EventChain"]:::code
        WriterChain["WriterChain"]:::code
        Refinement["RefinementChain"]:::code
    end

    %% DocWriter
    DocWriter["DocWriter"]:::code

    %% Outputs
    subgraph "Output Artifacts"
        Out1["Bhopal_Echoes.docx"]:::data
        Out2["Echoes_of_Silverwood.docx"]:::data
        Out3["Echoes_of_the_Algorithm.docx"]:::data
        Out4["Silver_Hush.docx"]:::data
        Out5["The_Cartographer's_Echo.docx"]:::data
        Out6["The_Cartonox_Archive.docx"]:::data
    end

    %% Flow
    Resume --> Orchestrator
    Premise --> Orchestrator
    Style --> Orchestrator
    Genre --> Orchestrator
    Config --> Orchestrator

    Orchestrator --> LLM
    Orchestrator --> MC
    Orchestrator --> SC
    SC --> Setting
    Setting --> Theme
    Theme --> Title
    Title --> Plot
    Plot --> Chapters
    Chapters --> Event
    Event --> WriterChain
    WriterChain --> Refinement
    Refinement --> DocWriter

    MC --> LLM
    SC --> LLM
    Setting --> LLM
    Theme --> LLM
    Title --> LLM
    Plot --> LLM
    Chapters --> LLM
    Event --> LLM
    WriterChain --> LLM
    Refinement --> LLM

    DocWriter --> Out1
    DocWriter --> Out2
    DocWriter --> Out3
    DocWriter --> Out4
    DocWriter --> Out5
    DocWriter --> Out6

    %% Alternative entry points
    alt1 --- Orchestrator
    alt2 --- Orchestrator
    alt3 --- Orchestrator

    %% Click events
    click Orchestrator "https://github.com/eeman1113/story/blob/main/main.py"
    click alt1 "https://github.com/eeman1113/story/blob/main/supercomputer_wont_be_enough_main.py"
    click alt2 "https://github.com/eeman1113/story/blob/main/ULTIMATE_POWER.py"
    click alt3 "https://github.com/eeman1113/story/blob/main/novel_generator.py"
    click MC "https://github.com/eeman1113/story/blob/main/character.py"
    click SC "https://github.com/eeman1113/story/blob/main/subject.py"
    click Config "https://github.com/eeman1113/story/blob/main/requirements.txt"
    click Resume "https://github.com/eeman1113/story/blob/main/docs/divi_1.pdf"
    click Out1 "https://github.com/eeman1113/story/blob/main/docs/Bhopal_Echoes.docx"
    click Out2 "https://github.com/eeman1113/story/blob/main/docs/Echoes_of_Silverwood.docx"
    click Out3 "https://github.com/eeman1113/story/blob/main/docs/Echoes_of_the_Algorithm.docx"
    click Out4 "https://github.com/eeman1113/story/blob/main/docs/Silver_Hush.docx"
    click Out5 "https://github.com/eeman1113/story/blob/main/docs/The_Cartographer's_Echo.docx"
    click Out6 "https://github.com/eeman1113/story/blob/main/docs/The_Cartonox_Archive.docx"

    %% Styles
    classDef code fill:#ccf,stroke:#000,font-weight:bold
    classDef external fill:#cfc,stroke:#080
    classDef data fill:#eee,stroke:#aaa
```
